python-code-style

When to use

• Writing new Python files for the project
• Reviewing code for style consistency
• Configuring ruff or another linter/formatter
• Onboarding a new contributor

Project conventions

These are the conventions established by the existing codebase at atlas/.

Import ordering

Three groups separated by a blank line:

import re
from pathlib import Path

import numpy as np
import yaml

from .base import Embedder

Within each group, sort alphabetically. Use import module over from module import symbol unless you need fewer than 3 symbols from a module.

String quoting

Double quotes for all strings and docstrings:

name = "servicenow-atlas"
description = f"Bundle version {version}"

Single quotes are allowed only to avoid escaping inside f-strings:

f"    - {h['publication']}/{h['file']}"

Naming conventions

Docstrings

Triple double quotes ("""..."""). Module-level docstrings provide design context. Function docstrings describe parameters, return values, and edge cases.

For RST cross-references to other code, use :meth:, :class:, :mod::

"""...as described in :meth:`Embedder.embed`..."""

When documenting parameters inline (not via Google-style section headers), place the description after --:

def chunk_file(path: Path, repo_root: Path) -> list[dict]:
    """Chunk a single markdown file, splitting on H2 boundaries.

    Malformed YAML frontmatter is logged and treated as no frontmatter.
    """

f-strings

Always use f-strings. Do not use .format() or % formatting.

# Correct
logger.info("Chunked %s files in %.2fs", count, elapsed)

# Also correct (f-strings for display strings)
path = f"{publication}/{filename}"

Line length

No strict line length is enforced. Use judgment:

• Keep lines under ~100 characters when readable.
• Break long strings at logical boundaries (e.g., between sentences).
• Long argument lists can span multiple lines.

Blank lines

• Two blank lines before top-level class/function definitions.
• One blank line between methods inside a class.
• One blank line after module docstring.
• Import groups separated by one blank line.

from __future__ import annotations

Add this as the first import in every .py file (after the module docstring):

"""Module docstring."""

from __future__ import annotations

This defers annotation evaluation and is required by the requires-python = ">=3.11" constraint.

Recommended setup

Configure ruff (not currently set up — recommended)

Create .ruff.toml:

target-version = "py311"
line-length = 100

[lint]
select = ["E", "F", "I", "N", "W", "UP", "D"]
ignore = ["D203", "D213", "D415"]  # Allow flexible docstring convention

[format]
quote-style = "double"

Then run:

ruff check .
ruff format .

Pre-commit hook (optional)

If you set up pre-commit, add .pre-commit-config.yaml with ruff and ruff-format.

References

• pyproject.toml — project configuration
• README.md — not a style guide, but documents project conventions
• ruff documentation for rule selection