PY-CLAS0003 · utility_namespace_class_count

Count stateless classes that only namespace module-shaped functions.

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

Definition

Inspect every class in the selected Python sources. Require at least one directly declared synchronous or asynchronous function. Report the class when every function is static, class bound without reading class state, or an ordinary method that only calls sibling methods. The class must have no base other than object, no class keyword other than metaclass=type, and no instance-oriented field declaration or receiver-state read. Uppercase constants do not suppress the finding because module constants express the same ownership directly.

Evidence

Each finding identifies the class range, function count, and every qualifying function with its decorators. The result value is the number of stateless utility namespace classes.

Exceptions

A type stub declares no bodies at all, so every method in one reads no state by construction and a .pyi file is never inspected here. Nontrivial inheritance and metaclasses exempt framework contracts, enums, Protocols, and ABCs. Lowercase annotated fields, receiver assignments, __slots__, and attrs or dataclass field factories exempt data-bearing classes. Receiver state reads, properties, constructors, abstract methods, and custom decorators also exempt the whole class. Calling another method through self does not establish state. The rule reports structure only and does not automatically move functions because public access paths may be externally visible.

Examples

Bad

`class TextTools` containing static helpers and `def render(self)` that only calls those
helpers is reported because a module already provides the same namespace boundary.

Good

class Record with an annotated value field is accepted. A Protocol, Enum, ABC, framework subclass, property-bearing class, or class whose ordinary method reads self.value is also accepted even when it contains static helpers.

References

• Adapts Pylint R0903 too-few-public-methods
• Cites “The Python Tutorial”, modules as namespaces. Open reference
• Cites “The Python Language Reference”, class creation and metaclasses. Open reference
• Cites “The Python Standard Library”, functions, staticmethod. Open reference
• Cites “The Python Standard Library”, functions, classmethod. Open reference
• Cites “PEP 544, Protocols”. Open reference