PY-COLL0001 · concrete_collection_parameter

Detect concrete collection parameters that require only an abstract capability.

This is a deterministic rule for python. Read its implementation.

Definition

Inspect operations performed directly on parameters annotated as list, variadic tuple, dict, or set. Report a broader collections.abc input contract only when all observed uses are known and non-mutating. A write through a subscript, which is values[key] = held or del values[key], reaches the same mutating method a named call reaches and keeps the concrete contract. This applies the Python convention of accepting the narrowest required capability while leaving concrete return types alone.

Evidence

Each finding names the callable, the parameter, the concrete annotation it declares, and the exact place the source states it, beside how many operations the body performs on it, which is what proves nothing needs the concrete type. An unknown call, mutation, fixed-position tuple, or mixed capability set suppresses the finding instead of guessing. The repair is a choice between the protocols the body could have asked for.

Exceptions

Keep concrete types at serialization, C-extension, framework, dispatch, hashing, and other exact representation boundaries. Fixed heterogeneous tuples may be records, coordinates, protocol fields, or hash keys. Mutable parameters should retain a mutable contract.

Examples

def first(values: list[int]): return values[0] returns true and can accept Sequence[int], and so does def save(row: dict[str, str]): return row.get("id"), which can accept Mapping[str, str]. def add(values: list[int]): values.append(1) returns false, because appending needs a mutable contract, and so does def store(row: dict[str, str]): row["id"] = "1", because writing one entry needs the same contract. A parameter whose uses the provider could not all resolve also returns false.

References

• Cites “Fluent Python”, chapter 13, Interfaces, Protocols, and ABCs
• Cites “The Python Standard Library”, typing, generic Sequence and Mapping parameters
• Cites “The Python Standard Library”, collections.abc abstract methods and mixins