On 5/13/2021 7:48 AM, Petr Viktorin wrote:
On 13. 05. 21 11:45, Antoine Pitrou wrote:
Le 13/05/2021 à 11:40, Irit Katriel a écrit :
On Thu, May 13, 2021 at 10:28 AM Antoine Pitrou <firstname.lastname@example.org mailto:email@example.com> wrote:
I agree that <optional> is a reasonable spelling.
I initially suggested <optional>, but now I'm not sure because it doesn't indicate what happens when you don't provide it (as in, what is the default value). So now I'm with <derived> or <implicit>.
"<derived>" makes think of a derived class, and leaves me confused. "<implicit>" is a bit better, but doesn't clearly say what the default value is, either. So in all cases I have to read the docstring in addition to the function signature.
Is <default> the term you're looking for?
In the dataclasses docs https://docs.python.org/3/library/dataclasses.html I document the module-level sentinel MISSING, then I document the function as:
dataclasses.field(*, default=MISSING, default_factory=MISSING, repr=True, hash=None, init=True, compare=True, metadata=None)
And I explain what MISSING means.
The help looks like:
field(*, default=<dataclasses._MISSING_TYPE object at 0x6fffffe46610>, default_factory=<dataclasses._MISSING_TYPE object at 0x6fffffe46610>, init=True, repr=True, hash=None, compare=True, metadata=None)
None of this is particularly awesome, but no one has complained about it yet.
I think it's important to state an actual value for the default value, instead of just using something like "<default>". Unless you know the actual default value, you can't write a wrapper.
Say I wanted to write something that calls dataclasses.field, but doesn't allow the user to specify repr, hash, init, compare, and metadata. I could write it as:
def myfield_func(*, default=MISSING, default_factory=MISSING): ...
If the real default values for "default" and "default_factory" weren't documented, there wouldn't be any easy way to write this.
I do think a python-wide standard for this would be helpful, but I don't see how to change existing code given backward compatibility constraints.