Skip to content
Sarj Standards

Python · maintainability

prefer-namedtuple-over-tuple-return

python:prefer-namedtuple-over-tuple-return

Public functions should return named records instead of fixed positional tuples.

Code
SARJ026
Default
error
Fix
none
Languages
python

Why

A positional tuple hides field meaning and lets callers silently swap or misread values.

Fix

Return a `NamedTuple`, frozen dataclass, or frozen validation model with named fields.

Before / after

Executed by this rule’s unit tests.

Before

Public function returns a positional pair

app/profile.py · focus
def load_profile() -> tuple[str, int]:
    return 'Ada', 42

After

Public function returns a named record

app/profile.py · focus
from typing import NamedTuple

class Profile(NamedTuple):
    name: str
    age: int

def load_profile() -> Profile:
    return Profile('Ada', 42)

Limits

  • Generated files, tests, private functions, nested functions, and declared overrides are excluded.
  • Only fixed multi-item tuple annotations or inferred tuple-literal returns are reported.