classification
Title: doc Fix Enum __members__ type
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: ethan.furman Nosy List: adelfino, barry, docs@python, eli.bendersky, ethan.furman, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2018-06-14 17:37 by adelfino, last changed 2018-06-14 19:55 by ethan.furman. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 7694 closed adelfino, 2018-06-14 17:57
Messages (4)
msg319532 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-14 17:37
Documentation says __members__ attribute returns an "ordered dictionary" but it returns a mappingproxy instead.

PR fixes this.
msg319536 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-06-14 18:16
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.
msg319537 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-14 18:48
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.
msg319542 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2018-06-14 19:55
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.
History
Date User Action Args
2018-06-14 19:55:45ethan.furmansetstatus: open -> closed
messages: + msg319542

assignee: docs@python -> ethan.furman
resolution: not a bug
stage: patch review -> resolved
2018-06-14 18:48:41adelfinosetmessages: + msg319537
2018-06-14 18:16:47serhiy.storchakasetnosy: + ethan.furman, barry, serhiy.storchaka, eli.bendersky
messages: + msg319536
2018-06-14 17:57:40adelfinosetkeywords: + patch
stage: patch review
pull_requests: + pull_request7309
2018-06-14 17:37:32adelfinocreate