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

Group	Contents
1 — Standard library	os, re, pathlib, argparse, json, etc.
2 — Third-party	numpy, yaml, mcp, onnxruntime, transformers, etc.
3 — Local (relative)	from .base import ..., from .chunk import ...

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

Category	Style	Example
Modules/packages	snake_case	chunk.py, make_bundle.py
Classes	PascalCase	OnnxEmbedder, MlxEmbedder
Functions/methods	snake_case	parse_frontmatter, embed_with_progress
Constants	UPPER_CASE	DEFAULT_MODEL_ID, _MAX_CHUNK_CHARS
Private (_ prefix)	_single_leading	_resolve_model_dir, _FRONTMATTER_RE
Type variables	_T or descriptive	—

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.
    """