classification
Title: Enum doc suggestion
Type: enhancement Stage:
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: ethan.furman Nosy List: barry, docs@python, eli.bendersky, ethan.furman, georg.brandl, mark, serhiy.storchaka
Priority: normal Keywords:

Created on 2015-01-21 20:00 by mark, last changed 2015-01-26 08:36 by mark. This issue is now closed.

Files
File name Uploaded Description Edit
py-enum.tar.gz mark, 2015-01-21 20:00 Shows old CONSTANTS, using enum, and using enum as a drop-in replacement for CONSTANTS
Messages (12)
msg234442 - (view) Author: Mark Summerfield (mark) * Date: 2015-01-21 20:00
I think it would be worth documenting
globals().update(MyEnumeration.__members__) in the "Interesting
Examples" section of the enum docs.

I suspect that most people will find that importing enums is annoying
because they'll get

import A
print(A.MyEnumeration.MAX)

when they're more used to

import A
print(A.MAX)

Of course the latter is easily achieved using the globals().update()
trick (as used in signals.py in 3.5).

Georg suggested I add this to the tracker.
msg234443 - (view) Author: Mark Summerfield (mark) * Date: 2015-01-21 20:01
Georg said to assign this to Ethan Furman but I don't seem to have that facility.
msg234590 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2015-01-24 02:41
Currently the way to add an Enum's members to a module's namespace is:

  globals().update(MyEnumeration.__members__)

but that seems quite ugly.  Is there anywhere else that the user is required to use __xxx__ methods for common functionality?

I think a new method, export_to(), would solve the problem much more nicely:

  @classmethod
  def export_to(cls, namespace):
      try:
          # assume a dict-like namespace
          namespace.update(cls.__members__)
      except AttributeError:
          # or an object-like namespace
          for name, member in cls.__members__.items():
              setattr(namespace, name, member)
msg234595 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2015-01-24 07:06
Well, for such operations (namespace manipulation) __dict__ is also often used, so I wouldn't say it's too ugly.
msg234604 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2015-01-24 12:23
I'm not sure why the current situation is annoying?

Python explicitly does not pollute the enclosing namespace with an Enum's members. So when you:

import A

It's fairly natural that you have access to A.MyEnum and not its members, no? Some modules (like some stdlib modules) may choose to push the enum members up to the module's scope explicitly, but I wouldn't necessarily call it best practice. Namespacing is Pythonic, splashing contents of classes into enclosing namespaces isn't.

So I guess what I'm trying to say is that I don't see a reason to explicitly suggest something that is, in general, against the spirit of Python, in the documentation.

[P.S. Thanks for reporting, Mark, I love your books!]
msg234606 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2015-01-24 12:48
I disagree. I assume that many new enums will be a replacement for module-level constants, but these still have to be available on the module. Keeping backward compatibility is not against the spirit of Python :)
msg234611 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-01-24 13:02
Agree with Eli.
msg234629 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2015-01-24 18:19
Georg, each library writer is entitled to do whatever she wants. Naturally, we can't prevent dumping contents of enums into the module namespaces, and yes, backwards compatibility makes sense for some modules.

However, that's tangential to *encouraging* this un-Pythonic behavior by including the trick in the official documentation. After all, namespaces is a good idea (from the Zen of Python), and Enums as namespaces are also a good idea (self-documenting code).

There's a huge amount of tricks we could add to the documentation, but we don't. There's wikis for that, blogs, Stack Overflow, Active Python recipes, what have you.

I wouldn't spend too much time arguing about this, though. If you feel strongly that this belongs in the standard documentation, go ahead. I just wanted to provide an alternative view of the issue.
msg234633 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2015-01-24 19:25
Likewise, I don't feel strongly that it *should* go in, but I wouldn't object to it.
msg234661 - (view) Author: Mark Summerfield (mark) * Date: 2015-01-25 10:59
Since this is a bit controversial, I've tried marking it as 'rejected' with this comment.

I've also added a very brief explanation and link back to here on my web site: http://www.qtrac.eu/pyenum.html
msg234671 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2015-01-25 15:43
Amusingly enough, I posted a question/answer to StackOverflow (http://stackoverflow.com/q/28130683/208880) and so far the only other respondent posted an answer with similar functionality to my own, and also recommended that such a method be added to the base Enum class.
msg234723 - (view) Author: Mark Summerfield (mark) * Date: 2015-01-26 08:36
Nice answer Ethan (but I can't vote you up since stack overflow won't let me vote or even comment anymore).

As for adding export_to(), it seems like a good idea. However, personally, I think the signature should be

    hoist_into(namespace, cls, *clses)

to allow multiple enums in the same module to be exported in one go. (Just kidding about the new name though.)

PS I should have said earlier, thanks Eli:-)
History
Date User Action Args
2015-01-26 08:36:45marksetmessages: + msg234723
2015-01-25 15:43:00ethan.furmansetmessages: + msg234671
2015-01-25 10:59:42marksetstatus: open -> closed
2015-01-25 10:59:27marksetresolution: rejected
messages: + msg234661
2015-01-24 19:25:07georg.brandlsetmessages: + msg234633
2015-01-24 18:19:09eli.benderskysetmessages: + msg234629
2015-01-24 13:02:43serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg234611
2015-01-24 12:48:06georg.brandlsetmessages: + msg234606
2015-01-24 12:23:33eli.benderskysetmessages: + msg234604
2015-01-24 07:06:56georg.brandlsetnosy: + georg.brandl
messages: + msg234595
2015-01-24 02:41:40ethan.furmansetnosy: + barry, eli.bendersky
messages: + msg234590
2015-01-21 20:13:32georg.brandlsetassignee: docs@python -> ethan.furman

nosy: + ethan.furman
2015-01-21 20:01:30marksetmessages: + msg234443
2015-01-21 20:00:29markcreate