Enum doc suggestion

[mark-summerfield]

BPO	23292
Nosy	@warsaw, @birkenfeld, @mark-summerfield, @ethanfurman, @serhiy-storchaka
Files	py-enum.tar.gz: Shows old CONSTANTS, using enum, and using enum as a drop-in replacement for CONSTANTS

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ethanfurman'
closed_at = <Date 2015-01-25.10:59:42.176>
created_at = <Date 2015-01-21.20:00:29.270>
labels = ['type-feature', 'docs']
title = 'Enum doc suggestion'
updated_at = <Date 2015-01-26.08:36:45.890>
user = 'https://github.com/mark-summerfield'

bugs.python.org fields:

activity = <Date 2015-01-26.08:36:45.890>
actor = 'mark'
assignee = 'ethan.furman'
closed = True
closed_date = <Date 2015-01-25.10:59:42.176>
closer = 'mark'
components = ['Documentation']
creation = <Date 2015-01-21.20:00:29.270>
creator = 'mark'
dependencies = []
files = ['37809']
hgrepos = []
issue_num = 23292
keywords = []
message_count = 12.0
messages = ['234442', '234443', '234590', '234595', '234604', '234606', '234611', '234629', '234633', '234661', '234671', '234723']
nosy_count = 7.0
nosy_names = ['barry', 'georg.brandl', 'mark', 'eli.bendersky', 'docs@python', 'ethan.furman', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'rejected'
stage = None
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23292'
versions = ['Python 3.5', 'Python 3.6']

[mark-summerfield]

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.

[mark-summerfield]

Georg said to assign this to Ethan Furman but I don't seem to have that facility.

[ethanfurman]

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)

[birkenfeld]

Well, for such operations (namespace manipulation) __dict__ is also often used, so I wouldn't say it's too ugly.

[elibendersky]

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!]

[birkenfeld]

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 :)

[serhiy-storchaka]

Agree with Eli.

[elibendersky]

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.

[birkenfeld]

Likewise, I don't feel strongly that it *should* go in, but I wouldn't object to it.

[mark-summerfield]

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

[ethanfurman]

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.

[mark-summerfield]

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:-)