pybind11 3.0.0

[BrewTestBot]

Created by brew bump

---

Created with brew bump-formula-pr.

release notes

Pybind11 3.0 includes an ABI bump, the first required bump in many years on Unix (Windows has had required bumps more often). This release contains the smart-holder branch, multi-phase init and subinterpreter support, `py::native_enum`, an interface to warnings, typing improvements, and more. CMake now defaults to FindPython mode. Please check our upgrade guide for more info on upgrading!
Support for Python 3.14, 3.14t, GraalPy, and PyPy 3.11 has been added, while legacy support for Python 3.7, PyPy 3.8/3.9, and CMake <3.15 has been removed. Most deprecated features have been kept for this release, but anything producing a warning in 3.0 may be removed in a future 3.x version. We also now have a deprecation page.
New Features:


The smart_holder branch has been merged, enabling py::class_<T, py::smart_holder>, which handles two-way conversion with std::unique_ptr<T> and std::shared_ptr<T> (simultaneously), disowning a Python object being passed to std::unique_ptr<T>, trampoline objects, and std::enable_shared_from_this. #5542


Added support for std::shared_ptr<const T> in py::init() when using py::smart_holder, complementing existing support for std::unique_ptr<const T>. #5731


Support const-only smart pointers. #5718


Eliminate cross-DSO RTTI reliance from trampoline_self_life_support functionality, smart_holder deleter detection, and other smart_holder bookkeeping. Resolves platform-specific issues on macOS related to cross-DSO dynamic_cast and typeid mismatches. #5728 (replaces #5700)




Changed PYBIND11_MODULE macro implementation to perform multi-phase module initialization (PEP 489) behind the scenes. #5574 and avoid destruction #5688


Support for sub-interpreters (both isolated (with separate GILs) and legacy (with a global GIL). Add the py::multiple_interpreters::per_interpreter_gil() tag (or, py::multiple_interpreters::shared_gil() for legacy interpreter support) to PYBIND11_MODULE calls (as the third parameter) to indicate that a module supports running with sub-interpreters. #5564


Rename macro PYBIND11_SUBINTERPRETER_SUPPORT -> PYBIND11_HAS_SUBINTERPRETER_SUPPORT to meet naming convention. #5682


Allow subinterpreter support to be disabled if defined to 0. This is mostly an emergency workaround, and is not exposed in CMake. #5708 and #5710


Modify internals pointer-to-pointer implementation to not use thread_local (better iOS support). #5709


Support implementations without subinterpreter support. #5732




Changed PYBIND11_EMBEDDED_MODULE macro implementation to perform multi-phase module initialization (PEP 489) behind the scenes and to support py::mod_gil_not_used(), py::multiple_interpreters::per_interpreter_gil() and py::multiple_interpreters::shared_gil(). #5665 and consolidate code #5670


Added API in pybind11/subinterpreter.h for embedding sub-intepreters (requires Python 3.12+). #5666


py::native_enum was added, for conversions between Python's native (stdlib) enum types and C++ enums. #5555


Add class doc string to py::native_enum. #5617


Fix signature for functions with a native_enum in the signature. #5619




Support py::numpy_scalar<> / py::make_scalar() for NumPy types. #5726


A py::release_gil_before_calling_cpp_dtor option (for py::class_) was added to resolve the long-standing issue #1446. #5522


Add dtype::normalized_num and dtype::num_of. #5429


Add support for array_t<handle> and array_t<object>. #5427


Added py::warnings namespace with py::warnings::warn and py::warnings::new_warning_type that provides the interface for Python warnings. #5291


stl.h list|set|map_caster were made more user friendly: it is no longer necessary to explicitly convert Python iterables to tuple(), set(), or map() in many common situations. #4686


The array_caster in pybind11/stl.h was enhanced to support value types that are not default-constructible. #5305


pybind11/conduit/pybind11_platform_abi_id.h was factored out, to maximize reusability of PYBIND11_PLATFORM_ABI_ID (for other Python/C++ binding systems). Separately, a note was added to explain that the conduit feature only covers from-Python-to-C++ conversions. #5375 | #5740


Added support for finding pybind11 using pkgconf distributed on pypi. #5552


Support --extension-suffix on the pybind11 command. #5360


Add semi-public API: pybind11::detail::is_holder_constructed and update example for pybind11::custom_type_setup in documentation. #5669


Added py::scoped_critical_section to support free-threaded mode. #5684 | #5706


New Features / fixes (typing):


Added option for different arg/return type hints to type_caster. Updated stl/filesystem to use correct arg/return type hints. Updated pybind11::typing to use correct arg/return type hints for nested types. #5450


Updated type hint for py::capsule to type.CapsuleType. #5567


Adds support for typing.SupportsInt and typing.SupportsFloat. Update Final to be narrower type hint. Make std::function match Callable type. Fix io_name bug in attr_with_type_hint. #5540


Rework of arg/return type hints to support .noconvert(). #5486


Add attr_with_type for declaring attribute types and Final, ClassVar type annotations. #5460


Allow annotate methods with py::pos_only when only have the self argument. Make arguments for auto-generated dunder methods positional-only. #5403


Added py::Args and py::KWArgs to enable custom type hinting of *args and **kwargs (see PEP 484). #5357


Switched to numpy.typing.NDArray and numpy.typing.ArrayLike. #5212


Use numpy.object_ instead of object. #5571


Fix module type hint. #5469


Fix Buffer type hint. #5662


Added support for collections.abc in type hints and convertible checks of STL casters and py::buffer. #5566


Fix typing and collections.abc type hint ambiguity. #5663


Add typing_extensions alternatives for all types that need them. #5693


Removals:


Remove support for pybind11 v2 internals versions (4, 5, 6). (The internals version number has been bumped for pybind11 v3.) #5512 | #5530


Remove make_simple_namespace (added in 2.8.0, deprecated in 2.8.1). #5597


Legacy-mode option PYBIND11_NUMPY_1_ONLY has been removed. #5595


Add a deprecation warning to .get_type (deprecated in pybind11 2.6 in 2020). #5596


Bug fixes:


Set __file__ on submodules. #5584. Except on embedded modules. #5650


pybind11-bound functions are now pickleable. #5580


Fix bug in attr_with_type_hint to allow objects to be in attr_with_type_hint. #5576


A -Wmaybe-uninitialized warning suppression was added in pybind11/eigen/matrix.h. #5516


PYBIND11_WARNING_POP was incorrectly defined as PYBIND11_PRAGMA(clang diagnostic push). #5448


PYBIND11_PLATFORM_ABI_ID (which is used in composing PYBIND11_INTERNALS_ID) was modernized to reflect actual ABI compatibility more accurately. #4953 | #5439


Fix buffer protocol implementation. #5407


Fix iterator increment operator does not skip first item. #5400


When getting or deleting an element in a container bound by bind_map, print the key in KeyError if it does not exist. #5397


pybind11::builtin_exception is now explicitly exported when linked to libc++. #5390


Allow subclasses of py::args and py::kwargs. #5381


Disable false-positive GCC 12 Bound Check warning. #5355


Update the dict when restoring pickles, instead of assigning a replacement dict. #5658


Properly define _DEBUG macro to 1 instead of defining it without value. #5639


Fix a missing time cast causing a compile error for newer ICC. #5621


Change the behavior of the default constructor of py::slice to be equivalent to :: in Python. #5620


Bug fixes and features (CMake):


Enable FindPython mode by default, with a COMPAT mode that sets some of the old variables to ease transition. #5553


Add an author warning that auto-calculated PYTHON_MODULE_EXTENSION may not respect SETUPTOOLS_EXT_SUFFIX during cross-compilation. #5495


Don't strip with CMAKE_BUILD_TYPE None. #5392


Fix an issue with NO_EXTRAS adding pybind11::windows_extras anyway. #5378


Fix issue with NEW/OLD message showing up. #5656


Use CMake's warnings as errors if available (CMake 3.24+). #5612


Add support for running pybind11's tests via presets in CMake 3.25+. #5655 and support --fresh. #5668


Experimental CMake support for Android. #5733


Presets now generate compile_commands.json. #5685


Bug fixes (free-threading):


Fix data race in free threaded CPython when accessing a shared static variable. #5494


A free-threading data race in all_type_info() was fixed. #5419


Added exception translator specific mutex used with try_translate_exceptions in the free-threaded build for internal locking. #5362


Internals:


Consolidated all PYBIND11_HAS_... feature macros into pybind11/detail/common.h to streamline backward compatibility checks and simplify internal refactoring. This change ensures consistent macro availability regardless of header inclusion order. #5647


pybind11/gil_simple.h was factored out from pybind11/gil.h, so that it can easily be reused. #5614


Use CPython macros to construct PYBIND11_VERSION_HEX. #5683


Documentation:


Improved reference_internal policy documentation. #5528


A new "Double locking, deadlocking, GIL" document was added. #5394


Add documenting for free-threading and subinterpreters.

#5659


Tests:


Download the final Catch2 2.x release if Catch download is requested. #5568


Explicitly used signed char for two numpy dtype tests. As seen when compiling using clang on Linux with the -funsigned-char flag. #5545


CI testing now includes -Wwrite-strings -Wunreachable-code -Wpointer-arith -Wredundant-decls in some jobs. #5523


Add nightly wheels to scientific-python's nightly wheelhouse. #5675


Expect free-threaded warning when loading a non-free-threaded module. #5680


Run pytest under Python devmode. #5715


New and removed platforms:


Support Python 3.14 (beta 1+). #5646


Added support for GraalPy Python implementation (https://github.com/oracle/graalpython). #5380


Support and test iOS in CI. #5705


Support for PyPy 3.11 added. #5508 And test in ci. #5534


Support for PyPy 3.8 and 3.9 was dropped. #5578


Support for Python 3.7 was removed. (Official end-of-life: 2023-06-27). #5191


Support for CMake older than 3.15 removed. CMake 3.15-4.0 supported. #5304 and fix regression #5691.


Use scikit-build-core for the build backend for the PyPI pybind11. The CMake generation has been moved to the sdist->wheel step. PYBIND11_GLOBAL_SDIST has been removed. #5598 and updated docs/ci. #5676


clang 20 tested and used for clang-tidy. #5692


Drop testing on MSVC 2019 (as it is being removed from GitHub). #5712


Support Windows C++20 and Linux C++23 in tests. #5707


Full Changelog: pybind/pybind11@v3.0.0rc4...v3.0.0

View the full release notes at https://github.com/pybind/pybind11/releases/tag/v3.0.0.

---