gh-112328: Document EnumDict in docs and release notes #121720
Conversation
|
All commit authors signed the Contributor License Agreement. |
bedevere-app
bot
added
docs
u2rafi
force-pushed
the
enumdict-docs-112328
branch
from
75c1bca to
d00adac
Compare
|
Hey @JelleZijlstra, mind taking a look? This was made during the EuroPython sprints. |
Doc/library/enum.rst
Outdated
| @@ -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. | |||
There was a problem hiding this comment.
| 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. |
Doc/library/enum.rst
Outdated
| .. class:: EnumType | ||
| .. class:: EnumDict | ||
|
|
||
| *EnumDict* is used by *EnumType* to keep track of the enum member orders and prevent reusing the member names. |
There was a problem hiding this comment.
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.
Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>
Doc/library/enum.rst
Outdated
| :class:`EnumDict` | ||
|
|
||
| A subclass of :class:`dict` that tracks order and enforces unique member names. | ||
|
|
There was a problem hiding this comment.
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.
Doc/library/enum.rst
Outdated
| *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. | ||
|
|
There was a problem hiding this comment.
Perhaps you can provide an example in a code block of when using EnumDict is different from a plain dict?
| *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 | |
Doc/whatsnew/3.13.rst
Outdated
| enum | ||
| ---- | ||
|
|
||
| * :class:`~enum.EnumDict` has been made public in :mod:`enum`. |
There was a problem hiding this comment.
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).
| * :class:`~enum.EnumDict` has been made public in :mod:`enum`. | |
| * :class:`~enum.EnumDict` has been made public in :mod:`enum`. |
|
@u2rafi, do you want to address the review? |
|
I'm continuing this PR in #123669. |
…H-121720) Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]> Co-authored-by: Ethan Furman <[email protected]>
…H-121720) Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]> Co-authored-by: Ethan Furman <[email protected]>
In PR #112514
EnumDictwas made public but was not documented. This patch adds the documentation.Resolves #112328
📚 Documentation preview 📚: https://cpython-previews--121720.org.readthedocs.build/