Dogmatic

An opinionated Python linter and formatter built on Ruff, with native rules for typed data boundaries, explicit dependency injection, async execution, pytest, named constants, and focused application modules.

uv tool install dogmatic
dogmatic check .
dogmatic format .

Maintainers: see the private multi-platform release process for building, testing, auditing, and publishing wheels for macOS and Linux.

The Python package also supports python -m dogmatic. Dogmatic uses Ruff's configuration format, including [tool.ruff] in pyproject.toml, ruff.toml, and existing rule selectors and suppressions.

Dogmatic's release version is independent of its Ruff engine version. Ruff's required-version setting checks the engine version, currently 0.16.6.

All custom checks and companion application policies are enabled by default. No policy download or enablement flags are required. The executable includes offline explanations, configuration examples, and the complete default policy:

dogmatic guide
dogmatic guide --starter
dogmatic guide --policy
dogmatic rule custom-repository-boundary
dogmatic config lint.custom

Existing projects can adopt policies incrementally while keeping these strict out-of-the-box defaults. Start with an opt-in configuration:

[tool.ruff.lint.custom]
policy-mode = "opt-in"
rule-groups = ["data-modeling"]

To adopt rules one file at a time, save a full Git commit SHA as ratchet-from under [tool.ruff]. Ordinary dogmatic check . then enforces whole files touched since that commit, including local edits and new files. Committed changes remain enforced after reverts. Use --show-files to inspect the enforced set, --fix to fix those files, or --no-ratchet for a full scan. This requires complete Git history and applies to CLI lint checks. dogmatic guide explains setup and CI configuration.

For adoption through individual accepted violations, review the findings, record the existing backlog, and enforce progress. Baselines require --no-ratchet if a ratchet is configured:

dogmatic guide --groups
dogmatic baseline create . --output .dogmatic-baseline.json
dogmatic check . --baseline .dogmatic-baseline.json
dogmatic baseline check --baseline .dogmatic-baseline.json

Commit the baseline and configuration. The baseline check is suitable for CI: it rejects new violations and obsolete allowances. After fixing accepted findings, run dogmatic baseline prune and commit the reduced baseline. Ordinary Ruff findings remain actionable. The bundled dogmatic guide includes the complete incremental adoption walkthrough, including adding groups, existing selector precedence, baseline replacement, editor behavior, and command limitations. dogmatic guide --starter --opt-in prints an empty opt-in configuration for starting with no policy groups.

Most rules work immediately. Repository boundaries require module mappings; application-specific validators, clients, and setup functions can be registered with lint.custom. Merge the starter configuration into your existing pyproject.toml and replace its example package names.

Application modules exceeding 300 code lines are flagged for review and splitting into focused submodules. Comments and docstrings do not count; tests, stubs, and notebooks are exempt. Configure lint.custom.max-module-lines to change the limit.

Packages with more than ten immediate application modules or subpackages are also flagged. Each child package counts once and is checked independently; the package initializer, tests, stubs, and non-Python assets are excluded. Configure lint.custom.max-package-entries to change this positive limit. File-based CLI checks inspect siblings even for single-file inputs; stdin and editor checks do not run this package-level rule. dogmatic guide explains suppression and incremental adoption.

dogmatic check . also flags repeated consecutive statement blocks within and across application modules, starting at five statements. This includes executable module code, main guards, class bodies, functions, and nested control flow; declarations alone do not qualify. Configure lint.custom.min-duplicate-statements to adjust this threshold. Comments, docstrings, spacing, and consistent local-variable renames are ignored. External APIs, literal values, and variable-use relationships must match. Cross-module detection requires a CLI file collection and does not run on stdin or in the language server.

Three additional default rules suggest shared abstractions when code differs: custom-duplicate-algorithm recognizes consistent policy-constant substitutions, custom-duplicate-workflow allows a small number of inserted steps, and custom-duplicate-computation compares sums and collection-building loops with comprehensions. Their offline explainers describe thresholds and exclusions. These are heuristic findings for review, with no automatic fixes; each rule can be disabled independently through the usual selectors.

For intentional findings, use targeted name-based exceptions such as # ruff: ignore[custom-query-in-loop] with a rationale. The bundled guide explains handling intentional findings, including framework entrypoints, negative-call tests, and unused-suppression checks.

Project settings and CLI flags override defaults. Use lint.ignore for targeted exceptions; lint.select replaces the selection. --isolated keeps Dogmatic's defaults while ignoring configuration files. --no-preview disables the default preview custom rules. Formatter preview is unchanged.

Dogmatic includes Ruff, originally developed by Astral Software Inc., under the MIT license. The upstream project is available at astral-sh/ruff. Dogmatic is an independent distribution; its application-specific policies are not upstream Ruff rules.

Dogmatic also checks framework leakage, repository transaction ownership, ambient clocks and randomness, queries inside loops, empty operational-error returns, repeated parameter groups, boolean workflow switches, domain input mutation, and broad dependencies with narrow usage. These rules are independently selectable and enabled by default. Architecture checks require explicit module mappings; broad dependencies require type registration. dogmatic guide explains each rule and its limits, and dogmatic guide --starter includes configuration examples.

custom-sequential-await flags potentially independent awaited calls executed in sequence or simple loops. It suggests reviewing asyncio.gather or task groups, while leaving dependent operations and existing task drains alone. The bundled guide explains ordering, bounded concurrency, and suppression of intentional sequential execution.

custom-too-many-data-parameters recommends reviewing functions with six or more data parameters. The dataclass rule also checks fixed tuple return records with three or more fields and nested fixed records. Configure the limits with lint.custom.max-data-parameters and lint.custom.max-tuple-return-fields. The bundled guide explains dependency exclusions, named-record constructors, and return-contract deduplication.

custom-no-unstructured-model-fields rejects JSON catch-all types, Any, object, and bare collections in Pydantic and dataclass fields. Use concrete types or nested models to describe their schema. custom-no-object-annotation also rejects object in parameters, returns, variables, and explicit type aliases. Both rules belong to data-modeling, apply in tests and stubs, and support standard suppressions. The bundled guide explains alias resolution and other static-analysis limits.