diff --git a/wrap/cmake/PybindWrap.cmake b/wrap/cmake/PybindWrap.cmake
index 3091e42735..85f956d50b 100644
--- a/wrap/cmake/PybindWrap.cmake
+++ b/wrap/cmake/PybindWrap.cmake
@@ -27,15 +27,24 @@ set(PYBIND11_PYTHON_VERSION ${WRAP_PYTHON_VERSION})
add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/../pybind11 pybind11)
-# User-friendly Pybind11 wrapping and installing function. Builds a Pybind11
-# module from the provided interface_header. For example, for the interface
-# header gtsam.h, this will build the wrap module 'gtsam_py.cc'.
+# User-friendly Pybind11 wrapping and installing function.
+# Builds a Pybind11 module from the provided interface_header.
+# For example, for the interface header gtsam.h, this will
+# build the wrap module 'gtsam_py.cc'.
#
# Arguments:
# ~~~
+# target: The Make target
# interface_header: The relative path to the wrapper interface definition file.
-# install_path: destination to install the library libs: libraries to link with
-# dependencies: Dependencies which need to be built before the wrapper
+# generated_cpp: The name of the cpp file which is generated from the tpl file.
+# module_name: The name of the Python module to use.
+# top_namespace: The C++ namespace under which the code to be wrapped exists.
+# ignore_classes: CMake list of classes to ignore from wrapping.
+# install_path: Destination to install the library.
+# module_template: The template file (.tpl) from which to generate the Pybind11 module.
+# libs: Libraries to link with.
+# dependencies: Dependencies which need to be built before the wrapper.
+# use_boost (optional): Flag indicating whether to include Boost.
function(pybind_wrap
target
interface_header
diff --git a/wrap/pybind11/.appveyor.yml b/wrap/pybind11/.appveyor.yml
index 8fbb726108..149a8a3dc9 100644
--- a/wrap/pybind11/.appveyor.yml
+++ b/wrap/pybind11/.appveyor.yml
@@ -1,64 +1,32 @@
version: 1.0.{build}
image:
-- Visual Studio 2017
- Visual Studio 2015
test: off
skip_branch_with_pr: true
build:
parallel: true
platform:
-- x64
- x86
environment:
matrix:
- PYTHON: 36
- CPP: 14
CONFIG: Debug
- PYTHON: 27
- CPP: 14
CONFIG: Debug
- - CONDA: 36
- CPP: latest
- CONFIG: Release
-matrix:
- exclude:
- - image: Visual Studio 2015
- platform: x86
- - image: Visual Studio 2015
- CPP: latest
- - image: Visual Studio 2017
- CPP: latest
- platform: x86
install:
- ps: |
- if ($env:PLATFORM -eq "x64") { $env:CMAKE_ARCH = "x64" }
- if ($env:APPVEYOR_JOB_NAME -like "*Visual Studio 2017*") {
- $env:CMAKE_GENERATOR = "Visual Studio 15 2017"
- $env:CMAKE_INCLUDE_PATH = "C:\Libraries\boost_1_64_0"
- $env:CXXFLAGS = "-permissive-"
- } else {
- $env:CMAKE_GENERATOR = "Visual Studio 14 2015"
- }
- if ($env:PYTHON) {
- if ($env:PLATFORM -eq "x64") { $env:PYTHON = "$env:PYTHON-x64" }
- $env:PATH = "C:\Python$env:PYTHON\;C:\Python$env:PYTHON\Scripts\;$env:PATH"
- python -W ignore -m pip install --upgrade pip wheel
- python -W ignore -m pip install pytest numpy --no-warn-script-location
- } elseif ($env:CONDA) {
- if ($env:CONDA -eq "27") { $env:CONDA = "" }
- if ($env:PLATFORM -eq "x64") { $env:CONDA = "$env:CONDA-x64" }
- $env:PATH = "C:\Miniconda$env:CONDA\;C:\Miniconda$env:CONDA\Scripts\;$env:PATH"
- $env:PYTHONHOME = "C:\Miniconda$env:CONDA"
- conda --version
- conda install -y -q pytest numpy scipy
- }
+ $env:CMAKE_GENERATOR = "Visual Studio 14 2015"
+ if ($env:PLATFORM -eq "x64") { $env:PYTHON = "$env:PYTHON-x64" }
+ $env:PATH = "C:\Python$env:PYTHON\;C:\Python$env:PYTHON\Scripts\;$env:PATH"
+ python -W ignore -m pip install --upgrade pip wheel
+ python -W ignore -m pip install pytest numpy --no-warn-script-location
- ps: |
- Start-FileDownload 'http://bitbucket.org/eigen/eigen/get/3.3.3.zip'
- 7z x 3.3.3.zip -y > $null
- $env:CMAKE_INCLUDE_PATH = "eigen-eigen-67e894c6cd8f;$env:CMAKE_INCLUDE_PATH"
+ Start-FileDownload 'https://gitlab.com/libeigen/eigen/-/archive/3.3.7/eigen-3.3.7.zip'
+ 7z x eigen-3.3.7.zip -y > $null
+ $env:CMAKE_INCLUDE_PATH = "eigen-3.3.7;$env:CMAKE_INCLUDE_PATH"
build_script:
- cmake -G "%CMAKE_GENERATOR%" -A "%CMAKE_ARCH%"
- -DPYBIND11_CPP_STANDARD=/std:c++%CPP%
+ -DCMAKE_CXX_STANDARD=14
-DPYBIND11_WERROR=ON
-DDOWNLOAD_CATCH=ON
-DCMAKE_SUPPRESS_REGENERATION=1
@@ -66,5 +34,4 @@ build_script:
- set MSBuildLogger="C:\Program Files\AppVeyor\BuildAgent\Appveyor.MSBuildLogger.dll"
- cmake --build . --config %CONFIG% --target pytest -- /m /v:m /logger:%MSBuildLogger%
- cmake --build . --config %CONFIG% --target cpptest -- /m /v:m /logger:%MSBuildLogger%
-- if "%CPP%"=="latest" (cmake --build . --config %CONFIG% --target test_cmake_build -- /m /v:m /logger:%MSBuildLogger%)
on_failure: if exist "tests\test_cmake_build" type tests\test_cmake_build\*.log*
diff --git a/wrap/pybind11/.clang-tidy b/wrap/pybind11/.clang-tidy
new file mode 100644
index 0000000000..e29d929897
--- /dev/null
+++ b/wrap/pybind11/.clang-tidy
@@ -0,0 +1,13 @@
+FormatStyle: file
+
+Checks: '
+llvm-namespace-comment,
+modernize-use-override,
+readability-container-size-empty,
+modernize-use-using,
+modernize-use-equals-default,
+modernize-use-auto,
+modernize-use-emplace,
+'
+
+HeaderFilterRegex: 'pybind11/.*h'
diff --git a/wrap/pybind11/.cmake-format.yaml b/wrap/pybind11/.cmake-format.yaml
new file mode 100644
index 0000000000..a2a69f3f89
--- /dev/null
+++ b/wrap/pybind11/.cmake-format.yaml
@@ -0,0 +1,73 @@
+parse:
+ additional_commands:
+ pybind11_add_module:
+ flags:
+ - THIN_LTO
+ - MODULE
+ - SHARED
+ - NO_EXTRAS
+ - EXCLUDE_FROM_ALL
+ - SYSTEM
+
+format:
+ line_width: 99
+ tab_size: 2
+
+ # If an argument group contains more than this many sub-groups
+ # (parg or kwarg groups) then force it to a vertical layout.
+ max_subgroups_hwrap: 2
+
+ # If a positional argument group contains more than this many
+ # arguments, then force it to a vertical layout.
+ max_pargs_hwrap: 6
+
+ # If a cmdline positional group consumes more than this many
+ # lines without nesting, then invalidate the layout (and nest)
+ max_rows_cmdline: 2
+ separate_ctrl_name_with_space: false
+ separate_fn_name_with_space: false
+ dangle_parens: false
+
+ # If the trailing parenthesis must be 'dangled' on its on
+ # 'line, then align it to this reference: `prefix`: the start'
+ # 'of the statement, `prefix-indent`: the start of the'
+ # 'statement, plus one indentation level, `child`: align to'
+ # the column of the arguments
+ dangle_align: prefix
+ # If the statement spelling length (including space and
+ # parenthesis) is smaller than this amount, then force reject
+ # nested layouts.
+ min_prefix_chars: 4
+
+ # If the statement spelling length (including space and
+ # parenthesis) is larger than the tab width by more than this
+ # amount, then force reject un-nested layouts.
+ max_prefix_chars: 10
+
+ # If a candidate layout is wrapped horizontally but it exceeds
+ # this many lines, then reject the layout.
+ max_lines_hwrap: 2
+
+ line_ending: unix
+
+ # Format command names consistently as 'lower' or 'upper' case
+ command_case: canonical
+
+ # Format keywords consistently as 'lower' or 'upper' case
+ # unchanged is valid too
+ keyword_case: 'upper'
+
+ # A list of command names which should always be wrapped
+ always_wrap: []
+
+ # If true, the argument lists which are known to be sortable
+ # will be sorted lexicographically
+ enable_sort: true
+
+ # If true, the parsers may infer whether or not an argument
+ # list is sortable (without annotation).
+ autosort: false
+
+# Causes a few issues - can be solved later, possibly.
+markup:
+ enable_markup: false
diff --git a/wrap/pybind11/.github/CONTRIBUTING.md b/wrap/pybind11/.github/CONTRIBUTING.md
new file mode 100644
index 0000000000..4ced21baaa
--- /dev/null
+++ b/wrap/pybind11/.github/CONTRIBUTING.md
@@ -0,0 +1,319 @@
+Thank you for your interest in this project! Please refer to the following
+sections on how to contribute code and bug reports.
+
+### Reporting bugs
+
+Before submitting a question or bug report, please take a moment of your time
+and ensure that your issue isn't already discussed in the project documentation
+provided at [pybind11.readthedocs.org][] or in the [issue tracker][]. You can
+also check [gitter][] to see if it came up before.
+
+Assuming that you have identified a previously unknown problem or an important
+question, it's essential that you submit a self-contained and minimal piece of
+code that reproduces the problem. In other words: no external dependencies,
+isolate the function(s) that cause breakage, submit matched and complete C++
+and Python snippets that can be easily compiled and run in isolation; or
+ideally make a small PR with a failing test case that can be used as a starting
+point.
+
+## Pull requests
+
+Contributions are submitted, reviewed, and accepted using GitHub pull requests.
+Please refer to [this article][using pull requests] for details and adhere to
+the following rules to make the process as smooth as possible:
+
+* Make a new branch for every feature you're working on.
+* Make small and clean pull requests that are easy to review but make sure they
+ do add value by themselves.
+* Add tests for any new functionality and run the test suite (`cmake --build
+ build --target pytest`) to ensure that no existing features break.
+* Please run [`pre-commit`][pre-commit] to check your code matches the
+ project style. (Note that `gawk` is required.) Use `pre-commit run
+ --all-files` before committing (or use installed-mode, check pre-commit docs)
+ to verify your code passes before pushing to save time.
+* This project has a strong focus on providing general solutions using a
+ minimal amount of code, thus small pull requests are greatly preferred.
+
+### Licensing of contributions
+
+pybind11 is provided under a BSD-style license that can be found in the
+``LICENSE`` file. By using, distributing, or contributing to this project, you
+agree to the terms and conditions of this license.
+
+You are under no obligation whatsoever to provide any bug fixes, patches, or
+upgrades to the features, functionality or performance of the source code
+("Enhancements") to anyone; however, if you choose to make your Enhancements
+available either publicly, or directly to the author of this software, without
+imposing a separate written license agreement for such Enhancements, then you
+hereby grant the following license: a non-exclusive, royalty-free perpetual
+license to install, use, modify, prepare derivative works, incorporate into
+other computer software, distribute, and sublicense such enhancements or
+derivative works thereof, in binary and source code form.
+
+
+## Development of pybind11
+
+To setup an ideal development environment, run the following commands on a
+system with CMake 3.14+:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -r tests/requirements.txt
+cmake -S . -B build -DDOWNLOAD_CATCH=ON -DDOWNLOAD_EIGEN=ON
+cmake --build build -j4
+```
+
+Tips:
+
+* You can use `virtualenv` (from PyPI) instead of `venv` (which is Python 3
+ only).
+* You can select any name for your environment folder; if it contains "env" it
+ will be ignored by git.
+* If you don’t have CMake 3.14+, just add “cmake” to the pip install command.
+* You can use `-DPYBIND11_FINDPYTHON=ON` to use FindPython on CMake 3.12+
+* In classic mode, you may need to set `-DPYTHON_EXECUTABLE=/path/to/python`.
+ FindPython uses `-DPython_ROOT_DIR=/path/to` or
+ `-DPython_EXECUTABLE=/path/to/python`.
+
+### Configuration options
+
+In CMake, configuration options are given with “-D”. Options are stored in the
+build directory, in the `CMakeCache.txt` file, so they are remembered for each
+build directory. Two selections are special - the generator, given with `-G`,
+and the compiler, which is selected based on environment variables `CXX` and
+similar, or `-DCMAKE_CXX_COMPILER=`. Unlike the others, these cannot be changed
+after the initial run.
+
+The valid options are:
+
+* `-DCMAKE_BUILD_TYPE`: Release, Debug, MinSizeRel, RelWithDebInfo
+* `-DPYBIND11_FINDPYTHON=ON`: Use CMake 3.12+’s FindPython instead of the
+ classic, deprecated, custom FindPythonLibs
+* `-DPYBIND11_NOPYTHON=ON`: Disable all Python searching (disables tests)
+* `-DBUILD_TESTING=ON`: Enable the tests
+* `-DDOWNLOAD_CATCH=ON`: Download catch to build the C++ tests
+* `-DOWNLOAD_EIGEN=ON`: Download Eigen for the NumPy tests
+* `-DPYBIND11_INSTALL=ON/OFF`: Enable the install target (on by default for the
+ master project)
+* `-DUSE_PYTHON_INSTALL_DIR=ON`: Try to install into the python dir
+
+
+A few standard CMake tricks: (click to expand)
+
+* Use `cmake --build build -v` to see the commands used to build the files.
+* Use `cmake build -LH` to list the CMake options with help.
+* Use `ccmake` if available to see a curses (terminal) gui, or `cmake-gui` for
+ a completely graphical interface (not present in the PyPI package).
+* Use `cmake --build build -j12` to build with 12 cores (for example).
+* Use `-G` and the name of a generator to use something different. `cmake
+ --help` lists the generators available.
+ - On Unix, setting `CMAKE_GENERATER=Ninja` in your environment will give
+ you automatic mulithreading on all your CMake projects!
+* Open the `CMakeLists.txt` with QtCreator to generate for that IDE.
+* You can use `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` to generate the `.json` file
+ that some tools expect.
+
+
PREPEND
+# But we can't use it yet
+string(REPLACE "include/" "${CMAKE_CURRENT_SOURCE_DIR}/include/" PYBIND11_HEADERS
+ "${PYBIND11_HEADERS}")
-# extract project version from source
-file(STRINGS "${PYBIND11_INCLUDE_DIR}/pybind11/detail/common.h" pybind11_version_defines
- REGEX "#define PYBIND11_VERSION_(MAJOR|MINOR|PATCH) ")
-foreach(ver ${pybind11_version_defines})
- if (ver MATCHES "#define PYBIND11_VERSION_(MAJOR|MINOR|PATCH) +([^ ]+)$")
- set(PYBIND11_VERSION_${CMAKE_MATCH_1} "${CMAKE_MATCH_2}" CACHE INTERNAL "")
- endif()
-endforeach()
-set(${PROJECT_NAME}_VERSION ${PYBIND11_VERSION_MAJOR}.${PYBIND11_VERSION_MINOR}.${PYBIND11_VERSION_PATCH})
-message(STATUS "pybind11 v${${PROJECT_NAME}_VERSION}")
+# Cache variables so pybind11_add_module can be used in parent projects
+set(PYBIND11_INCLUDE_DIR
+ "${CMAKE_CURRENT_LIST_DIR}/include"
+ CACHE INTERNAL "")
+
+# Note: when creating targets, you cannot use if statements at configure time -
+# you need generator expressions, because those will be placed in the target file.
+# You can also place ifs *in* the Config.in, but not here.
+
+# This section builds targets, but does *not* touch Python
+
+# Build the headers-only target (no Python included):
+# (long name used here to keep this from clashing in subdirectory mode)
+add_library(pybind11_headers INTERFACE)
+add_library(pybind11::pybind11_headers ALIAS pybind11_headers) # to match exported target
+add_library(pybind11::headers ALIAS pybind11_headers) # easier to use/remember
-option (USE_PYTHON_INCLUDE_DIR "Install pybind11 headers in Python include directory instead of default installation prefix" OFF)
-if (USE_PYTHON_INCLUDE_DIR)
- file(RELATIVE_PATH CMAKE_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_PREFIX} ${PYTHON_INCLUDE_DIRS})
+include("${CMAKE_CURRENT_SOURCE_DIR}/tools/pybind11Common.cmake")
+
+# Relative directory setting
+if(USE_PYTHON_INCLUDE_DIR AND DEFINED Python_INCLUDE_DIRS)
+ file(RELATIVE_PATH CMAKE_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_PREFIX} ${Python_INCLUDE_DIRS})
+elseif(USE_PYTHON_INCLUDE_DIR AND DEFINED PYTHON_INCLUDE_DIR)
+ file(RELATIVE_PATH CMAKE_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_PREFIX} ${PYTHON_INCLUDE_DIRS})
endif()
-if(NOT (CMAKE_VERSION VERSION_LESS 3.0)) # CMake >= 3.0
- # Build an interface library target:
- add_library(pybind11 INTERFACE)
- add_library(pybind11::pybind11 ALIAS pybind11) # to match exported target
- target_include_directories(pybind11 INTERFACE $
- $
+# Fill in headers target
+target_include_directories(
+ pybind11_headers ${pybind11_system} INTERFACE $
$)
- target_compile_options(pybind11 INTERFACE $)
- add_library(module INTERFACE)
- add_library(pybind11::module ALIAS module)
- if(NOT MSVC)
- target_compile_options(module INTERFACE -fvisibility=hidden)
+target_compile_features(pybind11_headers INTERFACE cxx_inheriting_constructors cxx_user_literals
+ cxx_right_angle_brackets)
+
+if(PYBIND11_INSTALL)
+ install(DIRECTORY ${PYBIND11_INCLUDE_DIR}/pybind11 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+ # GNUInstallDirs "DATADIR" wrong here; CMake search path wants "share".
+ set(PYBIND11_CMAKECONFIG_INSTALL_DIR
+ "share/cmake/${PROJECT_NAME}"
+ CACHE STRING "install path for pybind11Config.cmake")
+
+ configure_package_config_file(
+ tools/${PROJECT_NAME}Config.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake"
+ INSTALL_DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})
+
+ if(CMAKE_VERSION VERSION_LESS 3.14)
+ # Remove CMAKE_SIZEOF_VOID_P from ConfigVersion.cmake since the library does
+ # not depend on architecture specific settings or libraries.
+ set(_PYBIND11_CMAKE_SIZEOF_VOID_P ${CMAKE_SIZEOF_VOID_P})
+ unset(CMAKE_SIZEOF_VOID_P)
+
+ write_basic_package_version_file(
+ ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
+ VERSION ${PROJECT_VERSION}
+ COMPATIBILITY AnyNewerVersion)
+
+ set(CMAKE_SIZEOF_VOID_P ${_PYBIND11_CMAKE_SIZEOF_VOID_P})
+ else()
+ # CMake 3.14+ natively supports header-only libraries
+ write_basic_package_version_file(
+ ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
+ VERSION ${PROJECT_VERSION}
+ COMPATIBILITY AnyNewerVersion ARCH_INDEPENDENT)
endif()
- target_link_libraries(module INTERFACE pybind11::pybind11)
- if(WIN32 OR CYGWIN)
- target_link_libraries(module INTERFACE $)
- elseif(APPLE)
- target_link_libraries(module INTERFACE "-undefined dynamic_lookup")
+
+ install(
+ FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake
+ ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
+ tools/FindPythonLibsNew.cmake
+ tools/pybind11Common.cmake
+ tools/pybind11Tools.cmake
+ tools/pybind11NewTools.cmake
+ DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})
+
+ if(NOT PYBIND11_EXPORT_NAME)
+ set(PYBIND11_EXPORT_NAME "${PROJECT_NAME}Targets")
endif()
- add_library(embed INTERFACE)
- add_library(pybind11::embed ALIAS embed)
- target_link_libraries(embed INTERFACE pybind11::pybind11 $)
+ install(TARGETS pybind11_headers EXPORT "${PYBIND11_EXPORT_NAME}")
+
+ install(
+ EXPORT "${PYBIND11_EXPORT_NAME}"
+ NAMESPACE "pybind11::"
+ DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})
+
+ # Uninstall target
+ if(PYBIND11_MASTER_PROJECT)
+ configure_file("${CMAKE_CURRENT_SOURCE_DIR}/tools/cmake_uninstall.cmake.in"
+ "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake" IMMEDIATE @ONLY)
+
+ add_custom_target(uninstall COMMAND ${CMAKE_COMMAND} -P
+ ${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake)
+ endif()
endif()
-if (PYBIND11_INSTALL)
- install(DIRECTORY ${PYBIND11_INCLUDE_DIR}/pybind11 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
- # GNUInstallDirs "DATADIR" wrong here; CMake search path wants "share".
- set(PYBIND11_CMAKECONFIG_INSTALL_DIR "share/cmake/${PROJECT_NAME}" CACHE STRING "install path for pybind11Config.cmake")
-
- configure_package_config_file(tools/${PROJECT_NAME}Config.cmake.in
- "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake"
- INSTALL_DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})
- # Remove CMAKE_SIZEOF_VOID_P from ConfigVersion.cmake since the library does
- # not depend on architecture specific settings or libraries.
- set(_PYBIND11_CMAKE_SIZEOF_VOID_P ${CMAKE_SIZEOF_VOID_P})
- unset(CMAKE_SIZEOF_VOID_P)
- write_basic_package_version_file(${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
- VERSION ${${PROJECT_NAME}_VERSION}
- COMPATIBILITY AnyNewerVersion)
- set(CMAKE_SIZEOF_VOID_P ${_PYBIND11_CMAKE_SIZEOF_VOID_P})
- install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake
- ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
- tools/FindPythonLibsNew.cmake
- tools/pybind11Tools.cmake
- DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})
-
- if(NOT (CMAKE_VERSION VERSION_LESS 3.0))
- if(NOT PYBIND11_EXPORT_NAME)
- set(PYBIND11_EXPORT_NAME "${PROJECT_NAME}Targets")
+# BUILD_TESTING takes priority, but only if this is the master project
+if(PYBIND11_MASTER_PROJECT AND DEFINED BUILD_TESTING)
+ if(BUILD_TESTING)
+ if(_pybind11_nopython)
+ message(FATAL_ERROR "Cannot activate tests in NOPYTHON mode")
+ else()
+ add_subdirectory(tests)
endif()
-
- install(TARGETS pybind11 module embed
- EXPORT "${PYBIND11_EXPORT_NAME}")
- if(PYBIND11_MASTER_PROJECT)
- install(EXPORT "${PYBIND11_EXPORT_NAME}"
- NAMESPACE "${PROJECT_NAME}::"
- DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})
+ endif()
+else()
+ if(PYBIND11_TEST)
+ if(_pybind11_nopython)
+ message(FATAL_ERROR "Cannot activate tests in NOPYTHON mode")
+ else()
+ add_subdirectory(tests)
endif()
endif()
endif()
+
+# Better symmetry with find_package(pybind11 CONFIG) mode.
+if(NOT PYBIND11_MASTER_PROJECT)
+ set(pybind11_FOUND
+ TRUE
+ CACHE INTERNAL "true if pybind11 and all required components found on the system")
+ set(pybind11_INCLUDE_DIR
+ "${PYBIND11_INCLUDE_DIR}"
+ CACHE INTERNAL "Directory where pybind11 headers are located")
+endif()
diff --git a/wrap/pybind11/CONTRIBUTING.md b/wrap/pybind11/CONTRIBUTING.md
deleted file mode 100644
index 0997918122..0000000000
--- a/wrap/pybind11/CONTRIBUTING.md
+++ /dev/null
@@ -1,54 +0,0 @@
-Thank you for your interest in this project! Please refer to the following
-sections on how to contribute code and bug reports.
-
-### Reporting bugs
-
-At the moment, this project is run in the spare time of a single person
-([Wenzel Jakob](http://rgl.epfl.ch/people/wjakob)) with very limited resources
-for issue tracker tickets. Thus, before submitting a question or bug report,
-please take a moment of your time and ensure that your issue isn't already
-discussed in the project documentation provided at
-[http://pybind11.readthedocs.org/en/latest](http://pybind11.readthedocs.org/en/latest).
-
-Assuming that you have identified a previously unknown problem or an important
-question, it's essential that you submit a self-contained and minimal piece of
-code that reproduces the problem. In other words: no external dependencies,
-isolate the function(s) that cause breakage, submit matched and complete C++
-and Python snippets that can be easily compiled and run on my end.
-
-## Pull requests
-Contributions are submitted, reviewed, and accepted using Github pull requests.
-Please refer to [this
-article](https://help.github.com/articles/using-pull-requests) for details and
-adhere to the following rules to make the process as smooth as possible:
-
-* Make a new branch for every feature you're working on.
-* Make small and clean pull requests that are easy to review but make sure they
- do add value by themselves.
-* Add tests for any new functionality and run the test suite (``make pytest``)
- to ensure that no existing features break.
-* Please run [``pre-commit``][pre-commit] and ``tools/check-style.sh`` to check
- your code matches the project style. (Note that ``check-style.sh`` requires
- ``gawk``.) Use `pre-commit run --all-files` before committing (or use
- installed-mode, check pre-commit docs) to verify your code passes before
- pushing to save time.
-* This project has a strong focus on providing general solutions using a
- minimal amount of code, thus small pull requests are greatly preferred.
-
-[pre-commit]: https://pre-commit.com
-
-### Licensing of contributions
-
-pybind11 is provided under a BSD-style license that can be found in the
-``LICENSE`` file. By using, distributing, or contributing to this project, you
-agree to the terms and conditions of this license.
-
-You are under no obligation whatsoever to provide any bug fixes, patches, or
-upgrades to the features, functionality or performance of the source code
-("Enhancements") to anyone; however, if you choose to make your Enhancements
-available either publicly, or directly to the author of this software, without
-imposing a separate written license agreement for such Enhancements, then you
-hereby grant the following license: a non-exclusive, royalty-free perpetual
-license to install, use, modify, prepare derivative works, incorporate into
-other computer software, distribute, and sublicense such enhancements or
-derivative works thereof, in binary and source code form.
diff --git a/wrap/pybind11/ISSUE_TEMPLATE.md b/wrap/pybind11/ISSUE_TEMPLATE.md
deleted file mode 100644
index 75df39981a..0000000000
--- a/wrap/pybind11/ISSUE_TEMPLATE.md
+++ /dev/null
@@ -1,17 +0,0 @@
-Make sure you've completed the following steps before submitting your issue -- thank you!
-
-1. Check if your question has already been answered in the [FAQ](http://pybind11.readthedocs.io/en/latest/faq.html) section.
-2. Make sure you've read the [documentation](http://pybind11.readthedocs.io/en/latest/). Your issue may be addressed there.
-3. If those resources didn't help and you only have a short question (not a bug report), consider asking in the [Gitter chat room](https://gitter.im/pybind/Lobby).
-4. If you have a genuine bug report or a more complex question which is not answered in the previous items (or not suitable for chat), please fill in the details below.
-5. Include a self-contained and minimal piece of code that reproduces the problem. If that's not possible, try to make the description as clear as possible.
-
-*After reading, remove this checklist and the template text in parentheses below.*
-
-## Issue description
-
-(Provide a short description, state the expected behavior and what actually happens.)
-
-## Reproducible example code
-
-(The code should be minimal, have no external dependencies, isolate the function(s) that cause breakage. Submit matched and complete C++ and Python snippets that can be easily compiled and run to diagnose the issue.)
diff --git a/wrap/pybind11/LICENSE b/wrap/pybind11/LICENSE
index 6f15578cc4..e466b0dfda 100644
--- a/wrap/pybind11/LICENSE
+++ b/wrap/pybind11/LICENSE
@@ -25,5 +25,5 @@ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-Please also refer to the file CONTRIBUTING.md, which clarifies licensing of
+Please also refer to the file .github/CONTRIBUTING.md, which clarifies licensing of
external contributions to this project including patches, pull requests, etc.
diff --git a/wrap/pybind11/MANIFEST.in b/wrap/pybind11/MANIFEST.in
index 6e57baeeef..9336b60302 100644
--- a/wrap/pybind11/MANIFEST.in
+++ b/wrap/pybind11/MANIFEST.in
@@ -1,2 +1,4 @@
-recursive-include include/pybind11 *.h
-include LICENSE README.md CONTRIBUTING.md
+recursive-include pybind11/include/pybind11 *.h
+recursive-include pybind11 *.py
+include pybind11/share/cmake/pybind11/*.cmake
+include LICENSE README.md pyproject.toml setup.py setup.cfg
diff --git a/wrap/pybind11/README.md b/wrap/pybind11/README.md
index 35d2d76ff9..69a0fc90b2 100644
--- a/wrap/pybind11/README.md
+++ b/wrap/pybind11/README.md
@@ -5,15 +5,14 @@
[](http://pybind11.readthedocs.org/en/master/?badge=master)
[](http://pybind11.readthedocs.org/en/stable/?badge=stable)
[](https://gitter.im/pybind/Lobby)
-[](https://travis-ci.org/pybind/pybind11)
+[](https://github.com/pybind/pybind11/actions)
[](https://ci.appveyor.com/project/wjakob/pybind11)
-**pybind11** is a lightweight header-only library that exposes C++ types in Python
-and vice versa, mainly to create Python bindings of existing C++ code. Its
-goals and syntax are similar to the excellent
-[Boost.Python](http://www.boost.org/doc/libs/1_58_0/libs/python/doc/) library
-by David Abrahams: to minimize boilerplate code in traditional extension
-modules by inferring type information using compile-time introspection.
+**pybind11** is a lightweight header-only library that exposes C++ types in
+Python and vice versa, mainly to create Python bindings of existing C++ code.
+Its goals and syntax are similar to the excellent [Boost.Python][] library by
+David Abrahams: to minimize boilerplate code in traditional extension modules
+by inferring type information using compile-time introspection.
The main issue with Boost.Python—and the reason for creating such a similar
project—is Boost. Boost is an enormously large and complex suite of utility
@@ -26,19 +25,18 @@ become an excessively large and unnecessary dependency.
Think of this library as a tiny self-contained version of Boost.Python 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 (2.7 or 3.x, or PyPy2.7 >= 5.7) 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.
+Python (2.7 or 3.5+, 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.
Tutorial and reference documentation is provided at
-[http://pybind11.readthedocs.org/en/master](http://pybind11.readthedocs.org/en/master).
-A PDF version of the manual is available
-[here](https://media.readthedocs.org/pdf/pybind11/master/pybind11.pdf).
+[pybind11.readthedocs.org][]. A PDF version of the manual is available
+[here][docs-pdf].
## Core features
-pybind11 can map the following core C++ features to Python
+pybind11 can map the following core C++ features to Python:
- Functions accepting and returning custom data structures per value, reference, or pointer
- Instance methods and static methods
@@ -51,15 +49,15 @@ pybind11 can map the following core C++ features to Python
- Custom operators
- Single and multiple inheritance
- STL data structures
-- Smart pointers with reference counting like ``std::shared_ptr``
+- Smart pointers with reference counting like `std::shared_ptr`
- Internal references with correct reference counting
- C++ classes with virtual (and pure virtual) methods can be extended in Python
## Goodies
In addition to the core functionality, pybind11 provides some extra goodies:
-- Python 2.7, 3.x, and PyPy (PyPy2.7 >= 5.7) are supported with an
- implementation-agnostic interface.
+- Python 2.7, 3.5+, and PyPy (tested on 7.3) are supported with an implementation-agnostic
+ interface.
- It is possible to bind C++11 lambda functions with captured variables. The
lambda capture data is stored inside the resulting Python function object.
@@ -83,10 +81,10 @@ In addition to the core functionality, pybind11 provides some extra goodies:
- Binaries are generally smaller by a factor of at least 2 compared to
equivalent bindings generated by Boost.Python. A recent pybind11 conversion
of PyRosetta, an enormous Boost.Python binding project,
- [reported](http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf) a binary
- size reduction of **5.4x** and compile time reduction by **5.8x**.
+ [reported][pyrosetta-report] a binary size reduction of **5.4x** and compile
+ time reduction by **5.8x**.
-- Function signatures are precomputed at compile time (using ``constexpr``),
+- Function signatures are precomputed at compile time (using `constexpr`),
leading to smaller binaries.
- With little extra effort, C++ types can be pickled and unpickled similar to
@@ -97,8 +95,11 @@ In addition to the core functionality, pybind11 provides some extra goodies:
1. Clang/LLVM 3.3 or newer (for Apple Xcode's clang, this is 5.0.0 or newer)
2. GCC 4.8 or newer
3. Microsoft Visual Studio 2015 Update 3 or newer
-4. Intel C++ compiler 17 or newer (16 with pybind11 v2.0 and 15 with pybind11 v2.0 and a [workaround](https://github.com/pybind/pybind11/issues/276))
+4. Intel C++ compiler 17 or newer (16 with pybind11 v2.0 and 15 with pybind11
+ v2.0 and a [workaround][intel-15-workaround])
5. Cygwin/GCC (tested on 2.5.1)
+6. NVCC (CUDA 11 tested)
+7. NVIDIA PGI (20.7 tested)
## About
@@ -122,8 +123,23 @@ Henry Schreiner,
Ivan Smirnov, and
Patrick Stewart.
+### Contributing
+
+See the [contributing guide][] for information on building and contributing to
+pybind11.
+
+
### License
pybind11 is provided under a BSD-style license that can be found in the
-``LICENSE`` file. By using, distributing, or contributing to this project,
+[`LICENSE`][] file. By using, distributing, or contributing to this project,
you agree to the terms and conditions of this license.
+
+
+[pybind11.readthedocs.org]: http://pybind11.readthedocs.org/en/master
+[docs-pdf]: https://media.readthedocs.org/pdf/pybind11/master/pybind11.pdf
+[Boost.Python]: http://www.boost.org/doc/libs/1_58_0/libs/python/doc/
+[pyrosetta-report]: http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf
+[contributing guide]: https://github.com/pybind/pybind11/blob/master/.github/CONTRIBUTING.md
+[`LICENSE`]: https://github.com/pybind/pybind11/blob/master/LICENSE
+[intel-15-workaround]: https://github.com/pybind/pybind11/issues/276
diff --git a/wrap/pybind11/docs/advanced/cast/custom.rst b/wrap/pybind11/docs/advanced/cast/custom.rst
index e4f99ac5b0..a779444c24 100644
--- a/wrap/pybind11/docs/advanced/cast/custom.rst
+++ b/wrap/pybind11/docs/advanced/cast/custom.rst
@@ -29,9 +29,9 @@ The following Python snippet demonstrates the intended usage from the Python sid
from example import print
print(A())
-To register the necessary conversion routines, it is necessary to add
-a partial overload to the ``pybind11::detail::type_caster`` template.
-Although this is an implementation detail, adding partial overloads to this
+To register the necessary conversion routines, it is necessary to add an
+instantiation of the ``pybind11::detail::type_caster`` template.
+Although this is an implementation detail, adding an instantiation of this
type is explicitly allowed.
.. code-block:: cpp
diff --git a/wrap/pybind11/docs/advanced/cast/eigen.rst b/wrap/pybind11/docs/advanced/cast/eigen.rst
index 59ba08c3c4..e01472d5ae 100644
--- a/wrap/pybind11/docs/advanced/cast/eigen.rst
+++ b/wrap/pybind11/docs/advanced/cast/eigen.rst
@@ -274,7 +274,7 @@ Vectors versus column/row matrices
Eigen and numpy have fundamentally different notions of a vector. In Eigen, a
vector is simply a matrix with the number of columns or rows set to 1 at
-compile time (for a column vector or row vector, respectively). Numpy, in
+compile time (for a column vector or row vector, respectively). NumPy, in
contrast, has comparable 2-dimensional 1xN and Nx1 arrays, but *also* has
1-dimensional arrays of size N.
diff --git a/wrap/pybind11/docs/advanced/cast/index.rst b/wrap/pybind11/docs/advanced/cast/index.rst
index 724585c920..3ce9ea0286 100644
--- a/wrap/pybind11/docs/advanced/cast/index.rst
+++ b/wrap/pybind11/docs/advanced/cast/index.rst
@@ -1,3 +1,5 @@
+.. _type-conversions:
+
Type conversions
################
diff --git a/wrap/pybind11/docs/advanced/cast/stl.rst b/wrap/pybind11/docs/advanced/cast/stl.rst
index e48409f025..7f708b81ea 100644
--- a/wrap/pybind11/docs/advanced/cast/stl.rst
+++ b/wrap/pybind11/docs/advanced/cast/stl.rst
@@ -157,7 +157,7 @@ the declaration
before any binding code (e.g. invocations to ``class_::def()``, etc.). This
macro must be specified at the top level (and outside of any namespaces), since
-it instantiates a partial template overload. If your binding code consists of
+it adds a template instantiation of ``type_caster``. If your binding code consists of
multiple compilation units, it must be present in every file (typically via a
common header) preceding any usage of ``std::vector``. Opaque types must
also have a corresponding ``class_`` declaration to associate them with a name
diff --git a/wrap/pybind11/docs/advanced/classes.rst b/wrap/pybind11/docs/advanced/classes.rst
index 031484c9d0..4927902069 100644
--- a/wrap/pybind11/docs/advanced/classes.rst
+++ b/wrap/pybind11/docs/advanced/classes.rst
@@ -71,7 +71,7 @@ helper class that is defined as follows:
/* Trampoline (need one for each virtual function) */
std::string go(int n_times) override {
- PYBIND11_OVERLOAD_PURE(
+ PYBIND11_OVERRIDE_PURE(
std::string, /* Return type */
Animal, /* Parent class */
go, /* Name of function in C++ (must match Python name) */
@@ -80,10 +80,10 @@ helper class that is defined as follows:
}
};
-The macro :c:macro:`PYBIND11_OVERLOAD_PURE` should be used for pure virtual
-functions, and :c:macro:`PYBIND11_OVERLOAD` should be used for functions which have
+The macro :c:macro:`PYBIND11_OVERRIDE_PURE` should be used for pure virtual
+functions, and :c:macro:`PYBIND11_OVERRIDE` should be used for functions which have
a default implementation. There are also two alternate macros
-:c:macro:`PYBIND11_OVERLOAD_PURE_NAME` and :c:macro:`PYBIND11_OVERLOAD_NAME` which
+:c:macro:`PYBIND11_OVERRIDE_PURE_NAME` and :c:macro:`PYBIND11_OVERRIDE_NAME` which
take a string-valued name argument between the *Parent class* and *Name of the
function* slots, which defines the name of function in Python. This is required
when the C++ and Python versions of the
@@ -122,7 +122,7 @@ Bindings should be made against the actual class, not the trampoline helper clas
Note, however, that the above is sufficient for allowing python classes to
extend ``Animal``, but not ``Dog``: see :ref:`virtual_and_inheritance` for the
-necessary steps required to providing proper overload support for inherited
+necessary steps required to providing proper overriding support for inherited
classes.
The Python session below shows how to override ``Animal::go`` and invoke it via
@@ -149,8 +149,7 @@ memory for the C++ portion of the instance will be left uninitialized, which
will generally leave the C++ instance in an invalid state and cause undefined
behavior if the C++ instance is subsequently used.
-.. versionadded:: 2.5.1
-
+.. versionchanged:: 2.6
The default pybind11 metaclass will throw a ``TypeError`` when it detects
that ``__init__`` was not called by a derived class.
@@ -160,7 +159,7 @@ Here is an example:
class Dachshund(Dog):
def __init__(self, name):
- Dog.__init__(self) # Without this, undefined behavior may occur if the C++ portions are referenced.
+ Dog.__init__(self) # Without this, a TypeError is raised.
self.name = name
def bark(self):
return "yap!"
@@ -182,15 +181,24 @@ Please take a look at the :ref:`macro_notes` before using this feature.
- because in these cases there is no C++ variable to reference (the value
is stored in the referenced Python variable), pybind11 provides one in
- the PYBIND11_OVERLOAD macros (when needed) with static storage duration.
- Note that this means that invoking the overloaded method on *any*
+ the PYBIND11_OVERRIDE macros (when needed) with static storage duration.
+ Note that this means that invoking the overridden method on *any*
instance will change the referenced value stored in *all* instances of
that type.
- Attempts to modify a non-const reference will not have the desired
effect: it will change only the static cache variable, but this change
will not propagate to underlying Python instance, and the change will be
- replaced the next time the overload is invoked.
+ replaced the next time the override is invoked.
+
+.. warning::
+
+ The :c:macro:`PYBIND11_OVERRIDE` and accompanying macros used to be called
+ ``PYBIND11_OVERLOAD`` up until pybind11 v2.5.0, and :func:`get_override`
+ used to be called ``get_overload``. This naming was corrected and the older
+ macro and function names may soon be deprecated, in order to reduce
+ confusion with overloaded functions and methods and ``py::overload_cast``
+ (see :ref:`classes`).
.. seealso::
@@ -238,20 +246,20 @@ override the ``name()`` method):
class PyAnimal : public Animal {
public:
using Animal::Animal; // Inherit constructors
- std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Animal, go, n_times); }
- std::string name() override { PYBIND11_OVERLOAD(std::string, Animal, name, ); }
+ std::string go(int n_times) override { PYBIND11_OVERRIDE_PURE(std::string, Animal, go, n_times); }
+ std::string name() override { PYBIND11_OVERRIDE(std::string, Animal, name, ); }
};
class PyDog : public Dog {
public:
using Dog::Dog; // Inherit constructors
- std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, Dog, go, n_times); }
- std::string name() override { PYBIND11_OVERLOAD(std::string, Dog, name, ); }
- std::string bark() override { PYBIND11_OVERLOAD(std::string, Dog, bark, ); }
+ std::string go(int n_times) override { PYBIND11_OVERRIDE(std::string, Dog, go, n_times); }
+ std::string name() override { PYBIND11_OVERRIDE(std::string, Dog, name, ); }
+ std::string bark() override { PYBIND11_OVERRIDE(std::string, Dog, bark, ); }
};
.. note::
- Note the trailing commas in the ``PYBIND11_OVERLOAD`` calls to ``name()``
+ Note the trailing commas in the ``PYBIND11_OVERIDE`` calls to ``name()``
and ``bark()``. These are needed to portably implement a trampoline for a
function that does not take any arguments. For functions that take
a nonzero number of arguments, the trailing comma must be omitted.
@@ -266,9 +274,9 @@ declare or override any virtual methods itself:
class PyHusky : public Husky {
public:
using Husky::Husky; // Inherit constructors
- std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Husky, go, n_times); }
- std::string name() override { PYBIND11_OVERLOAD(std::string, Husky, name, ); }
- std::string bark() override { PYBIND11_OVERLOAD(std::string, Husky, bark, ); }
+ std::string go(int n_times) override { PYBIND11_OVERRIDE_PURE(std::string, Husky, go, n_times); }
+ std::string name() override { PYBIND11_OVERRIDE(std::string, Husky, name, ); }
+ std::string bark() override { PYBIND11_OVERRIDE(std::string, Husky, bark, ); }
};
There is, however, a technique that can be used to avoid this duplication
@@ -281,15 +289,15 @@ follows:
template class PyAnimal : public AnimalBase {
public:
using AnimalBase::AnimalBase; // Inherit constructors
- std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, AnimalBase, go, n_times); }
- std::string name() override { PYBIND11_OVERLOAD(std::string, AnimalBase, name, ); }
+ std::string go(int n_times) override { PYBIND11_OVERRIDE_PURE(std::string, AnimalBase, go, n_times); }
+ std::string name() override { PYBIND11_OVERRIDE(std::string, AnimalBase, name, ); }
};
template class PyDog : public PyAnimal {
public:
using PyAnimal::PyAnimal; // Inherit constructors
// Override PyAnimal's pure virtual go() with a non-pure one:
- std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, DogBase, go, n_times); }
- std::string bark() override { PYBIND11_OVERLOAD(std::string, DogBase, bark, ); }
+ std::string go(int n_times) override { PYBIND11_OVERRIDE(std::string, DogBase, go, n_times); }
+ std::string bark() override { PYBIND11_OVERRIDE(std::string, DogBase, bark, ); }
};
This technique has the advantage of requiring just one trampoline method to be
@@ -342,7 +350,7 @@ valid for the trampoline class but not the registered class. This is primarily
for performance reasons: when the trampoline class is not needed for anything
except virtual method dispatching, not initializing the trampoline class
improves performance by avoiding needing to do a run-time check to see if the
-inheriting python instance has an overloaded method.
+inheriting python instance has an overridden method.
Sometimes, however, it is useful to always initialize a trampoline class as an
intermediate class that does more than just handle virtual method dispatching.
@@ -373,7 +381,7 @@ references (See also :ref:`faq_reference_arguments`). Another way of solving
this is to use the method body of the trampoline class to do conversions to the
input and return of the Python method.
-The main building block to do so is the :func:`get_overload`, this function
+The main building block to do so is the :func:`get_override`, this function
allows retrieving a method implemented in Python from within the trampoline's
methods. Consider for example a C++ method which has the signature
``bool myMethod(int32_t& value)``, where the return indicates whether
@@ -385,10 +393,10 @@ Python side by allowing the Python function to return ``None`` or an ``int``:
bool MyClass::myMethod(int32_t& value)
{
pybind11::gil_scoped_acquire gil; // Acquire the GIL while in this scope.
- // Try to look up the overloaded method on the Python side.
- pybind11::function overload = pybind11::get_overload(this, "myMethod");
- if (overload) { // method is found
- auto obj = overload(value); // Call the Python function.
+ // Try to look up the overridden method on the Python side.
+ pybind11::function override = pybind11::get_override(this, "myMethod");
+ if (override) { // method is found
+ auto obj = override(value); // Call the Python function.
if (py::isinstance(obj)) { // check if it returned a Python integer type
value = obj.cast(); // Cast it and assign it to the value.
return true; // Return true; value should be used.
@@ -559,6 +567,46 @@ crucial that instances are deallocated on the C++ side to avoid memory leaks.
py::class_>(m, "MyClass")
.def(py::init<>())
+.. _destructors_that_call_python:
+
+Destructors that call Python
+============================
+
+If a Python function is invoked from a C++ destructor, an exception may be thrown
+of type :class:`error_already_set`. If this error is thrown out of a class destructor,
+``std::terminate()`` will be called, terminating the process. Class destructors
+must catch all exceptions of type :class:`error_already_set` to discard the Python
+exception using :func:`error_already_set::discard_as_unraisable`.
+
+Every Python function should be treated as *possibly throwing*. When a Python generator
+stops yielding items, Python will throw a ``StopIteration`` exception, which can pass
+though C++ destructors if the generator's stack frame holds the last reference to C++
+objects.
+
+For more information, see :ref:`the documentation on exceptions `.
+
+.. code-block:: cpp
+
+ class MyClass {
+ public:
+ ~MyClass() {
+ try {
+ py::print("Even printing is dangerous in a destructor");
+ py::exec("raise ValueError('This is an unraisable exception')");
+ } catch (py::error_already_set &e) {
+ // error_context should be information about where/why the occurred,
+ // e.g. use __func__ to get the name of the current function
+ e.discard_as_unraisable(__func__);
+ }
+ }
+ };
+
+.. note::
+
+ pybind11 does not support C++ destructors marked ``noexcept(false)``.
+
+.. versionadded:: 2.6
+
.. _implicit_conversions:
Implicit conversions
@@ -1065,7 +1113,7 @@ described trampoline:
class Trampoline : public A {
public:
- int foo() const override { PYBIND11_OVERLOAD(int, A, foo, ); }
+ int foo() const override { PYBIND11_OVERRIDE(int, A, foo, ); }
};
class Publicist : public A {
@@ -1109,6 +1157,8 @@ error:
.. note:: This attribute is currently ignored on PyPy
+.. versionadded:: 2.6
+
Custom automatic downcasters
============================
@@ -1191,3 +1241,21 @@ appropriate derived-class pointer (e.g. using
more complete example, including a demonstration of how to provide
automatic downcasting for an entire class hierarchy without
writing one get() function for each class.
+
+Accessing the type object
+=========================
+
+You can get the type object from a C++ class that has already been registered using:
+
+.. code-block:: python
+
+ py::type T_py = py::type::of();
+
+You can directly use ``py::type::of(ob)`` to get the type object from any python
+object, just like ``type(ob)`` in Python.
+
+.. note::
+
+ Other types, like ``py::type::of()``, do not work, see :ref:`type-conversions`.
+
+.. versionadded:: 2.6
diff --git a/wrap/pybind11/docs/advanced/embedding.rst b/wrap/pybind11/docs/advanced/embedding.rst
index 3930316032..98a5c52190 100644
--- a/wrap/pybind11/docs/advanced/embedding.rst
+++ b/wrap/pybind11/docs/advanced/embedding.rst
@@ -18,7 +18,7 @@ information, see :doc:`/compiling`.
.. code-block:: cmake
- cmake_minimum_required(VERSION 3.0)
+ cmake_minimum_required(VERSION 3.4)
project(example)
find_package(pybind11 REQUIRED) # or `add_subdirectory(pybind11)`
diff --git a/wrap/pybind11/docs/advanced/exceptions.rst b/wrap/pybind11/docs/advanced/exceptions.rst
index 75ad7f7f4a..a96f8e8f4d 100644
--- a/wrap/pybind11/docs/advanced/exceptions.rst
+++ b/wrap/pybind11/docs/advanced/exceptions.rst
@@ -1,18 +1,24 @@
Exceptions
##########
-Built-in exception translation
-==============================
+Built-in C++ to Python exception translation
+============================================
+
+When Python calls C++ code through pybind11, pybind11 provides a C++ exception handler
+that will trap C++ exceptions, translate them to the corresponding Python exception,
+and raise them so that Python code can handle them.
-When C++ code invoked from Python throws an ``std::exception``, it is
-automatically converted into a Python ``Exception``. pybind11 defines multiple
-special exception classes that will map to different types of Python
-exceptions:
+pybind11 defines translations for ``std::exception`` and its standard
+subclasses, and several special exception classes that translate to specific
+Python exceptions. Note that these are not actually Python exceptions, so they
+cannot be examined using the Python C API. Instead, they are pure C++ objects
+that pybind11 will translate the corresponding Python exception when they arrive
+at its exception handler.
.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}|
+--------------------------------------+--------------------------------------+
-| C++ exception type | Python exception type |
+| Exception thrown by C++ | Translated to Python exception type |
+======================================+======================================+
| :class:`std::exception` | ``RuntimeError`` |
+--------------------------------------+--------------------------------------+
@@ -46,16 +52,11 @@ exceptions:
| | ``__setitem__`` in dict-like |
| | objects, etc.) |
+--------------------------------------+--------------------------------------+
-| :class:`pybind11::error_already_set` | Indicates that the Python exception |
-| | flag has already been set via Python |
-| | API calls from C++ code; this C++ |
-| | exception is used to propagate such |
-| | a Python exception back to Python. |
-+--------------------------------------+--------------------------------------+
-When a Python function invoked from C++ throws an exception, it is converted
-into a C++ exception of type :class:`error_already_set` whose string payload
-contains a textual summary.
+Exception translation is not bidirectional. That is, *catching* the C++
+exceptions defined above above will not trap exceptions that originate from
+Python. For that, catch :class:`pybind11::error_already_set`. See :ref:`below
+` for further details.
There is also a special exception :class:`cast_error` that is thrown by
:func:`handle::call` when the input arguments cannot be converted to Python
@@ -78,6 +79,19 @@ This call creates a Python exception class with the name ``PyExp`` in the given
module and automatically converts any encountered exceptions of type ``CppExp``
into Python exceptions of type ``PyExp``.
+It is possible to specify base class for the exception using the third
+parameter, a `handle`:
+
+.. code-block:: cpp
+
+ py::register_exception(module, "PyExp", PyExc_RuntimeError);
+
+Then `PyExp` can be caught both as `PyExp` and `RuntimeError`.
+
+The class objects of the built-in Python exceptions are listed in the Python
+documentation on `Standard Exceptions `_.
+The default base class is `PyExc_Exception`.
+
When more advanced exception translation is needed, the function
``py::register_exception_translator(translator)`` can be used to register
functions that can translate arbitrary exception types (and which may include
@@ -100,7 +114,6 @@ and use this in the associated exception translator (note: it is often useful
to make this a static declaration when using it inside a lambda expression
without requiring capturing).
-
The following example demonstrates this for a hypothetical exception classes
``MyCustomException`` and ``OtherException``: the first is translated to a
custom python exception ``MyCustomError``, while the second is translated to a
@@ -134,7 +147,7 @@ section.
.. note::
- You must call either ``PyErr_SetString`` or a custom exception's call
+ Call either ``PyErr_SetString`` or a custom exception's call
operator (``exc(string)``) for every exception caught in a custom exception
translator. Failure to do so will cause Python to crash with ``SystemError:
error return without exception set``.
@@ -142,3 +155,144 @@ section.
Exceptions that you do not plan to handle should simply not be caught, or
may be explicitly (re-)thrown to delegate it to the other,
previously-declared existing exception translators.
+
+.. _handling_python_exceptions_cpp:
+
+Handling exceptions from Python in C++
+======================================
+
+When C++ calls Python functions, such as in a callback function or when
+manipulating Python objects, and Python raises an ``Exception``, pybind11
+converts the Python exception into a C++ exception of type
+:class:`pybind11::error_already_set` whose payload contains a C++ string textual
+summary and the actual Python exception. ``error_already_set`` is used to
+propagate Python exception back to Python (or possibly, handle them in C++).
+
+.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}|
+
++--------------------------------------+--------------------------------------+
+| Exception raised in Python | Thrown as C++ exception type |
++======================================+======================================+
+| Any Python ``Exception`` | :class:`pybind11::error_already_set` |
++--------------------------------------+--------------------------------------+
+
+For example:
+
+.. code-block:: cpp
+
+ try {
+ // open("missing.txt", "r")
+ auto file = py::module::import("io").attr("open")("missing.txt", "r");
+ auto text = file.attr("read")();
+ file.attr("close")();
+ } catch (py::error_already_set &e) {
+ if (e.matches(PyExc_FileNotFoundError)) {
+ py::print("missing.txt not found");
+ } else if (e.match(PyExc_PermissionError)) {
+ py::print("missing.txt found but not accessible");
+ } else {
+ throw;
+ }
+ }
+
+Note that C++ to Python exception translation does not apply here, since that is
+a method for translating C++ exceptions to Python, not vice versa. The error raised
+from Python is always ``error_already_set``.
+
+This example illustrates this behavior:
+
+.. code-block:: cpp
+
+ try {
+ py::eval("raise ValueError('The Ring')");
+ } catch (py::value_error &boromir) {
+ // Boromir never gets the ring
+ assert(false);
+ } catch (py::error_already_set &frodo) {
+ // Frodo gets the ring
+ py::print("I will take the ring");
+ }
+
+ try {
+ // py::value_error is a request for pybind11 to raise a Python exception
+ throw py::value_error("The ball");
+ } catch (py::error_already_set &cat) {
+ // cat won't catch the ball since
+ // py::value_error is not a Python exception
+ assert(false);
+ } catch (py::value_error &dog) {
+ // dog will catch the ball
+ py::print("Run Spot run");
+ throw; // Throw it again (pybind11 will raise ValueError)
+ }
+
+Handling errors from the Python C API
+=====================================
+
+Where possible, use :ref:`pybind11 wrappers ` instead of calling
+the Python C API directly. When calling the Python C API directly, in
+addition to manually managing reference counts, one must follow the pybind11
+error protocol, which is outlined here.
+
+After calling the Python C API, if Python returns an error,
+``throw py::error_already_set();``, which allows pybind11 to deal with the
+exception and pass it back to the Python interpreter. This includes calls to
+the error setting functions such as ``PyErr_SetString``.
+
+.. code-block:: cpp
+
+ PyErr_SetString(PyExc_TypeError, "C API type error demo");
+ throw py::error_already_set();
+
+ // But it would be easier to simply...
+ throw py::type_error("pybind11 wrapper type error");
+
+Alternately, to ignore the error, call `PyErr_Clear
+`_.
+
+Any Python error must be thrown or cleared, or Python/pybind11 will be left in
+an invalid state.
+
+.. _unraisable_exceptions:
+
+Handling unraisable exceptions
+==============================
+
+If a Python function invoked from a C++ destructor or any function marked
+``noexcept(true)`` (collectively, "noexcept functions") throws an exception, there
+is no way to propagate the exception, as such functions may not throw.
+Should they throw or fail to catch any exceptions in their call graph,
+the C++ runtime calls ``std::terminate()`` to abort immediately.
+
+Similarly, Python exceptions raised in a class's ``__del__`` method do not
+propagate, but are logged by Python as an unraisable error. In Python 3.8+, a
+`system hook is triggered
+`_
+and an auditing event is logged.
+
+Any noexcept function should have a try-catch block that traps
+class:`error_already_set` (or any other exception that can occur). Note that
+pybind11 wrappers around Python exceptions such as
+:class:`pybind11::value_error` are *not* Python exceptions; they are C++
+exceptions that pybind11 catches and converts to Python exceptions. Noexcept
+functions cannot propagate these exceptions either. A useful approach is to
+convert them to Python exceptions and then ``discard_as_unraisable`` as shown
+below.
+
+.. code-block:: cpp
+
+ void nonthrowing_func() noexcept(true) {
+ try {
+ // ...
+ } catch (py::error_already_set &eas) {
+ // Discard the Python error using Python APIs, using the C++ magic
+ // variable __func__. Python already knows the type and value and of the
+ // exception object.
+ eas.discard_as_unraisable(__func__);
+ } catch (const std::exception &e) {
+ // Log and discard C++ exceptions.
+ third_party::log(e);
+ }
+ }
+
+.. versionadded:: 2.6
diff --git a/wrap/pybind11/docs/advanced/functions.rst b/wrap/pybind11/docs/advanced/functions.rst
index 984b046efa..c895517c50 100644
--- a/wrap/pybind11/docs/advanced/functions.rst
+++ b/wrap/pybind11/docs/advanced/functions.rst
@@ -360,7 +360,7 @@ like so:
.. code-block:: cpp
py::class_("MyClass")
- .def("myFunction", py::arg("arg") = (SomeType *) nullptr);
+ .def("myFunction", py::arg("arg") = static_cast(nullptr));
Keyword-only arguments
======================
@@ -378,17 +378,37 @@ argument in a function definition:
f(1, b=2) # good
f(1, 2) # TypeError: f() takes 1 positional argument but 2 were given
-Pybind11 provides a ``py::kwonly`` object that allows you to implement
+Pybind11 provides a ``py::kw_only`` object that allows you to implement
the same behaviour by specifying the object between positional and keyword-only
argument annotations when registering the function:
.. code-block:: cpp
m.def("f", [](int a, int b) { /* ... */ },
- py::arg("a"), py::kwonly(), py::arg("b"));
+ py::arg("a"), py::kw_only(), py::arg("b"));
-Note that, as in Python, you cannot combine this with a ``py::args`` argument.
-This feature does *not* require Python 3 to work.
+Note that you currently cannot combine this with a ``py::args`` argument. This
+feature does *not* require Python 3 to work.
+
+.. versionadded:: 2.6
+
+Positional-only arguments
+=========================
+
+Python 3.8 introduced a new positional-only argument syntax, using ``/`` in the
+function definition (note that this has been a convention for CPython
+positional arguments, such as in ``pow()``, since Python 2). You can
+do the same thing in any version of Python using ``py::pos_only()``:
+
+.. code-block:: cpp
+
+ m.def("f", [](int a, int b) { /* ... */ },
+ py::arg("a"), py::pos_only(), py::arg("b"));
+
+You now cannot give argument ``a`` by keyword. This can be combined with
+keyword-only arguments, as well.
+
+.. versionadded:: 2.6
.. _nonconverting_arguments:
diff --git a/wrap/pybind11/docs/advanced/misc.rst b/wrap/pybind11/docs/advanced/misc.rst
index 7798462df7..a5899c67a4 100644
--- a/wrap/pybind11/docs/advanced/misc.rst
+++ b/wrap/pybind11/docs/advanced/misc.rst
@@ -7,14 +7,14 @@ General notes regarding convenience macros
==========================================
pybind11 provides a few convenience macros such as
-:func:`PYBIND11_DECLARE_HOLDER_TYPE` and ``PYBIND11_OVERLOAD_*``. Since these
+:func:`PYBIND11_DECLARE_HOLDER_TYPE` and ``PYBIND11_OVERRIDE_*``. Since these
are "just" macros that are evaluated in the preprocessor (which has no concept
of types), they *will* get confused by commas in a template argument; for
example, consider:
.. code-block:: cpp
- PYBIND11_OVERLOAD(MyReturnType, Class, func)
+ PYBIND11_OVERRIDE(MyReturnType, Class, func)
The limitation of the C preprocessor interprets this as five arguments (with new
arguments beginning after each comma) rather than three. To get around this,
@@ -26,10 +26,10 @@ using the ``PYBIND11_TYPE`` macro:
// Version 1: using a type alias
using ReturnType = MyReturnType;
using ClassType = Class;
- PYBIND11_OVERLOAD(ReturnType, ClassType, func);
+ PYBIND11_OVERRIDE(ReturnType, ClassType, func);
// Version 2: using the PYBIND11_TYPE macro:
- PYBIND11_OVERLOAD(PYBIND11_TYPE(MyReturnType),
+ PYBIND11_OVERRIDE(PYBIND11_TYPE(MyReturnType),
PYBIND11_TYPE(Class), func)
The ``PYBIND11_MAKE_OPAQUE`` macro does *not* require the above workarounds.
@@ -59,7 +59,7 @@ could be realized as follows (important changes highlighted):
/* Acquire GIL before calling Python code */
py::gil_scoped_acquire acquire;
- PYBIND11_OVERLOAD_PURE(
+ PYBIND11_OVERRIDE_PURE(
std::string, /* Return type */
Animal, /* Parent class */
go, /* Name of function */
@@ -176,9 +176,9 @@ pybind11 version. Consider the following example:
.. code-block:: cpp
- auto data = (MyData *) py::get_shared_data("mydata");
+ auto data = reinterpret_cast(py::get_shared_data("mydata"));
if (!data)
- data = (MyData *) py::set_shared_data("mydata", new MyData(42));
+ data = static_cast(py::set_shared_data("mydata", new MyData(42)));
If the above snippet was used in several separately compiled extension modules,
the first one to be imported would create a ``MyData`` instance and associate
@@ -304,3 +304,34 @@ the default settings are restored to prevent unwanted side effects.
.. [#f4] http://www.sphinx-doc.org
.. [#f5] http://github.com/pybind/python_example
+
+.. _avoiding-cpp-types-in-docstrings:
+
+Avoiding C++ types in docstrings
+================================
+
+Docstrings are generated at the time of the declaration, e.g. when ``.def(...)`` is called.
+At this point parameter and return types should be known to pybind11.
+If a custom type is not exposed yet through a ``py::class_`` constructor or a custom type caster,
+its C++ type name will be used instead to generate the signature in the docstring:
+
+.. code-block:: text
+
+ | __init__(...)
+ | __init__(self: example.Foo, arg0: ns::Bar) -> None
+ ^^^^^^^
+
+
+This limitation can be circumvented by ensuring that C++ classes are registered with pybind11
+before they are used as a parameter or return type of a function:
+
+.. code-block:: cpp
+
+ PYBIND11_MODULE(example, m) {
+
+ auto pyFoo = py::class_(m, "Foo");
+ auto pyBar = py::class_(m, "Bar");
+
+ pyFoo.def(py::init());
+ pyBar.def(py::init());
+ }
diff --git a/wrap/pybind11/docs/advanced/pycpp/numpy.rst b/wrap/pybind11/docs/advanced/pycpp/numpy.rst
index f1941392fa..e50d24a991 100644
--- a/wrap/pybind11/docs/advanced/pycpp/numpy.rst
+++ b/wrap/pybind11/docs/advanced/pycpp/numpy.rst
@@ -81,7 +81,7 @@ buffer objects (e.g. a NumPy matrix).
constexpr bool rowMajor = Matrix::Flags & Eigen::RowMajorBit;
py::class_(m, "Matrix", py::buffer_protocol())
- .def("__init__", [](py::buffer b) {
+ .def(py::init([](py::buffer b) {
typedef Eigen::Stride Strides;
/* Request a buffer descriptor from Python */
@@ -101,8 +101,8 @@ buffer objects (e.g. a NumPy matrix).
auto map = Eigen::Map(
static_cast(info.ptr), info.shape[0], info.shape[1], strides);
- return Matrix(m);
- });
+ return Matrix(map);
+ }));
For reference, the ``def_buffer()`` call for this Eigen data type should look
as follows:
@@ -274,9 +274,9 @@ simply using ``vectorize``).
py::buffer_info buf3 = result.request();
- double *ptr1 = (double *) buf1.ptr,
- *ptr2 = (double *) buf2.ptr,
- *ptr3 = (double *) buf3.ptr;
+ double *ptr1 = static_cast(buf1.ptr);
+ double *ptr2 = static_cast(buf2.ptr);
+ double *ptr3 = static_cast(buf3.ptr);
for (size_t idx = 0; idx < buf1.shape[0]; idx++)
ptr3[idx] = ptr1[idx] + ptr2[idx];
@@ -371,6 +371,8 @@ Ellipsis
Python 3 provides a convenient ``...`` ellipsis notation that is often used to
slice multidimensional arrays. For instance, the following snippet extracts the
middle dimensions of a tensor with the first and last index set to zero.
+In Python 2, the syntactic sugar ``...`` is not available, but the singleton
+``Ellipsis`` (of type ``ellipsis``) can still be used directly.
.. code-block:: python
@@ -385,6 +387,9 @@ operation on the C++ side:
py::array a = /* A NumPy array */;
py::array b = a[py::make_tuple(0, py::ellipsis(), 0)];
+.. versionchanged:: 2.6
+ ``py::ellipsis()`` is now also avaliable in Python 2.
+
Memory view
===========
@@ -426,3 +431,6 @@ We can also use ``memoryview::from_memory`` for a simple 1D contiguous buffer:
.. note::
``memoryview::from_memory`` is not available in Python 2.
+
+.. versionchanged:: 2.6
+ ``memoryview::from_memory`` added.
diff --git a/wrap/pybind11/docs/advanced/pycpp/object.rst b/wrap/pybind11/docs/advanced/pycpp/object.rst
index 19a226a876..70e493acd9 100644
--- a/wrap/pybind11/docs/advanced/pycpp/object.rst
+++ b/wrap/pybind11/docs/advanced/pycpp/object.rst
@@ -1,6 +1,8 @@
Python types
############
+.. _wrappers:
+
Available wrappers
==================
@@ -13,6 +15,13 @@ Available types include :class:`handle`, :class:`object`, :class:`bool_`,
:class:`iterable`, :class:`iterator`, :class:`function`, :class:`buffer`,
:class:`array`, and :class:`array_t`.
+.. warning::
+
+ Be sure to review the :ref:`pytypes_gotchas` before using this heavily in
+ your C++ API.
+
+.. _casting_back_and_forth:
+
Casting back and forth
======================
@@ -55,6 +64,7 @@ This example obtains a reference to the Python ``Decimal`` class.
py::object scipy = py::module::import("scipy");
return scipy.attr("__version__");
+
.. _calling_python_functions:
Calling Python functions
@@ -168,3 +178,74 @@ Generalized unpacking according to PEP448_ is also supported:
Python functions from C++, including keywords arguments and unpacking.
.. _PEP448: https://www.python.org/dev/peps/pep-0448/
+
+.. _implicit_casting:
+
+Implicit casting
+================
+
+When using the C++ interface for Python types, or calling Python functions,
+objects of type :class:`object` are returned. It is possible to invoke implicit
+conversions to subclasses like :class:`dict`. The same holds for the proxy objects
+returned by ``operator[]`` or ``obj.attr()``.
+Casting to subtypes improves code readability and allows values to be passed to
+C++ functions that require a specific subtype rather than a generic :class:`object`.
+
+.. code-block:: cpp
+
+ #include
+ using namespace pybind11::literals;
+
+ py::module os = py::module::import("os");
+ py::module path = py::module::import("os.path"); // like 'import os.path as path'
+ py::module np = py::module::import("numpy"); // like 'import numpy as np'
+
+ py::str curdir_abs = path.attr("abspath")(path.attr("curdir"));
+ py::print(py::str("Current directory: ") + curdir_abs);
+ py::dict environ = os.attr("environ");
+ py::print(environ["HOME"]);
+ py::array_t arr = np.attr("ones")(3, "dtype"_a="float32");
+ py::print(py::repr(arr + py::int_(1)));
+
+These implicit conversions are available for subclasses of :class:`object`; there
+is no need to call ``obj.cast()`` explicitly as for custom classes, see
+:ref:`casting_back_and_forth`.
+
+.. note::
+ If a trivial conversion via move constructor is not possible, both implicit and
+ explicit casting (calling ``obj.cast()``) will attempt a "rich" conversion.
+ For instance, ``py::list env = os.attr("environ");`` will succeed and is
+ equivalent to the Python code ``env = list(os.environ)`` that produces a
+ list of the dict keys.
+
+.. TODO: Adapt text once PR #2349 has landed
+
+Handling exceptions
+===================
+
+Python exceptions from wrapper classes will be thrown as a ``py::error_already_set``.
+See :ref:`Handling exceptions from Python in C++
+` for more information on handling exceptions
+raised when calling C++ wrapper classes.
+
+.. _pytypes_gotchas:
+
+Gotchas
+=======
+
+Default-Constructed Wrappers
+----------------------------
+
+When a wrapper type is default-constructed, it is **not** a valid Python object (i.e. it is not ``py::none()``). It is simply the same as
+``PyObject*`` null pointer. To check for this, use
+``static_cast(my_wrapper)``.
+
+Assigning py::none() to wrappers
+--------------------------------
+
+You may be tempted to use types like ``py::str`` and ``py::dict`` in C++
+signatures (either pure C++, or in bound signatures), and assign them default
+values of ``py::none()``. However, in a best case scenario, it will fail fast
+because ``None`` is not convertible to that type (e.g. ``py::dict``), or in a
+worse case scenario, it will silently work but corrupt the types you want to
+work with (e.g. ``py::str(py::none())`` will yield ``"None"`` in Python).
diff --git a/wrap/pybind11/docs/basics.rst b/wrap/pybind11/docs/basics.rst
index 7bf4d426d3..71440c9c66 100644
--- a/wrap/pybind11/docs/basics.rst
+++ b/wrap/pybind11/docs/basics.rst
@@ -11,11 +11,11 @@ included set of test cases.
Compiling the test cases
========================
-Linux/MacOS
+Linux/macOS
-----------
On Linux you'll need to install the **python-dev** or **python3-dev** packages as
-well as **cmake**. On Mac OS, the included python version works out of the box,
+well as **cmake**. On macOS, the included python version works out of the box,
but **cmake** must still be installed.
After installing the prerequisites, run
@@ -35,6 +35,14 @@ Windows
On Windows, only **Visual Studio 2015** and newer are supported since pybind11 relies
on various C++11 language features that break older versions of Visual Studio.
+.. Note::
+
+ To use the C++17 in Visual Studio 2017 (MSVC 14.1), pybind11 requires the flag
+ ``/permissive-`` to be passed to the compiler `to enforce standard conformance`_. When
+ building with Visual Studio 2019, this is not strictly necessary, but still adviced.
+
+.. _`to enforce standard conformance`: https://docs.microsoft.com/en-us/cpp/build/reference/permissive-standards-conformance?view=vs-2017
+
To compile and run the tests:
.. code-block:: batch
@@ -130,7 +138,7 @@ On Linux, the above example can be compiled using the following command:
$ c++ -O3 -Wall -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix`
-For more details on the required compiler flags on Linux and MacOS, see
+For more details on the required compiler flags on Linux and macOS, see
:ref:`building_manually`. For complete cross-platform compilation instructions,
refer to the :ref:`compiling` page.
diff --git a/wrap/pybind11/docs/changelog.rst b/wrap/pybind11/docs/changelog.rst
index 2def2b0719..8f95c12741 100644
--- a/wrap/pybind11/docs/changelog.rst
+++ b/wrap/pybind11/docs/changelog.rst
@@ -6,6 +6,165 @@ Changelog
Starting with version 1.8.0, pybind11 releases use a `semantic versioning
`_ policy.
+v2.6.0 (IN PROGRESS)
+--------------------
+
+See :ref:`upgrade-guide-2.6` for help upgrading to the new version.
+
+* Provide an additional spelling of ``py::module`` - ``py::module_`` (with a
+ trailing underscore), for C++20 compatibility. Only relevant when used
+ unqualified.
+ `#2489 `_
+
+* ``pybind11_add_module()`` now accepts an optional ``OPT_SIZE`` flag that
+ switches the binding target to size-based optimization regardless global
+ CMake build type (except in debug mode, where optimizations remain disabled).
+ This reduces binary size quite substantially (~25%).
+ `#2463 `_
+
+* Keyword-only arguments supported in Python 2 or 3 with ``py::kw_only()``.
+ `#2100 `_
+
+* Positional-only arguments supported in Python 2 or 3 with ``py::pos_only()``.
+ `#2459 `_
+
+* Access to the type object now provided with ``py::type::of()`` and
+ ``py::type::of(h)``.
+ `#2364 `_
+
+
+* Perfect forwarding support for methods.
+ `#2048 `_
+
+* Added ``py::error_already_set::discard_as_unraisable()``.
+ `#2372 `_
+
+* ``py::hash`` is now public.
+ `#2217 `_
+
+* ``py::is_final()`` class modifier to block subclassing (CPython only).
+ `#2151 `_
+
+* ``py::memoryview`` update and documentation.
+ `#2223 `_
+
+* The Python package was reworked to be more powerful and useful.
+ `#2433 `_
+
+ * :ref:`build-setuptools` is easier thanks to a new
+ ``pybind11.setup_helpers`` module, which provides utilities to use
+ setuptools with pybind11. It can be used via PEP 518, ``setup_requires``,
+ or by directly copying ``setup_helpers.py`` into your project.
+
+ * CMake configuration files are now included in the Python package. Use
+ ``pybind11.get_cmake_dir()`` or ``python -m pybind11 --cmakedir`` to get
+ the directory with the CMake configuration files, or include the
+ site-packages location in your ``CMAKE_MODULE_PATH``. Or you can use the
+ new ``pybind11[global]`` extra when you install ``pybind11``, which
+ installs the CMake files and headers into your base environment in the
+ standard location
+
+ * ``pybind11-config`` is another way to write ``python -m pybind11`` if you
+ have your PATH set up.
+
+* Minimum CMake required increased to 3.4.
+ `#2338 `_ and
+ `#2370 `_
+
+ * Full integration with CMake’s C++ standard system replaces
+ ``PYBIND11_CPP_STANDARD``.
+
+ * Generated config file is now portable to different Python/compiler/CMake
+ versions.
+
+ * Virtual environments prioritized if ``PYTHON_EXECUTABLE`` is not set
+ (``venv``, ``virtualenv``, and ``conda``) (similar to the new FindPython
+ mode).
+
+ * Other CMake features now natively supported, like
+ ``CMAKE_INTERPROCEDURAL_OPTIMIZATION``, ``set(CMAKE_CXX_VISIBILITY_PRESET
+ hidden)``.
+
+* Optional :ref:`find-python-mode` and :ref:`nopython-mode` with CMake.
+ `#2370 `_
+
+* Uninstall target added.
+ `#2265 `_ and
+ `#2346 `_
+
+* ``PYBIND11_OVERLOAD*`` macros and ``get_overload`` function replaced by
+ correctly-named ``PYBIND11_OVERRIDE*`` and ``get_override``, fixing
+ inconsistencies in the presene of a closing ``;`` in these macros.
+ ``get_type_overload`` is deprecated.
+ `#2325 `_
+
+Smaller or developer focused features:
+
+* Moved ``mkdoc.py`` to a new repo, `pybind11-mkdoc`_.
+
+.. _pybind11-mkdoc: https://github.com/pybind/pybind11-mkdoc
+
+* Error now thrown when ``__init__`` is forgotten on subclasses.
+ `#2152 `_
+
+* If ``__eq__`` defined but not ``__hash__``, ``__hash__`` is now set to
+ ``None``.
+ `#2291 `_
+
+* ``py::ellipsis`` now also works on Python 2.
+ `#2360 `_
+
+* Throw if conversion to ``str`` fails.
+ `#2477 `_
+
+* Added missing signature for ``py::array``.
+ `#2363 `_
+
+* Pointer to ``std::tuple`` & ``std::pair`` supported in cast.
+ `#2334 `_
+
+* Small fixes in NumPy support. ``py::array`` now uses ``py::ssize_t`` as first
+ argument type.
+ `#2293 `_
+
+* Bugfixes related to more extensive testing
+ `#2321 `_
+
+* Bug in timezone issue in Eastern hemisphere midnight fixed.
+ `#2438 `_
+
+* ``std::chrono::time_point`` now works when the resolution is not the same as
+ the system.
+ `#2481 `_
+
+* Bug fixed where ``py::array_t`` could accept arrays that did not match the
+ requested ordering.
+ `#2484 `_
+
+* PyPy fixes, including support for PyPy3 and PyPy 7.
+ `#2146 `_
+
+* CPython 3.9 fixes.
+ `#2253 `_
+
+* More C++20 support.
+ `#2489 `_
+
+* Debug Python interpreter support.
+ `#2025 `_
+
+* NVCC (CUDA 11) now supported and tested in CI.
+ `#2461 `_
+
+* NVIDIA PGI compilers now supported and tested in CI.
+ `#2475 `_
+
+* Extensive style checking in CI, with `pre-commit`_ support.
+
+.. _pre-commit: https://pre-commit.com
+
+
+
v2.5.0 (Mar 31, 2020)
-----------------------------------------------------
@@ -536,7 +695,7 @@ v2.2.0 (August 31, 2017)
in reference cycles.
`#856 `_.
-* Numpy and buffer protocol related improvements:
+* NumPy and buffer protocol related improvements:
1. Support for negative strides in Python buffer objects/numpy arrays. This
required changing integers from unsigned to signed for the related C++ APIs.
@@ -1267,7 +1426,7 @@ Happy Christmas!
* Improved support for ``std::shared_ptr<>`` conversions
* Initial support for ``std::set<>`` conversions
* Fixed type resolution issue for types defined in a separate plugin module
-* Cmake build system improvements
+* CMake build system improvements
* Factored out generic functionality to non-templated code (smaller code size)
* Added a code size / compile time benchmark vs Boost.Python
* Added an appveyor CI script
diff --git a/wrap/pybind11/docs/classes.rst b/wrap/pybind11/docs/classes.rst
index a63f6a1969..f3610ef367 100644
--- a/wrap/pybind11/docs/classes.rst
+++ b/wrap/pybind11/docs/classes.rst
@@ -74,7 +74,7 @@ Note how ``print(p)`` produced a rather useless summary of our data structure in
>>> print(p)
-To address this, we could bind an utility function that returns a human-readable
+To address this, we could bind a utility function that returns a human-readable
summary to the special method slot named ``__repr__``. Unfortunately, there is no
suitable functionality in the ``Pet`` data structure, and it would be nice if
we did not have to change it. This can easily be accomplished by binding a
@@ -373,8 +373,8 @@ sequence.
py::class_(m, "Pet")
.def(py::init())
- .def("set", (void (Pet::*)(int)) &Pet::set, "Set the pet's age")
- .def("set", (void (Pet::*)(const std::string &)) &Pet::set, "Set the pet's name");
+ .def("set", static_cast(&Pet::set), "Set the pet's age")
+ .def("set", static_cast(&Pet::set), "Set the pet's name");
The overload signatures are also visible in the method's docstring:
diff --git a/wrap/pybind11/docs/compiling.rst b/wrap/pybind11/docs/compiling.rst
index bfb1cd8056..cbf14a466b 100644
--- a/wrap/pybind11/docs/compiling.rst
+++ b/wrap/pybind11/docs/compiling.rst
@@ -3,6 +3,8 @@
Build systems
#############
+.. _build-setuptools:
+
Building with setuptools
========================
@@ -13,6 +15,135 @@ the [python_example]_ repository.
.. [python_example] https://github.com/pybind/python_example
+A helper file is provided with pybind11 that can simplify usage with setuptools.
+
+To use pybind11 inside your ``setup.py``, you have to have some system to
+ensure that ``pybind11`` is installed when you build your package. There are
+four possible ways to do this, and pybind11 supports all four: You can ask all
+users to install pybind11 beforehand (bad), you can use
+:ref:`setup_helpers-pep518` (good, but very new and requires Pip 10),
+:ref:`setup_helpers-setup_requires` (discouraged by Python packagers now that
+PEP 518 is available, but it still works everywhere), or you can
+:ref:`setup_helpers-copy-manually` (always works but you have to manually sync
+your copy to get updates).
+
+An example of a ``setup.py`` using pybind11's helpers:
+
+.. code-block:: python
+
+ from setuptools import setup
+ from pybind11.setup_helpers import Pybind11Extension
+
+ ext_modules = [
+ Pybind11Extension(
+ "python_example",
+ ["src/main.cpp"],
+ ),
+ ]
+
+ setup(
+ ...,
+ ext_modules=ext_modules
+ )
+
+If you want to do an automatic search for the highest supported C++ standard,
+that is supported via a ``build_ext`` command override; it will only affect
+``Pybind11Extensions``:
+
+.. code-block:: python
+
+ from setuptools import setup
+ from pybind11.setup_helpers import Pybind11Extension, build_ext
+
+ ext_modules = [
+ Pybind11Extension(
+ "python_example",
+ ["src/main.cpp"],
+ ),
+ ]
+
+ setup(
+ ...,
+ cmdclass={"build_ext": build_ext},
+ ext_modules=ext_modules
+ )
+
+.. _setup_helpers-pep518:
+
+PEP 518 requirements (Pip 10+ required)
+---------------------------------------
+
+If you use `PEP 518's `_
+``pyproject.toml`` file, you can ensure that ``pybind11`` is available during
+the compilation of your project. When this file exists, Pip will make a new
+virtual environment, download just the packages listed here in ``requires=``,
+and build a wheel (binary Python package). It will then throw away the
+environment, and install your wheel.
+
+Your ``pyproject.toml`` file will likely look something like this:
+
+.. code-block:: toml
+
+ [build-system]
+ requires = ["setuptools", "wheel", "pybind11==2.6.0"]
+ build-backend = "setuptools.build_meta"
+
+.. note::
+
+ The main drawback to this method is that a `PEP 517`_ compliant build tool,
+ such as Pip 10+, is required for this approach to work; older versions of
+ Pip completely ignore this file. If you distribute binaries (called wheels
+ in Python) using something like `cibuildwheel`_, remember that ``setup.py``
+ and ``pyproject.toml`` are not even contained in the wheel, so this high
+ Pip requirement is only for source builds, and will not affect users of
+ your binary wheels.
+
+.. _PEP 517: https://www.python.org/dev/peps/pep-0517/
+.. _cibuildwheel: https://cibuildwheel.readthedocs.io
+
+.. _setup_helpers-setup_requires:
+
+Classic ``setup_requires``
+--------------------------
+
+If you want to support old versions of Pip with the classic
+``setup_requires=["pybind11"]`` keyword argument to setup, which triggers a
+two-phase ``setup.py`` run, then you will need to use something like this to
+ensure the first pass works (which has not yet installed the ``setup_requires``
+packages, since it can't install something it does not know about):
+
+.. code-block:: python
+
+ try:
+ from pybind11.setup_helpers import Pybind11Extension
+ except ImportError:
+ from setuptools import Extension as Pybind11Extension
+
+
+It doesn't matter that the Extension class is not the enhanced subclass for the
+first pass run; and the second pass will have the ``setup_requires``
+requirements.
+
+This is obviously more of a hack than the PEP 518 method, but it supports
+ancient versions of Pip.
+
+.. _setup_helpers-copy-manually:
+
+Copy manually
+-------------
+
+You can also copy ``setup_helpers.py`` directly to your project; it was
+designed to be usable standalone, like the old example ``setup.py``. You can
+set ``include_pybind11=False`` to skip including the pybind11 package headers,
+so you can use it with git submodules and a specific git version. If you use
+this, you will need to import from a local file in ``setup.py`` and ensure the
+helper file is part of your MANIFEST.
+
+
+.. versionchanged:: 2.6
+
+ Added ``setup_helpers`` file.
+
Building with cppimport
========================
@@ -33,8 +164,8 @@ extension module can be created with just a few lines of code:
.. code-block:: cmake
- cmake_minimum_required(VERSION 2.8.12)
- project(example)
+ cmake_minimum_required(VERSION 3.4...3.18)
+ project(example LANGUAGES CXX)
add_subdirectory(pybind11)
pybind11_add_module(example example.cpp)
@@ -50,6 +181,9 @@ PyPI integration, can be found in the [cmake_example]_ repository.
.. [cmake_example] https://github.com/pybind/cmake_example
+.. versionchanged:: 2.6
+ CMake 3.4+ is required.
+
pybind11_add_module
-------------------
@@ -59,7 +193,7 @@ function with the following signature:
.. code-block:: cmake
pybind11_add_module( [MODULE | SHARED] [EXCLUDE_FROM_ALL]
- [NO_EXTRAS] [SYSTEM] [THIN_LTO] source1 [source2 ...])
+ [NO_EXTRAS] [THIN_LTO] [OPT_SIZE] source1 [source2 ...])
This function behaves very much like CMake's builtin ``add_library`` (in fact,
it's a wrapper function around that command). It will add a library target
@@ -86,49 +220,62 @@ latter optimizations are never applied in ``Debug`` mode. If ``NO_EXTRAS`` is
given, they will always be disabled, even in ``Release`` mode. However, this
will result in code bloat and is generally not recommended.
-By default, pybind11 and Python headers will be included with ``-I``. In order
-to include pybind11 as system library, e.g. to avoid warnings in downstream
-code with warn-levels outside of pybind11's scope, set the option ``SYSTEM``.
-
As stated above, LTO is enabled by default. Some newer compilers also support
different flavors of LTO such as `ThinLTO`_. Setting ``THIN_LTO`` will cause
the function to prefer this flavor if available. The function falls back to
-regular LTO if ``-flto=thin`` is not available.
+regular LTO if ``-flto=thin`` is not available. If
+``CMAKE_INTERPROCEDURAL_OPTIMIZATION`` is set (either ON or OFF), then that
+will be respected instead of the built-in flag search.
+
+The ``OPT_SIZE`` flag enables size-based optimization equivalent to the
+standard ``/Os`` or ``-Os`` compiler flags and the ``MinSizeRel`` build type,
+which avoid optimizations that that can substantially increase the size of the
+resulting binary. This flag is particularly useful in projects that are split
+into performance-critical parts and associated bindings. In this case, we can
+compile the project in release mode (and hence, optimize performance globally),
+and specify ``OPT_SIZE`` for the binding target, where size might be the main
+concern as performance is often less critical here. A ~25% size reduction has
+been observed in practice. This flag only changes the optimization behavior at
+a per-target level and takes precedence over the global CMake build type
+(``Release``, ``RelWithDebInfo``) except for ``Debug`` builds, where
+optimizations remain disabled.
.. _ThinLTO: http://clang.llvm.org/docs/ThinLTO.html
Configuration variables
-----------------------
-By default, pybind11 will compile modules with the C++14 standard, if available
-on the target compiler, falling back to C++11 if C++14 support is not
-available. Note, however, that this default is subject to change: future
-pybind11 releases are expected to migrate to newer C++ standards as they become
-available. To override this, the standard flag can be given explicitly in
-`CMAKE_CXX_STANDARD `_:
+By default, pybind11 will compile modules with the compiler default or the
+minimum standard required by pybind11, whichever is higher. You can set the
+standard explicitly with
+`CMAKE_CXX_STANDARD `_:
.. code-block:: cmake
- # Use just one of these:
- set(CMAKE_CXX_STANDARD 11)
- set(CMAKE_CXX_STANDARD 14)
- set(CMAKE_CXX_STANDARD 17) # Experimental C++17 support
+ set(CMAKE_CXX_STANDARD 14) # or 11, 14, 17, 20
+ set(CMAKE_CXX_STANDARD_REQUIRED ON) # optional, ensure standard is supported
+ set(CMAKE_CXX_EXTENSIONS OFF) # optional, keep compiler extensionsn off
- add_subdirectory(pybind11) # or find_package(pybind11)
-Note that this and all other configuration variables must be set **before** the
-call to ``add_subdirectory`` or ``find_package``. The variables can also be set
-when calling CMake from the command line using the ``-D=`` flag.
+The variables can also be set when calling CMake from the command line using
+the ``-D=`` flag. You can also manually set ``CXX_STANDARD``
+on a target or use ``target_compile_features`` on your targets - anything that
+CMake supports.
-The target Python version can be selected by setting ``PYBIND11_PYTHON_VERSION``
-or an exact Python installation can be specified with ``PYTHON_EXECUTABLE``.
-For example:
+Classic Python support: The target Python version can be selected by setting
+``PYBIND11_PYTHON_VERSION`` or an exact Python installation can be specified
+with ``PYTHON_EXECUTABLE``. For example:
.. code-block:: bash
cmake -DPYBIND11_PYTHON_VERSION=3.6 ..
- # or
- cmake -DPYTHON_EXECUTABLE=path/to/python ..
+
+ # Another method:
+ cmake -DPYTHON_EXECUTABLE=/path/to/python ..
+
+ # This often is a good way to get the current Python, works in environments:
+ cmake -DPYTHON_EXECUTABLE=$(python3 -c "import sys; print(sys.executable)") ..
+
find_package vs. add_subdirectory
---------------------------------
@@ -139,8 +286,8 @@ See the `Config file`_ docstring for details of relevant CMake variables.
.. code-block:: cmake
- cmake_minimum_required(VERSION 2.8.12)
- project(example)
+ cmake_minimum_required(VERSION 3.4...3.18)
+ project(example LANGUAGES CXX)
find_package(pybind11 REQUIRED)
pybind11_add_module(example example.cpp)
@@ -151,12 +298,19 @@ the pybind11 repository :
.. code-block:: bash
+ # Classic CMake
cd pybind11
mkdir build
cd build
cmake ..
make install
+ # CMake 3.15+
+ cd pybind11
+ cmake -S . -B build
+ cmake --build build -j 2 # Build on 2 cores
+ cmake --install build
+
Once detected, the aforementioned ``pybind11_add_module`` can be employed as
before. The function usage and configuration variables are identical no matter
if pybind11 is added as a subdirectory or found as an installed package. You
@@ -165,41 +319,134 @@ can refer to the same [cmake_example]_ repository for a full sample project
.. _Config file: https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in
-Advanced: interface library target
-----------------------------------
-When using a version of CMake greater than 3.0, pybind11 can additionally
-be used as a special *interface library* . The target ``pybind11::module``
-is available with pybind11 headers, Python headers and libraries as needed,
-and C++ compile definitions attached. This target is suitable for linking
-to an independently constructed (through ``add_library``, not
-``pybind11_add_module``) target in the consuming project.
+.. _find-python-mode:
+
+FindPython mode
+---------------
+
+CMake 3.12+ (3.15+ recommended) added a new module called FindPython that had a
+highly improved search algorithm and modern targets and tools. If you use
+FindPython, pybind11 will detect this and use the existing targets instead:
.. code-block:: cmake
- cmake_minimum_required(VERSION 3.0)
- project(example)
+ cmake_minumum_required(VERSION 3.15...3.18)
+ project(example LANGUAGES CXX)
+
+ find_package(Python COMPONENTS Interpreter Development REQUIRED)
+ find_package(pybind11 CONFIG REQUIRED)
+ # or add_subdirectory(pybind11)
+
+ pybind11_add_module(example example.cpp)
+
+You can also use the targets (as listed below) with FindPython. If you define
+``PYBIND11_FINDPYTHON``, pybind11 will perform the FindPython step for you
+(mostly useful when building pybind11's own tests, or as a way to change search
+algorithms from the CMake invocation, with ``-DPYBIND11_FINDPYTHON=ON``.
+
+.. warning::
+
+ If you use FindPython2 and FindPython3 to dual-target Python, use the
+ individual targets listed below, and avoid targets that directly include
+ Python parts.
+
+There are `many ways to hint or force a discovery of a specific Python
+installation `_),
+setting ``Python_ROOT_DIR`` may be the most common one (though with
+virtualenv/venv support, and Conda support, this tends to find the correct
+Python version more often than the old system did).
+
+.. versionadded:: 2.6
+
+Advanced: interface library targets
+-----------------------------------
+
+Pybind11 supports modern CMake usage patterns with a set of interface targets,
+available in all modes. The targets provided are:
+
+ ``pybind11::headers``
+ Just the pybind11 headers and minimum compile requirements
+
+ ``pybind11::python2_no_register``
+ Quiets the warning/error when mixing C++14 or higher and Python 2
+
+ ``pybind11::pybind11``
+ Python headers + ``pybind11::headers`` + ``pybind11::python2_no_register`` (Python 2 only)
+
+ ``pybind11::python_link_helper``
+ Just the "linking" part of pybind11:module
+
+ ``pybind11::module``
+ Everything for extension modules - ``pybind11::pybind11`` + ``Python::Module`` (FindPython CMake 3.15+) or ``pybind11::python_link_helper``
+
+ ``pybind11::embed``
+ Everything for embedding the Python interpreter - ``pybind11::pybind11`` + ``Python::Embed`` (FindPython) or Python libs
+
+ ``pybind11::lto`` / ``pybind11::thin_lto``
+ An alternative to `INTERPROCEDURAL_OPTIMIZATION` for adding link-time optimization.
+
+ ``pybind11::windows_extras``
+ ``/bigobj`` and ``/mp`` for MSVC.
+
+ ``pybind11::opt_size``
+ ``/Os`` for MSVC, ``-Os`` for other compilers. Does nothing for debug builds.
+
+Two helper functions are also provided:
+
+ ``pybind11_strip(target)``
+ Strips a target (uses ``CMAKE_STRIP`` after the target is built)
+
+ ``pybind11_extension(target)``
+ Sets the correct extension (with SOABI) for a target.
+
+You can use these targets to build complex applications. For example, the
+``add_python_module`` function is identical to:
+
+.. code-block:: cmake
+
+ cmake_minimum_required(VERSION 3.4)
+ project(example LANGUAGES CXX)
find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11)
add_library(example MODULE main.cpp)
- target_link_libraries(example PRIVATE pybind11::module)
- set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}"
- SUFFIX "${PYTHON_MODULE_EXTENSION}")
+
+ target_link_libraries(example PRIVATE pybind11::module pybind11::lto pybind11::windows_extras)
+
+ pybind11_extension(example)
+ pybind11_strip(example)
+
+ set_target_properties(example PROPERTIES CXX_VISIBILITY_PRESET "hidden"
+ CUDA_VISIBILITY_PRESET "hidden")
+
+Instead of setting properties, you can set ``CMAKE_*`` variables to initialize these correctly.
.. warning::
Since pybind11 is a metatemplate library, it is crucial that certain
compiler flags are provided to ensure high quality code generation. In
contrast to the ``pybind11_add_module()`` command, the CMake interface
- library only provides the *minimal* set of parameters to ensure that the
- code using pybind11 compiles, but it does **not** pass these extra compiler
- flags (i.e. this is up to you).
+ provides a *composable* set of targets to ensure that you retain flexibility.
+ It can be expecially important to provide or set these properties; the
+ :ref:`FAQ ` contains an explanation on why these are needed.
+
+.. versionadded:: 2.6
+
+.. _nopython-mode:
+
+Advanced: NOPYTHON mode
+-----------------------
+
+If you want complete control, you can set ``PYBIND11_NOPYTHON`` to completely
+disable Python integration (this also happens if you run ``FindPython2`` and
+``FindPython3`` without running ``FindPython``). This gives you complete
+freedom to integrate into an existing system (like `Scikit-Build's
+`_ ``PythonExtensions``).
+``pybind11_add_module`` and ``pybind11_extension`` will be unavailable, and the
+targets will be missing any Python specific behavior.
- These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL``
- and ``/LTCG`` on Visual Studio) and .OBJ files with many sections on Visual
- Studio (``/bigobj``). The :ref:`FAQ ` contains an
- explanation on why these are needed.
+.. versionadded:: 2.6
Embedding the Python interpreter
--------------------------------
@@ -213,8 +460,8 @@ information about usage in C++, see :doc:`/advanced/embedding`.
.. code-block:: cmake
- cmake_minimum_required(VERSION 3.0)
- project(example)
+ cmake_minimum_required(VERSION 3.4...3.18)
+ project(example LANGUAGES CXX)
find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11)
@@ -251,7 +498,7 @@ Besides, the ``--extension-suffix`` option may or may not be available, dependin
on the distribution; in the latter case, the module extension can be manually
set to ``.so``.
-On Mac OS: the build command is almost the same but it also requires passing
+On macOS: the build command is almost the same but it also requires passing
the ``-undefined dynamic_lookup`` flag so as to ignore missing symbols when
building the module:
@@ -275,6 +522,25 @@ build system that works on all platforms including Windows.
of possibly importing a second Python library into a process that already
contains one (which will lead to a segfault).
+
+Building with vcpkg
+===================
+You can download and install pybind11 using the Microsoft `vcpkg
+`_ dependency manager:
+
+.. code-block:: bash
+
+ git clone https://github.com/Microsoft/vcpkg.git
+ cd vcpkg
+ ./bootstrap-vcpkg.sh
+ ./vcpkg integrate install
+ vcpkg install pybind11
+
+The pybind11 port in vcpkg is kept up to date by Microsoft team members and
+community contributors. If the version is out of date, please `create an issue
+or pull request `_ on the vcpkg
+repository.
+
Generating binding code automatically
=====================================
@@ -291,3 +557,10 @@ extensible, and applies to very complex C++ libraries, composed of thousands of
classes or incorporating modern meta-programming constructs.
.. [AutoWIG] https://github.com/StatisKit/AutoWIG
+
+[robotpy-build]_ is a is a pure python, cross platform build tool that aims to
+simplify creation of python wheels for pybind11 projects, and provide
+cross-project dependency management. Additionally, it is able to autogenerate
+customizable pybind11-based wrappers by parsing C++ header files.
+
+.. [robotpy-build] https://robotpy-build.readthedocs.io
diff --git a/wrap/pybind11/docs/faq.rst b/wrap/pybind11/docs/faq.rst
index b68562910a..5f7866fa76 100644
--- a/wrap/pybind11/docs/faq.rst
+++ b/wrap/pybind11/docs/faq.rst
@@ -285,7 +285,7 @@ CMake code. Conflicts can arise, however, when using pybind11 in a project that
Python detection in a system with several Python versions installed.
This difference may cause inconsistencies and errors if *both* mechanisms are used in the same project. Consider the following
-Cmake code executed in a system with Python 2.7 and 3.x installed:
+CMake code executed in a system with Python 2.7 and 3.x installed:
.. code-block:: cmake
diff --git a/wrap/pybind11/docs/reference.rst b/wrap/pybind11/docs/reference.rst
index a9fbe60015..e3a61afb6b 100644
--- a/wrap/pybind11/docs/reference.rst
+++ b/wrap/pybind11/docs/reference.rst
@@ -46,7 +46,7 @@ With reference counting
Convenience classes for specific Python types
=============================================
-.. doxygenclass:: module
+.. doxygenclass:: module_
:members:
.. doxygengroup:: pytypes
@@ -91,15 +91,15 @@ Inheritance
See :doc:`/classes` and :doc:`/advanced/classes` for more detail.
-.. doxygendefine:: PYBIND11_OVERLOAD
+.. doxygendefine:: PYBIND11_OVERRIDE
-.. doxygendefine:: PYBIND11_OVERLOAD_PURE
+.. doxygendefine:: PYBIND11_OVERRIDE_PURE
-.. doxygendefine:: PYBIND11_OVERLOAD_NAME
+.. doxygendefine:: PYBIND11_OVERRIDE_NAME
-.. doxygendefine:: PYBIND11_OVERLOAD_PURE_NAME
+.. doxygendefine:: PYBIND11_OVERRIDE_PURE_NAME
-.. doxygenfunction:: get_overload
+.. doxygenfunction:: get_override
Exceptions
==========
diff --git a/wrap/pybind11/docs/requirements.txt b/wrap/pybind11/docs/requirements.txt
index 3818fe80ee..f4c3dc2e0b 100644
--- a/wrap/pybind11/docs/requirements.txt
+++ b/wrap/pybind11/docs/requirements.txt
@@ -1 +1,5 @@
-breathe == 4.5.0
+breathe==4.20.0
+commonmark==0.9.1
+recommonmark==0.6.0
+sphinx==3.2.1
+sphinx_rtd_theme==0.5.0
diff --git a/wrap/pybind11/docs/upgrade.rst b/wrap/pybind11/docs/upgrade.rst
index 3f5697391b..62e2312e94 100644
--- a/wrap/pybind11/docs/upgrade.rst
+++ b/wrap/pybind11/docs/upgrade.rst
@@ -8,6 +8,92 @@ 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.6:
+
+v2.6
+====
+
+The ``tools/clang`` submodule and ``tools/mkdoc.py`` have been moved to a
+standalone package, `pybind11-mkdoc`_. If you were using those tools, please
+use them via a pip install from the new location.
+
+.. _pybind11-mkdoc: https://github.com/pybind/pybind11-mkdoc
+
+An error is now thrown when ``__init__`` is forgotten on subclasses. This was
+incorrect before, but was not checked. Add a call to ``__init__`` if it is
+missing.
+
+The undocumented ``h.get_type()`` method has been deprecated and replaced by
+``py::type::of(h)``.
+
+If ``__eq__`` defined but not ``__hash__``, ``__hash__`` is now set to
+``None``, as in normal CPython. You should add ``__hash__`` if you intended the
+class to be hashable, possibly using the new ``py::hash`` shortcut.
+
+Usage of the ``PYBIND11_OVERLOAD*`` macros and ``get_overload`` function should
+be replaced by ``PYBIND11_OVERRIDE*`` and ``get_override``. In the future, the
+old macros may be deprecated and removed.
+
+The ``pybind11`` package on PyPI no longer fills the wheel "headers" slot - if
+you were using the headers from this slot, they are available by requesting the
+``global`` extra, that is, ``pip install "pybind11[global]"``. (Most users will
+be unaffected, as the ``pybind11/include`` location is reported by ``python -m
+pybind11 --includes`` and ``pybind11.get_include()`` is still correct and has
+not changed since 2.5).
+
+CMake support:
+--------------
+
+The minimum required version of CMake is now 3.4. Several details of the CMake
+support have been deprecated; warnings will be shown if you need to change
+something. The changes are:
+
+* ``PYBIND11_CPP_STANDARD=`` is deprecated, please use
+ ``CMAKE_CXX_STANDARD=`` instead, or any other valid CMake CXX or CUDA
+ standard selection method, like ``target_compile_features``.
+
+* If you do not request a standard, pybind11 targets will compile with the
+ compiler default, but not less than C++11, instead of forcing C++14 always.
+ If you depend on the old behavior, please use ``set(CMAKE_CXX_STANDARD 14)``
+ instead.
+
+* Direct ``pybind11::module`` usage should always be accompanied by at least
+ ``set(CMAKE_CXX_VISIBILITY_PRESET hidden)`` or similar - it used to try to
+ manually force this compiler flag (but not correctly on all compilers or with
+ CUDA).
+
+* ``pybind11_add_module``'s ``SYSTEM`` argument is deprecated and does nothing;
+ linking now behaves like other imported libraries consistently in both
+ config and submodule mode, and behaves like a ``SYSTEM`` library by
+ default.
+
+* If ``PYTHON_EXECUTABLE`` is not set, virtual environments (``venv``,
+ ``virtualenv``, and ``conda``) are prioritized over the standard search
+ (similar to the new FindPython mode).
+
+In addition, the following changes may be of interest:
+
+* ``CMAKE_INTERPROCEDURAL_OPTIMIZATION`` will be respected by
+ ``pybind11_add_module`` if set instead of linking to ``pybind11::lto`` or
+ ``pybind11::thin_lto``.
+
+* Using ``find_package(Python COMPONENTS Interpreter Development)`` before
+ pybind11 will cause pybind11 to use the new Python mechanisms instead of its
+ own custom search, based on a patched version of classic ``FindPythonInterp``
+ / ``FindPythonLibs``. In the future, this may become the default.
+
+
+
+v2.5
+====
+
+The Python package now includes the headers as data in the package itself, as
+well as in the "headers" wheel slot. ``pybind11 --includes`` and
+``pybind11.get_include()`` report the new location, which is always correct
+regardless of how pybind11 was installed, making the old ``user=`` argument
+meaningless. If you are not using the function to get the location already, you
+are encouraged to switch to the package location.
+
v2.2
====
diff --git a/wrap/pybind11/include/pybind11/attr.h b/wrap/pybind11/include/pybind11/attr.h
index 54065fc9e1..d0a8b34b8f 100644
--- a/wrap/pybind11/include/pybind11/attr.h
+++ b/wrap/pybind11/include/pybind11/attr.h
@@ -40,8 +40,9 @@ struct sibling { handle value; sibling(const handle &value) : value(value.ptr())
/// Annotation indicating that a class derives from another given type
template struct base {
+
PYBIND11_DEPRECATED("base() was deprecated in favor of specifying 'T' as a template argument to class_")
- base() { }
+ base() { } // NOLINT(modernize-use-equals-default): breaks MSVC 2015 when adding an attribute
};
/// Keep patient alive while nurse lives
@@ -61,7 +62,7 @@ struct metaclass {
handle value;
PYBIND11_DEPRECATED("py::metaclass() is no longer required. It's turned on by default now.")
- metaclass() {}
+ metaclass() { } // NOLINT(modernize-use-equals-default): breaks MSVC 2015 when adding an attribute
/// Override pybind11's default metaclass
explicit metaclass(handle value) : value(value) { }
@@ -138,7 +139,7 @@ struct function_record {
function_record()
: is_constructor(false), is_new_style_constructor(false), is_stateless(false),
is_operator(false), is_method(false),
- has_args(false), has_kwargs(false), has_kwonly_args(false) { }
+ has_args(false), has_kwargs(false), has_kw_only_args(false) { }
/// Function name
char *name = nullptr; /* why no C++ strings? They generate heavier code.. */
@@ -185,14 +186,17 @@ struct function_record {
/// True if the function has a '**kwargs' argument
bool has_kwargs : 1;
- /// True once a 'py::kwonly' is encountered (any following args are keyword-only)
- bool has_kwonly_args : 1;
+ /// True once a 'py::kw_only' is encountered (any following args are keyword-only)
+ bool has_kw_only_args : 1;
/// Number of arguments (including py::args and/or py::kwargs, if present)
std::uint16_t nargs;
/// Number of trailing arguments (counted in `nargs`) that are keyword-only
- std::uint16_t nargs_kwonly = 0;
+ std::uint16_t nargs_kw_only = 0;
+
+ /// Number of leading arguments (counted in `nargs`) that are positional-only
+ std::uint16_t nargs_pos_only = 0;
/// Python method object
PyMethodDef *def = nullptr;
@@ -366,10 +370,10 @@ template <> struct process_attribute : process_attribu
static void init(const is_new_style_constructor &, function_record *r) { r->is_new_style_constructor = true; }
};
-inline void process_kwonly_arg(const arg &a, function_record *r) {
+inline void process_kw_only_arg(const arg &a, function_record *r) {
if (!a.name || strlen(a.name) == 0)
- pybind11_fail("arg(): cannot specify an unnamed argument after an kwonly() annotation");
- ++r->nargs_kwonly;
+ pybind11_fail("arg(): cannot specify an unnamed argument after an kw_only() annotation");
+ ++r->nargs_kw_only;
}
/// Process a keyword argument attribute (*without* a default value)
@@ -379,7 +383,7 @@ template <> struct process_attribute : process_attribute_default {
r->args.emplace_back("self", nullptr, handle(), true /*convert*/, false /*none not allowed*/);
r->args.emplace_back(a.name, nullptr, handle(), !a.flag_noconvert, a.flag_none);
- if (r->has_kwonly_args) process_kwonly_arg(a, r);
+ if (r->has_kw_only_args) process_kw_only_arg(a, r);
}
};
@@ -412,14 +416,21 @@ template <> struct process_attribute : process_attribute_default {
}
r->args.emplace_back(a.name, a.descr, a.value.inc_ref(), !a.flag_noconvert, a.flag_none);
- if (r->has_kwonly_args) process_kwonly_arg(a, r);
+ if (r->has_kw_only_args) process_kw_only_arg(a, r);
}
};
/// Process a keyword-only-arguments-follow pseudo argument
-template <> struct process_attribute : process_attribute_default {
- static void init(const kwonly &, function_record *r) {
- r->has_kwonly_args = true;
+template <> struct process_attribute : process_attribute_default {
+ static void init(const kw_only &, function_record *r) {
+ r->has_kw_only_args = true;
+ }
+};
+
+/// Process a positional-only-argument maker
+template <> struct process_attribute : process_attribute_default {
+ static void init(const pos_only &, function_record *r) {
+ r->nargs_pos_only = static_cast(r->args.size());
}
};
diff --git a/wrap/pybind11/include/pybind11/buffer_info.h b/wrap/pybind11/include/pybind11/buffer_info.h
index 8349a46b8b..308be06a33 100644
--- a/wrap/pybind11/include/pybind11/buffer_info.h
+++ b/wrap/pybind11/include/pybind11/buffer_info.h
@@ -24,7 +24,7 @@ struct buffer_info {
std::vector strides; // Number of bytes between adjacent entries (for each per dimension)
bool readonly = false; // flag to indicate if the underlying storage may be written to
- buffer_info() { }
+ buffer_info() = default;
buffer_info(void *ptr, ssize_t itemsize, const std::string &format, ssize_t ndim,
detail::any_container shape_in, detail::any_container strides_in, bool readonly=false)
diff --git a/wrap/pybind11/include/pybind11/cast.h b/wrap/pybind11/include/pybind11/cast.h
index d788992df1..b071008e67 100644
--- a/wrap/pybind11/include/pybind11/cast.h
+++ b/wrap/pybind11/include/pybind11/cast.h
@@ -59,7 +59,7 @@ class loader_life_support {
Py_CLEAR(ptr);
// A heuristic to reduce the stack's capacity (e.g. after long recursive calls)
- if (stack.capacity() > 16 && stack.size() != 0 && stack.capacity() / stack.size() > 2)
+ if (stack.capacity() > 16 && !stack.empty() && stack.capacity() / stack.size() > 2)
stack.shrink_to_fit();
}
@@ -163,7 +163,7 @@ inline const std::vector &all_type_info(PyTypeObject *type)
*/
PYBIND11_NOINLINE inline detail::type_info* get_type_info(PyTypeObject *type) {
auto &bases = all_type_info(type);
- if (bases.size() == 0)
+ if (bases.empty())
return nullptr;
if (bases.size() > 1)
pybind11_fail("pybind11::detail::get_type_info: type has multiple pybind11-registered bases");
@@ -220,7 +220,7 @@ struct value_and_holder {
{}
// Default constructor (used to signal a value-and-holder not found by get_value_and_holder())
- value_and_holder() {}
+ value_and_holder() = default;
// Used for past-the-end iterator
value_and_holder(size_t index) : index{index} {}
@@ -432,7 +432,7 @@ PYBIND11_NOINLINE inline std::string error_string() {
#if !defined(PYPY_VERSION)
if (scope.trace) {
- PyTracebackObject *trace = (PyTracebackObject *) scope.trace;
+ auto *trace = (PyTracebackObject *) scope.trace;
/* Get the deepest trace possible */
while (trace->tb_next)
@@ -458,7 +458,7 @@ PYBIND11_NOINLINE inline handle get_object_handle(const void *ptr, const detail:
auto &instances = get_internals().registered_instances;
auto range = instances.equal_range(ptr);
for (auto it = range.first; it != range.second; ++it) {
- for (auto vh : values_and_holders(it->second)) {
+ for (const auto &vh : values_and_holders(it->second)) {
if (vh.type == type)
return handle((PyObject *) it->second);
}
@@ -636,7 +636,7 @@ class type_caster_generic {
/// native typeinfo, or when the native one wasn't able to produce a value.
PYBIND11_NOINLINE bool try_load_foreign_module_local(handle src) {
constexpr auto *local_key = PYBIND11_MODULE_LOCAL_ID;
- const auto pytype = src.get_type();
+ const auto pytype = type::handle_of(src);
if (!hasattr(pytype, local_key))
return false;
@@ -1006,6 +1006,7 @@ template using is_std_char_type = any_of<
std::is_same /* std::wstring */
>;
+
template
struct type_caster::value && !is_std_char_type::value>> {
using _py_type_0 = conditional_t;
@@ -1034,12 +1035,12 @@ struct type_caster::value && !is_std_char_t
: (py_type) PYBIND11_LONG_AS_LONGLONG(src.ptr());
}
+ // Python API reported an error
bool py_err = py_value == (py_type) -1 && PyErr_Occurred();
- // Protect std::numeric_limits::min/max with parentheses
- if (py_err || (std::is_integral::value && sizeof(py_type) != sizeof(T) &&
- (py_value < (py_type) (std::numeric_limits::min)() ||
- py_value > (py_type) (std::numeric_limits::max)()))) {
+ // Check to see if the conversion is valid (integers should match exactly)
+ // Signed/unsigned checks happen elsewhere
+ if (py_err || (std::is_integral::value && sizeof(py_type) != sizeof(T) && py_value != (py_type) (T) py_value)) {
bool type_error = py_err && PyErr_ExceptionMatches(
#if PY_VERSION_HEX < 0x03000000 && !defined(PYPY_VERSION)
PyExc_SystemError
@@ -1129,7 +1130,7 @@ template <> class type_caster : public type_caster {
}
/* Check if this is a C++ type */
- auto &bases = all_type_info((PyTypeObject *) h.get_type().ptr());
+ auto &bases = all_type_info((PyTypeObject *) type::handle_of(h).ptr());
if (bases.size() == 1) { // Only allowing loading from a single-value type
value = values_and_holders(reinterpret_cast(h.ptr())).begin()->value_ptr();
return true;
@@ -1243,7 +1244,7 @@ template struct string_caster {
load_src.ptr(), UTF_N == 8 ? "utf-8" : UTF_N == 16 ? "utf-16" : "utf-32", nullptr));
if (!utfNbytes) { PyErr_Clear(); return false; }
- const CharT *buffer = reinterpret_cast(PYBIND11_BYTES_AS_STRING(utfNbytes.ptr()));
+ const auto *buffer = reinterpret_cast(PYBIND11_BYTES_AS_STRING(utfNbytes.ptr()));
size_t length = (size_t) PYBIND11_BYTES_SIZE(utfNbytes.ptr()) / sizeof(CharT);
if (UTF_N > 8) { buffer++; length--; } // Skip BOM for UTF-16/32
value = StringType(buffer, length);
@@ -1257,7 +1258,7 @@ template struct string_caster {
static handle cast(const StringType &src, return_value_policy /* policy */, handle /* parent */) {
const char *buffer = reinterpret_cast(src.data());
- ssize_t nbytes = ssize_t(src.size() * sizeof(CharT));
+ auto nbytes = ssize_t(src.size() * sizeof(CharT));
handle s = decode_utfN(buffer, nbytes);
if (!s) throw error_already_set();
return s;
@@ -1363,7 +1364,7 @@ template struct type_caster 1 && str_len <= 4) {
- unsigned char v0 = static_cast(value[0]);
+ auto v0 = static_cast(value[0]);
size_t char0_bytes = !(v0 & 0x80) ? 1 : // low bits only: 0-127
(v0 & 0xE0) == 0xC0 ? 2 : // 0b110xxxxx - start of 2-byte sequence
(v0 & 0xF0) == 0xE0 ? 3 : // 0b1110xxxx - start of 3-byte sequence
@@ -1421,6 +1422,17 @@ template class Tuple, typename... Ts> class tuple_caster
return cast_impl(std::forward(src), policy, parent, indices{});
}
+ // copied from the PYBIND11_TYPE_CASTER macro
+ template
+ static handle cast(T *src, return_value_policy policy, handle parent) {
+ if (!src) return none().release();
+ if (policy == return_value_policy::take_ownership) {
+ auto h = cast(std::move(*src), policy, parent); delete src; return h;
+ } else {
+ return cast(*src, policy, parent);
+ }
+ }
+
static constexpr auto name = _("Tuple[") + concat(make_caster::name...) + _("]");
template using cast_op_type = type;
@@ -1696,7 +1708,7 @@ template type_caster &load_type(type_ca
throw cast_error("Unable to cast Python instance to C++ type (compile in debug mode for details)");
#else
throw cast_error("Unable to cast Python instance of type " +
- (std::string) str(handle.get_type()) + " to C++ type '" + type_id() + "'");
+ (std::string) str(type::handle_of(handle)) + " to C++ type '" + type_id() + "'");
#endif
}
return conv;
@@ -1747,7 +1759,7 @@ detail::enable_if_t::value, T> move(object &&obj) {
throw cast_error("Unable to cast Python instance to C++ rvalue: instance has multiple references"
" (compile in debug mode for details)");
#else
- throw cast_error("Unable to move from Python " + (std::string) str(obj.get_type()) +
+ throw cast_error("Unable to move from Python " + (std::string) str(type::handle_of(obj)) +
" instance to C++ " + type_id() + " instance: instance has multiple references");
#endif
@@ -1756,7 +1768,7 @@ detail::enable_if_t::value, T> move(object &&obj) {
return ret;
}
-// Calling cast() on an rvalue calls pybind::cast with the object rvalue, which does:
+// Calling cast() on an rvalue calls pybind11::cast with the object rvalue, which does:
// - If we have to move (because T has no copy constructor), do it. This will fail if the moved
// object has multiple references, but trying to copy will fail to compile.
// - If both movable and copyable, check ref count: if 1, move; otherwise copy
@@ -1785,16 +1797,16 @@ PYBIND11_NAMESPACE_BEGIN(detail)
template ::value, int>>
object object_or_cast(T &&o) { return pybind11::cast(std::forward(o)); }
-struct overload_unused {}; // Placeholder type for the unneeded (and dead code) static variable in the OVERLOAD_INT macro
-template using overload_caster_t = conditional_t<
- cast_is_temporary_value_reference::value, make_caster, overload_unused>;
+struct override_unused {}; // Placeholder type for the unneeded (and dead code) static variable in the PYBIND11_OVERRIDE_OVERRIDE macro
+template using override_caster_t = conditional_t<
+ cast_is_temporary_value_reference::value, make_caster, override_unused>;
// Trampoline use: for reference/pointer types to value-converted values, we do a value cast, then
// store the result in the given variable. For other types, this is a no-op.
template enable_if_t::value, T> cast_ref(object &&o, make_caster &caster) {
return cast_op(load_type(caster, o));
}
-template enable_if_t::value, T> cast_ref(object &&, overload_unused &) {
+template enable_if_t::value, T> cast_ref(object &&, override_unused &) {
pybind11_fail("Internal error: cast_ref fallback invoked"); }
// Trampoline use: Having a pybind11::cast with an invalid reference type is going to static_assert, even
@@ -1899,7 +1911,12 @@ struct arg_v : arg {
/// \ingroup annotations
/// Annotation indicating that all following arguments are keyword-only; the is the equivalent of an
/// unnamed '*' argument (in Python 3)
-struct kwonly {};
+struct kw_only {};
+
+/// \ingroup annotations
+/// Annotation indicating that all previous arguments are positional-only; the is the equivalent of an
+/// unnamed '/' argument (in Python 3.8)
+struct pos_only {};
template
arg_v arg::operator=(T &&value) const { return {std::move(*this), std::forward(value)}; }
@@ -1912,7 +1929,7 @@ inline namespace literals {
String literal version of `arg`
\endrst */
constexpr arg operator"" _a(const char *name, size_t) { return arg(name); }
-}
+} // namespace literals
PYBIND11_NAMESPACE_BEGIN(detail)
@@ -2187,13 +2204,25 @@ object object_api::call(Args &&...args) const {
PYBIND11_NAMESPACE_END(detail)
+
+template
+handle type::handle_of() {
+ static_assert(
+ std::is_base_of>::value,
+ "py::type::of only supports the case where T is a registered C++ types."
+ );
+
+ return detail::get_type_handle(typeid(T), true);
+}
+
+
#define PYBIND11_MAKE_OPAQUE(...) \
namespace pybind11 { namespace detail { \
template<> class type_caster<__VA_ARGS__> : public type_caster_base<__VA_ARGS__> { }; \
}}
/// Lets you pass a type containing a `,` through a macro parameter without needing a separate
-/// typedef, e.g.: `PYBIND11_OVERLOAD(PYBIND11_TYPE(ReturnType), PYBIND11_TYPE(Parent), f, arg)`
+/// typedef, e.g.: `PYBIND11_OVERRIDE(PYBIND11_TYPE(ReturnType), PYBIND11_TYPE(Parent), f, arg)`
#define PYBIND11_TYPE(...) __VA_ARGS__
PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
diff --git a/wrap/pybind11/include/pybind11/chrono.h b/wrap/pybind11/include/pybind11/chrono.h
index 6b9ab9b82a..cbe9acec35 100644
--- a/wrap/pybind11/include/pybind11/chrono.h
+++ b/wrap/pybind11/include/pybind11/chrono.h
@@ -33,9 +33,9 @@ PYBIND11_NAMESPACE_BEGIN(detail)
template class duration_caster {
public:
typedef typename type::rep rep;
- typedef typename type::period period;
+ using period = typename type::period;
- typedef std::chrono::duration> days;
+ using days = std::chrono::duration>;
bool load(handle src, bool) {
using namespace std::chrono;
@@ -98,7 +98,7 @@ template class duration_caster {
// This is for casting times on the system clock into datetime.datetime instances
template class type_caster> {
public:
- typedef std::chrono::time_point type;
+ using type = std::chrono::time_point;
bool load(handle src, bool) {
using namespace std::chrono;
@@ -140,7 +140,7 @@ template class type_caster(system_clock::from_time_t(std::mktime(&cal)) + msecs);
return true;
}
@@ -150,21 +150,28 @@ template class type_caster(src));
+ // Get out microseconds, and make sure they are positive, to avoid bug in eastern hemisphere time zones
+ // (cfr. https://github.com/pybind/pybind11/issues/2417)
+ using us_t = duration;
+ auto us = duration_cast(src.time_since_epoch() % seconds(1));
+ if (us.count() < 0)
+ us += seconds(1);
+
+ // Subtract microseconds BEFORE `system_clock::to_time_t`, because:
+ // > If std::time_t has lower precision, it is implementation-defined whether the value is rounded or truncated.
+ // (https://en.cppreference.com/w/cpp/chrono/system_clock/to_time_t)
+ std::time_t tt = system_clock::to_time_t(time_point_cast(src - us));
// this function uses static memory so it's best to copy it out asap just in case
// otherwise other code that is using localtime may break this (not just python code)
std::tm localtime = *std::localtime(&tt);
- // Declare these special duration types so the conversions happen with the correct primitive types (int)
- using us_t = duration;
-
return PyDateTime_FromDateAndTime(localtime.tm_year + 1900,
localtime.tm_mon + 1,
localtime.tm_mday,
localtime.tm_hour,
localtime.tm_min,
localtime.tm_sec,
- (duration_cast(src.time_since_epoch() % seconds(1))).count());
+ us.count());
}
PYBIND11_TYPE_CASTER(type, _("datetime.datetime"));
};
diff --git a/wrap/pybind11/include/pybind11/detail/class.h b/wrap/pybind11/include/pybind11/detail/class.h
index d58f04e612..b4a11c0a04 100644
--- a/wrap/pybind11/include/pybind11/detail/class.h
+++ b/wrap/pybind11/include/pybind11/detail/class.h
@@ -169,7 +169,7 @@ extern "C" inline PyObject *pybind11_meta_call(PyObject *type, PyObject *args, P
auto instance = reinterpret_cast(self);
// Ensure that the base __init__ function(s) were called
- for (auto vh : values_and_holders(instance)) {
+ for (const auto &vh : values_and_holders(instance)) {
if (!vh.holder_constructed()) {
PyErr_Format(PyExc_TypeError, "%.200s.__init__() must be called when overriding __init__",
vh.type->type->tp_name);
@@ -592,7 +592,7 @@ inline PyObject* make_new_python_type(const type_record &rec) {
auto &internals = get_internals();
auto bases = tuple(rec.bases);
- auto base = (bases.size() == 0) ? internals.instance_base
+ auto base = (bases.empty()) ? internals.instance_base
: bases[0].ptr();
/* Danger zone: from now (and until PyType_Ready), make sure to
@@ -616,7 +616,7 @@ inline PyObject* make_new_python_type(const type_record &rec) {
type->tp_doc = tp_doc;
type->tp_base = type_incref((PyTypeObject *)base);
type->tp_basicsize = static_cast(sizeof(instance));
- if (bases.size() > 0)
+ if (!bases.empty())
type->tp_bases = bases.release().ptr();
/* Don't inherit base __init__ */
diff --git a/wrap/pybind11/include/pybind11/detail/common.h b/wrap/pybind11/include/pybind11/detail/common.h
index 33805e0f91..1f8390fbab 100644
--- a/wrap/pybind11/include/pybind11/detail/common.h
+++ b/wrap/pybind11/include/pybind11/detail/common.h
@@ -9,6 +9,10 @@
#pragma once
+#define PYBIND11_VERSION_MAJOR 2
+#define PYBIND11_VERSION_MINOR 6
+#define PYBIND11_VERSION_PATCH 0.dev1
+
#define PYBIND11_NAMESPACE_BEGIN(name) namespace name {
#define PYBIND11_NAMESPACE_END(name) }
@@ -96,10 +100,6 @@
# define PYBIND11_MAYBE_UNUSED __attribute__ ((__unused__))
#endif
-#define PYBIND11_VERSION_MAJOR 2
-#define PYBIND11_VERSION_MINOR 5
-#define PYBIND11_VERSION_PATCH dev1
-
/* Don't let Python.h #define (v)snprintf as macro because they are implemented
properly in Visual Studio since 2015. */
#if defined(_MSC_VER) && _MSC_VER >= 1900
@@ -154,6 +154,7 @@
#include
#include
#include
+#include
#include
#include
#include
@@ -501,8 +502,16 @@ template using select_indices = typename select_indices_impl using bool_constant = std::integral_constant;
template struct negation : bool_constant { };
+// PGI cannot detect operator delete with the "compatible" void_t impl, so
+// using the new one (C++14 defect, so generally works on newer compilers, even
+// if not in C++17 mode)
+#if defined(__PGIC__)
+template using void_t = void;
+#else
template struct void_t_impl { using type = void; };
template using void_t = typename void_t_impl::type;
+#endif
+
/// Compile-time all/any/none of that check the boolean value of all template types
#if defined(__cpp_fold_expressions) && !(defined(_MSC_VER) && (_MSC_VER < 1916))
@@ -528,17 +537,17 @@ template class... Predicates> using satisfies_none_of
/// Strip the class from a method type
template struct remove_class { };
-template struct remove_class { typedef R type(A...); };
-template struct remove_class { typedef R type(A...); };
+template struct remove_class { using type = R (A...); };
+template struct remove_class { using type = R (A...); };
/// Helper template to strip away type modifiers
-template struct intrinsic_type { typedef T type; };
-template struct intrinsic_type { typedef typename intrinsic_type::type type; };
-template struct intrinsic_type { typedef typename intrinsic_type::type type; };
-template struct intrinsic_type { typedef typename intrinsic_type::type type; };
-template struct intrinsic_type { typedef typename intrinsic_type::type type; };
-template struct intrinsic_type { typedef typename intrinsic_type::type type; };
-template struct intrinsic_type { typedef typename intrinsic_type::type type; };
+template struct intrinsic_type { using type = T; };
+template struct intrinsic_type