From eddcf08eb749e7bb5c1fdf675916adbebde7a65b Mon Sep 17 00:00:00 2001 From: Wenzel Jakob Date: Fri, 19 Apr 2024 17:22:10 +0200 Subject: [PATCH] doc updates --- docs/api_core.rst | 23 ++++++++++------------- docs/changelog.rst | 21 +++++++++++++++------ docs/lowlevel.rst | 3 +-- 3 files changed, 26 insertions(+), 21 deletions(-) diff --git a/docs/api_core.rst b/docs/api_core.rst index c7aa194d..e6f7b82a 100644 --- a/docs/api_core.rst +++ b/docs/api_core.rst @@ -1313,12 +1313,12 @@ the reference section on :ref:`class binding `. overlapping or identical input types (e.g. :cpp:class:`object`) and must run code at runtime to select the right overload. - You should probably write a thorough docstring explicing the expected inputs - in this case, since the behavior won't be obvious from the auto-generated - function signature list in the docstring. It can be frustrating when a - function call fails with an error message stating that the provided - arguments aren't compatible with any overload, when the associated error - message suggests otherwise. + You should probably write a thorough docstring that explicitly mentions the + expected inputs in this case, since the behavior won't be obvious from the + auto-generated function signature. It can be frustrating when a function + call fails with an error message stating that the provided arguments aren't + compatible with any overload, when the associated error message suggests + otherwise. .. cpp:function:: next_overload() @@ -1896,9 +1896,6 @@ Enum binding annotations The following annotations can be specified using the variable-length ``Extra`` parameter of the constructor :cpp:func:`enum_::enum_`. -Enums also support the :cpp:struct:`dynamic_attr` and -:cpp:struct:`type_slots` annotations -documented for :ref:`classes `. .. cpp:struct:: is_arithmetic @@ -1998,7 +1995,7 @@ Class binding .. cpp:function:: template class_ &def(new_ arg, const Extra &... extra) - Bind a C++ factory fuction as a Python object constructor (``__new__``). + Bind a C++ factory function as a Python object constructor (``__new__``). This is an advanced feature; prefer :cpp:struct:`nb::init\<..\> ` where possible. See the discussion of :ref:`customizing object creation ` for more details. @@ -2317,7 +2314,7 @@ Class binding Bind the enumeration of type `T` to the identifier `name` within the scope `scope`. The variable length `extra` parameter can be used to pass a docstring and other :ref:`enum binding annotations - ` such as :cpp:class:`is_arithmetic`. + ` (currently, only :cpp:class:`is_arithmetic` is supported). .. cpp:function:: enum_ &value(const char * name, T value, const char * doc = nullptr) @@ -2376,7 +2373,7 @@ Class binding .. cpp:struct:: template init_implicit - See :cpp:class:`init` for detail on binding constructorts. The main + See :cpp:class:`init` for detail on binding constructors. The main difference between :cpp:class:`init` and `init_implicit` is that the latter only supports constructors taking a single argument `Arg`, and that it marks the constructor as usable for implicit conversions from `Arg`. @@ -2759,7 +2756,7 @@ Miscellaneous .. cpp:class:: template typed - This helper class provides an an interface to parameterize generic types to + This helper class provides an interface to parameterize generic types to improve generated Python function signatures (e.g., to turn ``list`` into ``list[MyType]``). diff --git a/docs/changelog.rst b/docs/changelog.rst index b79bd944..280e756e 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -128,6 +128,15 @@ These release breaks API and ABI compatibility, requiring a new major version according to `SemVer `__. The following changes are noteworthy: +* The :cpp:class:`nb::enum_\() ` binding declaration is now a + wrapper that creates either a ``enum.Enum`` or ``enum.IntEnum``-derived type. + Previously, nanobind relied on a custom enumeration base class that was a + frequent source of friction for users. + + This change may break code that casts entries to integers, which now only + works for arithmetic (``enum.IntEnum``-derived) enumerations. Replace + ``int(my_enum_entry)`` with ``my_enum_entry.value`` to work around the issue. + * The :cpp:func:`nb::bind_vector\() ` and :cpp:func:`nb::bind_map\() ` interfaces were found to be severely flawed since element access (``__getitem__``) created views into the @@ -144,7 +153,7 @@ noteworthy: solutions. * The ``nb::raw_doc`` annotation was found to be too inflexible and was - therefore removed in this version. + removed in this version. * The ``nb::typed`` wrapper listed above actually already existed in previous nanobind versions but was awkward to use, as it required the user to provide @@ -175,11 +184,11 @@ noteworthy: if nanobind did not know about that base. (PR `#471 `__). -* nanobind can now handle keyword arguments that are not interned, which - avoids spurious TypeErrors in constructs like ``fn(**pickle.loads(...))``. - The speed of normal function calls (which generally do have interned - keyword arguments) should be unaffected. - (PR `#469 `__). +* nanobind can now handle keyword arguments that are not interned, which avoids + spurious ``TypeError`` exceptions in constructs like + ``fn(**pickle.loads(...))``. The speed of normal function calls (which + generally do have interned keyword arguments) should be unaffected. (PR `#469 + `__). * The ``owner=nb::handle()`` default value of the :cpp:func:`nb::ndarray ` constructor was removed since it was bug-prone. You now have to diff --git a/docs/lowlevel.rst b/docs/lowlevel.rst index dbc8dc4a..6bbd655e 100644 --- a/docs/lowlevel.rst +++ b/docs/lowlevel.rst @@ -266,5 +266,4 @@ as attributes of the type object (in its ``__dict__``) and store a borrowed ``PyObject*`` reference in the supplemental data. If you use an attribute name that begins with the symbol ``@``, then nanobind will prevent Python code from rebinding or deleting the attribute after it has been set, making -the borrowed reference reasonably safe. See the implementation of ``nb::enum_`` -for an example. +the borrowed reference reasonably safe.