Python API reference¶

dddlint is a library as well as a CLI. The pipeline is three steps you can call directly: extract definitions from source, check them against a config, and read back findings.

Pipeline at a glance¶

from pathlib import Path
from tempfile import mkdtemp

from dddlint.check import check
from dddlint.config import Config, SynonymGroup
from dddlint.extract import definitions, language_for

source = Path(mkdtemp()) / "repo.py"
source.write_text("class ClientRepository:\n    pass\n")

language = language_for(source)
defs = definitions(source, language)

config = Config(synonyms=[SynonymGroup(canonical="customer", aliases=["client"])])
findings = check(defs, config)

assert language == "python"
assert defs[0].name == "ClientRepository"
assert findings[0].rule == "alias"

dddlint.extract¶

language_for(path)¶

Return the tree-sitter language name auto-detected from path, or None if it cannot be detected.

from pathlib import Path

from dddlint.extract import language_for

assert language_for(Path("main.rs")) == "rust"
assert language_for(Path("data.unknownext")) is None

definitions(path, language)¶

Parse path with the given language and return a list of Definition. Reads classes, functions, methods, structs, interfaces, enums, traits, variables, and constants.

Definition¶

Frozen dataclass describing one extracted name.

dddlint.check¶

check(definitions, config)¶

Run every code rule over definitions and return a flat list of Finding.

tokenise(name)¶

Split an identifier into lowercase tokens on case and separator boundaries. This is the unit both rule matching and drift detection work on.

from dddlint.check import tokenise

assert tokenise("getUserById") == ("get", "user", "by", "id")
assert tokenise("get_user_by_id") == ("get", "user", "by", "id")
assert tokenise("HTTPServer") == ("http", "server")

Finding¶

Frozen dataclass describing one violation.

dddlint.config¶

load_config(path)¶

Read and validate a dddlint.yaml into a Config. See the configuration reference for the schema and the Config, SynonymGroup, and Context models.

dddlint.config_check¶

check_config(config, path)¶

Validate a Config for internal contradictions and return a list of Finding with config: rule names. Run automatically by dddlint lint.

dddlint.discover¶

source_files(root, exclude, base=None)¶

Yield every file under root, skipping the built-in directories, the exclude gitwildmatch patterns, and any .gitignore. Patterns are matched against paths relative to base, defaulting to root. Pass the config file's directory as base so patterns keep working when root is a subdirectory.

from pathlib import Path
from tempfile import mkdtemp

from dddlint.discover import source_files

root = Path(mkdtemp())
(root / "src").mkdir()
(root / "src" / "keep.py").write_text("x = 1\n")
(root / "src" / "gen.py").write_text("y = 2\n")

found = {p.name for p in source_files(root / "src", ["src/gen.py"], root)}

assert found == {"keep.py"}

dddlint.embed¶

await embed_names(names, config, model=None)¶

Embed names with the pydantic-ai model from an Embeddings config and return {name: vector}. Only names missing from config.cache are sent, in batches of config.batch_size; the cache is keyed by model and dimensions. Pass model to inject an EmbeddingModel directly instead of resolving config.model.

dddlint.cluster¶

Vector helpers over plain list[float], backed by numpy.

dddlint.insights¶

Meaning-level analysis for dddlint map. Each takes the definitions, a {name: vector} mapping, and a Config.

Insight¶

Frozen dataclass describing one observation.

Point¶

Frozen dataclass placing one name on the map: name, x, y, role ("verb" for functions and methods, else "noun"), scope, and cluster.