Code Quality

Code Quality

Maintaining a clean, strictly typed, and uniform codebase is critical for reproducible machine learning research and collaborative development. The MLFramework Template enforces code quality standards through automated formatting and static type analysis.

Toolchain

This template utilizes a modern, high-performance Python toolchain managed by uv:

• Ruff: An extremely fast Python linter and code formatter written in Rust. It replaces legacy tools such as flake8, isort, and black.
• Mypy: A static type checker for Python. The template configures Mypy in strict mode to ensure robustness across the core architecture and pipeline logic.

Automation via Makefile

To abstract the execution of these tools, the repository includes a Makefile with predefined targets. These commands automatically utilize the isolated .venv environment managed by uv, ensuring no conflicts with system-level Python installations.

Formatting the Codebase

To automatically format all Python files, enforce line lengths, and sort imports according to the defined standard, execute:

make format

Static Analysis and Linting

To identify syntax errors, unused variables, or type inconsistencies without modifying the files, execute:

make lint

Complete Pipeline Check

Before committing any code to the version control system, it is highly recommended to run the combined check:

make check

This command sequentially executes the formatter and the linter. If any step fails, the output will indicate the exact file and line requiring manual intervention.

Type Checking Practices

Because Mypy is configured with strict = true in pyproject.toml, all function signatures must include correct type hints.

When overriding standard framework methods (e.g., PyTorch Lightning hooks) that require arguments you do not intend to use, prefix the argument name with an underscore (e.g., _batch_idx). This idiom explicitly signals to both Ruff and Mypy that the variable is intentionally unused, thereby preventing unnecessary warnings while maintaining strict interface compliance.