Python Style ¶

Python's philosophy—"There should be one obvious way to do it"—guides how we write code at Dedalus. This guide codifies our conventions for Slurmq.

We're heavily inspired by Google's Python style guide, adapted for our needs.

The Documents ¶

Document	What It Covers	Who It's For
Guide	The foundations—formatting, naming, structure	Everyone
Best Practices	Patterns that work well in practice	Anyone who wants to level up
Reference	Complete style reference with rationale	Deep dives, understanding "why"

Guide is definitive. If you read nothing else, read that.

Best Practices collects patterns that have proven useful. Not mandatory, but worth adopting.

Reference provides the complete style guide with full rationale (Definition → Pros → Cons → Decision) behind each choice.

Why Bother ¶

Style guides get a bad reputation. They can feel pedantic. But consider: every minute spent debating formatting is a minute not spent building something useful.

Python already solved most style debates with tools like ruff. These docs handle the rest.

The goal isn't uniformity for its own sake. It's readability. Code is read far more than it's written. Consistent style means readers spend their mental energy understanding logic, not deciphering formatting quirks.

What These Docs Do ¶

Establish shared vocabulary for code reviews
Document Python idioms with concrete examples
Explain tradeoffs when multiple approaches work
Reduce surprises during review

What These Docs Don't Do ¶

List every possible comment a reviewer could make
Replace judgment with rules
Justify rewriting working code for style points

There will always be differences between programmers. That's fine. We're not aiming for perfect uniformity—we're aiming for code that's easy to read and maintain.

Key Principles ¶

Clarity ¶

The code's purpose should be obvious to readers:

Use descriptive variable names
Add comments that explain why, not what
Break up dense code with whitespace
Extract complex logic into well-named functions

Simplicity ¶

Write code for the people who will use, read, and maintain it:

Don't add unnecessary abstraction
Prefer stdlib over external dependencies
Use mundane names for mundane things
Avoid "clever" code

Consistency ¶

Match the patterns already in the codebase:

Use the same naming conventions
Follow existing module structure
Match error handling patterns

Tooling ¶

We use modern Python tooling—fast, Rust-based tools that have become the industry standard.

Project Management: uv ¶

uv is an extremely fast Python package and project manager. It replaces pip, pip-tools, pipx, poetry, pyenv, and virtualenv with a single tool that's 10-100x faster.

uv sync              # Install dependencies from lockfile
uv add httpx         # Add a dependency
uv run pytest        # Run commands in the virtual environment
uv python install    # Install Python versions

Linting & Formatting: ruff ¶

ruff is an extremely fast Python linter and formatter. It replaces Flake8, Black, isort, and dozens of Flake8 plugins with a single tool that's 10-100x faster.

uv run ruff check src/slurmq/       # Find issues
uv run ruff check src/slurmq/ --fix # Auto-fix what can be fixed
uv run ruff format src/slurmq/      # Format code (replaces Black)

Ruff provides 800+ built-in rules with native re-implementations of popular plugins. It catches issues instantly—no more waiting for slow linters.

Type Checking: ty ¶

ty is Astral's Rust-based type checker. It completes our all-Astral toolchain (uv + ruff + ty) and is 10-100x faster than mypy.

uv run ty check src/slurmq/

All Together ¶

# Full check before commit
uv run ruff check src/slurmq/ --fix
uv run ruff format src/slurmq/
uv run ty check src/slurmq/
uv run pytest

All code must pass these checks before merge.

Quick Reference ¶

Naming ¶

Type	Convention	Example
Module	`snake_case`	`quota.py`
Class	`PascalCase`	`QuotaChecker`
Function	`snake_case`	`fetch_user_jobs`
Constant	`SCREAMING_SNAKE`	`DEFAULT_TIMEOUT`
Private	`_leading_underscore`	`_internal_state`

Imports ¶

# Standard library
from __future__ import annotations

import subprocess
from collections.abc import Sequence
from typing import Any

# Third-party
from pydantic import BaseModel

# Local
from slurmq.core.quota import QuotaChecker
from slurmq.core.models import JobRecord

Type Hints ¶

Required for all public APIs:

def fetch_user_jobs(
    user: str,
    cluster: ClusterConfig,
    *,
    all_users: bool = False,
) -> list[JobRecord]:
    """Fetch job records from Slurm."""
    ...

Docstrings ¶

Google style, always for public APIs:

def calculate_gpu_hours(records: list[JobRecord]) -> float:
    """Calculate total allocated GPU-hours from job records.

    Args:
        records: Job records to sum.

    Returns:
        Total GPU-hours (allocation-based, not utilization).

    Raises:
        ValueError: If records contain invalid data.

    """

Next Steps ¶

Start with the Guide. It covers formatting, naming, and structure—the fundamentals you'll use every day.