Mention enum.nonmember in Enum HOWTO and add an example

[jhenly]

Documentation

This issue is related to this StackOverflow question.

When searching for a way to exclude an enum class attribute from its members, the Enum HOWTO documentation makes it seem like _ignore_ and _Private__names are the only options. There is no mention of the the enum.nonmember decorator in the Enum HOWTO documentation.

The _ignore_ documentation in the "Supported _sunder_ names" section^[LINK] currently states:

• _ignore_ – a list of names, either as a list or a str, that will not be transformed into members, and will be removed from the final class

The "_Private__names" section^[LINK] currently states:

_Private__names

Private names are not converted to enum members, but remain normal attributes.

Changed in version 3.11.

---

Proposals

• Add a note block under the _ignore_ documentation that says something along the lines of:

  "Note: If removal from the final class is not desired, the nonmember() decorator can be used instead.

• Add a line to the _Private__names documentation that says something similar to:

  "The same functionality can be achieved for non private names using the nonmember() decorator.

• Add an example to the enum.nonmember decorator's documentation:

  >>> from enum import Enum, nonmember
  >>> class MyEnum(Enum):
  ...     A = 1
  ...     B = nonmember(2)
  ...
  >>> list(MyEnum)
  [<MyEnum.A: 1>]
  >>> MyEnum.B
  2

  Note: I'm not actually sure how to use @enum.nonmember as a decorator, or @enum.member. Are their decorator forms meant to be used with nested/internal classes?

• Maybe add a subsection to the Finer Points section titled "Specifying Nonmembers", with an example.

Private Names and enum.member

I don't know why anyone would want or need a name mangled enum. But, I would expect a name mangled enum when explicitly using enum.member with a private name. For instance:

>>> from enum import Enum, member
>>> class MyEnum(Enum):
...     A = 1
...     # expect _MyEnum__B to be in MyEnum
...     __B = member(2)
...
>>> list(MyEnum)
[<MyEnum.A: 1>]

Maybe a note should be added to the enum.member or _Private__names section stating that enum.member has no effect on private names.

Unless enum.member should allow you to explicitly use private names. In which case the check in EnumDict should be:

if _is_private(self._cls_name, key) and not isinstance(value, member):

Separate Issue

Should the "Finer Points" section be nested under "When to use __new__() vs. __init__()" in Enum HOWTO, or should it be at the same depth?

[Eclips4]

cc @ethanfurman