Skip to content

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

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.

Sign up for GitHub

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

Merged
ethanfurman merged 6 commits into from
Dec 19, 2024
Merged

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

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d00adac
Document EnumDict in docs and release notes
u2rafi Jul 14, 2024
3bff0b9
Restore deleted EnumType
u2rafi Jul 14, 2024
11e2fd1
Update Doc/library/enum.rst
u2rafi Jul 16, 2024
e8c368e
Update description
u2rafi Jul 28, 2024
58fbf7b
move entries; some rewording
ethanfurman Dec 19, 2024
aee56d0
Merge branch 'main' into enumdict-docs-112328
ethanfurman Dec 19, 2024
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
20 changes: 20 additions & 0 deletions Doc/library/enum.rst
View file
Open in desktop
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`

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

@AA-Turner AA-Turner Jul 29, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I understand that this is used by EnumType, but I don't think it should go first in the list, unless it is expected to be very widely used. I would suggest the end of the list as it is new? Also ensure that you update the versionadded directives at the end of the list with this new class.

:class:`EnumType`

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


.. class:: EnumDict

*EnumDict* is a subclass of :class:`dict` that keeps track of the order of enum members and prevents reusing member names. Use *EnumDict* when member names must be unique and their order needs to be preserved.

@AA-Turner AA-Turner Jul 29, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Perhaps you can provide an example in a code block of when using EnumDict is different from a plain dict?

Suggested change
*EnumDict* is a subclass of :class:`dict` that keeps track of the order of enum members and prevents reusing member names. Use *EnumDict* when member names must be unique and their order needs to be preserved.
*EnumDict* is a subclass of :class:`dict` that keeps track of
the order of enum members and prevents reusing member names.
Use *EnumDict* when member names must be unique
and their order needs to be preserved.
.. versionadded:: 3.14

.. 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.

.. class:: EnumType
Comment thread
encukou marked this conversation as resolved.
Resolved

*EnumType* is the :term:`metaclass` for *enum* enumerations. It is possible
Expand Down
5 changes: 5 additions & 0 deletions Doc/whatsnew/3.13.rst
View file
Open in desktop
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`.

@AA-Turner AA-Turner Jul 29, 2024

Copy link
Copy Markdown
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