diff --git a/docs/changelog.rst b/docs/changelog.rst index 15cf8d959..bf8ffc571 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -3,64 +3,294 @@ Changelog ######### -Starting with version 1.8, pybind11 releases use a -[semantic versioning](http://semver.org) policy. +Starting with version 1.8, pybind11 releases use a `semantic versioning +`_ 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 `_. + +* 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 `_. + +* Significant work on the documentation -- in particular, the monolitic + ``advanced.rst`` file was restructured into a easier to read hierarchical + organization. `#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 `_. + + 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 + `_. + + 4. Further improvements to support structured dtypes throughout the system. + `#472 `_, + `#474 `_, + `#459 `_, + `#453 `_, + `#452 `_, and + `#505 `_. + + 5. Fast access operators. `#497 `_. + + 6. Constructors for arrays whose storage is owned by another object. + `#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`` types. + + 9. Added ``memoryview`` wrapper type which is constructible from ``buffer_info``. + +* Eigen: many additional conversions and support for non-contiguous + arrays/slices. + `#427 `_, + `#315 `_, + `#316 `_, + `#312 `_, and + `#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 + `_. + + + 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_("MyClass") + .alias() + .... + + write + + .. code-block:: cpp + + py::class_("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 + `_. -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 - statements from a string or file -* eigen.h type converter fixed for non-contiguous arrays (e.g. slices) -* Print more informative error messages when ``make_tuple()`` or ``cast()`` fail -* ``std::enable_shared_from_this<>`` now also works for ``const`` values -* A return value policy can now be passed to ``handle::operator()`` -* ``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. -* ``arg()`` now accepts a wider range of argument types for default values -* Added ``py::repr()`` function which is equivalent to Python's builtin ``repr()``. -* Added support for registering structured dtypes via ``PYBIND11_NUMPY_DTYPE()`` macro. -* Added ``PYBIND11_STR_TYPE`` macro which maps to the ``builtins.str`` type. -* Added a simplified ``buffer_info`` constructor for 1-dimensional buffers. -* Format descriptor strings should now be accessed via ``format_descriptor::format()`` - (for compatibility purposes, the old syntax ``format_descriptor::value`` will still - work for non-structured data types). -* Added a class wrapping NumPy array descriptors: ``dtype``. -* Added buffer/NumPy support for ``char[N]`` and ``std::array`` types. -* ``array`` gained new constructors accepting dtype objects. -* 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. -* Added constructors for ``str`` from ``bytes`` and for ``bytes`` from ``str``. - This will do the UTF-8 decoding/encoding as required. -* Added constructors for ``str`` and ``bytes`` from zero-terminated char pointers, - and from char pointers and length. -* Added ``memoryview`` wrapper type which is constructible from ``buffer_info``. -* 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)``. -* Added ``py::print()`` function which replicates Python's API and writes to Python's - ``sys.stdout`` by default (as opposed to C's ``stdout`` like ``std::cout``). -* Added ``py::dict`` keyword constructor:``auto d = dict("number"_a=42, "name"_a="World");`` -* Added ``py::str::format()`` method and ``_s`` literal: - ``py::str s = "1 + 2 = {}"_s.format(3);`` -* Attribute and item accessors now have a more complete interface which makes it possible - 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 - to do it manually via ``PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr)``. -* Default return values policy changes: non-static properties now use ``reference_internal`` - and static properties use ``reference`` (previous default was ``automatic``, i.e. ``copy``). -* Support for ``std::experimental::optional`` and ``std::optional`` (C++17). -* Various minor improvements of library internals (no user-visible changes) + statements from a string or file. `rev. 0d3fc3 + `_. + +* pybind11 can now create types with a modifiable dictionary. + `#437 `_ and + `#444 `_. + +* Support for translation of arbitrary C++ exceptions to Python counterparts. + `#296 `_ and + `#273 `_. + +* Report full backtraces through mixed C++/Python code, better reporting for + import errors, fixed GIL management in exception processing. + `#537 `_, + `#494 `_, + `rev. e72d95 `_, and + `rev. 099d6e `_. + +* Support for bit-level operations, comparisons, and serialization of C++ + enumerations. `#503 `_, + `#508 `_, + `#380 `_, + `#309 `_. + `#311 `_. + +* The ``class_`` constructor now accepts its template arguments in any order. + `#385 `_. + +* Attribute and item accessors now have a more complete interface which makes + it possible to chain attributes as in + ``obj.attr("a")[key].attr("b").attr("method")(1, 2, 3)``. `#425 + `_. + +* Major redesign of the default and conversion constructors in ``pytypes.h``. + `#464 `_. + +* Added built-in support for ``std::shared_ptr`` holder type. It is no longer + necessary to to include a declaration of the form + ``PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr)`` (though continuing to + do so won't cause an error). + `#454 `_. + +* New ``py::overload_cast`` casting operator to select among multiple possible + overloads of a function. An example: + + .. code-block:: cpp + + py::class_(m, "Pet") + .def("set", py::overload_cast(&Pet::set), "Set the pet's age") + .def("set", py::overload_cast(&Pet::set), "Set the pet's name"); + + This feature only works on C++14-capable compilers. + `#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 `_. + +* Redesigned ``pytest``-based test suite. `#321 `_. + +* Instance tracking to detect reference leaks in test suite. `#324 `_ + +* pybind11 can now distinguish between multiple different instances that are + located at the same memory address, but which have different types. + `#329 `_. + +* Improved logic in ``move`` return value policy. + `#510 `_, + `#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 `_. + +* ``py::print()`` function whose behavior matches that of the native Python + ``print()`` function. `#372 `_. + +* Added ``py::dict`` keyword constructor:``auto d = dict("number"_a=42, + "name"_a="World");``. `#372 `_. + +* Added ``py::str::format()`` method and ``_s`` literal: ``py::str s = "1 + 2 + = {}"_s.format(3);``. `#372 `_. + +* Added ``py::repr()`` function which is equivalent to Python's builtin + ``repr()``. `#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 `_ and + `#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 + `_. + +* Bindings for ``std::valarray``. + `#545 `_. + +* Improved support for C++17 capable compilers. + `#562 `_. + +* Bindings for ``std::optional``. + `#475 `_, + `#476 `_, + `#479 `_, + `#499 `_, and + `#501 `_. + +* ``stl_bind.h``: general improvements and support for ``std::map`` and + ``std::unordered_map``. + `#490 `_, + `#282 `_, + `#235 `_. + +* The ``std::tuple``, ``std::pair``, ``std::list``, and ``std::vector`` type + casters now accept any Python sequence type as input. `rev. 107285 + `_. + +* Improved CMake Python detection on multi-architecture Linux. + `#532 `_. + +* Infrastructure to selectively disable or enable parts of the automatically + generated docstrings. `#486 `_. + +* ``reference`` and ``reference_internal`` are now the default return value + properties for static and non-static properties, respectively. `#473 + `_. (the previous defaults + were ``automatic``). `#473 `_. + +* Support for ``std::unique_ptr`` with non-default deleters or no deleter at + all (``py::nodelete``). `#384 `_. + +* Removed ``handle.call()`` method to invoke Python functions, the new syntax + is simply ``handle()``. It can also be invoked explicitly via + ``handle::operator()``, where ``X`` is an optional return value policy. + +* Print more informative error messages when ``make_tuple()`` or ``cast()`` + fail. `#262 `_. + +* Creation of holder types for classes deriving from + ``std::enable_shared_from_this<>`` now also works for ``const`` values. + `#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 `_. + +* ``arg()`` now accepts a wider range of argument types for default values. + `#244 `_. + +* Support ``keep_alive`` where the nurse object may be ``None``. `#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) ----------------------