Zengtudor/pybind11
1
0
Fork 0
mirror of https://github.com/pybind/pybind11.git synced 2024-11-13 09:03:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

added changelog for v2.0.0-rc1

Browse Source
This commit is contained in:
Wenzel Jakob 2016-12-23 16:01:04 +01:00
parent 05920e363e
commit d3549d6027
1 changed files with 283 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

336
docs/changelog.rst
View File

@ -3,64 +3,294 @@
Changelog Changelog
######### #########
Starting with version 1.8, pybind11 releases use a Starting with version 1.8, pybind11 releases use a `semantic versioning
[semantic versioning](http://semver.org) policy. <http://semver.org>`_ policy.
Breaking changes queued for v2.0.0 (Not yet released) v2.0.0-rc1 (Dec 23)
----------------------------------------------------- -----------------------------------------------------
* Redesigned virtual call mechanism and user-facing syntax (see
https://github.com/pybind/pybind11/commit/86d825f3302701d81414ddd3d38bcd09433076bc)
* Remove ``handle.call()`` method The pybind11 developers are excited to issue a release candidate of pybind11
with a subsequent v2.0.0 release planned in early January next year.
An incredible amount of effort by went into pybind11 over the last ~5 months,
leading to a release that is jam-packed with exciting new features and numerous
usuability improvements. The following list is roughly ordered in order of
importance and links PRs or individual commits whenever applicable.
Happy Christmas!
* Support for binding C++ class hierarchies that make use of multiple
inheritance. `#410 <https://github.com/pybind/pybind11/pull/410>`_.
* PyPy support: pybind11 now supports nightly builds of PyPy and will
interoperate with the future 5.7 release. No code changes are necessary,
everything "just" works as usual. Note that we only target the Python 2.7
branch for now; support for 3.x will be added once its ``cpyext`` extension
support catches up. `#527 <https://github.com/pybind/pybind11/pull/527>`_.
* Significant work on the documentation -- in particular, the monolitic
``advanced.rst`` file was restructured into a easier to read hierarchical
organization. `#448 <https://github.com/pybind/pybind11/pull/448>`_.
* Many NumPy-related improvements:
1. Object-oriented API to access and modify NumPy ``ndarray`` instances,
replicating much of the corresponding NumPy C API functionality.
`#402 <https://github.com/pybind/pybind11/pull/402>`_.
2. NumPy array ``dtype`` array descriptors are now first-class citizens and
are exposed via a new class ``py::dtype``.
3. Structured dtypes can be registered using the ``PYBIND11_NUMPY_DTYPE()``
macro. Special ``array`` constructors accepting dtype objects were also
added.
One potential caveat involving this change: format descriptor strings
should now be accessed via ``format_descriptor::format()`` (however, for
compatibility purposes, the old syntax ``format_descriptor::value`` will
still work for non-structured data types). `#308
<https://github.com/pybind/pybind11/pull/308>`_.
4. Further improvements to support structured dtypes throughout the system.
`#472 <https://github.com/pybind/pybind11/pull/472>`_,
`#474 <https://github.com/pybind/pybind11/pull/474>`_,
`#459 <https://github.com/pybind/pybind11/pull/459>`_,
`#453 <https://github.com/pybind/pybind11/pull/453>`_,
`#452 <https://github.com/pybind/pybind11/pull/452>`_, and
`#505 <https://github.com/pybind/pybind11/pull/505>`_.
5. Fast access operators. `#497 <https://github.com/pybind/pybind11/pull/497>`_.
6. Constructors for arrays whose storage is owned by another object.
`#440 <https://github.com/pybind/pybind11/pull/440>`_.
7. Added constructors for ``array`` and ``array_t`` explicitly accepting shape
and strides; if strides are not provided, they are deduced assuming
C-contiguity. Also added simplified constructors for 1-dimensional case.
8. Added buffer/NumPy support for ``char[N]`` and ``std::array<char, N>`` types.
9. Added ``memoryview`` wrapper type which is constructible from ``buffer_info``.
* Eigen: many additional conversions and support for non-contiguous
arrays/slices.
`#427 <https://github.com/pybind/pybind11/pull/427>`_,
`#315 <https://github.com/pybind/pybind11/pull/315>`_,
`#316 <https://github.com/pybind/pybind11/pull/316>`_,
`#312 <https://github.com/pybind/pybind11/pull/312>`_, and
`#267 <https://github.com/pybind/pybind11/pull/267>`_
* Incompatible changes in ``class_<...>::class_()``:
1. Declarations of types that provide access via the buffer protocol must
now include the ``py::buffer_protocol()`` annotation as an argument to
the ``class_`` constructor.
2. Declarations of types that require a custom metaclass (i.e. all classes
which include static properties via commands such as
``def_readwrite_static()``) must now include the ``py::metaclass()``
annotation as an argument to the ``class_`` constructor.
These two changes were necessary to make type definitions in pybind11
future-proof, and to support PyPy via its cpyext mechanism. `#527
<https://github.com/pybind/pybind11/pull/527>`_.
3. This version of pybind11 uses a redesigned mechnism for instantiating
trempoline classes that are used to override virtual methods from within
Python. This led to the following user-visible syntax change: instead of
.. code-block:: cpp
py::class_<TrampolineClass>("MyClass")
.alias<MyClass>()
....
write
.. code-block:: cpp
py::class_<MyClass, TrampolineClass>("MyClass")
....
Importantly, both the original and the trampoline class are now
specified as an arguments (in arbitrary order) to the ``py::class_``
template, and the ``alias<..>()`` call is gone. The new scheme has zero
overhead in cases when Python doesn't override any functions of the
underlying C++ class. `rev. 86d825
<https://github.com/pybind/pybind11/commit/86d825>`_.
1.9.0 (Not yet released)
------------------------
* Queued changes: map indexing suite, documentation for indexing suites.
* Mapping a stateless C++ function to Python and back is now "for free" (i.e. no call overheads)
* Support for translation of arbitrary C++ exceptions to Python counterparts
* Added ``eval`` and ``eval_file`` functions for evaluating expressions and * Added ``eval`` and ``eval_file`` functions for evaluating expressions and
statements from a string or file statements from a string or file. `rev. 0d3fc3
* eigen.h type converter fixed for non-contiguous arrays (e.g. slices) <https://github.com/pybind/pybind11/commit/0d3fc3>`_.
* Print more informative error messages when ``make_tuple()`` or ``cast()`` fail
* ``std::enable_shared_from_this<>`` now also works for ``const`` values * pybind11 can now create types with a modifiable dictionary.
* A return value policy can now be passed to ``handle::operator()`` `#437 <https://github.com/pybind/pybind11/pull/437>`_ and
* ``make_iterator()`` improvements for better compatibility with various types `#444 <https://github.com/pybind/pybind11/pull/444>`_.
(now uses prefix increment operator); it now also accepts iterators with
different begin/end types as long as they are equality comparable. * Support for translation of arbitrary C++ exceptions to Python counterparts.
* ``arg()`` now accepts a wider range of argument types for default values `#296 <https://github.com/pybind/pybind11/pull/296>`_ and
* Added ``py::repr()`` function which is equivalent to Python's builtin ``repr()``. `#273 <https://github.com/pybind/pybind11/pull/273>`_.
* Added support for registering structured dtypes via ``PYBIND11_NUMPY_DTYPE()`` macro.
* Added ``PYBIND11_STR_TYPE`` macro which maps to the ``builtins.str`` type. * Report full backtraces through mixed C++/Python code, better reporting for
* Added a simplified ``buffer_info`` constructor for 1-dimensional buffers. import errors, fixed GIL management in exception processing.
* Format descriptor strings should now be accessed via ``format_descriptor::format()`` `#537 <https://github.com/pybind/pybind11/pull/537>`_,
(for compatibility purposes, the old syntax ``format_descriptor::value`` will still `#494 <https://github.com/pybind/pybind11/pull/494>`_,
work for non-structured data types). `rev. e72d95 <https://github.com/pybind/pybind11/commit/e72d95>`_, and
* Added a class wrapping NumPy array descriptors: ``dtype``. `rev. 099d6e <https://github.com/pybind/pybind11/commit/099d6e>`_.
* Added buffer/NumPy support for ``char[N]`` and ``std::array<char, N>`` types.
* ``array`` gained new constructors accepting dtype objects. * Support for bit-level operations, comparisons, and serialization of C++
* Added constructors for ``array`` and ``array_t`` explicitly accepting shape and enumerations. `#503 <https://github.com/pybind/pybind11/pull/503>`_,
strides; if strides are not provided, they are deduced assuming C-contiguity. `#508 <https://github.com/pybind/pybind11/pull/508>`_,
Also added simplified constructors for 1-dimensional case. `#380 <https://github.com/pybind/pybind11/pull/380>`_,
* Added constructors for ``str`` from ``bytes`` and for ``bytes`` from ``str``. `#309 <https://github.com/pybind/pybind11/pull/309>`_.
This will do the UTF-8 decoding/encoding as required. `#311 <https://github.com/pybind/pybind11/pull/311>`_.
* Added constructors for ``str`` and ``bytes`` from zero-terminated char pointers,
and from char pointers and length. * The ``class_`` constructor now accepts its template arguments in any order.
* Added ``memoryview`` wrapper type which is constructible from ``buffer_info``. `#385 <https://github.com/pybind/pybind11/pull/385>`_.
* New syntax to call a Python function from C++ using keyword arguments and unpacking,
e.g. ``foo(1, 2, "z"_a=3)`` or ``bar(1, *args, "z"_a=3, **kwargs)``. * Attribute and item accessors now have a more complete interface which makes
* Added ``py::print()`` function which replicates Python's API and writes to Python's it possible to chain attributes as in
``sys.stdout`` by default (as opposed to C's ``stdout`` like ``std::cout``). ``obj.attr("a")[key].attr("b").attr("method")(1, 2, 3)``. `#425
* Added ``py::dict`` keyword constructor:``auto d = dict("number"_a=42, "name"_a="World");`` <https://github.com/pybind/pybind11/pull/425>`_.
* Added ``py::str::format()`` method and ``_s`` literal:
``py::str s = "1 + 2 = {}"_s.format(3);`` * Major redesign of the default and conversion constructors in ``pytypes.h``.
* Attribute and item accessors now have a more complete interface which makes it possible `#464 <https://github.com/pybind/pybind11/pull/464>`_.
to chain attributes ``obj.attr("a")[key].attr("b").attr("method")(1, 2, 3)```.
* Added built-in support for ``std::shared_ptr`` holder type. There is no more need * Added built-in support for ``std::shared_ptr`` holder type. It is no longer
to do it manually via ``PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr<T>)``. necessary to to include a declaration of the form
* Default return values policy changes: non-static properties now use ``reference_internal`` ``PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr<T>)`` (though continuing to
and static properties use ``reference`` (previous default was ``automatic``, i.e. ``copy``). do so won't cause an error).
* Support for ``std::experimental::optional<T>`` and ``std::optional<T>`` (C++17). `#454 <https://github.com/pybind/pybind11/pull/454>`_.
* Various minor improvements of library internals (no user-visible changes)
* New ``py::overload_cast`` casting operator to select among multiple possible
overloads of a function. An example:
.. code-block:: cpp
py::class_<Pet>(m, "Pet")
.def("set", py::overload_cast<int>(&Pet::set), "Set the pet's age")
.def("set", py::overload_cast<const std::string &>(&Pet::set), "Set the pet's name");
This feature only works on C++14-capable compilers.
`#541 <https://github.com/pybind/pybind11/pull/541>`_.
* C++ types are automatically cast to Python types, e.g. when assigning
them as an attribute. For instance, the following is now legal:
.. code-block:: cpp
py::module m = /* ... */
m.attr("constant") = 123;
(Previously, a ``py::cast`` call was necessary to avoid a compilation error.)
`#551 <https://github.com/pybind/pybind11/pull/551>`_.
* Redesigned ``pytest``-based test suite. `#321 <https://github.com/pybind/pybind11/pull/321>`_.
* Instance tracking to detect reference leaks in test suite. `#324 <https://github.com/pybind/pybind11/pull/324>`_
* pybind11 can now distinguish between multiple different instances that are
located at the same memory address, but which have different types.
`#329 <https://github.com/pybind/pybind11/pull/329>`_.
* Improved logic in ``move`` return value policy.
`#510 <https://github.com/pybind/pybind11/pull/510>`_,
`#297 <https://github.com/pybind/pybind11/pull/297>`_.
* Generalized unpacking API to permit calling Python functions from C++ using
notation such as ``foo(a1, a2, *args, "ka"_a=1, "kb"_a=2, **kwargs)``. `#372 <https://github.com/pybind/pybind11/pull/372>`_.
* ``py::print()`` function whose behavior matches that of the native Python
``print()`` function. `#372 <https://github.com/pybind/pybind11/pull/372>`_.
* Added ``py::dict`` keyword constructor:``auto d = dict("number"_a=42,
"name"_a="World");``. `#372 <https://github.com/pybind/pybind11/pull/372>`_.
* Added ``py::str::format()`` method and ``_s`` literal: ``py::str s = "1 + 2
= {}"_s.format(3);``. `#372 <https://github.com/pybind/pybind11/pull/372>`_.
* Added ``py::repr()`` function which is equivalent to Python's builtin
``repr()``. `#333 <https://github.com/pybind/pybind11/pull/333>`_.
* Improved construction and destruction logic for holder types. It is now
possible to reference instances with smart pointer holder types without
constructing the holder if desired. The ``PYBIND11_DECLARE_HOLDER_TYPE``
macro now accepts an optional second parameter to indicate whether the holder
type uses intrusive reference counting.
`#533 <https://github.com/pybind/pybind11/pull/533>`_ and
`#561 <https://github.com/pybind/pybind11/pull/561>`_.
* Mapping a stateless C++ function to Python and back is now "for free" (i.e.
no extra indirections or argument conversion overheads). `rev. 954b79
<https://github.com/pybind/pybind11/commit/954b79>`_.
* Bindings for ``std::valarray<T>``.
`#545 <https://github.com/pybind/pybind11/pull/545>`_.
* Improved support for C++17 capable compilers.
`#562 <https://github.com/pybind/pybind11/pull/562>`_.
* Bindings for ``std::optional<t>``.
`#475 <https://github.com/pybind/pybind11/pull/475>`_,
`#476 <https://github.com/pybind/pybind11/pull/476>`_,
`#479 <https://github.com/pybind/pybind11/pull/479>`_,
`#499 <https://github.com/pybind/pybind11/pull/499>`_, and
`#501 <https://github.com/pybind/pybind11/pull/501>`_.
* ``stl_bind.h``: general improvements and support for ``std::map`` and
``std::unordered_map``.
`#490 <https://github.com/pybind/pybind11/pull/490>`_,
`#282 <https://github.com/pybind/pybind11/pull/282>`_,
`#235 <https://github.com/pybind/pybind11/pull/235>`_.
* The ``std::tuple``, ``std::pair``, ``std::list``, and ``std::vector`` type
casters now accept any Python sequence type as input. `rev. 107285
<https://github.com/pybind/pybind11/commit/107285>`_.
* Improved CMake Python detection on multi-architecture Linux.
`#532 <https://github.com/pybind/pybind11/pull/532>`_.
* Infrastructure to selectively disable or enable parts of the automatically
generated docstrings. `#486 <https://github.com/pybind/pybind11/pull/486>`_.
* ``reference`` and ``reference_internal`` are now the default return value
properties for static and non-static properties, respectively. `#473
<https://github.com/pybind/pybind11/pull/473>`_. (the previous defaults
were ``automatic``). `#473 <https://github.com/pybind/pybind11/pull/473>`_.
* Support for ``std::unique_ptr`` with non-default deleters or no deleter at
all (``py::nodelete``). `#384 <https://github.com/pybind/pybind11/pull/384>`_.
* Removed ``handle.call()`` method to invoke Python functions, the new syntax
is simply ``handle()``. It can also be invoked explicitly via
``handle::operator<X>()``, where ``X`` is an optional return value policy.
* Print more informative error messages when ``make_tuple()`` or ``cast()``
fail. `#262 <https://github.com/pybind/pybind11/pull/262>`_.
* Creation of holder types for classes deriving from
``std::enable_shared_from_this<>`` now also works for ``const`` values.
`#260 <https://github.com/pybind/pybind11/pull/260>`_.
* ``make_iterator()`` improvements for better compatibility with various
types (now uses prefix increment operator); it now also accepts iterators
with different begin/end types as long as they are equality comparable.
`#247 <https://github.com/pybind/pybind11/pull/247>`_.
* ``arg()`` now accepts a wider range of argument types for default values.
`#244 <https://github.com/pybind/pybind11/pull/244>`_.
* Support ``keep_alive`` where the nurse object may be ``None``. `#341
<https://github.com/pybind/pybind11/pull/341>`_.
* Added constructors for ``str`` and ``bytes`` from zero-terminated char
pointers, and from char pointers and length. Added constructors for ``str``
from ``bytes`` and for ``bytes`` from ``str``, which will perform UTF-8
decoding/encoding as required.
* Many other improvements of library internals without user-visible changes
1.8.1 (July 12, 2016) 1.8.1 (July 12, 2016)
---------------------- ----------------------