Weird `enum.Enum` signature?

[ego-thales]

Hello,

I'm wondering the following regarding Enum.__signature__:

1. Why return a str (better suited for __text_signature__ isn't it?)
2. When there are members, why choose '(*values)' over the more accurate (I think) '(value)'?

cpython/Lib/enum.py

Lines 1148 to 1150 in f218549

	def __signature__(cls):
	if cls._member_names_:
	return '(*values)'

If acted upon, I think it would be better to replace current signatures with Signature types. For example for enums with members:

__signature__ = Signature([Parameter("value", Parameter.POSITIONAL_OR_KEYWORD)])

All the best!

[picnixz]

First of all, dunders are generally reserved for the language so their behavior and usage (unless documented) should be considered internal. Now, while there are no docs for __signature__, the following is said in inspect.signature:

CPython implementation detail: If the passed object has a __signature__ attribute, we may use it to create the signature. The exact semantics are an implementation detail and are subject to unannounced changes. Consult the source code for current semantics.

There is no directive telling whether __signature__ must hold a Signature object or something else. OTOH, __text_signature__ is relevant to objects implemented in C and used by Argument Clinic, which is again an implementation detail.

When there are members, why choose '(*values)' over the more accurate (I think) '(value)'?

I don't have an answer for that so I'll ask @ethanfurman.

[ethanfurman]

When there are members, why choose '(*values)' over the more accurate (I think) '(value)'?

While enums usually have a single item as a value, it is possible for them to have several. For example, if you had an enum of points:

class Point(Enum):
    ORIGIN = 0, 0
    ANOTHER = 1, -5

then to look them up by value would be

Point(0, 0)  # for the origin

Hence, *values.

[ego-thales]

@ethanfurman: 😮 I did not know that, thanks for the explanation, it makes sense now. However, I think the case should still be made for IntEnum and StrEnum, these those can only have int and str values. Don't you think?

@picnixz I understand your point, however, I do think that undocumented use are exactly those that should go towards future standards while their modification do not break compatibility (as other implementations cannot rest on them until they are documented).

But in any case, I just saw that my suggestion was already implemented, I somehow quoted ancient blob... sorry!

---

As discussed, I might reopen a separate issue for IntEnum and StrEnum signatures.

All the best.

Edit: Apparently, StrEnum can take multiple arguments even though it is not documented, for "encoding" and "errors". As such, My remark regarding *values vs. value only applies to IntEnum.

cpython/Lib/enum.py

Lines 1352 to 1359 in 80295a8

	if len(values) >= 2:
	# check that encoding argument is a string
	if not isinstance(values[1], str):
	raise TypeError('encoding must be a string, not %r' % (values[1], ))
	if len(values) == 3:
	# check that errors argument is a string
	if not isinstance(values[2], str):
	raise TypeError('errors must be a string, not %r' % (values[2]))

[picnixz]

I do think that undocumented use are exactly those that should go towards future standards while their modification do not break compatibility (as other implementations cannot rest on them until they are documented).

If you want to standardize undocumented features, I'd suggest opening a DPO thread on https://discuss.python.org/c/core-dev/23, but check if there doesn't exist a topic on that already (I think there is one).