Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gh-112328: Document EnumDict in docs and release notes #121720

Merged
merged 6 commits into from
Dec 19, 2024
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion Doc/library/enum.rst
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,10 @@ are not normal Python classes. See
Module Contents
---------------

:class:`EnumDict`

An enum class :class:`dict` that tracks order and enforces unique member names.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
An enum class :class:`dict` that tracks order and enforces unique member names.
A subclass of :class:`dict` that tracks order and enforces unique member names.


:class:`EnumType`

The ``type`` for Enum and its subclasses.
Expand Down Expand Up @@ -159,12 +163,28 @@ Data Types
----------


.. class:: EnumType
encukou marked this conversation as resolved.
Show resolved Hide resolved
.. class:: EnumDict

*EnumDict* is used by *EnumType* to keep track of the enum member orders and prevent reusing the member names.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would start by saying what it is, not what it's used for.

Ideally the documentation should also say something about when you would use this and why. I don't know why you would use it though, so I can't help with writing that explanation.


.. attribute:: EnumDict.member_names

Return list of member names.

.. method:: EnumDict.__setitem__(self, key, value)

Set any item as an enum member that is not dundered and not a descriptor.

.. method:: EnumDict.update(self, members, **more_members)

Update the dictionary from the given iterable or dictionary members and more_members.

*EnumType* is the :term:`metaclass` for *enum* enumerations. It is possible
to subclass *EnumType* -- see :ref:`Subclassing EnumType <enumtype-examples>`
for details.

.. class:: EnumType

u2rafi marked this conversation as resolved.
Show resolved Hide resolved
``EnumType`` is responsible for setting the correct :meth:`!__repr__`,
:meth:`!__str__`, :meth:`!__format__`, and :meth:`!__reduce__` methods on the
final *enum*, as well as creating the enum members, properly handling
Expand Down
5 changes: 5 additions & 0 deletions Doc/whatsnew/3.13.rst
Original file line number Diff line number Diff line change
Expand Up @@ -742,6 +742,11 @@ email
(Contributed by Thomas Dwyer and Victor Stinner for :gh:`102988` to improve
the :cve:`2023-27043` fix.)

enum
----

* :class:`~enum.EnumDict` has been made public in :mod:`enum`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's New should provide a quick overview to the casual reader. It might be useful to note that EnumDict was previously private, but I would expect that most people who know that already know what it is used for -- can we rephrase here to say that a new public type has been added that can be used in XYZ scenarios? You can also add a credit note for Ethan and a link to the GH issue (#112328).

Suggested change
* :class:`~enum.EnumDict` has been made public in :mod:`enum`.
* :class:`~enum.EnumDict` has been made public in :mod:`enum`.


fractions
---------

Expand Down
Loading