missing dataclass decorator in match-statement example

[ahmetveburak]

BPO	44109
Nosy	@rhettinger, @ericvsmith, @brandtbucher, @akulakov, @ahmetveburak

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-05-11.12:36:08.995>
labels = ['type-bug', '3.10', 'docs']
title = 'missing dataclass decorator in match-statement example'
updated_at = <Date 2021-06-26.13:55:21.690>
user = 'https://github.com/ahmetveburak'

bugs.python.org fields:

activity = <Date 2021-06-26.13:55:21.690>
actor = 'andrei.avk'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-05-11.12:36:08.995>
creator = 'ahmetveburak'
dependencies = []
files = []
hgrepos = []
issue_num = 44109
keywords = []
message_count = 6.0
messages = ['393454', '393607', '393678', '393812', '396527', '396550']
nosy_count = 6.0
nosy_names = ['rhettinger', 'eric.smith', 'docs@python', 'brandtbucher', 'andrei.avk', 'ahmetveburak']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue44109'
versions = ['Python 3.10']

Linked PRs

• gh-88275: Add __init__ method to the example #120281
• [3.14] gh-88275: Add missing __init__ method to match example (GH-120281) #134142
• [3.13] gh-88275: Add missing __init__ method to match example (GH-120281) #134143

[brandtbucher]

I don't really think there is anything wrong with the documentation. I can copy-and-paste all of the code from the PEP-634 section of the 3.10 What's New into the REPL without any issues (provided that named subjects like point/points/test_variable/color are actually defined).

Note that none of the example snippets actually *create* Point instances. Rather, some of the patterns *match* Point instances... which is sort of the opposite of instantiation.

As the Point class is currently written, instantiation would probably look like:

>> p = Point()
>> p.x = 0
>> p.y = 0

Sure, it would help to have an __init__ defined in real code, but I sort of feel like adding it to this example would just distract (especially since the example doesn't actually *need* it).

Thoughts from others?

[rhettinger]

Thoughts from others?

As it stands, the Point class is weird and atypical by only using class variables. The example would be improved by adding @DataClass or inheriting from typing.NamedTuple.

[ericvsmith]

I agree with Raymond: a more useful example would use dataclasses or typing.NamedTuple. The use of class variables is unusual, and it took me a while to understand how it would work.

[akulakov]

I agree the example is confusing for all of the stated reasons.

It seems to me it's better to use a plain class with a __init__() for two reason:

• for people who are not familiar with namedtuples or dataclasses, it would be harder to learn two fairly complex topics at the same time. Docs for both are fairly extensive.

• for those who *are* familiar with namedtuples or dataclasses (whichever is used in the example), the example may imply they should be used with pattern matching, and that plain classes may not work or not work well.

I can make a PR that adds __init__ if this makes sense..

[akulakov]

Ahmet: once there's agreement on how to fix this, would you like to work on a patch?