Should new enum types added recently to collect module constants be documented at all? For example AddressFamily is absent in socket.__all__ [1]. [1] http://bugs.python.org/issue20689
Hi, IMO we should not document enum types because Python implementations other than CPython may want to implement them differently (ex: not all Python implementations have an enum module currently). By experience, exposing too many things in the public API becomes a problem later when you want to modify the code. Victor Le 14 août 2014 07:47, "Serhiy Storchaka" <storchaka@gmail.com> a écrit :
Should new enum types added recently to collect module constants be documented at all? For example AddressFamily is absent in socket.__all__ [1].
[1] http://bugs.python.org/issue20689
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/ victor.stinner%40gmail.com
On 14 August 2014 19:25, Victor Stinner <victor.stinner@gmail.com> wrote:
Hi,
IMO we should not document enum types because Python implementations other than CPython may want to implement them differently (ex: not all Python implementations have an enum module currently). By experience, exposing too many things in the public API becomes a problem later when you want to modify the code.
Implementations claiming conformance with Python 3.4 will have to have an enum module - there just aren't any of those other than CPython at this point (I expect PyPy3 will catch up before too long, since the changes between 3.2 and 3.4 shouldn't be too dramatic from an implementation perspective). In this particular case, though, I think the relevant question is "Why are they enums?" and the answer is "for the better representations". I'm not clear on the use case for exposing and documenting the enum types themselves (although I don't have any real objection either). Regards, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
The enemy must be documented and exported, since users will encounter them. On Aug 14, 2014 4:54 AM, "Nick Coghlan" <ncoghlan@gmail.com> wrote:
On 14 August 2014 19:25, Victor Stinner <victor.stinner@gmail.com> wrote:
Hi,
IMO we should not document enum types because Python implementations other than CPython may want to implement them differently (ex: not all Python implementations have an enum module currently). By experience, exposing too many things in the public API becomes a problem later when you want to modify the code.
Implementations claiming conformance with Python 3.4 will have to have an enum module - there just aren't any of those other than CPython at this point (I expect PyPy3 will catch up before too long, since the changes between 3.2 and 3.4 shouldn't be too dramatic from an implementation perspective).
In this particular case, though, I think the relevant question is "Why are they enums?" and the answer is "for the better representations". I'm not clear on the use case for exposing and documenting the enum types themselves (although I don't have any real objection either).
Regards, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/guido%40python.org
On 14/08/2014 17:14, Ethan Furman wrote:
On 08/14/2014 08:51 AM, Ben Hoyt wrote:
The BDFL actually wrote:-
The enemy must be documented and exported, since users will encounter them.
QOTW.
enum == enemy? Is that you, Raymond? ;-)
ROFL! Thanks, I needed that!
:D
-- ~Ethan~
I'll be seeing the PSF in court, on the grounds that I've just bust a gut laughing :) -- My fellow Pythonistas, ask not what our language can do for you, ask what you can do for our language. Mark Lawrence
participants (7)
-
Ben Hoyt -
Ethan Furman -
Guido van Rossum -
Mark Lawrence -
Nick Coghlan -
Serhiy Storchaka -
Victor Stinner