Decide the fate of `enum.bin`

[azerty-svg]

First, this module defines a bin function that is not present in the documentation. Such a method should be documented or made private. Indeed, it would feel weird for a user to use from enum import * and have the standard bin() function overriden.

The commit that introcuced this function is #7aaeb2a
This function only appears to have be used by the commit for Flag.missing, where it's present two or three times

Thus, i guess this function was created for internal code refactorisation.
This is a normal use for a function. However, a function used for this should not be available to an importer of enum. It should especially not be able to cause problems in the code of the importer.

I suggest renaming the function _bin and replacing existing occurences of call to this function by a call to its new name.

Broadlier speaking, I do not see a valid reason for the import of builtins in the enum module, because it is bad practice: the only use case is builtin functions having been redefined inside the code, which is a source of confusions and errors and therefore not good practice.

This probably means they're other problems like this in the enum module. One I found is the decorator @property. I did not investigated this one further.

[StanFromIreland]

Please do not throw multiple things into one issue. The comment can just be a PR if you have a suggestion. For the function, I use this issue.

CC @ethanfurman

[picnixz]

Indeed, it would feel weird for a user to use from enum import * and have the standard bin() function overriden

This wouldn't happen as the module defines an __all__ which, in this case, doesn't re-export bin. So users importing the module wouldn't be annoyed (or they must access it explicitly). Now, I don't know if it's was an oversight that we didn't document bin or not. Ethan, has bin ever been considered part of the public API?

The nonsense in this code, present in the class EnumCheck, is the comment about powers of 1.

This is indeed a typo, probably because it was copy-pasted from above.

Broadlier speaking, I do not see a valid reason for the import of builtins in the enum module, because it is bad practice: the only use case is builtin functions having been redefined inside the code, which is a source of confusions and errors and therefore not good practice.

Sometimes practility beats purity. If the function was meant to be public, enum.bin is clearer than anything else (it's really the same as bin with a few tweaks; calling enum_bin would be overly verbose IMO).

[azerty-svg]

I understand, but it doesn't feel to me like it's meant to be public in this case. Because this function is not the kind of things one would expect to find in a module about enumerations.

[picnixz]

As a utility function that is meant only for enums, this is the place where one would expect. It can be a helper for people who want to subclass the enum type itself. However, if it was meant to be private, we need to first deprecate it (it's publicly named and we could break stuff) and the make it private. If it was meant to be part of the public API, then we should document it. I don't really know whether it was meant to be private or not though.

Concerning the import to builtins, I think it's really because of enum.property, which is however documented: https://docs.python.org/3/library/enum.html#enum.property, so this is why we need to import builtins to be able to use it internally (here, we can't change the name of this exposed function without going through a deprecation period and probably a Discourse post and lots of discussions).

[azerty-svg]

If we document enum.bin, I think we can use the docstring. It looks explaining enough to me:
`"""
Like built-in bin(), except negative values are represented in
twos-compliment, and the leading bit always indicates sign
(0=positive, 1=negative).

>>> bin(10)
'0b0 1010'
>>> bin(~10)   # ~10 is -11
'0b1 0101'
"""`

We would just need to correct the spelling mistake: it's two's complement and not compliment

[picnixz]

Yes, but I first want to know if it was meant to be public (which is why I changed the issue's title).

[azerty-svg]

We could maybe ask @ethanfurman , who made the initial commit. His last commit to enum.py is from July, 10. And it look's on his contribution activity that he's still active

[azerty-svg]

Though he may not remember what he thought back in 2021, date of the initial commit