Documentation says __members__ attribute returns an "ordered dictionary" but it returns a mappingproxy instead.

PR fixes this.

Is not returning a mappingproxy an implementation detail? The important thing is that the result is a mapping of names to members, and that it is ordered.

I can't really say if it the return of __members__ is an implementation detail as there's no mention of that in the doc, but from reading the doc I think it's reasonable to think this is allowed:

import enum

class Colors(enum.Enum):
    RED = enum.auto()
    BLUE = enum.auto()

Colors.__members__['GREEN'] = enum.auto()

And the traceback:

Traceback (most recent call last):
  File "<pyshell#8>", line 1, in <module>
    Colors.__members__['GREEN'] = enum.auto()
TypeError: 'mappingproxy' object does not support item assignment

is somewhat confusing, as the documentation says an "ordered dictionary" is to be returned, and the traceback talks about a mapping proxy.

Serhiy is correct.  The exact return type only needs to be ordered, and have appropriate dictionary methods such as `keys()`, `values()`, and `items()`.

The reason a mappingproxy was chosen is exactly because what you just tried is illegal and/or confusing:

- illegal because an Enum cannot be modified that way
- confusing because the dictionary returned is only a copy of the Enum class' __dict__, and successful attempts to modify it would not change the Enum class.

It is an implementation detail because the exact type of dictionary returned could change in the future.

assignee: docs@python -> ethan.furman
resolution: not a bug
stage: patch review -> resolved