assert-every-dataclass-field-is-read

Assert that every field a dataclass declares is read somewhere.

Why

A dataclass field is written on every instance whether or not anything wants it. The generated __init__ stores what it is handed, so the write is automatic and guaranteed. Only a read is evidence that the field is still wanted, and a read is what disappears quietly.

Delete the last line that reads a field and nothing reports it. The program still runs, the field is still declared, every caller still has to supply a value, and the tests covering the field still pass, because they construct their own instance and assert on a value they passed in themselves. The declaration has become a claim about the program that is no longer true, and the test suite is the thing that hides it.

This tool asks the other question. For every field declared by a @dataclass in the trees you point it at, it asks whether anything reads the value back, and reports the ones nothing does.

Installation

pip install assert-every-dataclass-field-is-read

Usage

# Every dataclass field in the program must be read by the program
assert-every-dataclass-field-is-read src lib/python scripts

# Search the tests too, but not the tests belonging to the package
# whose field is being checked
assert-every-dataclass-field-is-read lib/python \
  --search-in lib/python --search-in test \
  --dont-search-in 'test/lib/python/{package}'

The first form is the one to reach for. Leaving the test tree out of the search entirely is both simpler and stricter than excusing a package's own tests, and it is the right default whenever the trees you check are the deployed program rather than test support code.

Reach for --dont-search-in when a tree holds dataclasses that tests are entitled to read — fixtures, doubles, helpers — and you still want a field kept alive only by its own tests to be reported.

Options

Exit codes

What counts as a read

A field Widget.color is read when the tool can see an expression that fetches it. It pairs an attribute with the class that owns it, rather than matching the bare name, so a local variable called color is not mistaken for a read of the field.

Annotations are resolved through X | None, quoted forms, and the element of a container (list[X], tuple[X, ...], dict[K, X] and their typing equivalents). Variables are scoped per function, so a name bound in one function says nothing about the same name in another.

Writes do not count. widget.color = "red" is how the field is filled in, not evidence that anything wants it, and dataclasses.replace is treated as a read only when the instance it is handed resolves to a class.

What it does not see

An attribute read whose base cannot be resolved to a class — a bare parameter, a subscript, a chained attribute — is counted as a read of every field of that name, because reporting it would be a guess. So a field whose name is shared with an attribute read loosely somewhere else is not reported.

A field a runtime reads for you, through a serializer or a template, has no read to find. Name it with --assume-read-matching rather than leaving it to be reported.

ClassVar annotations and unannotated class attributes are not dataclass fields, and are not checked.

GitHub Action

- uses: 10U-Labs/assert-every-dataclass-field-is-read@latest
  with:
    trees: src lib/python scripts
    verbose: "true"

License

Apache-2.0.