Python Api Signature

Process

1. Keep the skill on public signature shape; defer all concrete type-hint rules to python-type-hints-strict.
2. Ban mutable default values such as [], {}, set(), and other shared mutable objects; prefer None plus fresh per-call initialization when emptiness is the real default.
3. Allow immutable defaults such as None, numbers, strings, booleans, tuples, frozensets, enum members, and stable constants when they match the API contract.
4. Use None as the default missing signal when None is not itself a valid business value; use a private sentinel such as _MISSING only when the API must distinguish "not provided" from "explicitly passed as None".
5. Keep parameter order predictable: required parameters first, then defaulted ones, then varargs only when truly needed, then keyword-only parameters.
6. Prefer keyword-only parameters when positional calls would hide intent, especially for boolean flags or easily confused same-shape values.
7. Treat a single boolean flag as a caution case and two or more boolean flags as a strong refactor signal; prefer semantic methods, clearer mode parameters, or a parameter object.
8. Reject broad public *args / **kwargs by default; allow them only for narrow wrapper, adapter, or framework-required signatures, and extract a parameter object when the explicit signature becomes too wide.

Examples

• Positive: Use tags: tuple[str, ...] = () for a fixed immutable default, or items: list[str] | None = None plus per-call initialization; force send_notify to be keyword-only when the flag must remain.
• Negative: Ship def send(items: list[str] = []): ..., hide public options in **kwargs, or stack multiple boolean flags into one crowded signature.

Outputs

• a review-ready public Python API-signature rule set or review guide
• defaults for safe parameter values, sentinel usage, ordering, keyword-only choices, and refactor signals
• local examples for common signature smells, safer alternatives, and split signals

Boundaries

• Do not define strict type-annotation syntax or typing escape hatches; use python-type-hints-strict for that.
• Do not choose the concrete parameter-object model; use python-model-selection when the API should extract one.
• Do not define class internals, naming rules, or framework-specific hook conventions beyond narrow signature-shape exceptions.
• Do not cover positional-only parameters (/) in the first draft except as an explicit out-of-scope note.

Local references

• examples.md: mutable-default examples, sentinel patterns, keyword-only and flag cases, fat-signature refactors, and split signals