Skip to content
Sarj Standards

Python · maintainability

stepdown

python:stepdown

A private helper used by one caller should be defined below that caller.

Code
SARJ023
Default
error
Fix
none
Languages
python

Why

Caller-first ordering keeps the module's public flow visible before its implementation details.

Fix

Move the private helper below its sole caller without changing either body.

Before / after

Executed by this rule’s unit tests.

Before

Private helper appears before its sole caller

service.py · focus
def _parse(payload: dict) -> dict:
    return payload

def handle(payload: dict) -> dict:
    return _parse(payload)

After

Private helper appears after its sole caller

service.py · focus
def handle(payload: dict) -> dict:
    return _parse(payload)

def _parse(payload: dict) -> dict:
    return payload

Limits

  • Generated files, tests, `__main__.py`, recursive helpers, and helpers with multiple callers are excluded.
  • Dynamic references that cannot identify a sole caller are not reported.