Skip to content

docs(skills): add dataclass-over-NamedTuple guideline to usethis-python-functions skill#1882

Merged
nathanjmcdougall merged 2 commits into
mainfrom
copilot/refactor-subprocessresult-using-dataclass
Apr 8, 2026
Merged

docs(skills): add dataclass-over-NamedTuple guideline to usethis-python-functions skill#1882
nathanjmcdougall merged 2 commits into
mainfrom
copilot/refactor-subprocessresult-using-dataclass

Conversation

Copilot AI commented Apr 8, 2026

Copy link
Copy Markdown
Contributor

Agents defaulted to NamedTuple for structured return types despite it leaking unintended tuple semantics (positional indexing, iteration, unpacking, positional equality). @dataclass is the correct default for grouping named fields.

Changes

  • usethis-python-functions skill (v1.3 → v1.4): adds a new "Prefer dataclasses over NamedTuples for structured types" section covering:
    • Why NamedTuple is the wrong default (tuple semantics leak implementation details)
    • When NamedTuple is genuinely appropriate (positional comparison, iteration, interop with tuple-expecting code)
    • Canonical example contrasting the two approaches
    • Common mistakes (choosing NamedTuple for brevity or speculative future unpacking)
# Bad: positional indexing silently works; fragile on field reorder
class Result(NamedTuple):
    stdout: str
    stderr: str

result[0]  # compiles and runs; wrong if fields ever reorder

# Good: only named access available
@dataclass
class Result:
    stdout: str
    stderr: str

result.stdout  # explicit and refactor-safe

Placed in usethis-python-functions alongside the existing "Avoid returning tuples" section, which already recommends dataclasses as the structured alternative.

…on-functions skill

Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/df95a12c-3243-420d-a407-77be66dd97e9

Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
Copilot AI changed the title [WIP] Refactor SubprocessResult to use dataclass instead of named tuple docs(skills): add dataclass-over-NamedTuple guideline to usethis-python-functions skill Apr 8, 2026
Copilot AI requested a review from nathanjmcdougall April 8, 2026 00:13
@nathanjmcdougall nathanjmcdougall marked this pull request as ready for review April 8, 2026 00:15
@nathanjmcdougall nathanjmcdougall merged commit a7920f4 into main Apr 8, 2026
1 check passed
@nathanjmcdougall nathanjmcdougall deleted the copilot/refactor-subprocessresult-using-dataclass branch April 8, 2026 00:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

agent: prefer dataclasses over named tuples for structured return types

2 participants