Hey guys, This is something that has been discussed before several times, whether in Python mailing list and whether in stackoverflow, each providing different answers. I believe that we should add a naming convention in pep8 to solve this issue. Enums in Python are a unique creature - it's a class, the members aren't injected into module level, it can have methods, but it's attributes are somewhat consts (although they can be modified via __new__). The fact that currently every person names them differently defies the whole purpose of a convention document. Although I'm in favor of lower-case instead of upper-case, I believe that we need to make a decision as no decision is somewhat worse and causes a lot of confusion. I'm not entirely sure how pep-8 was built (was it a poll? was it a BDFL announcement? was it discovered in a fortune cookie just like pep 285?), regardless how it built I believe we should make that addition for a clearer future :-) Any thoughts?
On Wed, Sep 14, 2016 at 9:20 PM, Bar Harel <bzvi7919@gmail.com> wrote:
The trouble is that enums are a bit of a chimera - part constant, part class attribute, part class instance, part integer (often). You can treat them as "constant ints with nice reprs", or you can treat them as "representations of set membership and nothing more", and all manner of other uses. I would accept a PEP 8 ruling that they be in lower-case *only* if it's qualified with a blanket permission to name something the same as its C counterpart when one exists.
socket.AF_INET <AddressFamily.AF_INET: 2>
There is absolutely no value in lower-casing something like this. (Even leaving aside backward compatibility; imagine this situation with a brand-new third party module that provides Python bindings to a C library.) If they're going to be constants that match the C constants, they should have names that match the C names. Perhaps the advice needs to be along the lines of: Decide what the purpose of the enum is, and follow a naming convention accordingly. Uppercase if you're basically making constants; lowercase if you're not; etcetera. ChrisA
On 14 September 2016 at 12:51, Chris Angelico <rosuav@gmail.com> wrote:
Agreed - it's not clear to me that a prescriptive rule has much benefit here. The OP said "I believe that we need to make a decision as no decision is somewhat worse and causes a lot of confusion" - personally, I don't agree, I think it's fine to leave this to the individual. And of course, no matter how many times we stress that any rules we add are "only recommendations", projects like pycodestyle will add checks (as they should) and then projects that mandate a clean run of a style checker will treat the rule as mandatory. So I'm basically -1 on a PEP 8 rule at this stage, but if we have to have one, I agree that it should say something along the lines of "depends on how you're using the enum". Paul PS FWIW, I tend to think of enums as named constants, and so would typically use uppercase, not lowercase. But I wouldn't like to impose that on everyone :-)
I recommend naming all enums UPPER_CASE. They're constants (within a namespace) and that's the rule for constants. It's helpful for the reader of the code to realize what they are when passed around -- they have a similar status to literal constants, you know they stand for a unique value and not for some computed quantity. On Wed, Sep 14, 2016 at 4:58 AM, Paul Moore <p.f.moore@gmail.com> wrote:
-- --Guido van Rossum (python.org/~guido)
On 09/15/2016 10:03 AM, Steven D'Aprano wrote:
On Wed, Sep 14, 2016 at 09:51:32PM +1000, Chris Angelico wrote:
Besides being CONSTANTS enum members are also Singletons, and since I find CamelCase easier to read than UPPERCASE I may use that instead; otherwise I leave it all lowercase. -- ~Ethan~
On Fri, Sep 16, 2016 at 3:03 AM, Steven D'Aprano <steve@pearwood.info> wrote:
Sometimes they function as integer constants (esp IntEnum), and sometimes more as just arbitrary values. See the examples in the docs [1] for Color and Mood, where the exact value is immaterial, just as long as Color.red is not Color.blue. Even though they happen to have integer values, they're not intended to be used as actual integers. For those cases, it's not as clear that they ought to be Color.RED and Color.BLUE - it's equally acceptable to have them in lowercase. But if one convention or the other had to be picked for all enums, I would go with all-caps, since they're most often going to be representing constant integers, per Guido's post. I don't know of _any_ real-world cases where they're not integers, though there are some examples in the docs. ChrisA [1] https://docs.python.org/3/library/enum.html
On Thu, Sep 15, 2016 at 10:54 AM, Chris Angelico <rosuav@gmail.com> wrote:
I disagree. The whole point of an enum is to define a new *kind* of constant. Clearly RED and BLUE are new constants. (The uppercase convention is not just for giving names to literals -- that's not what "constant" means.)
Amen.
ChrisA
-- --Guido van Rossum (python.org/~guido)
On Fri, Sep 16, 2016 at 4:06 AM, Guido van Rossum <guido@python.org> wrote:
Well, my view was largely colored [1] by the official docs. Your view is broadly the same as my ideal preference, just without the caveats and flexibility of accepting it the other way. So should the docs be updated to upper-case everything? With or without an actual PEP 8 change, that would send a strong message to the community. I'm sure I'm not the only person who looks at official examples as a style guide as well as a syntax demo. ChrisA [1] Sorry [2], that pun was just terrible [2] Actually I'm not sorry. But the pun was still terrible.
On Fri, Sep 16, 2016 at 4:26 AM, Guido van Rossum <guido@python.org> wrote:
Please update the docs.
Roger that. http://bugs.python.org/issue28172 ChrisA
On Fri, Sep 16, 2016 at 03:54:18AM +1000, Chris Angelico wrote:
Yes, but when would you write something like this? Color.red = <new Enumeration value> That's not to be confused with the case: text_colour = Color.RED # later... text_colour = Color.BLUE where *text_colour* is clearly used as a variable, not a constant. But the enumerations themselves are still constant. -- Steve
On Wed, Sep 14, 2016 at 9:20 PM, Bar Harel <bzvi7919@gmail.com> wrote:
The trouble is that enums are a bit of a chimera - part constant, part class attribute, part class instance, part integer (often). You can treat them as "constant ints with nice reprs", or you can treat them as "representations of set membership and nothing more", and all manner of other uses. I would accept a PEP 8 ruling that they be in lower-case *only* if it's qualified with a blanket permission to name something the same as its C counterpart when one exists.
socket.AF_INET <AddressFamily.AF_INET: 2>
There is absolutely no value in lower-casing something like this. (Even leaving aside backward compatibility; imagine this situation with a brand-new third party module that provides Python bindings to a C library.) If they're going to be constants that match the C constants, they should have names that match the C names. Perhaps the advice needs to be along the lines of: Decide what the purpose of the enum is, and follow a naming convention accordingly. Uppercase if you're basically making constants; lowercase if you're not; etcetera. ChrisA
On 14 September 2016 at 12:51, Chris Angelico <rosuav@gmail.com> wrote:
Agreed - it's not clear to me that a prescriptive rule has much benefit here. The OP said "I believe that we need to make a decision as no decision is somewhat worse and causes a lot of confusion" - personally, I don't agree, I think it's fine to leave this to the individual. And of course, no matter how many times we stress that any rules we add are "only recommendations", projects like pycodestyle will add checks (as they should) and then projects that mandate a clean run of a style checker will treat the rule as mandatory. So I'm basically -1 on a PEP 8 rule at this stage, but if we have to have one, I agree that it should say something along the lines of "depends on how you're using the enum". Paul PS FWIW, I tend to think of enums as named constants, and so would typically use uppercase, not lowercase. But I wouldn't like to impose that on everyone :-)
I recommend naming all enums UPPER_CASE. They're constants (within a namespace) and that's the rule for constants. It's helpful for the reader of the code to realize what they are when passed around -- they have a similar status to literal constants, you know they stand for a unique value and not for some computed quantity. On Wed, Sep 14, 2016 at 4:58 AM, Paul Moore <p.f.moore@gmail.com> wrote:
-- --Guido van Rossum (python.org/~guido)
On 09/15/2016 10:03 AM, Steven D'Aprano wrote:
On Wed, Sep 14, 2016 at 09:51:32PM +1000, Chris Angelico wrote:
Besides being CONSTANTS enum members are also Singletons, and since I find CamelCase easier to read than UPPERCASE I may use that instead; otherwise I leave it all lowercase. -- ~Ethan~
On Fri, Sep 16, 2016 at 3:03 AM, Steven D'Aprano <steve@pearwood.info> wrote:
Sometimes they function as integer constants (esp IntEnum), and sometimes more as just arbitrary values. See the examples in the docs [1] for Color and Mood, where the exact value is immaterial, just as long as Color.red is not Color.blue. Even though they happen to have integer values, they're not intended to be used as actual integers. For those cases, it's not as clear that they ought to be Color.RED and Color.BLUE - it's equally acceptable to have them in lowercase. But if one convention or the other had to be picked for all enums, I would go with all-caps, since they're most often going to be representing constant integers, per Guido's post. I don't know of _any_ real-world cases where they're not integers, though there are some examples in the docs. ChrisA [1] https://docs.python.org/3/library/enum.html
On Thu, Sep 15, 2016 at 10:54 AM, Chris Angelico <rosuav@gmail.com> wrote:
I disagree. The whole point of an enum is to define a new *kind* of constant. Clearly RED and BLUE are new constants. (The uppercase convention is not just for giving names to literals -- that's not what "constant" means.)
Amen.
ChrisA
-- --Guido van Rossum (python.org/~guido)
On Fri, Sep 16, 2016 at 4:06 AM, Guido van Rossum <guido@python.org> wrote:
Well, my view was largely colored [1] by the official docs. Your view is broadly the same as my ideal preference, just without the caveats and flexibility of accepting it the other way. So should the docs be updated to upper-case everything? With or without an actual PEP 8 change, that would send a strong message to the community. I'm sure I'm not the only person who looks at official examples as a style guide as well as a syntax demo. ChrisA [1] Sorry [2], that pun was just terrible [2] Actually I'm not sorry. But the pun was still terrible.
On Fri, Sep 16, 2016 at 4:26 AM, Guido van Rossum <guido@python.org> wrote:
Please update the docs.
Roger that. http://bugs.python.org/issue28172 ChrisA
On Fri, Sep 16, 2016 at 03:54:18AM +1000, Chris Angelico wrote:
Yes, but when would you write something like this? Color.red = <new Enumeration value> That's not to be confused with the case: text_colour = Color.RED # later... text_colour = Color.BLUE where *text_colour* is clearly used as a variable, not a constant. But the enumerations themselves are still constant. -- Steve
participants (6)
-
Bar Harel -
Chris Angelico -
Ethan Furman -
Guido van Rossum -
Paul Moore -
Steven D'Aprano