From f683978910323251da99f77c4cb76970d44bd40d Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Sun, 30 Mar 2025 14:56:24 -0700 Subject: [PATCH 01/20] =?UTF-8?q?Squashed=20prepv300/manuscript=20?= =?UTF-8?q?=E2=80=94=2030b9c268aeb98308ea42aaccfd5fe454e173c6fc=20?= =?UTF-8?q?=E2=80=94=202025-03-30=2014:56:03=20-0700=20[skip=20ci]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [Browse prepv300/manuscript tree](https://github.com/rwgk/pybind11/tree/30b9c268aeb98308ea42aaccfd5fe454e173c6fc) [Browse prepv300/manuscript commits](https://github.com/rwgk/pybind11/commits/30b9c268aeb98308ea42aaccfd5fe454e173c6fc/) --- docs/upgrade.rst | 77 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/docs/upgrade.rst b/docs/upgrade.rst index 5cef2b81ab..1611858ad0 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -8,6 +8,83 @@ to a new version. But it goes into more detail. This includes things like deprecated APIs and their replacements, build system changes, general code modernization and other useful information. +.. _upgrade-guide-3.0: + +v3.0 +==== + +pybind11 v3.0 introduces major new features, but the vast majority of +existing extensions are expected to build and run without modification. Minor +adjustments may be needed in rare cases, and any such changes can be easily +wrapped in preprocessor conditionals to maintain compatibility with the +2.x series. + +However, due to new features and modernizations, extensions built with +pybind11 v3.0 are not ABI-compatible with those built using v2.12. To ensure +cross-extension-module compatibility, it is recommended to rebuild all +pybind11-based extensions with v3.0. + +A major new feature in this release is the integration of +``py::smart_holder``, which improves support for ``std::unique_ptr`` +and ``std::shared_ptr``, resolving several long-standing issues. See +:ref:`smart_holder` for details. Closely related is the addition +of ``py::trampoline_self_life_support``, documented under +:ref:`overriding_virtuals`. + +This release includes a major modernization of cross-extension-module +ABI compatibility handling. The new implementation reflects actual ABI +compatibility much more accurately than in previous versions. The details +are subtle and complex; see +`#4953 `_ and +`#5439 `_. + +Also new in v3.0 is ``py::native_enum``, a modern API for exposing +C++ enumerations as native Python types — typically standard-library +``enum.Enum`` or related subclasses. This provides improved integration with +Python's enum system, compared to the older (now deprecated) ``py::enum_``. +See #5555 _ for details. + +Functions exposed with pybind11 are now pickleable. This removes a +long-standing obstacle when using pybind11-bound functions with Python features +that rely on pickling, such as multiprocessing and caching tools. +See #5580 _ for details. + +Migration Recommendations +------------------------- + +We recommend migrating to pybind11 v3.0 promptly, while keeping initial +changes to a minimum. Most projects can upgrade simply by updating the +pybind11 version, without altering existing binding code. + +After a short stabilization period — enough to surface any subtle issues — +you may incrementally adopt new features where appropriate: + +* Use ``py::smart_holder`` and ``py::trampoline_self_life_support`` as needed, + or to improve code health. Note that ``py::classh`` is available as a + shortcut — for example, ``py::classh`` is shorthand for + ``py::class_``. This is designed to enable easy + experimentation with ``py::smart_holder`` without introducing distracting + whitespace changes. In many cases, a global replacement of ``py::class_`` + with ``py::classh`` can be an effective first step. Build failures will + quickly identify places where ``std::shared_ptr<...>`` holders need to be + removed. Runtime failures (assuming good unit test coverage) will highlight + base-and-derived class situations that require coordinated changes. + +* Gradually migrate from ``py::enum_`` to ``py::native_enum`` to improve + integration with Python's standard enum types. + +There is no urgency to refactor existing, working bindings — adopt new +features as the need arises or as part of ongoing maintenance efforts. + +Potential stumbling blocks when migrating to v3.0 +------------------------------------------------- + +The following issues are very unlikely to arise, and easy to work around: + +* TODO holder caster traits specializations may be needed + +* TODO enum caster traits specializations may be needed + .. _upgrade-guide-2.12: v2.12 From 1407f096718c4deda0dd4b7e57f3f08b3b72030e Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Mon, 31 Mar 2025 18:03:43 -0400 Subject: [PATCH 02/20] docs: update changelog Signed-off-by: Henry Schreiner --- docs/changelog.rst | 213 ++++++++++++++++++++++++++++++++++++++-- tools/make_changelog.py | 1 + 2 files changed, 208 insertions(+), 6 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index a91082113f..a44c193be3 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -15,24 +15,225 @@ IN DEVELOPMENT Changes will be summarized here periodically. + New Features: -* Support for Python 3.7 was removed. (Official end-of-life: 2023-06-27). - `#5191 `_ +* The ``smart-holder`` branch has been merged, enabling ``py::class_``, which handles two-way conversion with + ``std::unique_ptr`` and ``std::shared_ptr`` (simultaneously), disowning + a Python object being passed to ``std::unique_ptr``, trampoline objects, + and ``std::enable_shared_from_this``. + `#5542 `_ + +* Remove pybind11 2.x internals versions, the internals version number has been + bumped. Using ``self._pybind11_conduit_v1_()`` (backported to several 2.x + versions) should keep extension compatibility. + `#5512 `_ + `#5530 `_ + +* (CMake) Enable FindPython mode by default, with a ``COMPAT`` mode that sets some of the old variables to ease transition. + `#5553 `_ + +* ``py::native_enum`` was added, for conversions between Python's native (stdlib) enum types and C++ enums. + `#5555 `_ + +* 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`` and ``array_t``. + `#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). + `#5375 `_ + +* Changed ``PYBIND11_MODULE`` macro implementation to perform multi-phase module initialization (PEP 489) behind the scenes. + `#5574 `_ + +* Added support for finding pybind11 using pkgconf distributed on pypi. + `#5552 `_ + +* Support ``--extension-suffix`` on the pybind11 command. + `#5360 `_ + + + +New Features (typing): + +.. feat(types) + +* 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 `_ + +.. fix(types) + +* Use ``numpy.object_`` instead of ``object``. + `#5571 `_ + +* Fix module type hint. + `#5469 `_ + + + +Bug fixes: + +* Set ``__file__`` on submodules. + `#5584 `_ + +* 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. + `#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 `_ + +* fix: using ``__cpp_nontype_template_args`` instead of ``__cpp_nontype_template_parameter_class``. + `#5330 `_ + +* Properly translate C++ exception to Python exception when creating Python buffer from wrapped object. + `#5324 `_ + +* Properly handle MSVC MT/MD incompatibility in ``PYBIND11_BUILD_ABI``. + `#4953 `_ + + + + +.. fix(cmake) + +Bug fixes (CMake): + +* 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 `_ + + +Bug fixes (free-threading): + +.. fix(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 `_ + + +Documentation: + +* Improved ``reference_internal`` policy documentation. + `#5528 `_ + +* A new "Double locking, deadlocking, GIL" document was added. + `#5394 `_ + +* Adds an answer (FAQ) for "What is a highly conclusive and simple way to find memory leaks?". + `#5340 `_ + + +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 `_ + +* Test PyPy3.11 in CI. + `#5534 `_ + + +New and removed platforms: + +* Added support for GraalPy Python implementation (https://github.com/oracle/graalpython). + `#5380 `_ + +* Support for PyPy 3.11 added. + `#5508 `_ + +* 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-3.30 supported. `#5304 `_ -* The ``array_caster`` in pybind11/stl.h was enhanced to support value types that are not default-constructible. - `#5305 `_ -* Added ``py::warnings`` namespace with ``py::warnings::warn`` and ``py::warnings::new_warning_type`` that provides the interface for Python warnings. - `#5291 `_ Version 2.13.6 (September 13, 2024) ----------------------------------- diff --git a/tools/make_changelog.py b/tools/make_changelog.py index 147ce1a971..2e2d9f40ca 100755 --- a/tools/make_changelog.py +++ b/tools/make_changelog.py @@ -42,6 +42,7 @@ "fix": "Bug fixes", "fix(types)": "", "fix(cmake)": "", + "fix(free-threading)": "", "docs": "Documentation", "tests": "Tests", "ci": "CI", From 9283e0006d8394c6380e1eb8e33f0ca0c3ce9a11 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Mon, 31 Mar 2025 18:21:20 -0400 Subject: [PATCH 03/20] docs: upgrade guide CMake suggestions Signed-off-by: Henry Schreiner --- docs/upgrade.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/upgrade.rst b/docs/upgrade.rst index 1611858ad0..8e32d5879d 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -24,6 +24,11 @@ pybind11 v3.0 are not ABI-compatible with those built using v2.12. To ensure cross-extension-module compatibility, it is recommended to rebuild all pybind11-based extensions with v3.0. +CMake support now defaults to the modern FindPython module. If you haven't +moved, we do some some backward compatibility ``PYTHON_*`` variables, but +please update to using ``Python_*`` variables (and setting ``PYTHON_*`` +variables will not affect the build anymore). + A major new feature in this release is the integration of ``py::smart_holder``, which improves support for ``std::unique_ptr`` and ``std::shared_ptr``, resolving several long-standing issues. See @@ -76,6 +81,11 @@ you may incrementally adopt new features where appropriate: There is no urgency to refactor existing, working bindings — adopt new features as the need arises or as part of ongoing maintenance efforts. +If you are using CMake, update to FindPython variables (mostly changing +variables from ``PYTHON_*`` -> ``Python_*``). You should see if you can use +``set(PYBIND11_FINDPYTHON ON)``, which has been supported for years and will +avoid setting the compatibly mode variables. + Potential stumbling blocks when migrating to v3.0 ------------------------------------------------- From 204d7c982936201d9ec33e07d02b27d7a67000da Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Mon, 7 Apr 2025 09:50:42 -0700 Subject: [PATCH 04/20] [skip ci] Explain type_caster_enum_type_enabled, copyable_holder_caster_shared_ptr_with_smart_holder_support_enabled, move_only_holder_caster_unique_ptr_with_smart_holder_support_enabled in Upgrade guide. --- docs/classes.rst | 2 +- docs/upgrade.rst | 59 ++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 58 insertions(+), 3 deletions(-) diff --git a/docs/classes.rst b/docs/classes.rst index 8788badcd5..b126256567 100644 --- a/docs/classes.rst +++ b/docs/classes.rst @@ -642,7 +642,7 @@ As of Python 3.13, the compatible `types in the stdlib enum module template struct type_caster_enum_type_enabled< FancyEnum, - std::enable_if_t::value>> : std::false_type {}; + enable_if_t::value>> : std::false_type {}; } #endif diff --git a/docs/upgrade.rst b/docs/upgrade.rst index 8e32d5879d..3869fa9bce 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -91,9 +91,64 @@ Potential stumbling blocks when migrating to v3.0 The following issues are very unlikely to arise, and easy to work around: -* TODO holder caster traits specializations may be needed +* In rare cases, a C++ enum may be bound to Python via a + :ref:`custom type caster `. In such cases, a + template specialization like this may be required: + + .. code-block:: cpp + + #if defined(PYBIND11_HAS_NATIVE_ENUM) + namespace pybind11::detail { + template + struct type_caster_enum_type_enabled< + FancyEnum, + enable_if_t::value>> : std::false_type {}; + } + #endif + + This specialization is needed only if the custom type caster is templated. + + The ``PYBIND11_HAS_NATIVE_ENUM`` guard is needed only + if backward compatibility with pybind11v2 is required. + +* Similarly, template specializations like the following may be required + if there are custom + + * ``pybind11::detail::copyable_holder_caster`` or + + * ``pybind11::detail::move_only_holder_caster`` + + implementations that are used for ``std::shared_ptr`` or ``std::unique_ptr`` + conversions: + + .. code-block:: cpp + + #if defined(PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT) + namespace pybind11::detail { + template + struct copyable_holder_caster_shared_ptr_with_smart_holder_support_enabled< + ExampleType, + enable_if_t::value>> : std::false_type {}; + } + #endif + + .. code-block:: cpp + + #if defined(PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT) + namespace pybind11::detail { + template + struct move_only_holder_caster_unique_ptr_with_smart_holder_support_enabled< + ExampleType, + enable_if_t::value>> : std::false_type {}; + } + #endif + + The ``PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT`` guard is needed only + if backward compatibility with pybind11v2 is required. + + (Note that ``copyable_holder_caster`` and ``move_only_holder_caster`` are not + documented, although they existed since 2017.) -* TODO enum caster traits specializations may be needed .. _upgrade-guide-2.12: From b9803c06f01552f940eda5840913ff546ffc2c3d Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Mon, 7 Apr 2025 11:21:01 -0700 Subject: [PATCH 05/20] [skip ci] Add a small section for py::bind_vector, py::bind_map & py::smart_holder --- docs/upgrade.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/upgrade.rst b/docs/upgrade.rst index 3869fa9bce..e07337e770 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -75,6 +75,11 @@ you may incrementally adopt new features where appropriate: removed. Runtime failures (assuming good unit test coverage) will highlight base-and-derived class situations that require coordinated changes. + Note that ``py::bind_vector`` and ``py::bind_map`` (in pybind11/stl_bind.h) + have a ``holder_type`` template parameter that defaults to + ``std::unique_ptr``. If ``py::smart_holder`` functionality is desired or + required, use e.g. ``py::bind_vector``. + * Gradually migrate from ``py::enum_`` to ``py::native_enum`` to improve integration with Python's standard enum types. From 5bcdf5345582361068963a5837ff984c2226be9f Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Mon, 7 Apr 2025 11:45:30 -0700 Subject: [PATCH 06/20] [skip ci] Fix tiny oversight: Reference back to the current release v2.13 (not v2.12) --- docs/upgrade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/upgrade.rst b/docs/upgrade.rst index e07337e770..c021cf7394 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -20,7 +20,7 @@ wrapped in preprocessor conditionals to maintain compatibility with the 2.x series. However, due to new features and modernizations, extensions built with -pybind11 v3.0 are not ABI-compatible with those built using v2.12. To ensure +pybind11 v3.0 are not ABI-compatible with those built using v2.13. To ensure cross-extension-module compatibility, it is recommended to rebuild all pybind11-based extensions with v3.0. From 2ab459c2d1bc8ef6e6372b966906b33e3b2b8642 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Mon, 7 Apr 2025 13:53:22 -0700 Subject: [PATCH 07/20] Remove sentence: Using self._pybind11_conduit_v1_() ... should keep extension compatibility. This isn't true, because we also modernized `PYBIND11_PLATFORM_ABI_ID` (which I believe was absolutely necessary). I think it'll be too complicated to explain that here, and there is a mention in the Upgrade guide. --- docs/changelog.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index a44c193be3..f4dc9eb734 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -25,9 +25,8 @@ New Features: and ``std::enable_shared_from_this``. `#5542 `_ -* Remove pybind11 2.x internals versions, the internals version number has been - bumped. Using ``self._pybind11_conduit_v1_()`` (backported to several 2.x - versions) should keep extension compatibility. +* Remove support for pybind11 v2 internals versions (4, 5, 6). + (The internals version number has been bumped for pybind11 v3.) `#5512 `_ `#5530 `_ From f8ed57c9f05150a5aa53c57629f85c2388cf8eef Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Mon, 7 Apr 2025 14:01:30 -0700 Subject: [PATCH 08/20] Changelog: combine #4953 and #5439 --- docs/changelog.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index f4dc9eb734..a1f0da5eb8 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -130,6 +130,7 @@ Bug fixes: `#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. @@ -156,11 +157,6 @@ Bug fixes: * Properly translate C++ exception to Python exception when creating Python buffer from wrapped object. `#5324 `_ -* Properly handle MSVC MT/MD incompatibility in ``PYBIND11_BUILD_ABI``. - `#4953 `_ - - - .. fix(cmake) From 67fa89c472833129e3ab3e862cd31a5237123e66 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Mon, 7 Apr 2025 14:18:10 -0700 Subject: [PATCH 09/20] [skip ci] Trivial whitespace/formatting fixes/enhancements. --- docs/changelog.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index a1f0da5eb8..6bdd1190ea 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -10,8 +10,8 @@ Changes will be added here periodically from the "Suggested changelog entry" block in pull request descriptions. -IN DEVELOPMENT --------------- +IN DEVELOPMENT (v3.0.0) +----------------------- Changes will be summarized here periodically. @@ -27,7 +27,7 @@ New Features: * Remove support for pybind11 v2 internals versions (4, 5, 6). (The internals version number has been bumped for pybind11 v3.) - `#5512 `_ + `#5512 `_ | `#5530 `_ * (CMake) Enable FindPython mode by default, with a ``COMPAT`` mode that sets some of the old variables to ease transition. @@ -69,7 +69,6 @@ New Features: `#5360 `_ - New Features (typing): .. feat(types) @@ -83,14 +82,15 @@ New Features (typing): * 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``. +* 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. +* 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. @@ -111,7 +111,6 @@ New Features (typing): `#5469 `_ - Bug fixes: * Set ``__file__`` on submodules. @@ -130,7 +129,7 @@ Bug fixes: `#5448 `_ * ``PYBIND11_PLATFORM_ABI_ID`` (which is used in composing ``PYBIND11_INTERNALS_ID``) was modernized to reflect actual ABI compatibility more accurately. - `#4953 `_ + `#4953 `_ | `#5439 `_ * Fix buffer protocol implementation. From 679978f50d8503d7131a9e315a3c96e9b80c6254 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sat, 17 May 2025 12:16:38 -0400 Subject: [PATCH 10/20] chore: add more to deprecation page [skip ci] Signed-off-by: Henry Schreiner --- docs/advanced/deprecated.rst | 57 +++++++++++++++++++++++++++++++++++ docs/upgrade.rst | 4 +++ tools/pybind11Config.cmake.in | 8 ++--- 3 files changed, 65 insertions(+), 4 deletions(-) diff --git a/docs/advanced/deprecated.rst b/docs/advanced/deprecated.rst index a43c447aa5..47710422bc 100644 --- a/docs/advanced/deprecated.rst +++ b/docs/advanced/deprecated.rst @@ -1,6 +1,63 @@ +.. _deprecated: + Deprecated ########## +The following features were deprecated before pybind11 3.0, and may be removed +in minor releases of pybind11 3.x. + +.. list-table:: Deprecated Features + :header-rows: 1 + :widths: 30 15 10 + + * - Feature + - Deprecated Version + - Year + * - ``py::metaclass()`` + - 2.1 + - 2017 + * - ``PYBIND11_PLUGIN`` + - 2.2 + - 2017 + * - ``py::set_error()`` replacing ``operator()`` + - 2.12 + - 2024 + * - ``get_type_overload`` + - 2.6 + - 2020 + * - ``call()`` + - 2.0 + - 2016 + * - ``.str()`` + - ? + - + * - ``.get_type()`` + - 2.6 + - + * - ``==`` and ``!=`` + - 2.2 + - 2017 + * - ``.check()`` + - ? + - + * - ``object(handle, bool)`` + - ? + - + * - ``error_already_set.clear()`` + - 2.2 + - 2017 + * - ``obj.attr(…)`` as ``bool`` + - ? + - + * - ``.contains`` + - ? (maybe 2.4) + - + * - ``py::capsule`` two-argument with destructor + - ? + - + + + .. _deprecated_enum: ``py::enum_`` diff --git a/docs/upgrade.rst b/docs/upgrade.rst index c021cf7394..ca0fe188d5 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -54,6 +54,10 @@ long-standing obstacle when using pybind11-bound functions with Python features that rely on pickling, such as multiprocessing and caching tools. See #5580 _ for details. +Anything producing a deprecation warning in the 2.x series may be removed in a +future minor release of 3.x. Most of these are still present in 3.0 in order to ease +transition. The new :doc:`deprecated` page details deprecations. + Migration Recommendations ------------------------- diff --git a/tools/pybind11Config.cmake.in b/tools/pybind11Config.cmake.in index 49990c719c..fac112ecb2 100644 --- a/tools/pybind11Config.cmake.in +++ b/tools/pybind11Config.cmake.in @@ -68,11 +68,11 @@ maximum version of CMake to 3.27+, then FindPython is the default (since FindPythonInterp/FindPythonLibs has been removed via policy `CMP0148`). Starting in pybind11 3.0, the new mode is the default, but we provide backward -compatible names (`PYTHON_*` vs. the new `Python_* names). Set the mode +compatible names (``PYTHON_*`` vs. the new ``Python_*`` names). Set the mode explicitly to avoid the compatibility defines. You can specify this mode -explicitly by setting `PYBIND11_FINDPYTHON` to `COMPAT`, but if you are changing -your CMakeLists anyway, please just use the `ON` mode. A future release may -default to `ON`. +explicitly by setting ``PYBIND11_FINDPYTHON`` to ``COMPAT``, but if you are changing +your CMakeLists anyway, please just use the ``ON`` mode. A future release may +default to ``ON``. New FindPython mode ^^^^^^^^^^^^^^^^^^^ From a79e3e71d8f421325e866376ae556872d0d90bc3 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sat, 17 May 2025 14:50:45 -0400 Subject: [PATCH 11/20] docs: update for recent additions Signed-off-by: Henry Schreiner --- docs/changelog.rst | 109 ++++++++++++++++++++++++++++++++++------ tools/make_changelog.py | 1 + 2 files changed, 96 insertions(+), 14 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 6bdd1190ea..38c9d194f2 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -25,18 +25,29 @@ New Features: and ``std::enable_shared_from_this``. `#5542 `_ -* Remove support for pybind11 v2 internals versions (4, 5, 6). - (The internals version number has been bumped for pybind11 v3.) - `#5512 `_ | - `#5530 `_ - -* (CMake) Enable FindPython mode by default, with a ``COMPAT`` mode that sets some of the old variables to ease transition. +* 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 `_ + +* (CMake) Enable FindPython mode by default, with a ``COMPAT`` mode that sets + some of the old variables to ease transition. `#5553 `_ * ``py::native_enum`` was added, for conversions between Python's native (stdlib) enum types and C++ enums. `#5555 `_ -* A ``py::release_gil_before_calling_cpp_dtor`` option (for ``py::class_``) was added to resolve the long-standing issue #1446. + * Add class doc string to ``py::native_enum``. + `#5617 `_. + + * Fix signature for functions with a native_enum in the signature. + `#5619 `_ + +* 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``. @@ -45,7 +56,9 @@ New Features: * Add support for ``array_t`` and ``array_t``. `#5427 `_ -* Added ``py::warnings`` namespace with ``py::warnings::warn`` and ``py::warnings::new_warning_type`` that provides the interface for Python warnings. +* 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 @@ -56,10 +69,13 @@ New Features: * 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). +* ``pybind11/conduit/pybind11_platform_abi_id.h`` was factored out, to maximize + reusability of ``PYBIND11_PLATFORM_ABI_ID`` (for other Python/C++ binding + systems). `#5375 `_ -* Changed ``PYBIND11_MODULE`` macro implementation to perform multi-phase module initialization (PEP 489) behind the scenes. +* Changed ``PYBIND11_MODULE`` macro implementation to perform multi-phase + module initialization (PEP 489) behind the scenes. `#5574 `_ * Added support for finding pybind11 using pkgconf distributed on pypi. @@ -93,7 +109,8 @@ New Features (typing): * 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. +* 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). @@ -110,11 +127,34 @@ New Features (typing): * 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 `_ + + +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 `_ + `#5584 `_. Except on embedded modules. `#5650 `_ * pybind11-bound functions are now pickleable. `#5580 `_ @@ -156,6 +196,19 @@ Bug fixes: * Properly translate C++ exception to Python exception when creating Python buffer from wrapped object. `#5324 `_ +* 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 `_ + + .. fix(cmake) @@ -170,6 +223,15 @@ Bug fixes (CMake): * 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 `_ + Bug fixes (free-threading): @@ -184,6 +246,15 @@ Bug fixes (free-threading): * 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 `_ + Documentation: @@ -196,6 +267,8 @@ Documentation: * Adds an answer (FAQ) for "What is a highly conclusive and simple way to find memory leaks?". `#5340 `_ +* Add documenting for free-threading and subinterpreters. + `#5659 `_ Tests: @@ -209,9 +282,16 @@ compiling using ``clang`` on Linux with the ``-funsigned-char`` flag. * Test PyPy3.11 in CI. `#5534 `_ +* CI testing now includes ``-Wwrite-strings -Wunreachable-code -Wpointer-arith -Wredundant-decls`` in some jobs. + `#5523 `_ + New and removed platforms: + +* Support Python 3.14 (beta 1). + `#5646 `_ + * Added support for GraalPy Python implementation (https://github.com/oracle/graalpython). `#5380 `_ @@ -224,10 +304,11 @@ New and removed platforms: * 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-3.30 supported. +* Support for CMake older than 3.15 removed. CMake 3.15-4.0 supported. `#5304 `_ - +* 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_PREFIX`` has been removed. + `#5598 `_ Version 2.13.6 (September 13, 2024) ----------------------------------- diff --git a/tools/make_changelog.py b/tools/make_changelog.py index 2e2d9f40ca..efb2a23dc8 100755 --- a/tools/make_changelog.py +++ b/tools/make_changelog.py @@ -47,6 +47,7 @@ "tests": "Tests", "ci": "CI", "chore": "Other", + "chore(cmake)": "", "unknown": "Uncategorised", } cats: dict[str, list[str]] = {c: [] for c in cats_descr} From a5985a5baecc156c1f9e60a69943e21d7d09a13b Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sat, 17 May 2025 23:47:27 -0400 Subject: [PATCH 12/20] docs: fixes and set rc1 version Signed-off-by: Henry Schreiner --- docs/advanced/deprecated.rst | 5 +++++ docs/classes.rst | 2 +- docs/upgrade.rst | 2 +- include/pybind11/detail/common.h | 6 +++--- 4 files changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/advanced/deprecated.rst b/docs/advanced/deprecated.rst index 47710422bc..df974a301d 100644 --- a/docs/advanced/deprecated.rst +++ b/docs/advanced/deprecated.rst @@ -3,6 +3,11 @@ Deprecated ########## +Support for Python 3.8 is deprecated and will be removed in 3.1. + +Support for C++11 is deprecated and will be removed in a future version. Please +use at least C++14. + The following features were deprecated before pybind11 3.0, and may be removed in minor releases of pybind11 3.x. diff --git a/docs/classes.rst b/docs/classes.rst index b126256567..8788badcd5 100644 --- a/docs/classes.rst +++ b/docs/classes.rst @@ -642,7 +642,7 @@ As of Python 3.13, the compatible `types in the stdlib enum module template struct type_caster_enum_type_enabled< FancyEnum, - enable_if_t::value>> : std::false_type {}; + std::enable_if_t::value>> : std::false_type {}; } #endif diff --git a/docs/upgrade.rst b/docs/upgrade.rst index ca0fe188d5..9c8e88196e 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -25,7 +25,7 @@ cross-extension-module compatibility, it is recommended to rebuild all pybind11-based extensions with v3.0. CMake support now defaults to the modern FindPython module. If you haven't -moved, we do some some backward compatibility ``PYTHON_*`` variables, but +moved, we do some backward compatibility ``PYTHON_*`` variables, but please update to using ``Python_*`` variables (and setting ``PYTHON_*`` variables will not affect the build anymore). diff --git a/include/pybind11/detail/common.h b/include/pybind11/detail/common.h index e3df32df3e..1c9e8f57c4 100644 --- a/include/pybind11/detail/common.h +++ b/include/pybind11/detail/common.h @@ -16,11 +16,11 @@ #define PYBIND11_VERSION_MAJOR 3 #define PYBIND11_VERSION_MINOR 0 -#define PYBIND11_VERSION_PATCH 0.dev1 +#define PYBIND11_VERSION_PATCH 0.rc1 // Similar to Python's convention: https://docs.python.org/3/c-api/apiabiversion.html -// Additional convention: 0xD = dev -#define PYBIND11_VERSION_HEX 0x030000D1 +// Use 0xA0 for dev +#define PYBIND11_VERSION_HEX 0x030000C1 #include "pybind11_namespace_macros.h" From 0c76f7eace1f8175bf33f1910a0292ad43d8845b Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sun, 18 May 2025 00:26:55 -0400 Subject: [PATCH 13/20] fix: support rc versions Signed-off-by: Henry Schreiner --- include/pybind11/detail/common.h | 2 +- tests/extra_python_package/test_files.py | 15 ++++++++++----- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/include/pybind11/detail/common.h b/include/pybind11/detail/common.h index 1c9e8f57c4..a6f4b30c5b 100644 --- a/include/pybind11/detail/common.h +++ b/include/pybind11/detail/common.h @@ -16,7 +16,7 @@ #define PYBIND11_VERSION_MAJOR 3 #define PYBIND11_VERSION_MINOR 0 -#define PYBIND11_VERSION_PATCH 0.rc1 +#define PYBIND11_VERSION_PATCH 0rc1 // Similar to Python's convention: https://docs.python.org/3/c-api/apiabiversion.html // Use 0xA0 for dev diff --git a/tests/extra_python_package/test_files.py b/tests/extra_python_package/test_files.py index e72a76b9cd..2919cf3ea3 100644 --- a/tests/extra_python_package/test_files.py +++ b/tests/extra_python_package/test_files.py @@ -2,6 +2,7 @@ import contextlib import os +import re import shutil import subprocess import sys @@ -15,6 +16,7 @@ DIR = Path(__file__).parent.resolve() MAIN_DIR = DIR.parent.parent +FILENAME_VERSION = re.compile(r"[-_]((\d+\.\d+\.\d+)(?:[a-z]+\d*)?)(?:-|\.tar\.gz$)") # Newer pytest has global path setting, but keeping old pytest for now sys.path.append(str(MAIN_DIR / "tools")) @@ -184,7 +186,7 @@ def test_build_sdist(monkeypatch, tmpdir): ) (sdist,) = tmpdir.visit("*.tar.gz") - version = sdist.basename.split("-")[1][:-7] + version = FILENAME_VERSION.search(sdist.basename).group(1) with tarfile.open(str(sdist), "r:gz") as tar: simpler = {n.split("/", 1)[-1] for n in tar.getnames()[1:]} @@ -197,6 +199,7 @@ def test_build_sdist(monkeypatch, tmpdir): assert files <= simpler assert b'name = "pybind11"' in pyproject_toml + assert f"Version: {version}" in pkg_info assert "License-Expression: BSD-3-Clause" in pkg_info assert "License-File: LICENSE" in pkg_info assert "Provides-Extra: global" in pkg_info @@ -220,6 +223,7 @@ def test_build_global_dist(monkeypatch, tmpdir): ) (sdist,) = tmpdir.visit("*.tar.gz") + version = FILENAME_VERSION.search(sdist.basename).group(2) with tarfile.open(str(sdist), "r:gz") as tar: simpler = {n.split("/", 1)[-1] for n in tar.getnames()[1:]} @@ -232,6 +236,7 @@ def test_build_global_dist(monkeypatch, tmpdir): assert files <= simpler assert b'name = "pybind11-global"' in pyproject_toml + assert f"Version: {version}" in pkg_info assert "License-Expression: BSD-3-Clause" in pkg_info assert "License-File: LICENSE" in pkg_info assert "Provides-Extra: global" not in pkg_info @@ -247,6 +252,7 @@ def tests_build_wheel(monkeypatch, tmpdir): ) (wheel,) = tmpdir.visit("*.whl") + version, simple_version = FILENAME_VERSION.search(wheel.basename).groups() files = {f"pybind11/{n}" for n in all_files} files |= { @@ -274,11 +280,10 @@ def tests_build_wheel(monkeypatch, tmpdir): assert 'set(pybind11_INCLUDE_DIR "${PACKAGE_PREFIX_DIR}/include")' in cmakeconfig - version = wheel.basename.split("-")[1] - simple_version = ".".join(version.split(".")[:3]) pkgconfig_expected = PKGCONFIG.format(VERSION=simple_version) assert pkgconfig_expected == pkgconfig + assert f"Version: {version}" in pkg_info assert "License-Expression: BSD-3-Clause" in pkg_info assert "License-File: LICENSE" in pkg_info assert "Provides-Extra: global" in pkg_info @@ -302,6 +307,7 @@ def tests_build_global_wheel(monkeypatch, tmpdir): ) (wheel,) = tmpdir.visit("*.whl") + version, simple_version = FILENAME_VERSION.search(wheel.basename).groups() files = {f"data/data/{n}" for n in headers} files |= {f"data/headers/{n[8:]}" for n in headers} @@ -326,6 +332,7 @@ def tests_build_global_wheel(monkeypatch, tmpdir): (pkg_info_path,) = (n for n in names if n.endswith("METADATA")) pkg_info = zipfile.Path(z, pkg_info_path).read_text(encoding="utf-8") + assert f"Version: {version}" in pkg_info assert "License-Expression: BSD-3-Clause" in pkg_info assert "License-File: LICENSE" in pkg_info assert "Provides-Extra: global" not in pkg_info @@ -337,7 +344,5 @@ def tests_build_global_wheel(monkeypatch, tmpdir): assert 'set(pybind11_INCLUDE_DIR "${PACKAGE_PREFIX_DIR}/include")' in cmakeconfig - version = wheel.basename.split("-")[1] - simple_version = ".".join(version.split(".")[:3]) pkgconfig_expected = PKGCONFIG.format(VERSION=simple_version) assert pkgconfig_expected == pkgconfig From ee14885f07e018e7d94c01754f675700eca9131f Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Sat, 17 May 2025 23:05:44 -0700 Subject: [PATCH 14/20] Undo erroneous copilot change: We need to use `detail::enable_if_t`, for compatibility with C++11 and C++14. --- docs/classes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/classes.rst b/docs/classes.rst index 8788badcd5..b126256567 100644 --- a/docs/classes.rst +++ b/docs/classes.rst @@ -642,7 +642,7 @@ As of Python 3.13, the compatible `types in the stdlib enum module template struct type_caster_enum_type_enabled< FancyEnum, - std::enable_if_t::value>> : std::false_type {}; + enable_if_t::value>> : std::false_type {}; } #endif From 7c93ea61b5dad84bee5e64ba3e87c22d75825c54 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Sat, 17 May 2025 23:13:54 -0700 Subject: [PATCH 15/20] Empty lines cleanup. --- docs/changelog.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 38c9d194f2..f7cbec1e60 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -94,7 +94,6 @@ New Features (typing): ``pybind11::typing`` to use correct arg/return type hints for nested types. `#5450 `_ - * Updated type hint for ``py::capsule`` to ``type.CapsuleType``. `#5567 `_ @@ -141,7 +140,6 @@ Removals: `#5512 `_ | `#5530 `_ - * Remove ``make_simple_namespace`` (added in 2.8.0, deprecated in 2.8.1). `#5597 `_ @@ -151,6 +149,7 @@ Removals: * Add a deprecation warning to ``.get_type`` (deprecated in pybind11 2.6 in 2020). `#5596 `_ + Bug fixes: * Set ``__file__`` on submodules. @@ -209,7 +208,6 @@ Bug fixes: `#5620 `_ - .. fix(cmake) Bug fixes (CMake): @@ -288,7 +286,6 @@ compiling using ``clang`` on Linux with the ``-funsigned-char`` flag. New and removed platforms: - * Support Python 3.14 (beta 1). `#5646 `_ @@ -310,6 +307,7 @@ New and removed platforms: * 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_PREFIX`` has been removed. `#5598 `_ + Version 2.13.6 (September 13, 2024) ----------------------------------- From dc2e75f4966bc07802e14574916fae4bc532c4bf Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Sat, 17 May 2025 23:23:33 -0700 Subject: [PATCH 16/20] Rewording of "CMake support now defaults to ..." paragraph. --- docs/upgrade.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/upgrade.rst b/docs/upgrade.rst index 9c8e88196e..cedaf3126c 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -25,9 +25,9 @@ cross-extension-module compatibility, it is recommended to rebuild all pybind11-based extensions with v3.0. CMake support now defaults to the modern FindPython module. If you haven't -moved, we do some backward compatibility ``PYTHON_*`` variables, but -please update to using ``Python_*`` variables (and setting ``PYTHON_*`` -variables will not affect the build anymore). +updated yet, we provide some backward compatibility for ``PYTHON_*`` variables, +but you should switch to using ``Python_*`` variables instead. Note that +setting ``PYTHON_*`` variables no longer affects the build. A major new feature in this release is the integration of ``py::smart_holder``, which improves support for ``std::unique_ptr`` From b6f33e652195d9774903a7bd1a2b9a6dc88c4048 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Sat, 17 May 2025 23:31:46 -0700 Subject: [PATCH 17/20] [skip ci] Add missing backticks in upgrade guide. --- docs/upgrade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/upgrade.rst b/docs/upgrade.rst index cedaf3126c..62d1eaca98 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -47,12 +47,12 @@ Also new in v3.0 is ``py::native_enum``, a modern API for exposing C++ enumerations as native Python types — typically standard-library ``enum.Enum`` or related subclasses. This provides improved integration with Python's enum system, compared to the older (now deprecated) ``py::enum_``. -See #5555 _ for details. +See `#5555 `_ for details. Functions exposed with pybind11 are now pickleable. This removes a long-standing obstacle when using pybind11-bound functions with Python features that rely on pickling, such as multiprocessing and caching tools. -See #5580 _ for details. +See `#5580 `_ for details. Anything producing a deprecation warning in the 2.x series may be removed in a future minor release of 3.x. Most of these are still present in 3.0 in order to ease From 23f7f74978143533c5233f17d62a7f42496c51af Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Sat, 17 May 2025 23:38:20 -0700 Subject: [PATCH 18/20] [skip ci] Try :ref:deprecated instead of :doc:deprecated --- docs/upgrade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/upgrade.rst b/docs/upgrade.rst index 62d1eaca98..bd4a20ed0f 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -56,7 +56,7 @@ See `#5580 `_ for details. Anything producing a deprecation warning in the 2.x series may be removed in a future minor release of 3.x. Most of these are still present in 3.0 in order to ease -transition. The new :doc:`deprecated` page details deprecations. +transition. The new :ref:`deprecated` page details deprecations. Migration Recommendations ------------------------- From b7cd0a37773c3e52b24092e6baabea76139f3658 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sun, 18 May 2025 23:51:11 -0400 Subject: [PATCH 19/20] docs: last bit of polish Signed-off-by: Henry Schreiner --- docs/advanced/deprecated.rst | 4 ++++ docs/changelog.rst | 43 ++++++++++++++++++++++-------------- 2 files changed, 30 insertions(+), 17 deletions(-) diff --git a/docs/advanced/deprecated.rst b/docs/advanced/deprecated.rst index df974a301d..dc07a77b94 100644 --- a/docs/advanced/deprecated.rst +++ b/docs/advanced/deprecated.rst @@ -8,6 +8,10 @@ Support for Python 3.8 is deprecated and will be removed in 3.1. Support for C++11 is deprecated and will be removed in a future version. Please use at least C++14. +Support for FindPythonLibs (not available in CMake 3.26+ mode) is deprecated +and will be removed in a future version. The default mode is also going to +change to ``"new"`` from ``"compat"`` in the future. + The following features were deprecated before pybind11 3.0, and may be removed in minor releases of pybind11 3.x. diff --git a/docs/changelog.rst b/docs/changelog.rst index f7cbec1e60..d300fa303d 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -10,11 +10,11 @@ Changes will be added here periodically from the "Suggested changelog entry" block in pull request descriptions. -IN DEVELOPMENT (v3.0.0) ------------------------ - -Changes will be summarized here periodically. +3.0.0 RC 1 +---------- +We may add one more opt-in feature (embedded subinterperters) before the final +release. New Features: @@ -25,6 +25,10 @@ New Features: and ``std::enable_shared_from_this``. `#5542 `_ +* Changed ``PYBIND11_MODULE`` macro implementation to perform multi-phase + module initialization (PEP 489) behind the scenes. + `#5574 `_ + * 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, @@ -33,9 +37,11 @@ New Features: module supports running with sub-interpreters. `#5564 `_ -* (CMake) Enable FindPython mode by default, with a ``COMPAT`` mode that sets - some of the old variables to ease transition. - `#5553 `_ +* 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 `_ * ``py::native_enum`` was added, for conversions between Python's native (stdlib) enum types and C++ enums. `#5555 `_ @@ -74,20 +80,18 @@ New Features: systems). `#5375 `_ -* Changed ``PYBIND11_MODULE`` macro implementation to perform multi-phase - module initialization (PEP 489) behind the scenes. - `#5574 `_ - * 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 `_ -New Features (typing): -.. feat(types) +New Features (typing): * Added option for different arg/return type hints to ``type_caster``. Updated ``stl/filesystem`` to use correct arg/return type hints. Updated @@ -208,10 +212,12 @@ Bug fixes: `#5620 `_ -.. fix(cmake) - Bug fixes (CMake): +* (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 `_ @@ -230,10 +236,11 @@ Bug fixes (CMake): * Add support for running pybind11's tests via presets in CMake 3.25+. `#5655 `_ +* Restructure venv support to support ``--fresh``, make in build folder. + `#5668 `_ -Bug fixes (free-threading): -.. fix(free-threading) +Bug fixes (free-threading): * Fix data race in free threaded CPython when accessing a shared static variable. `#5494 `_ @@ -244,6 +251,7 @@ Bug fixes (free-threading): * 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 @@ -268,6 +276,7 @@ Documentation: * Add documenting for free-threading and subinterpreters. `#5659 `_ + Tests: * Download the final Catch2 2.x release if Catch download is requested. From b88e1154406f7f8699998511f86717e8677f4935 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Sun, 18 May 2025 21:38:54 -0700 Subject: [PATCH 20/20] [skip ci] Piggy-back trivial whitespace cleanup that was missed in PR #5669 --- docs/advanced/classes.rst | 2 +- tests/test_custom_type_setup.cpp | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced/classes.rst b/docs/advanced/classes.rst index a8c2da17b2..c1592bb20e 100644 --- a/docs/advanced/classes.rst +++ b/docs/advanced/classes.rst @@ -1384,7 +1384,7 @@ You can do that using ``py::custom_type_setup``: auto *type = &heap_type->ht_type; type->tp_flags |= Py_TPFLAGS_HAVE_GC; type->tp_traverse = [](PyObject *self_base, visitproc visit, void *arg) { - // https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse + // https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse #if PY_VERSION_HEX >= 0x03090000 Py_VISIT(Py_TYPE(self_base)); #endif diff --git a/tests/test_custom_type_setup.cpp b/tests/test_custom_type_setup.cpp index ef87ed484d..35d30abcf7 100644 --- a/tests/test_custom_type_setup.cpp +++ b/tests/test_custom_type_setup.cpp @@ -26,7 +26,7 @@ TEST_SUBMODULE(custom_type_setup, m) { auto *type = &heap_type->ht_type; type->tp_flags |= Py_TPFLAGS_HAVE_GC; type->tp_traverse = [](PyObject *self_base, visitproc visit, void *arg) { - // https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse +// https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse #if PY_VERSION_HEX >= 0x03090000 Py_VISIT(Py_TYPE(self_base)); #endif