oaklint

CI codecov PyPI Python License

oak is an opinionated, agent-first Python linter - a cross between Black and Ruff that enforces a curated set of rules targeting common sources of technical debt. These are the patterns that accumulate quietly, from minor style drift up to real structural problems, and they show up most in agent-written code and junior-developer code. oak is built to be both a linter and a learning tool: every rule explains why it exists, so the code gets fixed and the author learns the reasoning behind the fix. Built in Rust on the rustpython-ruff_python_parser crate, so it parses exactly what a modern Python toolchain does while staying a small standalone binary.

oak runs alongside ruff, black, and whatever else is already in your toolchain rather than replacing any of them. It stays fully compatible and layers its curated rules on top, so you keep your existing formatter and linter and add oak for the checks they do not cover.

Some of these rules are hot takes - deliberately more opinionated than a general-purpose linter would risk. In practice I have found they are what keeps medium-to-large teams and their codebases maintainable as they grow.

The set grows by one rule: if a standard can be systematically deduced from the code - checked mechanically rather than by judgment - it gets added here. Anything that needs human taste to adjudicate stays out.

Installation

oak ships as a prebuilt wheel on PyPI, so it installs with no Rust toolchain:

uv tool install oaklint       # install the oak command globally
uvx oaklint path/to/file.py   # or run it without installing
pip install oaklint           # or with pip

The distribution is named oaklint; the installed command is oak.

Usage

oak path/to/file.py src/            # report violations, exit 1 if any
oak --fix src/                      # rewrite files to resolve fixable violations
oak docs OAK005,OAK012              # print the full reasoning for one or more rules

Every rule ships with a full documentation page that an agent or a human can read on demand. Running oak docs <codes> prints the complete rationale, Good/Bad examples, and the recommended fix for exactly those rules - so the reader learns why the rule exists and how to apply the change, without leaving the terminal or hunting through the repo.

Output

A run is structured to be read by an agent under a token budget, not to repeat itself once per line:

Run `oak docs OAK007,OAK014,OAK015` for full rule reasoning, or fetch each individually.

  Code    Count  Rule
  OAK007     10  A public function or class is defined below a private function in the same scope.
  OAK014      3  A function returns a fixed-shape dict literal instead of a named type.
  OAK015      5  A function or method name does not lead with an action verb.
  Total      18

OAK007 - Public function or class must be placed above private functions
  tests/conftest.py:106:5: `build_client`
  tests/conftest.py:126:5: `Ledger`

OAK014 - Function returning a record must use a class, not a dict
  tests/conftest.py:69:9

OAK015 - Function or method name must lead with an action verb
  tests/conftest.py:85:5: `gateway`
  tests/conftest.py:89:5: `ledger`

Found 18 violations

The shape is deliberately agent-friendly and context-length-aware:

  • The docs command leads. One line points at the full reasoning for every rule the run hit, and says each can be fetched on its own - the agent pulls the deep explanation only for the rules it decides to act on, instead of paying for it up front.
  • The summary table amortizes the explanation. Each rule's definition and its violation count appear exactly once, so an agent can triage which rules matter before reading a single location.
  • Locations are grouped, not annotated. The per-rule message is stated once as a section header, then followed by bare path:line:column lines - each suffixed with the specific identifier at fault (a function name, import alias, or offending token) when the rule has one. A file that trips one rule a hundred times costs a hundred short lines, not a hundred repetitions of the same sentence and the same oak docs pointer.

This keeps a large run's output roughly proportional to the number of distinct rules plus the number of locations, rather than to the product of the two - so a sweep over a whole codebase stays inside an agent's context window.

Rules

Code Rule
OAK001 Missing blank line after an indented block (if/for/while/with/try/match) or before a continuation (elif/else/except/finally).
OAK002 Missing blank line before a return.
OAK003 Comment must be a sentence-case NOTE/TODO/XXX ending with a period.
OAK004 Continuation line must align under the comment's first word.
OAK005 Import must not use an alias.
OAK006 Only functions may be private; classes and module- or class-level names must be public.
OAK007 Private functions must be placed below all public functions and classes in a scope.
OAK008 Name must not be a single character.
OAK009 Test must assert observable behavior, not mock calls.
OAK010 Mock library must not be used, prefer an in-process fake.
OAK011 pytest.raises must not use match=; assert the full error message.
OAK012 Function returning multiple values must use a class, not a tuple.
OAK013 Empty string must not stand for an absent value; use None.
OAK014 Function returning a record must use a class, not a dict.
OAK015 Function or method name must lead with an action verb.
OAK016 Test must not contain conditional logic (if/elif/else).

OAK001 and OAK002 are fixable with --fix, which inserts the missing blank line. OAK003 through OAK016 are report-only. Each rule has a page in docs/rules/ with its rationale and a good/bad example.

A blank line is required before a continuation (elif, else, except, finally); only case is left tight and never flagged. A guard clause whose block is a single return needs no blank line after it. A comment written directly above a statement belongs to it, so the separating blank line is expected above the whole comment run, not between the comment and its statement.

Configuration

oak reads settings from the first of .oak.toml, oak.toml, or [tool.oak] in pyproject.toml found by walking up from the current directory. A pyproject.toml without a [tool.oak] table is skipped and the search continues upward.

[tool.oak]
select = ["OAK001"]              # when set, only these codes lint (prefixes like "OAK" and "ALL" work)
ignore = ["OAK002"]              # removed from the active set after select
exclude = ["tests/**", "vendor"] # globs skipped entirely
action-verbs = ["yeet", "reconcile"] # extra leading verbs OAK015 accepts

[tool.oak.per-file-ignores]
"tests/**" = ["OAK002"]          # codes silenced only for matching files

In a standalone oak.toml the same keys are written at the top level (no [tool.oak] header). Unknown keys are a hard error and keys are kebab-case.

Inline suppression

A comment can silence a violation in place, following ruff's # noqa model:

import numpy as np  # noak                 # silences every oak rule on this line
import numpy as np  # noak: OAK005         # silences only OAK005 on this line
import numpy as np  # noak: OAK005,OAK008  # silences a comma-separated list

A # oak: noqa comment silences a whole file, with the same optional code list:

# oak: noqa               # silences every oak rule in this file
# oak: noqa: OAK005,OAK008  # silences only these codes in this file

A line directive is anchored to the line the violation is reported on, and the keyword reads case-insensitively (# NOAK). A bare directive with no codes blankets its scope; naming codes narrows it to exactly those.

Default rule set

With no select key, oak runs only the default-on set - the low-friction hygiene, formatting, and structural rules OAK001 through OAK008 plus OAK012 (no tuple returns), which almost any team accepts. The opinionated house-style rules stay off until you opt into them.

Enable the opinionated rules by naming them in select - the testing rules (OAK009, OAK010, OAK011), the record-dict rule (OAK014), the empty-string rule (OAK013), and the action-verb rule (OAK015). Setting select replaces the default set, so list every code you want to run, including the default-on ones you want to keep:

[tool.oak]
# NOTE: The default rules plus the action-verb rule.
select = [
    "OAK001", "OAK002", "OAK003", "OAK004", "OAK005",
    "OAK006", "OAK007", "OAK008", "OAK012", "OAK015",
]

select = ["ALL"] runs every rule, including the opinionated and heuristic ones. OAK015 is heuristic and fires against a maintained verb allowlist, so expect to tune it before turning it on broadly.

Development

make check     # fmt --check + clippy -D warnings + tests (the CI gate)
make format    # cargo fmt
make coverage  # per-file source coverage report

make coverage uses Rust's built-in -C instrument-coverage and the system llvm-cov/llvm-profdata, so it needs neither cargo-llvm-cov nor a rustup component. Point it at other target directories or llvm binaries with CARGO_TARGET_DIR, LLVM_COV, and LLVM_PROFDATA, and pass extra flags straight through (make coverage -- --show-missing-lines).

Rules live in src/rules/, one module per rule code (named oak0NN_<domain>_<thing>.rs), with helpers shared between two codes of a family in src/rules/util/. The pipeline is: config::Config::discover (resolve settings) → discovery (find .py files, drop excluded) → linter::check_source (parse + run rules) → filter by select/ignore/per-file-ignores → diagnostics::Violation (report) → linter::apply_fixes (--fix).

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.6)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for oakhan3 from gravatar.com oakhan3

Credits

Author: Omar Ali Khan

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.8

Tags

linter python static-analysis code-quality

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

oaklint-0.1.3.tar.gz (86.6 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

oaklint-0.1.3-py3-none-win_amd64.whl (1.8 MB view details)

Uploaded Python 3Windows x86-64

oaklint-0.1.3-py3-none-musllinux_1_2_x86_64.whl (1.9 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

oaklint-0.1.3-py3-none-musllinux_1_2_aarch64.whl (1.8 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

oaklint-0.1.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.8 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

oaklint-0.1.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.7 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

oaklint-0.1.3-py3-none-macosx_11_0_arm64.whl (1.7 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

oaklint-0.1.3-py3-none-macosx_10_12_x86_64.whl (1.8 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file oaklint-0.1.3.tar.gz.

File metadata

  • Download URL: oaklint-0.1.3.tar.gz
  • Upload date:
  • Size: 86.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for oaklint-0.1.3.tar.gz
Algorithm Hash digest
SHA256 354afe1d173c3e40206282b1f501e3c7154f3165fbad59bdfc32cfc22016c3ef
MD5 e3d6e660821c9c746242d6ae05910841
BLAKE2b-256 33dea2c729ee31a0651d74c8f4417b71c4bfbdf14a55fe9472b0e2ed877190e9

See more details on using hashes here.

Provenance

The following attestation bundles were made for oaklint-0.1.3.tar.gz:

Publisher: release.yml on omaralikhn/oaklint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oaklint-0.1.3-py3-none-win_amd64.whl.

File metadata

  • Download URL: oaklint-0.1.3-py3-none-win_amd64.whl
  • Upload date:
  • Size: 1.8 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for oaklint-0.1.3-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 835591346c851a662de56f295755a4d84cd2b66b36dac04114138b51166edeb2
MD5 884d3c15910c9f638ee0c25fa2fbf395
BLAKE2b-256 e565dc84e11d2b50abd5d23844033cc8535ad3ca96345c85bf99fa93415cc26a

See more details on using hashes here.

Provenance

The following attestation bundles were made for oaklint-0.1.3-py3-none-win_amd64.whl:

Publisher: release.yml on omaralikhn/oaklint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oaklint-0.1.3-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for oaklint-0.1.3-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 b772b9486061bd75441d4cab75893bf1fe33c7a318b5fb9dd8317651dc80dab5
MD5 3ac355767cfee745635840205c1b9f50
BLAKE2b-256 15fb12ea305172b681732a30861b6d9055ed9cf7457c70ffd15deb1fc63da471

See more details on using hashes here.

Provenance

The following attestation bundles were made for oaklint-0.1.3-py3-none-musllinux_1_2_x86_64.whl:

Publisher: release.yml on omaralikhn/oaklint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oaklint-0.1.3-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for oaklint-0.1.3-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 d2bbf2b36bd3a29285a700f0d41dce7b385326c5b46afb76ea7fe6698b202f4f
MD5 20b6abdc9aed22d070cb08f837384914
BLAKE2b-256 608d4beedf7e6ba45912d164598b8d4373e62e4f2f33394ddbad1523855dbf1d

See more details on using hashes here.

Provenance

The following attestation bundles were made for oaklint-0.1.3-py3-none-musllinux_1_2_aarch64.whl:

Publisher: release.yml on omaralikhn/oaklint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oaklint-0.1.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for oaklint-0.1.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e9b9b19c89cb02a6b349d9e224edd5086191611cd7ea6cce2f4e4618cfdd940b
MD5 eeb729d6ca453fd66c556015bb8ab6f2
BLAKE2b-256 019e9ff1eb1d02d2c3fecf5b1df4046f4306ee0e159c62c8b7ce7e9c917849f6

See more details on using hashes here.

Provenance

The following attestation bundles were made for oaklint-0.1.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on omaralikhn/oaklint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oaklint-0.1.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for oaklint-0.1.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 a2a913fc926d2a4d3af8e044aaf4f16231fc27b9d98b9b7a01cf4e670fe65afe
MD5 029cdf1913cefdcb9ccccaa38ea7d59d
BLAKE2b-256 be4d2e0e321ff3e6cb48aa1b7a861802d4424d9ba7a232cb5179e692e306aa1f

See more details on using hashes here.

Provenance

The following attestation bundles were made for oaklint-0.1.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on omaralikhn/oaklint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oaklint-0.1.3-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for oaklint-0.1.3-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d8de5631c939b311da2c7510294835c79e148f46d68171a893f8662f1950e81e
MD5 33dc327fbe1935be7d9835ce1e49efbd
BLAKE2b-256 5cb25b6f60733d97bbfd3f83d0deb8cf67f7cd1797107993989d5e1f6bdcdfd8

See more details on using hashes here.

Provenance

The following attestation bundles were made for oaklint-0.1.3-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on omaralikhn/oaklint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oaklint-0.1.3-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for oaklint-0.1.3-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 02b50525dca2aa65361752890fa9d2748d1573c3c91a06b907dab5cdd7078195
MD5 803313363f8d8f65b38bf017759e85a2
BLAKE2b-256 c6aa1907925cf2354a273c6a3c9e796a80b8c3ded9650ce26d993570409f4080

See more details on using hashes here.

Provenance

The following attestation bundles were made for oaklint-0.1.3-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on omaralikhn/oaklint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page