Metadata-Version: 2.5
Name: namelint
Version: 0.3.0
Summary: Reports where a Python function's name contradicts its body.
Project-URL: Homepage, https://github.com/abilian/namelint
Project-URL: Repository, https://github.com/abilian/namelint
Project-URL: Issues, https://github.com/abilian/namelint/issues
Project-URL: Changelog, https://github.com/abilian/namelint/blob/main/CHANGES.md
Author: Abilian SAS
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ast,linter,naming,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: cyclopts>=5.4.0
Description-Content-Type: text/markdown

# namelint

Reports where a Python function's **name contradicts its body**.

`ruff` already knows that `getUserName` is not `snake_case`. No linter knows that `get_user` opens a socket, that `collect_entry` is a generator no caller can iterate twice, or that `check_user_is_valid` sits in a test module making claims pytest will never collect. That gap is this tool's subject. Every check needs the AST; none is a grep over identifiers.

It holds no opinion about vocabulary. "Too generic", "too long", "prefer a domain term" belong in a style guide and in code review. namelint reports only that a name and the code under it disagree, naming the fact that made them disagree, so the fact is what you argue with.

## Install

```sh
uv tool install namelint     # on PATH, globally
uvx namelint check src/      # or without installing anything
pip install namelint
```

Its one runtime dependency is [Cyclopts](https://cyclopts.readthedocs.io/), for the command line. The checks themselves import only `ast`. Python 3.12 or newer.

## Use

```sh
namelint check                                # lint the current directory
namelint check src/app/users.py               # or one file
namelint check --select NAM106 src/           # one check only (repeatable)
namelint check --ignore NAM108 src/           # everything but one (repeatable)
namelint check --output-format full src/      # add a hint under each finding
namelint check --output-format concise src/   # one line per finding, for editors and CI
namelint check --output-format json src/      # one JSON object per line
namelint check --output-format github src/    # annotations in a GitHub Actions log
namelint check --stats src/                   # counts per check, with a rate
namelint check --no-allowlist src/            # report everything, allowlist or not
namelint check --exit-zero src/               # report findings, exit 0 anyway
namelint check --show-settings                # the settings in force, and their file
namelint init                                 # add [tool.namelint] to pyproject.toml
namelint init --accept-existing               # ...and accept every current finding
namelint allow --select NAM108 src/           # accept the current findings of one check
namelint allow --prune                        # ...and drop entries that match nothing
namelint explain                              # the naming conventions, explained
namelint explain NAM106 --level junior        # one check: junior, senior or expert
```

By default, findings are grouped under their file:

```
src/app/users.py
  42:5   NAM106  get_user performs I/O (calls httpx.get)
  108:1  NAM104  set_env_vars reads as a command but returns (count, skipped)

2 findings in 1 file
```

`--output-format full` adds a hint below each reported line:

```
src/app/users.py
  42:5   NAM106  get_user performs I/O (calls httpx.get)
                 hint: get_ promises a cheap lookup, use fetch_, load_ or read_
```

`--output-format concise` prints the one-line format that editors and CI annotators already parse, hint included:

```
src/app/users.py:42:5: NAM106 get_user performs I/O (calls httpx.get); get_ promises a cheap lookup, use fetch_, load_ or read_
```

Exit codes: **0** clean, **1** findings, **2** namelint itself failed. A file it cannot parse is reported on stderr and skipped: one Python 2 file in a vendored tree must not end a run over 80,000 functions.

`--stats` serves calibration. It reports per thousand functions, so two codebases of different sizes can be compared. Nested functions are not checked, so they are not counted either:

```
$ namelint check --stats ~/src/cpython/Lib
functions scanned: 51726
  NAM101      17     0.33 per 1000
  NAM102       3     0.06 per 1000
  NAM103      10     0.19 per 1000
  NAM104      35     0.68 per 1000
  NAM105      14     0.27 per 1000
  NAM106      26     0.50 per 1000
  NAM108      18     0.35 per 1000
```

## The checks

All eight specified checks are implemented. Each entry gives what the check reports and what it stays quiet about, since for this kind of rule the exemptions are most of the work. What a check cannot decide on its own goes in the [allowlist](#allowlist).

### `NAM101`: a test that will never run

Reports a function in a test module that contains an assertion, takes no arguments, and is not named `test*`. pytest collects only `test*`, so pytest skips the function. A suite that stays green over it proves nothing about the code it claims to cover.

```python
# tests/test_users.py
def check_user_is_valid():  # NAM101 — pytest will not collect this
    assert build().ok
```

Silent on:

- anything outside a test module. A test module is a `test_*.py`, a `*_test.py`, or any file under a `tests/` directory.
- a decorated function, since that is the shape of a fixture.
- a `_`-prefixed helper. A leading underscore already says "not collected".
- a setup or teardown hook: unittest's `setUp`/`tearDown` family and pytest's `setup_module`/`teardown_method` family.
- a helper that takes the thing it checks; arity is the discriminator, so `assert_ok(response)` stays quiet.

A `with pytest.raises(...)` counts as an assertion.

### `NAM102`: a property named like a command

`obj.get_child` reads as an attribute at the call site and as a bound method to anyone who knows Python. A verb head promises an action the caller cannot see being taken.

```python
class Node:
    @property
    def get_unique_child(self):  # NAM102 — 'get' is predominantly a verb
        ...
```

Whether a word is a verb comes from a table derived from the Universal Dependencies English treebanks (`tools/build_verb_table.py`), never from a hand-written list. Only words used as a bare verb at least 90% of the time count, so `name`, `value`, `drive` and `handle` stay quiet. A word the treebanks do not know (`parse`, `compute`) is silence.

Expect to allowlist noun compounds: `verify_mode` and `include_dir` open with words that are nearly always verbs, yet name a mode and a directory.

### `NAM103`: a predicate that does not return a bool

`if is_ready():` reads the name, never the body. An `is_`/`has_`/`can_`/`should_`/`was_`/`check_` that hands back a string or a count is truthy for every value but one, so the empty string and the zero are the bug. The failure lands in whatever caller tested the result.

```python
def is_capturing(self) -> str | bool:  # NAM103 — annotated -> str | bool
    if self._fixture:
        return f"fixture {self._fixture.name}"
    return False
```

The check reads annotations and return shapes, and does no type inference, so an unknown return is silence:

- a return the AST cannot read, such as `return self._compute()`.
- `-> Any` or `-> object`, which put the uncertainty in the annotation.
- `-> TypeGuard[X]` and `-> TypeIs[X]`, which do return a bool; the subscript says what it proves.
- `return None`, which is how half the predicates ever written take an early exit.
- a name whose last word also names the returned type, which makes it a factory: `is_instance_schema(cls) -> IsInstanceSchema` builds an "is-instance" schema. Whole words only, so `is_valid() -> ValidationResult` is still reported.
- a `check_` annotated `-> None`, which answers by raising.

### `NAM104` and `NAM105`: what the verb promises about the return

A leading verb is a promise. `total = get_total()` expects a value; `reset_cache()` promises to act and answer nothing. So a value verb must return something (`NAM105`). A command verb must not (`NAM104`).

```python
def get_top_level_stats(self):  # NAM105 — no return carries a value
    for func, stats in self.stats.items():
        self.total_calls += stats.calls


def set_shape(lines, width):  # NAM104 — returns [line[:width] for ...]
    return [line[:width] for line in lines]
```

Value verbs: `get`, `find`, `compute`, `calc`, `calculate`, `count`, `lookup`, `as`, `to`, `format`. Command verbs: `set`, `reset`, `clear`, `close`, `print`, `emit`, `insert`, `append`, `show`, `stop`, `warn`, `init`, `update`, `save`. Both lists hold only verbs the corpus shows to be one-sided: `get_` returns a value in 916 of 921 public functions, `reset_` returns none in 56 of 59. Verbs that go both ways (`load_`, `create_`, `make_`, `read_`, `add_`, `run_`, `handle_`) are in neither list.

Silent on:

- private and dunder names.
- a bare one-word name such as `get` or `close`, whose contract lives in its type.
- an explicit `return None` in a query: importlib's `get_source()` returns None to mean "no source".
- a query that is a declaration (`@abstractmethod`, `@overload`, a stub body) or that ends by raising.
- in a command: `return None` as an early exit, `return self` for chaining, a bool literal reporting success, and `return super().set_cookie(...)` passing on the same command.

Expect to allowlist the copy-and-update idiom, where `options.update_width(80)` returns a changed copy on purpose, and words that are not verbs here: `close_to_zero` is an adjective, and `set_validator` validates sets.

### `NAM106`: a `get_` that performs I/O

`get` is a contract in Python: `dict.get`, `getattr`, `os.environ.get` are all cheap and total. A `get_` that opens a socket breaks the promise its caller read.

```python
def get_user(uid):  # NAM106 — calls httpx.get
    return httpx.get(f"/u/{uid}").json()
```

It fires on `open`, `Path.read_*`/`write_*`, `urlopen`, DBAPI `execute`/`fetchone`/`fetchall`, socket `recv`/`send`, and anything rooted at `requests`, `httpx`, `urllib`, `socket`, `subprocess` or `aiohttp`. The message suggests `fetch_`, `load_` or `read_`. `dict.get` and `getattr` don't count as evidence.

### `NAM107`: a generator under a non-lazy name

**Opt-in:** this check runs only with `--select NAM107`, because it fires too often to be a default (see below).

A caller who believes they hold a list and actually hold a one-shot iterator writes a bug that surfaces two loops later, far from this function.

```python
def collect_stale_entry(root):  # NAM107 — contains yield
    for path in root.iterdir():
        if stale(path):
            yield path
```

Silent on:

- a plural final word: `items`, `values`, `user_records`.
- a lazy prefix (`iter_`, `walk_`, `gen_`, `generate_`, `stream_`, `scan_`, `traverse_`, `produce_`, `yield_`, `enumerate_`, `chunk_`), checked after any leading underscores.
- dunders.
- a `yield` that belongs to a protocol: a pytest fixture, a `@contextmanager`, an `@asynccontextmanager`, a pluggy `@hookimpl` wrapper. In all four the noun name is correct on purpose (`db_session`, `temp_config`, `client`).

**This check is the one currently in question.** It fires at 17.1 per thousand functions in `httpx` and 14.8 in `rich`, far outside what a well-named codebase should produce. The known false-positive class is the undecorated protocol generator: an ABC method where `yield request` *is* the interface. It stays opt-in until a narrower detector brings that rate down.

### `NAM108`: a method that repeats its class name

`config.read_config()` says "config" twice; the call site already holds the class.

```python
class Config:
    def read_config(self):  # NAM108 — method of Config
        ...
```

The whole class name must appear as a run of words, so `CodeContext.update_code_context` matches and `ConfigLoader.config_path` does not.

Silent on:

- test modules and `Test*` classes.
- private methods.
- a method named exactly like its class (`Filter.filter`).
- a class where three or more methods repeat the name. That is a namespace on purpose (tkinter's `Wm.wm_title`, `Wm.wm_frame`).

This is the check that most needs the allowlist. A user name is not the same thing as a user's name, and `Style.background_style` returns a different style. Only the author knows which repeat is a slip.

## In CI and pre-commit

In a GitHub Actions workflow, `--output-format github` prints annotations that GitHub shows on the pull request's diff:

```yaml
- run: uvx namelint check --output-format github
```

For [pre-commit](https://pre-commit.com/), add the hook to `.pre-commit-config.yaml`:

```yaml
- repo: https://github.com/abilian/namelinter
  rev: v0.3.0
  hooks:
    - id: namelint
```

The hook runs `namelint check --force-exclude`. pre-commit names each file it passes, and `--force-exclude` keeps the `exclude` patterns in force for named files.

## Configuration

namelint takes `[tool.namelint]` from the `pyproject.toml` in the current directory or the nearest parent. `namelint init` writes the table with the default settings:

```toml
[tool.namelint]
# select = ["NAM101", "NAM102", "NAM103", "NAM104", "NAM105", "NAM106", "NAM108"]
ignore = []
exclude = []
per-file-ignores = {}
respect-gitignore = true
output-format = "grouped"
```

- `select` lists the checks to run. Without it, every check runs except the opt-in `NAM107`.
- `ignore` lists checks to skip.
- `exclude` lists shell patterns for paths to skip. They add to the directories always skipped (`.git`, `.venv`, `venv`, `__pycache__`, `node_modules`, `.tox`, `.nox`, `build`, `dist`). A file named on the command line is linted even when a pattern matches it, unless `--force-exclude` is given.
- `per-file-ignores` maps a path pattern to the checks to skip in matching files: `{ "migrations/*" = ["NAM108"] }`.
- `respect-gitignore` skips what git ignores, using `git ls-files`. Outside a git repository, or without git, namelint walks all directories.
- `output-format` is `grouped`, `full`, `concise`, `json` or `github`.

A path pattern is matched against each part of a path. It is also matched against the whole path, taken relative to the directory holding `pyproject.toml`. So `migrations/*` means the same from any working directory.

On the command line, `--select` replaces the configured list, `--ignore` adds to it, and `--output-format` replaces the configured format. An unknown key, an unknown code or a value of the wrong type is an error, with exit code 2, so a typo can't pass for a setting that was applied.

## Allowlist

When namelint reports a name that is ambiguous but legitimate, list it under the code that reported it, in `pyproject.toml`:

```toml
[tool.namelint.allow]
NAM104 = ["update_width", "close_to_*"]
NAM108 = ["User.user_name", "Style.*_style"]
```

An entry matches a function name or `Class.method`, with shell wildcards. It covers only the code it sits under. namelint reads the `pyproject.toml` in the current directory or the nearest parent. An unknown code or a malformed entry is an error, with exit code 2. `--output-format json` includes a `qualname` field, ready to paste.

Two commands write the allowlist for you:

- `namelint init` adds a `[tool.namelint]` table with the default settings, and an empty `[tool.namelint.allow]`. It refuses to run if namelint is already configured. With `--accept-existing` it fills the allowlist with what namelint reports today, which is how to adopt namelint on an existing codebase: the next run is clean, and only new code gets reported.
- `namelint allow` adds the current findings to the allowlist, keeping what is there. Narrow it with `--select`/`--ignore` and paths, and review the diff before committing. With `--prune` it also removes the entries that no longer match anything reported, so the allowlist shrinks as names get fixed. Run `--prune` over the whole project, since an entry for code outside the given paths looks unused. Entries for checks that did not run are kept.

Both lint the given paths (the current directory by default) and record each reported function as `Class.method` or a bare function name.

Both rewrite only the `[tool.namelint.allow]` table, sorted, so regenerating it gives a stable diff. Every other line of `pyproject.toml` is left as it was, but comments inside that table are lost. With no `pyproject.toml` anywhere up the tree, one is created in the current directory.

There are no inline suppression comments. An allowlist keeps the project's exceptions in one reviewable place.

## Calibration

A rule that fires often on a codebase no reviewer would call badly named is a **wrong rule**. It is also no evidence about that codebase. So every check is measured against a fixed corpus of nine projects before it ships. Any check running above roughly two false positives in thirty gets a narrower detector, drops to advisory, or is cut.

```sh
uv run tools/calibrate.py                 # fetch what is missing, then measure
uv run tools/calibrate.py --only click    # one project
uv run tools/calibrate.py --no-fetch      # re-measure after changing a detector
```

It shallow-clones CPython's `Lib/`, attrs, pydantic, requests, httpx, rich, click, pytest and flask into `corpus/`, then writes `calibration/summary.md` (the table), `findings.jsonl` (the full output, so two runs can be diffed) and `sample.md` (a seeded random sample per check, with source lines, as checkboxes to adjudicate by hand). The sample is seeded on purpose: measuring a changed detector against a fresh sample measures the sample. Every row records the commit it came from, because a number with no commit behind it is a rumour.

The current run covers 71,274 functions and reports 437 findings, `NAM107` included:

| Project | NAM101 | NAM102 | NAM103 | NAM104 | NAM105 | NAM106 | NAM107 | NAM108 |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| cpython | 0.33 | 0.06 | 0.19 | 0.68 | 0.27 | 0.50 | 2.22 | 0.35 |
| attrs | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 1.09 | 0.00 |
| pydantic | 0.98 | 0.14 | 0.00 | 1.40 | 0.56 | 0.70 | 0.84 | 0.14 |
| requests | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 |
| httpx | 0.00 | 0.00 | 0.00 | 0.95 | 0.00 | 0.95 | **17.08** | 2.85 |
| rich | 0.59 | 0.59 | 0.00 | **6.49** | 0.00 | 0.00 | **14.75** | 2.36 |
| click | 0.00 | 0.00 | 0.00 | 0.00 | **6.18** | 0.00 | **10.82** | 4.64 |
| pytest | 0.17 | 0.84 | 0.17 | 0.17 | 0.00 | 0.50 | **8.72** | 0.34 |
| flask | 0.00 | 0.00 | 0.00 | 0.00 | 1.17 | 2.33 | 1.17 | 2.33 |

The table counts findings per thousand functions, with no allowlist. rich's `NAM104` rate comes from the copy-and-update `ConsoleOptions` API; click's `NAM105` from the `format_help(ctx, formatter)` family, which writes into the formatter it is given. CPython is pinned to `v3.13.0`, since `main` uses syntax a 3.14 interpreter cannot parse; a run on `main` would measure the interpreter.

## As a library

`lint_module(tree, path) -> list[Finding]` is also flake8's plugin contract, so a flake8 adapter needs an entry point and a wrapper, with no second copy of the checks. `checks.py` imports only `ast` and the `Finding` and `Context` records; the verb table reaches it through `Context`. It is a pure function of a node and a `Context`: it touches no filesystem and reads no configuration.

```python
import ast
from pathlib import Path
from namelint.visitor import lint_module, lint_source

for finding in lint_source("def get_user(u):\n    return httpx.get(u)\n", Path("x.py")):
    print(finding.code, finding.name, finding.evidence)
```

A `Finding` has `code`, `line`, `col`, `name`, `message`, `evidence`, and `owner` (the enclosing class, if any). The `evidence` field names the fact behind the report: "calls `httpx.get`" is a fact you can dispute, "performs I/O" is not.

There is no ruff plugin, because ruff has no plugin API.

## Status

**0.2.0, pre-release.** All eight checks are implemented; `NAM107` is on probation and off by default, and `NAM102`, `NAM104` and `NAM108` lean on the allowlist for names only their author can read. The output format and the `NAM1xx` codes are not frozen yet.

## Development

```sh
uv sync
make test          # pytest
make lint          # ruff check, ruff format --check, ty, pyrefly, mypy
nox -s tests       # against 3.12, 3.13 and 3.14
```

The design lives in the notes:

- `notes/02-specs.md`: the reasoning behind each rule, the corpus design, the open questions.
- `notes/01-background.md`: where the rules came from, and which candidates were dropped.

A check is finished when it has been run over the corpus and adjudicated, with the sample committed beside it. Green unit tests are the step before that.

## Licence

namelint is distributed under the Apache License 2.0, copyright 2026 Abilian SAS.
