mirror of
https://github.com/pybind/pybind11.git
synced 2024-11-14 09:34:46 +00:00
48534089f7
* CI: Intel icc/icpc via oneAPI
Add testing for Intel icc/icpc via the oneAPI images.
Intel oneAPI is in a late beta stage, currently shipping
oneAPI beta09 with ICC 20.2.
CI: Skip Interpreter Tests for Intel
Cannot find how to add this, neiter the package `libc6-dev` nor
`intel-oneapi-mkl-devel` help when installed to solve this:
```
-- Looking for C++ include pthread.h
-- Looking for C++ include pthread.h - not found
CMake Error at /__t/cmake/3.18.4/x64/cmake-3.18.4-Linux-x86_64/share/cmake-3.18/Modules/FindPackageHandleStandardArgs.cmake:165 (message):
Could NOT find Threads (missing: Threads_FOUND)
Call Stack (most recent call first):
/__t/cmake/3.18.4/x64/cmake-3.18.4-Linux-x86_64/share/cmake-3.18/Modules/FindPackageHandleStandardArgs.cmake:458 (_FPHSA_FAILURE_MESSAGE)
/__t/cmake/3.18.4/x64/cmake-3.18.4-Linux-x86_64/share/cmake-3.18/Modules/FindThreads.cmake:234 (FIND_PACKAGE_HANDLE_STANDARD_ARGS)
tests/test_embed/CMakeLists.txt:17 (find_package)
```
CI: libc6-dev from GCC for ICC
CI: Run bare metal for oneAPI
CI: Ubuntu 18.04 for oneAPI
CI: Intel +Catch -Eigen
CI: CMake from Apt (ICC tests)
CI: Replace Intel Py with GCC Py
CI: Intel w/o GCC's Eigen
CI: ICC with verbose make
[Debug] Find core dump
tests: use arg{} instead of arg() for Intel
tests: adding a few more missing {}
fix: sync with @tobiasleibner's branch
fix: try ubuntu 20-04
fix: drop exit 1
docs: Apply suggestions from code review
Co-authored-by: Tobias Leibner <tobias.leibner@googlemail.com>
Workaround for ICC enable_if issues
Another workaround for ICC's enable_if issues
fix error in previous commit
Disable one test for the Intel compiler in C++17 mode
Add back one instance of py::arg().noconvert()
Add NOLINT to fix clang-tidy check
Work around for ICC internal error in PYBIND11_EXPAND_SIDE_EFFECTS in C++17 mode
CI: Intel ICC with C++17
docs: pybind11/numpy.h does not require numpy at build time. (#2720)
This is nice enough to be mentioned explicitly in the docs.
docs: Update warning about Python 3.9.0 UB, now that 3.9.1 has been released (#2719)
Adjusting `type_caster<std::reference_wrapper<T>>` to support const/non-const propagation in `cast_op`. (#2705)
* Allow type_caster of std::reference_wrapper<T> to be the same as a native reference.
Before, both std::reference_wrapper<T> and std::reference_wrapper<const T> would
invoke cast_op<type>. This doesn't allow the type_caster<> specialization for T
to distinguish reference_wrapper types from value types.
After, the type_caster<> specialization invokes cast_op<type&>, which allows
reference_wrapper to behave in the same way as a native reference type.
* Add tests/examples for std::reference_wrapper<const T>
* Add tests which use mutable/immutable variants
This test is a chimera; it blends the pybind11 casters with a custom
pytype implementation that supports immutable and mutable calls.
In order to detect the immutable/mutable state, the cast_op needs
to propagate it, even through e.g. std::reference<const T>
Note: This is still a work in progress; some things are crashing,
which likely means that I have a refcounting bug or something else
missing.
* Add/finish tests that distinguish const& from &
Fixes the bugs in my custom python type implementation,
demonstrate test that requires const& and reference_wrapper<const T>
being treated differently from Non-const.
* Add passing a const to non-const method.
* Demonstrate non-const conversion of reference_wrapper in tests.
Apply formatting presubmit check.
* Fix build errors from presubmit checks.
* Try and fix a few more CI errors
* More CI fixes.
* More CI fixups.
* Try and get PyPy to work.
* Additional minor fixups. Getting close to CI green.
* More ci fixes?
* fix clang-tidy warnings from presubmit
* fix more clang-tidy warnings
* minor comment and consistency cleanups
* PyDECREF -> Py_DECREF
* copy/move constructors
* Resolve codereview comments
* more review comment fixes
* review comments: remove spurious &
* Make the test fail even when the static_assert is commented out.
This expands the test_freezable_type_caster a bit by:
1/ adding accessors .is_immutable and .addr to compare identity
from python.
2/ Changing the default cast_op of the type_caster<> specialization
to return a non-const value. In normal codepaths this is a reasonable
default.
3/ adding roundtrip variants to exercise the by reference, by pointer
and by reference_wrapper in all call paths. In conjunction with 2/, this
demonstrates the failure case of the existing std::reference_wrpper conversion,
which now loses const in a similar way that happens when using the default cast_op_type<>.
* apply presubmit formatting
* Revert inclusion of test_freezable_type_caster
There's some concern that this test is a bit unwieldly because of the use
of the raw <Python.h> functions. Removing for now.
* Add a test that validates const references propagation.
This test verifies that cast_op may be used to correctly detect
const reference types when used with std::reference_wrapper.
* mend
* Review comments based changes.
1. std::add_lvalue_reference<type> -> type&
2. Simplify the test a little more; we're never returning the ConstRefCaster
type so the class_ definition can be removed.
* formatted files again.
* Move const_ref_caster test to builtin_casters
* Review comments: use cast_op and adjust some comments.
* Simplify ConstRefCasted test
I like this version better as it moves the assertion that matters
back into python.
ci: drop pypy2 linux, PGI 20.7, add Python 10 dev (#2724)
* ci: drop pypy2 linux, add Python 10 dev
* ci: fix mistake
* ci: commented-out PGI 20.11, drop 20.7
fix: regression with installed pybind11 overriding local one (#2716)
* fix: regression with installed pybind11 overriding discovered one
Closes #2709
* docs: wording incorrect
style: remove redundant instance->owned = true (#2723)
which was just before set to True in instance->allocate_layout()
fix: also throw in the move-constructor added by the PYBIND11_OBJECT macro, after the argument has been moved-out (if necessary) (#2701)
Make args_are_all_* ICC workarounds unconditional
Disable test_aligned on Intel ICC
Fix test_aligned on Intel ICC
Skip test_python_alreadyset_in_destructor on Intel ICC
Fix test_aligned again
ICC CI: Downgrade pytest
pytest 6 does not capture the `discard_as_unraisable` stderr and
just writes a warning with its content instead.
* refactor: simpler Intel workaround, suggested by @laramiel
* fix: try version with impl to see if it is easier to compile
* docs: update README for ICC
Co-authored-by: Axel Huebl <axel.huebl@plasma.ninja>
Co-authored-by: Henry Schreiner <henryschreineriii@gmail.com>
192 lines
7.9 KiB
ReStructuredText
192 lines
7.9 KiB
ReStructuredText
.. figure:: https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png
|
||
:alt: pybind11 logo
|
||
|
||
**pybind11 — Seamless operability between C++11 and Python**
|
||
|
||
|Latest Documentation Status| |Stable Documentation Status| |Gitter chat| |CI| |Build status|
|
||
|
||
|Repology| |PyPI package| |Conda-forge| |Python Versions|
|
||
|
||
`Setuptools example <https://github.com/pybind/python_example>`_
|
||
• `Scikit-build example <https://github.com/pybind/scikit_build_example>`_
|
||
• `CMake example <https://github.com/pybind/cmake_example>`_
|
||
|
||
.. start
|
||
|
||
.. warning::
|
||
|
||
Combining older versions of pybind11 (< 2.6.0) with Python 3.9.0 will
|
||
trigger undefined behavior that typically manifests as crashes during
|
||
interpreter shutdown (but could also destroy your data. **You have been
|
||
warned.**)
|
||
|
||
We recommend that you update to the latest patch release of Python (3.9.1),
|
||
which includes a `fix <https://github.com/python/cpython/pull/22670>`_
|
||
that resolves this problem. If you do use Python 3.9.0, please update to
|
||
the latest version of pybind11 (2.6.0 or newer), which includes a temporary
|
||
workaround specifically when Python 3.9.0 is detected at runtime.
|
||
|
||
|
||
**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.
|
||
|
||
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 libraries that works with almost every C++ compiler in
|
||
existence. This compatibility has its cost: arcane template tricks and
|
||
workarounds are necessary to support the oldest and buggiest of compiler
|
||
specimens. Now that C++11-compatible compilers are widely available,
|
||
this heavy machinery has 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.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
|
||
`pybind11.readthedocs.io <https://pybind11.readthedocs.io/en/latest>`_.
|
||
A PDF version of the manual is available
|
||
`here <https://pybind11.readthedocs.io/_/downloads/en/latest/pdf/>`_.
|
||
And the source code is always available at
|
||
`github.com/pybind/pybind11 <https://github.com/pybind/pybind11>`_.
|
||
|
||
|
||
Core features
|
||
-------------
|
||
|
||
|
||
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
|
||
- Overloaded functions
|
||
- Instance attributes and static attributes
|
||
- Arbitrary exception types
|
||
- Enumerations
|
||
- Callbacks
|
||
- Iterators and ranges
|
||
- Custom operators
|
||
- Single and multiple inheritance
|
||
- STL data structures
|
||
- 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.5+, and PyPy/PyPy3 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.
|
||
|
||
- pybind11 uses C++11 move constructors and move assignment operators
|
||
whenever possible to efficiently transfer custom data types.
|
||
|
||
- It’s easy to expose the internal storage of custom data types through
|
||
Pythons’ buffer protocols. This is handy e.g. for fast conversion
|
||
between C++ matrix classes like Eigen and NumPy without expensive
|
||
copy operations.
|
||
|
||
- pybind11 can automatically vectorize functions so that they are
|
||
transparently applied to all entries of one or more NumPy array
|
||
arguments.
|
||
|
||
- Python’s slice-based access and assignment operations can be
|
||
supported with just a few lines of code.
|
||
|
||
- Everything is contained in just a few header files; there is no need
|
||
to link against any additional libraries.
|
||
|
||
- 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**.
|
||
|
||
- 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 regular Python objects.
|
||
|
||
Supported compilers
|
||
-------------------
|
||
|
||
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 classic C++ compiler 18 or newer (ICC 20.2 tested in CI)
|
||
5. Cygwin/GCC (previously tested on 2.5.1)
|
||
6. NVCC (CUDA 11.0 tested in CI)
|
||
7. NVIDIA PGI (20.9 tested in CI)
|
||
|
||
About
|
||
-----
|
||
|
||
This project was created by `Wenzel
|
||
Jakob <http://rgl.epfl.ch/people/wjakob>`_. Significant features and/or
|
||
improvements to the code were contributed by Jonas Adler, Lori A. Burns,
|
||
Sylvain Corlay, Eric Cousineau, Ralf Grosse-Kunstleve, Trent Houliston, Axel
|
||
Huebl, @hulucc, Yannick Jadoul, Sergey Lyskov Johan Mabille, Tomasz Miąsko,
|
||
Dean Moldovan, Ben Pritchard, Jason Rhinelander, Boris Schäling, Pim
|
||
Schellart, Henry Schreiner, Ivan Smirnov, Boris Staletic, and Patrick Stewart.
|
||
|
||
We thank Google for a generous financial contribution to the continuous
|
||
integration infrastructure used by this project.
|
||
|
||
|
||
Contributing
|
||
~~~~~~~~~~~~
|
||
|
||
See the `contributing
|
||
guide <https://github.com/pybind/pybind11/blob/master/.github/CONTRIBUTING.md>`_
|
||
for information on building and contributing to pybind11.
|
||
|
||
License
|
||
~~~~~~~
|
||
|
||
pybind11 is provided under a BSD-style license that can be found in the
|
||
`LICENSE <https://github.com/pybind/pybind11/blob/master/LICENSE>`_
|
||
file. By using, distributing, or contributing to this project, you agree
|
||
to the terms and conditions of this license.
|
||
|
||
.. |Latest Documentation Status| image:: https://readthedocs.org/projects/pybind11/badge?version=latest
|
||
:target: http://pybind11.readthedocs.org/en/latest
|
||
.. |Stable Documentation Status| image:: https://img.shields.io/badge/docs-stable-blue.svg
|
||
:target: http://pybind11.readthedocs.org/en/stable
|
||
.. |Gitter chat| image:: https://img.shields.io/gitter/room/gitterHQ/gitter.svg
|
||
:target: https://gitter.im/pybind/Lobby
|
||
.. |CI| image:: https://github.com/pybind/pybind11/workflows/CI/badge.svg
|
||
:target: https://github.com/pybind/pybind11/actions
|
||
.. |Build status| image:: https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true
|
||
:target: https://ci.appveyor.com/project/wjakob/pybind11
|
||
.. |PyPI package| image:: https://img.shields.io/pypi/v/pybind11.svg
|
||
:target: https://pypi.org/project/pybind11/
|
||
.. |Conda-forge| image:: https://img.shields.io/conda/vn/conda-forge/pybind11.svg
|
||
:target: https://github.com/conda-forge/pybind11-feedstock
|
||
.. |Repology| image:: https://repology.org/badge/latest-versions/python:pybind11.svg
|
||
:target: https://repology.org/project/python:pybind11/versions
|
||
.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/pybind11.svg
|
||
:target: https://pypi.org/project/pybind11/
|