PY-COLL0004 · explicit_tuple_construction

Count explicit immutable collection construction in project code.

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

Definition

Report every unshadowed call to the builtin tuple or frozenset constructor. This project’s internal collection policy uses lists and sets unless immutable identity is a proved domain or public contract. A constructor call is the exact place that concrete representation enters.

Evidence

The value is the number of immutable collection constructor calls. A review fix converts an empty tuple or tuple built from a literal sequence to the corresponding list. Other calls stay report-only because changing hashability, ordering, or a public return type needs review.

Exceptions

A source file that binds either builtin name is conservatively excluded because the call may target project code. Keep immutable identity where the value is a dictionary key, crosses a stable public boundary, or is required by another API, and exclude that exact location.

Examples

Bad

`items = tuple(source)` and `names = frozenset(values)` force internal data into immutable
concrete containers without a stated contract.

Good

items = list(source) and names = set(values) retain the general project representation. A fixed heterogeneous tuple such as (x, y) remains a record expression and is not a constructor.

References

• Cites “Fluent Python”, chapter 2, An Array of Sequences
• Cites “The Python Language Reference”, list displays. Open reference
• Cites “Pydantic documentation”, standard library types, tuples. Open reference