Enforcing Consistent Class Element Ordering in Ruff Linter

[Nickleaton]

Proposal: Enforcing Consistent Class Element Ordering in Ruff Linter

Summary

Introduce a new Ruff linter rule to enforce a consistent ordering of class elements, ensuring readability, maintainability, and logical grouping of methods.

Motivation

Python developers often structure classes in a way that groups related methods together, improving code comprehension and reducing cognitive load. However, there is currently no built-in enforcement of method ordering, leading to inconsistencies across projects. This proposal defines a structured order that:

• Preserves programmer-defined groupings.
• Ensures subclasses follow parent-defined method ordering.
• Organizes special methods (dunder methods) in a logical sequence.

Rule Definition

1. Class Variables

Class-level variables should be declared first, before any methods.

class Example:
    CLASS_VAR = 42

2. Creation Methods

These methods should appear in the following order if present:

• __init_subclass__
• __init__

class Example:
    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
    
    def __init__(self):
        pass

3. Public and Private Methods

• Methods should follow the order defined in the parent class.
• If a subclass introduces a new method, that method defines a new expected order for its children.
• This order is not alphabetical but instead follows logical programmer intent.
• Names of public and private methods should follow a good naming convention. Since it's difficult for a program to infer logical groupings, the linter assumes that the programmer has arranged methods correctly within a class.
• All subclasses must maintain the order defined by their parent class.
• If a new method is added in a subclass, it is assumed to be in the right place, and all further subclasses of that subclass must follow the updated order.
• The enforcement is essentially a list of method names in a specific order, which must be respected throughout the class hierarchy.

Example:

class Base:
    def method_a(self):
        pass
    
    def method_b(self):
        pass

class Derived(Base):
    def method_a(self):
        pass  # Must remain in the same order as Base
    
    def method_b(self):
        pass
    
    def method_c(self):
        pass  # Adds a new ordering constraint for future subclasses

4. Dunder Methods

Dunder methods should be grouped logically and ordered as follows:

1. Object Initialization & Destruction

   • __new__
   • __init__
   • __del__

2. String Representation

   • __repr__
   • __str__
   • __format__
   • __bytes__

3. Comparison & Ordering

   • __eq__, __ne__
   • __lt__, __le__, __gt__, __ge__

4. Arithmetic & Unary Operators

5. Bitwise Operators

6. In-Place Operators

7. Type Conversion & Casting

8. Attribute Access

9. Container & Sequence Protocol

10. Context Manager Methods

    • __enter__ before __exit__

Example:

class Example:
    def __eq__(self, other):
        pass
    
    def __lt__(self, other):
        pass

    def __repr__(self):
        pass
    
    def __str__(self):
        pass

Configuration Option

There should be an optional configuration setting that allows projects to define their preferred method ordering explicitly. This configuration would list method names in a specific order, which the linter would enforce. This ensures flexibility for teams with established conventions while maintaining consistency across subclasses.

Example configuration:

[tool.ruff.class_order]
preferred_order = [
    "__init_subclass__",
    "__init__",
    "setup",
    "execute",
    "cleanup",
    "__repr__",
    "__str__"
]

Implementation Details

• This rule should be opt-in initially.
• The linter should learn method order from parent classes and enforce it in subclasses.
• Logical dunder method groupings should be enforced when present.
• A configuration option should allow teams to define a custom preferred method order.

Conclusion

This rule will standardize class structures, making Python codebases more consistent and readable, while still respecting developer intent.

[MichaReiser]

Thanks for the detailed write up and the rule proposal. I can see how a rule like this could be useful. I do agree that it will probably require a fair amount of configuration support to be useful for many projects. I also think that the rule requires an autofix, it's otherwise annoying for users if they have to reorder members manually

We may want to consider adding such a rule in the future, but we don't plan on adding such an opinionated rule now because we first want to recategorize the rules (#1774) to make it easier for users to opt-in/opt-out to only correctness, idiomatic, or stylistic (like this) rule.

[Nickleaton]

Thanks. I've actually spent today writing some code for this. I've got some basic first steps done. First time I've used the ast library, and its surprisingly fast.

On the configuration, it depends. For dunder methods, the outline above which I found on the net is pretty good. That would be a one off.

For the rest, assuming you want the same order as the parent class is more than reasonable. It then learns the order from your own code. ie. Just keep it consistent rather than force it.

I did discover a django opinionated rule set by the way. There are probably others.

Anything with deep heirarchies would benefit from it.

I'm going to write it as a stand along script, down load some projects and run it against them to see what it throws up.

One area where its a bit more complicated, is with multi-inheritance. For the moment I'm assuming first class imported is the pattern to follow.