pyorder

A Python source code ordering linter.

Overview

pyorder is a development tool built on the ast library for ordering Python source code according to specified rules and conventions. Specifically, it is designed to order definitions within a Python module. It does not attempt to order everything in a source file, like attributes or statements outside of definitions. pyorder focuses on ordering Python code according to best practices regarding readability of Python code.

Usage

# install pyorder as a development dependency
uv add pyorder --dev
# check Python files
uv run pyorder path/to/your/file1.py path/to/your/file2.py
# fix Python files
uv run pyorder --fix path/to/your/file1.py path/to/your/file2.py

The --fix option will modify all files that are not ordered according to the rules. Although pyorder attempts to respect valid Python syntax, it does NOT guarantee valid Python syntax or that no logical errors will be introduced after reordering. It simply reorders the definitions according to the rules. Run pyorder without the --fix option first to see the diff output of files that would be modified. Please check all modified files after fixing to ensure that your code is correct.

What exactly is being ordered

pyorder parses a given file as an abstract syntax tree (AST) and considers instances of ast.FunctionDef, ast.AsyncFunctionDef, and ast.ClassDef on the module level and the class level within module-level classes. The philosophy behind this being that definitions structure a codebase and ordering just those gives a good balance between a forced order for readability and structure and freedom to write your code as you please.

Ordering Rules

pyorder enforces the rules on two levels, module-level definitions and class-level definitions of module-level classes. The listed rules below are applied as a sorting key in that priority order within each level of definitions.

Module-level definitions

• callers-before-callees: a definition that calls another definition appears before that definition (excluded are hard dependencies that are needed at definition time, e.g. base classes, arg/kwargs defaults, or decorators).
• functions-before-classes: functions should be defined before classes within the module.
• visibility-ordering: public before private definitions (e.g., public, _private, __more_private)
• alphabetical-ordering: definitions are ordered alphabetically.

Class-level definitions

• classes-before-methods: nested classes should be defined before methods.
• constructor-first: Constructor methods (e.g., __new__, __init__) should be defined before other methods.
• abstract-first: methods decorated with @abstractmethod should be defined before other methods.
• overrides-first: methods decorated with @override should be defined before other methods.
• special-methods-first: special methods (e.g., __str__, __repr__) should be defined before other methods.
• classmethods-first: methods decorated with @classmethod should be defined before other methods.
• callers-before-callees: a definition that calls another definition should be defined before that definition (excluded are hard dependencies that are needed at definition time, e.g. base classes, arg/kwargs defaults, or decorators).
• visibility-ordering: public before private definitions (e.g., public, _private, __more_private) within the class.
• alphabetical-ordering: definitions are ordered alphabetically within the class.

Customization

pyorder does not support inline comments like # noqa. The missing support for inline comments is intentional and is part of this tool's philosophy of enforcing a consistent ordering of Python source code.However pyorder is built on pyrig-runtime. Therefore customization can be done by writing a plugin. pyrig is another tool built on pyrig-runtime and describes how to write a plugin based on the system of pyrig-runtime subclasses.

Documentation

Please refer to the official documentation for more details and examples.