Skip to main content
Syft-Flwr uses automated tools to maintain code quality and consistency across the codebase.

​
Ruff Linter and Formatter

The project uses Ruff, a fast Python linter and formatter written in Rust. Ruff combines the functionality of multiple tools (Flake8, Black, isort, etc.) into a single, blazing-fast tool.

​
Running Ruff

uv run ruff check .

​
Ruff Configuration

Ruff is configured in pyproject.toml:
pyproject.toml
[tool.ruff]
exclude = [".archive"]

[tool.ruff.lint]
extend-select = ["I"]  # Enable isort-style import sorting

[tool.ruff.lint.per-file-ignores]
"**/__init__.py" = ["F401"]  # Allow unused imports in __init__.py

​
What Ruff Checks

  • Line length (default 88 characters)
  • Indentation and whitespace
  • Quote style consistency
  • Trailing commas
  • Import sorting (isort-compatible)
  • Unused imports
  • Import order and grouping
  • Duplicate imports
  • Unused variables
  • Undefined names
  • Syntax errors
  • Common anti-patterns
  • Type annotation issues
  • Docstring presence and format
  • Naming conventions
  • Complexity warnings
  • Security vulnerabilities

​
Pre-commit Hooks

Pre-commit hooks automatically check code quality before each commit, ensuring that only clean code enters the repository.

​
Installing Pre-commit Hooks

1

Install hooks

Install the pre-commit hooks in your local repository:
uv run pre-commit install
2

Verify installation

Make a test commit to verify hooks are working:
git commit --allow-empty -m "test: verify pre-commit hooks"

​
Running Pre-commit Manually

uv run pre-commit run

​
Configured Hooks

The project uses the following pre-commit hooks (configured in .pre-commit-config.yaml):

​
Standard Pre-commit Hooks

check-ast

Validates Python syntax by checking the abstract syntax tree

trailing-whitespace

Removes trailing whitespace from all files

check-docstring-first

Ensures docstrings appear before code in modules

check-json

Validates JSON file syntax (excludes .vscode)

check-yaml

Validates YAML file syntax

check-merge-conflict

Detects merge conflict markers in files

check-executables-have-shebangs

Ensures executable files have proper shebangs

debug-statements

Detects debug statements like pdb.set_trace()

requirements-txt-fixer

Sorts and fixes requirements.txt files

mixed-line-ending

Ensures consistent line endings (LF)

​
Ruff Hooks

ruff

Runs Ruff linter with auto-fix on Python, .pyi, and Jupyter filesArguments: --fix, --exit-non-zero-on-fix, --show-fixes

ruff-format

Runs Ruff formatter on Python, .pyi, and Jupyter files

​
Notebook Hooks

nbstripout

Strips output from Jupyter notebooks before committingThis keeps notebooks clean and prevents large diffs from cell outputs.

​
Pre-commit Configuration

The complete .pre-commit-config.yaml configuration:
.pre-commit-config.yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
  rev: v4.5.0
  hooks:
  - id: check-ast
    always_run: true
  - id: trailing-whitespace
    always_run: true
  - id: check-docstring-first
    always_run: true
  - id: check-json
    always_run: true
    exclude: ".vscode"
  - id: check-yaml
    always_run: true
  - id: check-merge-conflict
    always_run: true
    args: [ "--assume-in-merge" ]
  - id: check-executables-have-shebangs
    always_run: true
  - id: debug-statements
    always_run: true
  - id: requirements-txt-fixer
    always_run: true
  - id: mixed-line-ending
    args: [ "--fix=lf" ]

- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: "v0.6.5"
  hooks:
  - id: ruff
    args: [ --fix, --exit-non-zero-on-fix, --show-fixes ]
    types_or: [ python, pyi, jupyter ]
  - id: ruff-format
    types_or: [ python, pyi, jupyter ]

- repo: https://github.com/kynan/nbstripout
  rev: 0.7.1
  hooks:
  - id: nbstripout

​
Bypassing Hooks

In rare cases, you may need to bypass pre-commit hooks:
Only bypass hooks when absolutely necessary. Bypassing hooks can introduce code quality issues.
git commit --no-verify -m "commit message"

​
Code Quality Workflow

Follow this workflow to maintain code quality:
1

Write code

Implement your changes following Python best practices
2

Format code

Run Ruff formatter to ensure consistent style:
uv run ruff format .
3

Fix linting issues

Run Ruff linter and fix auto-fixable issues:
uv run ruff check . --fix
4

Run tests

Ensure all tests pass:
just test-unit
5

Commit changes

Commit your changes. Pre-commit hooks will run automatically:
git add .
git commit -m "feat: your feature description"

​
CI Code Quality Checks

Code quality checks run automatically in CI on every push and pull request:
  • Ruff linting: Checks for code quality issues
  • Ruff formatting: Verifies code is properly formatted
  • Pre-commit hooks: All configured hooks run in CI
  • Type checking: Static type analysis (if configured)

​
Best Practices

  • Follow PEP 8 style guide
  • Write clear, descriptive variable and function names
  • Keep functions small and focused
  • Add docstrings to all public functions and classes
  • Use type hints for function parameters and return values
Organize imports in three groups:
  1. Standard library imports
  2. Third-party imports
  3. Local application imports
Ruff automatically sorts imports within these groups.
Use Google-style or NumPy-style docstrings:
def function(param1: str, param2: int) -> bool:
    """Brief description.
    
    Detailed description if needed.
    
    Args:
        param1: Description of param1
        param2: Description of param2
        
    Returns:
        Description of return value
        
    Raises:
        ValueError: When invalid input is provided
    """
    return True
  • Use specific exception types
  • Provide informative error messages
  • Clean up resources in finally blocks
  • Use context managers (with statements) when possible

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us