Merge branch 'master' into sh_merge_master

Author: rwgk

.github/workflows/ci.yml

@@ -109,12 +109,15 @@ jobs:
       run: python -m pip install pytest-github-actions-annotate-failures
 
     # First build - C++11 mode and inplace
-    # More-or-less randomly adding -DPYBIND11_SIMPLE_GIL_MANAGEMENT=ON here.
+    # More-or-less randomly adding -DPYBIND11_SIMPLE_GIL_MANAGEMENT=ON here
+    # (same for PYBIND11_NUMPY_1_ONLY, but requires a NumPy 1.x at runtime).
     - name: Configure C++11 ${{ matrix.args }}
       run: >
         cmake -S . -B .
         -DPYBIND11_WERROR=ON
+        -DPYBIND11_DISABLE_HANDLE_TYPE_NAME_DEFAULT_IMPLEMENTATION=ON
         -DPYBIND11_SIMPLE_GIL_MANAGEMENT=ON
+        -DPYBIND11_NUMPY_1_ONLY=ON
         -DDOWNLOAD_CATCH=ON
         -DDOWNLOAD_EIGEN=ON
         -DCMAKE_CXX_STANDARD=11
@@ -139,11 +142,13 @@ jobs:
 
     # Second build - C++17 mode and in a build directory
     # More-or-less randomly adding -DPYBIND11_SIMPLE_GIL_MANAGEMENT=OFF here.
+    # (same for PYBIND11_NUMPY_1_ONLY, but requires a NumPy 1.x at runtime).
     - name: Configure C++17
       run: >
         cmake -S . -B build2
         -DPYBIND11_WERROR=ON
         -DPYBIND11_SIMPLE_GIL_MANAGEMENT=OFF
+        -DPYBIND11_NUMPY_1_ONLY=ON
         -DDOWNLOAD_CATCH=ON
         -DDOWNLOAD_EIGEN=ON
         -DCMAKE_CXX_STANDARD=17
@@ -661,6 +666,11 @@ jobs:
       run: |
         python3 -m pip install cmake -r tests/requirements.txt
 
+    - name: Ensure NumPy 2 is used (required Python >= 3.9)
+      if: matrix.container == 'almalinux:9'
+      run: |
+        python3 -m pip install 'numpy>=2.0.0b1' 'scipy>=1.13.0rc1'
+
     - name: Configure
       shell: bash
       run: >
@@ -896,8 +906,10 @@ jobs:
         python-version: ${{ matrix.python }}
 
     - name: Prepare env
+      # Ensure use of NumPy 2 (via NumPy nightlies but can be changed soon)
       run: |
         python3 -m pip install -r tests/requirements.txt
+        python3 -m pip install 'numpy>=2.0.0b1' 'scipy>=1.13.0rc1'
 
     - name: Update CMake
       uses: jwlawson/actions-setup-cmake@v2.0

.github/workflows/labeler.yml

@@ -14,7 +14,7 @@ jobs:
       pull-requests: write
     steps:
 
-    - uses: actions/labeler@main
+    - uses: actions/labeler@v4
       if: >
         github.event.pull_request.merged == true &&
         !startsWith(github.event.pull_request.title, 'chore(deps):') &&

CMakeLists.txt

@@ -107,15 +107,25 @@ endif()
 option(PYBIND11_INSTALL "Install pybind11 header files?" ${PYBIND11_MASTER_PROJECT})
 option(PYBIND11_TEST "Build pybind11 test suite?" ${PYBIND11_MASTER_PROJECT})
 option(PYBIND11_NOPYTHON "Disable search for Python" OFF)
+option(PYBIND11_DISABLE_HANDLE_TYPE_NAME_DEFAULT_IMPLEMENTATION
+       "To enforce that a handle_type_name<> specialization exists" OFF)
 option(PYBIND11_SIMPLE_GIL_MANAGEMENT
        "Use simpler GIL management logic that does not support disassociation" OFF)
+option(PYBIND11_NUMPY_1_ONLY
+       "Disable NumPy 2 support to avoid changes to previous pybind11 versions." OFF)
 set(PYBIND11_INTERNALS_VERSION
     ""
     CACHE STRING "Override the ABI version, may be used to enable the unstable ABI.")
 
+if(PYBIND11_DISABLE_HANDLE_TYPE_NAME_DEFAULT_IMPLEMENTATION)
+  add_compile_definitions(PYBIND11_DISABLE_HANDLE_TYPE_NAME_DEFAULT_IMPLEMENTATION)
+endif()
 if(PYBIND11_SIMPLE_GIL_MANAGEMENT)
   add_compile_definitions(PYBIND11_SIMPLE_GIL_MANAGEMENT)
 endif()
+if(PYBIND11_NUMPY_1_ONLY)
+  add_compile_definitions(PYBIND11_NUMPY_1_ONLY)
+endif()
 
 cmake_dependent_option(
   USE_PYTHON_INCLUDE_DIR

README.rst

@@ -40,10 +40,10 @@ with everything stripped away that isn't relevant for binding
 generation. Without comments, the core header files only require ~4K
 lines of code and depend on Python (3.6+, or PyPy) and the C++
 standard library. This compact implementation was possible thanks to
-some of the new C++11 language features (specifically: tuples, lambda
-functions and variadic templates). Since its creation, this library has
-grown beyond Boost.Python in many ways, leading to dramatically simpler
-binding code in many common situations.
+some C++11 language features (specifically: tuples, lambda functions and
+variadic templates). Since its creation, this library has grown beyond
+Boost.Python in many ways, leading to dramatically simpler binding code in many
+common situations.
 
 Tutorial and reference documentation is provided at
 `pybind11.readthedocs.io <https://pybind11.readthedocs.io/en/latest>`_.
@@ -75,6 +75,7 @@ pybind11 can map the following core C++ features to Python:
 - Internal references with correct reference counting
 - C++ classes with virtual (and pure virtual) methods can be extended
   in Python
+- Integrated NumPy support (NumPy 2 requires pybind11 2.12+)
 
 Goodies
 -------

docs/changelog.rst

@@ -15,9 +15,183 @@ IN DEVELOPMENT
 
 Changes will be summarized here periodically.
 
+Version 2.12.0 (March 27, 2025)
+-------------------------------
+
+New Features:
+
+* ``pybind11`` now supports compiling for
+  `NumPy 2 <https://numpy.org/devdocs/numpy_2_0_migration_guide.html>`_. Most
+  code shouldn't change (see :ref:`upgrade-guide-2.12` for details). However,
+  if you experience issues you can define ``PYBIND11_NUMPY_1_ONLY`` to disable
+  the new support for now, but this will be removed in the future.
+  `#5050 <https://github.com/pybind/pybind11/pull/5050>`_
+
+* ``pybind11/gil_safe_call_once.h`` was added (it needs to be included
+  explicitly). The primary use case is GIL-safe initialization of C++
+  ``static`` variables.
+  `#4877 <https://github.com/pybind/pybind11/pull/4877>`_
+
+* Support move-only iterators in ``py::make_iterator``,
+  ``py::make_key_iterator``, ``py::make_value_iterator``.
+  `#4834 <https://github.com/pybind/pybind11/pull/4834>`_
+
+* Two simple ``py::set_error()`` functions were added and the documentation was
+  updated accordingly. In particular, ``py::exception<>::operator()`` was
+  deprecated (use one of the new functions instead). The documentation for
+  ``py::exception<>`` was further updated to not suggest code that may result
+  in undefined behavior.
+  `#4772 <https://github.com/pybind/pybind11/pull/4772>`_
+
+Bug fixes:
+
+* Removes potential for Undefined Behavior during process teardown.
+  `#4897 <https://github.com/pybind/pybind11/pull/4897>`_
+
+* Improve compatibility with the nvcc compiler (especially CUDA 12.1/12.2).
+  `#4893 <https://github.com/pybind/pybind11/pull/4893>`_
+
+* ``pybind11/numpy.h`` now imports NumPy's ``multiarray`` and ``_internal``
+  submodules with paths depending on the installed version of NumPy (for
+  compatibility with NumPy 2).
+  `#4857 <https://github.com/pybind/pybind11/pull/4857>`_
+
+* Builtins collections names in docstrings are now consistently rendered in
+  lowercase (list, set, dict, tuple), in accordance with PEP 585.
+  `#4833 <https://github.com/pybind/pybind11/pull/4833>`_
+
+* Added ``py::typing::Iterator<T>``, ``py::typing::Iterable<T>``.
+  `#4832 <https://github.com/pybind/pybind11/pull/4832>`_
+
+* Render ``py::function`` as ``Callable`` in docstring.
+  `#4829 <https://github.com/pybind/pybind11/pull/4829>`_
+
+* Also bump ``PYBIND11_INTERNALS_VERSION`` for MSVC, which unlocks two new
+  features without creating additional incompatibilities.
+  `#4819 <https://github.com/pybind/pybind11/pull/4819>`_
+
+* Guard against crashes/corruptions caused by modules built with different MSVC
+  versions.
+  `#4779 <https://github.com/pybind/pybind11/pull/4779>`_
+
+* A long-standing bug in the handling of Python multiple inheritance was fixed.
+  See PR #4762 for the rather complex details.
+  `#4762 <https://github.com/pybind/pybind11/pull/4762>`_
+
+* Fix ``bind_map`` with ``using`` declarations.
+  `#4952 <https://github.com/pybind/pybind11/pull/4952>`_
+
+* Qualify ``py::detail::concat`` usage to avoid ADL selecting one from
+  somewhere else, such as modernjson's concat.
+  `#4955 <https://github.com/pybind/pybind11/pull/4955>`_
+
+* Use new PyCode API on Python 3.12+.
+  `#4916 <https://github.com/pybind/pybind11/pull/4916>`_
+
+* Minor cleanup from warnings reported by Clazy.
+  `#4988 <https://github.com/pybind/pybind11/pull/4988>`_
+
+* Remove typing and duplicate ``class_`` for ``KeysView``/``ValuesView``/``ItemsView``.
+  `#4985 <https://github.com/pybind/pybind11/pull/4985>`_
+
+* Use ``PyObject_VisitManagedDict()`` and ``PyObject_ClearManagedDict()`` on Python 3.13 and newer.
+  `#4973 <https://github.com/pybind/pybind11/pull/4973>`_
+
+* Update ``make_static_property_type()`` to make it compatible with Python 3.13.
+  `#4971 <https://github.com/pybind/pybind11/pull/4971>`_
+
+.. fix(types)
+
+* Render typed iterators for ``make_iterator``, ``make_key_iterator``,
+  ``make_value_iterator``.
+  `#4876 <https://github.com/pybind/pybind11/pull/4876>`_
+
+* Add several missing type name specializations.
+  `#5073 <https://github.com/pybind/pybind11/pull/5073>`_
+
+* Change docstring render for ``py::buffer``, ``py::sequence`` and
+  ``py::handle`` (to ``Buffer``, ``Sequence``, ``Any``).
+  `#4831 <https://github.com/pybind/pybind11/pull/4831>`_
+
+* Fixed ``base_enum.__str__`` docstring.
+  `#4827 <https://github.com/pybind/pybind11/pull/4827>`_
+
+* Enforce single line docstring signatures.
+  `#4735 <https://github.com/pybind/pybind11/pull/4735>`_
+
+* Special 'typed' wrappers now available in ``typing.h`` to annotate tuple, dict,
+  list, set, and function.
+  `#4259 <https://github.com/pybind/pybind11/pull/4259>`_
+
+* Create ``handle_type_name`` specialization to type-hint variable length tuples.
+  `#5051 <https://github.com/pybind/pybind11/pull/5051>`_
+
+.. fix(build)
+
+* Setting ``PYBIND11_FINDPYTHON`` to OFF will force the old FindPythonLibs mechanism to be used.
+  `#5042 <https://github.com/pybind/pybind11/pull/5042>`_
+
+* Skip empty ``PYBIND11_PYTHON_EXECUTABLE_LAST`` for the first cmake run.
+  `#4856 <https://github.com/pybind/pybind11/pull/4856>`_
+
+* Fix FindPython mode exports & avoid ``pkg_resources`` if
+  ``importlib.metadata`` available.
+  `#4941 <https://github.com/pybind/pybind11/pull/4941>`_
+
+* ``Python_ADDITIONAL_VERSIONS`` (classic search) now includes 3.12.
+  `#4909 <https://github.com/pybind/pybind11/pull/4909>`_
+
+* ``pybind11.pc`` is now relocatable by default as long as install destinations
+  are not absolute paths.
+  `#4830 <https://github.com/pybind/pybind11/pull/4830>`_
+
+* Correctly detect CMake FindPython removal when used as a subdirectory.
+  `#4806 <https://github.com/pybind/pybind11/pull/4806>`_
+
+* Don't require the libs component on CMake 3.18+ when using
+  PYBIND11_FINDPYTHON (fixes manylinux builds).
+  `#4805 <https://github.com/pybind/pybind11/pull/4805>`_
+
+* ``pybind11_strip`` is no longer automatically applied when
+  ``CMAKE_BUILD_TYPE`` is unset.
+  `#4780 <https://github.com/pybind/pybind11/pull/4780>`_
+
+* Support ``DEBUG_POSFIX`` correctly for debug builds.
+  `#4761 <https://github.com/pybind/pybind11/pull/4761>`_
+
+* Hardcode lto/thin lto for Emscripten cross-compiles.
+  `#4642 <https://github.com/pybind/pybind11/pull/4642>`_
+
+* Upgrade maximum supported CMake version to 3.27 to fix CMP0148 warnings.
+  `#4786 <https://github.com/pybind/pybind11/pull/4786>`_
+
+Documentation:
+
+* Small fix to grammar in ``functions.rst``.
+  `#4791 <https://github.com/pybind/pybind11/pull/4791>`_
+
+* Remove upper bound in example pyproject.toml for setuptools.
+  `#4774 <https://github.com/pybind/pybind11/pull/4774>`_
+
+CI:
+
+* CI: Update NVHPC to 23.5 and Ubuntu 20.04.
+  `#4764 <https://github.com/pybind/pybind11/pull/4764>`_
+
+* Test on PyPy 3.10.
+  `#4714 <https://github.com/pybind/pybind11/pull/4714>`_
+
+Other:
+
+* Use Ruff formatter instead of Black.
+  `#4912 <https://github.com/pybind/pybind11/pull/4912>`_
+
+* An ``assert()`` was added to help Coverty avoid generating a false positive.
+  `#4817 <https://github.com/pybind/pybind11/pull/4817>`_
+
 
 Version 2.11.1 (July 17, 2023)
------------------------------
+------------------------------
 
 Changes:
 
@@ -32,7 +206,7 @@ Changes:
 
 
 Version 2.11.0 (July 14, 2023)
------------------------------
+------------------------------
 
 New features:
 

docs/release.rst

@@ -36,19 +36,19 @@ If you don't have nox, you should either use ``pipx run nox`` instead, or use
 
   - Run ``nox -s tests_packaging`` to ensure this was done correctly.
 
-  - Ensure that all the information in ``setup.cfg`` is up-to-date, like
+- Ensure that all the information in ``setup.cfg`` is up-to-date, like
     supported Python versions.
 
-  - Add release date in ``docs/changelog.rst`` and integrate the output of
-    ``nox -s make_changelog``.
+- Add release date in ``docs/changelog.rst`` and integrate the output of
+  ``nox -s make_changelog``.
 
-    - Note that the ``make_changelog`` command inspects
-      `needs changelog <https://github.com/pybind/pybind11/pulls?q=is%3Apr+is%3Aclosed+label%3A%22needs+changelog%22>`_.
+  - Note that the ``nox -s make_changelog`` command inspects
+    `needs changelog <https://github.com/pybind/pybind11/pulls?q=is%3Apr+is%3Aclosed+label%3A%22needs+changelog%22>`_.
 
-    - Manually clear the ``needs changelog`` labels using the GitHub web
-      interface (very easy: start by clicking the link above).
+  - Manually clear the ``needs changelog`` labels using the GitHub web
+    interface (very easy: start by clicking the link above).
 
-  - ``git add`` and ``git commit``, ``git push``. **Ensure CI passes**. (If it
+- ``git add`` and ``git commit``, ``git push``. **Ensure CI passes**. (If it
     fails due to a known flake issue, either ignore or restart CI.)
 
 - Add a release branch if this is a new MINOR version, or update the existing

docs/upgrade.rst

@@ -8,6 +8,34 @@ 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-2.12:
+
+v2.12
+=====
+
+NumPy support has been upgraded to support the 2.x series too. The two relevant
+changes are that:
+
+* ``dtype.flags()`` is now a ``uint64`` and ``dtype.alignment()`` an
+  ``ssize_t`` (and NumPy may return an larger than integer value for
+  ``itemsize()`` in NumPy 2.x).
+
+* The long deprecated NumPy function ``PyArray_GetArrayParamsFromObject``
+  function is not available anymore.
+
+Due to NumPy changes, you may experience difficulties updating to NumPy 2.
+Please see the [NumPy 2 migration guide](https://numpy.org/devdocs/numpy_2_0_migration_guide.html) for details.
+For example, a more direct change could be that the default integer ``"int_"``
+(and ``"uint"``) is now ``ssize_t`` and not ``long`` (affects 64bit windows).
+
+If you want to only support NumPy 1.x for now and are having problems due to
+the two internal changes listed above, you can define
+``PYBIND11_NUMPY_1_ONLY`` to disable the new support for now. Make sure you
+define this on all pybind11 compile units, since it could be a source of ODR
+violations if used inconsistently. This option will be removed in the future,
+so adapting your code is highly recommended.
+
+
 .. _upgrade-guide-2.11:
 
 v2.11