diff options
Diffstat (limited to 'ext/pybind11/docs/changelog.rst')
| -rw-r--r-- | ext/pybind11/docs/changelog.rst | 452 |
1 files changed, 399 insertions, 53 deletions
diff --git a/ext/pybind11/docs/changelog.rst b/ext/pybind11/docs/changelog.rst index 15cf8d959..aba8a2009 100644 --- a/ext/pybind11/docs/changelog.rst +++ b/ext/pybind11/docs/changelog.rst @@ -3,64 +3,410 @@ Changelog ######### -Starting with version 1.8, pybind11 releases use a -[semantic versioning](http://semver.org) policy. +Starting with version 1.8.0, pybind11 releases use a `semantic versioning +<http://semver.org>`_ policy. -Breaking changes queued for v2.0.0 (Not yet released) + +v2.1.1 (April 7, 2017) ----------------------------------------------------- -* Redesigned virtual call mechanism and user-facing syntax (see - https://github.com/pybind/pybind11/commit/86d825f3302701d81414ddd3d38bcd09433076bc) -* Remove ``handle.call()`` method +* Fixed minimum version requirement for MSVC 2015u3 + `#773 <https://github.com/pybind/pybind11/pull/773>`_. + +v2.1.0 (March 22, 2017) +----------------------------------------------------- + +* pybind11 now performs function overload resolution in two phases. The first + phase only considers exact type matches, while the second allows for implicit + conversions to take place. A special ``noconvert()`` syntax can be used to + completely disable implicit conversions for specific arguments. + `#643 <https://github.com/pybind/pybind11/pull/643>`_, + `#634 <https://github.com/pybind/pybind11/pull/634>`_, + `#650 <https://github.com/pybind/pybind11/pull/650>`_. + +* Fixed a regression where static properties no longer worked with classes + using multiple inheritance. The ``py::metaclass`` attribute is no longer + necessary (and deprecated as of this release) when binding classes with + static properties. + `#679 <https://github.com/pybind/pybind11/pull/679>`_, + +* Classes bound using ``pybind11`` can now use custom metaclasses. + `#679 <https://github.com/pybind/pybind11/pull/679>`_, + +* ``py::args`` and ``py::kwargs`` can now be mixed with other positional + arguments when binding functions using pybind11. + `#611 <https://github.com/pybind/pybind11/pull/611>`_. + +* Improved support for C++11 unicode string and character types; added + extensive documentation regarding pybind11's string conversion behavior. + `#624 <https://github.com/pybind/pybind11/pull/624>`_, + `#636 <https://github.com/pybind/pybind11/pull/636>`_, + `#715 <https://github.com/pybind/pybind11/pull/715>`_. + +* pybind11 can now avoid expensive copies when converting Eigen arrays to NumPy + arrays (and vice versa). `#610 <https://github.com/pybind/pybind11/pull/610>`_. + +* The "fast path" in ``py::vectorize`` now works for any full-size group of C or + F-contiguous arrays. The non-fast path is also faster since it no longer performs + copies of the input arguments (except when type conversions are necessary). + `#610 <https://github.com/pybind/pybind11/pull/610>`_. + +* Added fast, unchecked access to NumPy arrays via a proxy object. + `#746 <https://github.com/pybind/pybind11/pull/746>`_. + +* Transparent support for class-specific ``operator new`` and + ``operator delete`` implementations. + `#755 <https://github.com/pybind/pybind11/pull/755>`_. + +* Slimmer and more efficient STL-compatible iterator interface for sequence types. + `#662 <https://github.com/pybind/pybind11/pull/662>`_. + +* Improved custom holder type support. + `#607 <https://github.com/pybind/pybind11/pull/607>`_. + +* ``nullptr`` to ``None`` conversion fixed in various builtin type casters. + `#732 <https://github.com/pybind/pybind11/pull/732>`_. + +* ``enum_`` now exposes its members via a special ``__members__`` attribute. + `#666 <https://github.com/pybind/pybind11/pull/666>`_. + +* ``std::vector`` bindings created using ``stl_bind.h`` can now optionally + implement the buffer protocol. `#488 <https://github.com/pybind/pybind11/pull/488>`_. + +* Automated C++ reference documentation using doxygen and breathe. + `#598 <https://github.com/pybind/pybind11/pull/598>`_. + +* Added minimum compiler version assertions. + `#727 <https://github.com/pybind/pybind11/pull/727>`_. + +* Improved compatibility with C++1z. + `#677 <https://github.com/pybind/pybind11/pull/677>`_. + +* Improved ``py::capsule`` API. Can be used to implement cleanup + callbacks that are involved at module destruction time. + `#752 <https://github.com/pybind/pybind11/pull/752>`_. + +* Various minor improvements and fixes. + `#595 <https://github.com/pybind/pybind11/pull/595>`_, + `#588 <https://github.com/pybind/pybind11/pull/588>`_, + `#589 <https://github.com/pybind/pybind11/pull/589>`_, + `#603 <https://github.com/pybind/pybind11/pull/603>`_, + `#619 <https://github.com/pybind/pybind11/pull/619>`_, + `#648 <https://github.com/pybind/pybind11/pull/648>`_, + `#695 <https://github.com/pybind/pybind11/pull/695>`_, + `#720 <https://github.com/pybind/pybind11/pull/720>`_, + `#723 <https://github.com/pybind/pybind11/pull/723>`_, + `#729 <https://github.com/pybind/pybind11/pull/729>`_, + `#724 <https://github.com/pybind/pybind11/pull/724>`_, + `#742 <https://github.com/pybind/pybind11/pull/742>`_, + `#753 <https://github.com/pybind/pybind11/pull/753>`_. + +v2.0.1 (Jan 4, 2017) +----------------------------------------------------- + +* Fix pointer to reference error in type_caster on MSVC + `#583 <https://github.com/pybind/pybind11/pull/583>`_. + +* Fixed a segmentation in the test suite due to a typo + `cd7eac <https://github.com/pybind/pybind11/commit/cd7eac>`_. + +v2.0.0 (Jan 1, 2017) +----------------------------------------------------- + +* Fixed a reference counting regression affecting types with custom metaclasses + (introduced in v2.0.0-rc1). + `#571 <https://github.com/pybind/pybind11/pull/571>`_. + +* Quenched a CMake policy warning. + `#570 <https://github.com/pybind/pybind11/pull/570>`_. + +v2.0.0-rc1 (Dec 23, 2016) +----------------------------------------------------- + +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 +usability improvements. The following list 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. A few minor features remain unsupported for the time + being (notably dynamic attributes in custom types). + `#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 - 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<char, N>`` 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<T>)``. -* 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<T>`` and ``std::optional<T>`` (C++17). -* Various minor improvements of library internals (no user-visible changes) + statements from a string or file. `rev. 0d3fc3 + <https://github.com/pybind/pybind11/commit/0d3fc3>`_. + +* pybind11 can now create types with a modifiable dictionary. + `#437 <https://github.com/pybind/pybind11/pull/437>`_ and + `#444 <https://github.com/pybind/pybind11/pull/444>`_. + +* Support for translation of arbitrary C++ exceptions to Python counterparts. + `#296 <https://github.com/pybind/pybind11/pull/296>`_ and + `#273 <https://github.com/pybind/pybind11/pull/273>`_. + +* Report full backtraces through mixed C++/Python code, better reporting for + import errors, fixed GIL management in exception processing. + `#537 <https://github.com/pybind/pybind11/pull/537>`_, + `#494 <https://github.com/pybind/pybind11/pull/494>`_, + `rev. e72d95 <https://github.com/pybind/pybind11/commit/e72d95>`_, and + `rev. 099d6e <https://github.com/pybind/pybind11/commit/099d6e>`_. + +* Support for bit-level operations, comparisons, and serialization of C++ + enumerations. `#503 <https://github.com/pybind/pybind11/pull/503>`_, + `#508 <https://github.com/pybind/pybind11/pull/508>`_, + `#380 <https://github.com/pybind/pybind11/pull/380>`_, + `#309 <https://github.com/pybind/pybind11/pull/309>`_. + `#311 <https://github.com/pybind/pybind11/pull/311>`_. + +* The ``class_`` constructor now accepts its template arguments in any order. + `#385 <https://github.com/pybind/pybind11/pull/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 + <https://github.com/pybind/pybind11/pull/425>`_. + +* Major redesign of the default and conversion constructors in ``pytypes.h``. + `#464 <https://github.com/pybind/pybind11/pull/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<T>)`` (though continuing to + do so won't cause an error). + `#454 <https://github.com/pybind/pybind11/pull/454>`_. + +* 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>`_. + +* Deprecated ``handle::call()`` method. The new syntax to call Python + functions 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) ---------------------- |