CodeSorter¶

CodeSorter is a LibCST codemod that automatically sorts and organizes Python code.

Warning

Only apply CodeSorter to a code base you own or maintain. Reordering an entire file is a sweeping, opinionated change that conflicts with in-flight work and erases the history of carefully chosen ordering. Opening a pull request that runs CodeSorter across someone else’s project is strongly discouraged — it is noisy, unsolicited, and burdensome to review. Adopt it as a pre-commit hook in your own repositories instead, where every contributor benefits from the consistent ordering.

Features¶

Smart Sorting: Automatically sorts functions, classes, and methods alphabetically
Decorator Awareness: Properly handles @property, @staticmethod, @classmethod, and @pytest.fixture decorators
Hierarchical Organization: Maintains logical grouping within classes and modules
Constant Grouping: Orders each scope as constants, then classes, then functions, sorting constants by dependency while preserving enum and dataclass field order
Keyword Sorting: Alphabetizes keyword arguments in calls, keyword-only parameters, and dict string keys, while preserving */** unpacking semantics and the keyword-argument order of order-sensitive callables such as OrderedDict
Pytest Integration: Special handling for pytest fixtures with proper scope ordering
CLI Interface: Simple command-line interface for easy integration
Pre-commit Hook: Ready-to-use pre-commit hook for automated code organization

Installation¶

From PyPI:

# install the codesorter CLI as a standalone tool
uv tool install codesorter
# or add it to a project's lint dependency group
uv add --group lint codesorter

From Source:

git clone https://github.com/praw-dev/CodeSorter.git
cd CodeSorter
uv tool install .

Development Installation:

git clone https://github.com/praw-dev/CodeSorter.git
cd CodeSorter
uv sync

Usage¶

Command Line Interface¶

The simplest way to use CodeSorter is through the command-line interface:

# Sort a single file
codesorter my_file.py

# Sort all Python files in a directory
codesorter my_project/

# Sort with additional options
codesorter --help

Pre-commit Hook¶

Add CodeSorter to your pre-commit configuration to automatically sort code on every commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/praw-dev/CodeSorter
    rev: v0.2.5
    hooks:
      - id: codesorter

Or use the check-only variant, which fails the hook without modifying files:

repos:
  - repo: https://github.com/praw-dev/CodeSorter
    rev: v0.2.5
    hooks:
      - id: codesorter-check

Programmatic Usage¶

You can also use CodeSorter programmatically:

import libcst as cst
from codesorter.sort_code import SortCodeCommand
from libcst.codemod import CodemodContext

# Parse your code
code = """
def z_function():
    pass

def a_function():
    pass
"""

# Create context and command
context = CodemodContext()
command = SortCodeCommand(context)

# Transform the code
result = command.transform_module(cst.parse_module(code))
print(result.code)

How It Works¶

CodeSorter uses LibCST (Concrete Syntax Tree) to parse and transform Python code. It applies sophisticated sorting rules:

Function Sorting¶

Functions are sorted alphabetically by name
Global functions are sorted separately from class methods

Class Method Sorting¶

Methods are grouped by kind, in this order:
- @abstractmethod methods
- pytest fixtures (autouse fixtures first)
- @staticmethod methods
- @classmethod methods
- cached properties and @property methods (getter, then setter, then deleter)
- @contextmanager methods
- regular instance methods
Within each group, methods are sorted alphabetically, with leading-underscore (_private and __dunder__) names ahead of public ones

Pytest Fixture Sorting¶

Fixtures are sorted by scope (session, package, module, class, function)
Within each scope, fixtures are sorted alphabetically
autouse fixtures are handled specially

Example Transformation¶

Before:

class MyClass:
    def z_method(self):
        pass

    @property
    def a_property(self):
        pass

    @staticmethod
    def b_static():
        pass

After:

class MyClass:
    @staticmethod
    def b_static():
        pass

    @property
    def a_property(self):
        pass

    def z_method(self):
        pass

Development¶

Setting Up Development Environment¶

# Clone the repository
git clone https://github.com/praw-dev/CodeSorter.git
cd CodeSorter

# Install with development dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install

Running Tests¶

# Run all tests
uv run pytest

# Run a specific test file
uv run pytest tests/test_sort_code.py

# Run the full tox matrix (tests, type, pre-commit)
uv run tox

Code Quality¶

The project uses several tools to maintain code quality:

Ruff: Fast linting and formatting
Pyright: Type checking
Pre-commit: Automated quality checks

Run all quality checks:

uv run pre-commit run --all-files

Contributing¶

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes and add tests
Run the test suite: uv run pytest
Run pre-commit hooks: pre-commit run --all-files
Commit your changes: git commit -m "Add feature"
Push to your fork: git push origin feature-name
Create a Pull Request

Examples¶

See the examples/ directory for before and after examples of CodeSorter in action:

examples/before_example.py: Unsorted code
examples/after_example.py: Same code after sorting

License¶

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Changelog¶

See the change log for the full list of changes.