classification
Title: Documenting dataclass and namedtuple changes for structural pattern matching
Type: Stage:
Components: Documentation Versions: Python 3.10
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: brandtbucher, docs@python, eric.smith, freundTech, gvanrossum, rhettinger
Priority: normal Keywords:

Created on 2021-04-07 10:40 by freundTech, last changed 2021-04-12 16:35 by brandtbucher.

Messages (12)
msg390413 - (view) Author: Adrian Freund (freundTech) * Date: 2021-04-07 10:40
PEP 634 structural pattern matching adds an auto-generated __match_args__ attribute to classes with the dataclass decorator and to namedtuples.

This change is currently not documented in the dataclass and namedtuple documentation, nor is it mentioned in PEP 557 Data Classes.


I would suggest adding mentions of this behaviour in those three places.

Additionally I think adding a new parameter to switch off generating __match_args__ to dataclass should be considered, as everything else generated by dataclass can be switched off using a parameter.
msg390426 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2021-04-07 12:14
Turning off the generation of __match_args__ should be a separate issue.
msg390430 - (view) Author: Adrian Freund (freundTech) * Date: 2021-04-07 13:09
Ok. I created https://bugs.python.org/issue43764 for that.
msg390457 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-04-07 18:03
> This change is currently not documented in the dataclass 
> and namedtuple documentation,

I don't think we need to do that. In the end, __match_args__ will be added in many places.  The right place to document it is in the pattern matching docs.
msg390676 - (view) Author: Adrian Freund (freundTech) * Date: 2021-04-09 23:09
I agree that __match_args__ shouldn't have to be added to the documentation of any class that supports it, however dataclass and (maybe to a lesser extend) NamedTuple aren't themselves classes, but aid in creating own classes. Their effects on classes generated by them should be documented.
The documentation also mentions other fields/methods generated by dataclass and NamedTyple.
msg390679 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2021-04-09 23:30
I do think it's worth mentioning that __match_args__ is automatically generated by @dataclass (if the class doesn't already define __match_args__). That seems like behavior that's very specific to @dataclass. Where else would you find out that defining your own __match_args__ prevents @dataclass from adding it?
msg390685 - (view) Author: Brandt Bucher (brandtbucher) * (Python committer) Date: 2021-04-10 02:02
If we end up adding a “match_args=False” option to the dataclass decorator (issue 43764), then the docs for that option would probably be sufficient for this purpose.

I’m imagining something like the docs for the “init” option, just substituting “__match_args__” for “__init__()”.
msg390692 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-04-10 04:52
For named tuples, there isn't an include/exclude option, so no extra mention is warranted.
msg390707 - (view) Author: Adrian Freund (freundTech) * Date: 2021-04-10 09:53
I think for namedtuple a short mention in the opening paragraph, where it also mentions the generation of a docstring and __repr__ method should be enough.
msg390725 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2021-04-10 17:24
Do you need anything from me here?
msg390733 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2021-04-10 19:16
> Do you need anything from me here?

No, I don't think so. Thanks.
msg390865 - (view) Author: Brandt Bucher (brandtbucher) * (Python committer) Date: 2021-04-12 16:35
> For named tuples, there isn't an include/exclude option, so no extra mention is warranted.

I think a note in the docs could still be valuable, if only because defining __match_args__ for named tuples changes the inherited tuple behavior for positional matches quite significantly: "case tuple(x)" and "case MyNT(x)" don't mean the same thing.

(Although perhaps this could be inferred from the new constructor signature.)
History
Date User Action Args
2021-04-12 16:35:21brandtbuchersetmessages: + msg390865
2021-04-10 19:16:18eric.smithsetmessages: + msg390733
2021-04-10 17:24:49gvanrossumsetmessages: + msg390725
2021-04-10 09:53:20freundTechsetmessages: + msg390707
2021-04-10 04:52:53rhettingersetnosy: + rhettinger
messages: + msg390692
2021-04-10 02:02:04brandtbuchersetmessages: + msg390685
2021-04-09 23:30:25eric.smithsetmessages: + msg390679
2021-04-09 23:24:23rhettingersetnosy: - rhettinger
2021-04-09 23:09:15freundTechsetmessages: + msg390676
2021-04-07 18:03:51rhettingersetnosy: + rhettinger
messages: + msg390457
2021-04-07 13:09:18freundTechsetmessages: + msg390430
2021-04-07 12:14:59eric.smithsetmessages: + msg390426
2021-04-07 11:11:49xtreaksetnosy: + eric.smith
2021-04-07 10:40:27freundTechcreate