Skip to main content

docattest for Python

docattest for Python projects: documentation that CI can fail. Your Markdown pages carry examples that run, facts that are compared with values in your code, tables whose rows are tests, and citations of tests you already have.

Try it in your browser first: the playground lets you break a small project's code and watch docattest catch its docs.

This package is what a Python user installs. It provides two commands:

  • docattest, the command you run. It is a launcher: it finds the docattest core (one binary for every language, which reads the pages and writes the report), tells it how to start the Python adapter and what command runs docattest in your project, and becomes it.
  • docattest-adapter-python, the adapter: the program that answers everything that needs Python. It speaks version 1 of the adapter protocol. You do not run it yourself.

The distribution is called docattest . Its import packages are docattest (the launcher) and docattest_python (the adapter).

Python 3.10 or newer. Standard library only: no dependencies.

Install

pip install docattest                 # the commands docattest and docattest-adapter-python

The core comes inside the wheel: there is one wheel for each of 5 platforms, py3-none-<platform> (the Python code is pure; only the core is native), and pip picks the one built for your machine. Nothing is downloaded when docattest runs, and Node is never needed.

platform name wheel tags
macOS 11+ on Apple silicon darwin-arm64 macosx_11_0_arm64
macOS 10.12+ on Intel darwin-x64 macosx_10_12_x86_64
Linux x86-64, glibc or musl linux-x64 manylinux_2_17_x86_64, manylinux2014_x86_64, musllinux_1_1_x86_64
Linux arm64, glibc or musl linux-arm64 manylinux_2_17_aarch64, manylinux2014_aarch64, musllinux_1_1_aarch64
Windows x64 windows-x64 win_amd64

The name is the platform's in every docattest package: the npm package and the Go archive that carry its core are called by it too.

The Linux core is a static binary, so one wheel serves glibc and musl (Alpine) alike. There is no source distribution, because it could not build the core: on any other platform pip install docattest finds nothing to install, rather than installing a docattest that cannot run. An install from a checkout (pip install -e adapters/python, for development) has no core either; its first run says so, names your platform, and says to install the wheel or set DOCATTEST_CORE.

python3 adapters/python/build_wheel.py --out <dir> --core <platform>=<binary> builds the wheels from cores built for each platform (the release workflow runs it; see CONTRIBUTING.md, "Releasing"). It needs nothing but the standard library and pip, which fetches setuptools for the build.

The launcher looks for the core in three places, in this order, the same as the npm package does:

  1. DOCATTEST_CORE , the path of a core binary. It is asked for its version (--version --json) and refused when it speaks another protocol than this package, or does not answer.

    $ DOCATTEST_CORE=/bin/echo python3 -m docattest check
    docattest: DOCATTEST_CORE (/bin/echo) is not a docattest core: it does not answer --version --json
    [exit 1]
    
  2. docattest/bin/docattest inside this package (docattest.exe on Windows): where the wheel for your platform carries it.

  3. <cache>/core/<version>/<name>/docattest, a cache shared with the npm package, where <name> is the platform's name from the table above. The version is the one in docattest_python/protocol/core.json, which this package pins. <cache> is:

on set cache
any system DOCATTEST_CACHE=/mine /mine
macOS ~/Library/Caches/docattest
Linux XDG_CACHE_HOME=/x /x/docattest
Linux XDG_CACHE_HOME=relative ~/.cache/docattest
Linux ~/.cache/docattest
Windows LOCALAPPDATA=C:\Local C:\Local\docattest
Windows ~\AppData\Local\docattest

XDG_CACHE_HOME counts only when it is an absolute path, as the XDG specification says.

DOCATTEST_TRACE=1 makes the launcher say which core it runs.

From a checkout of the repository, without installing anything:

cargo build --release --manifest-path core/Cargo.toml
export DOCATTEST_CORE="$PWD/core/target/release/docattest"
export PYTHONPATH="$PWD/adapters/python"
python3 -m docattest check --root adapters/python/tests/fixture

docattest hooks install, hooks install --git and agents install write down a command that runs docattest without Node: the virtualenv's own script when the virtualenv is inside the project, else docattest when that is the script the PATH finds, else the script by its full path, else this interpreter by its full path (python -m docattest). The launcher knows no coding agent. For a virtualenv inside the project it says {root}/.venv/bin/docattest, and the core writes the root as the reader of the command names it: "$CLAUDE_PROJECT_DIR"/.venv/bin/docattest impact --hook in a hook of Claude Code (its descriptor's projectRoot), ./.venv/bin/docattest in AGENTS.md and in a git hook. Set DOCATTEST_COMMAND to have it write something else (uv run docattest).

Any agent, or none, can use the two plain commands, from anywhere inside the project: docattest impact --file <path> after an edit and docattest check before finishing. docattest hooks install --agent gemini (or cursor, or a descriptor file of your own) installs hooks for another agent; docs/agents.md has the details.

A bare core, run without the launcher, finds the adapter as docattest-adapter-python on the PATH, or through DOCATTEST_ADAPTER_PYTHON : a JSON array (["python3", "/path/to/adapters/python/bin/docattest-adapter-python"]) or a command line split on spaces.

Configure

docattest.config.json at the project root:

{
  "pages": ["README.md", "docs/**/*.md"],
  "sources": ["src/**/*.py"],
  "surfaces": { "default": "shoplib" },
  "setup": "docs/docattest_setup.py",
  "adapter": "python"
}
  • surfaces name what pages are allowed to observe. An entry is

    • a module name, "shoplib" or "shoplib.shipping": imported as written. It is looked for in the project root, then in src/, then wherever import finds it;
    • a path, "./src/shoplib" or "./shoplib/shipping.py": that file of the project, imported under the name Python gives it (src/shoplib/shipping.py is shoplib.shipping: the path from the first directory without an __init__.py);
    • both, { "import": "shoplib", "path": "build/lib/shoplib/__init__.py" }: examples import import, and it is read from path.

    A surface may be a program, a __main__.py ("shopd": "./src/shopd/__main__.py"): importing it would run it, so its constants are all that facts read of it (see Facts, below).

  • What a surface exports is its __all__ when that is written out as a list. Otherwise it is the module's public names: every function, class and assigned name that does not start with _, and, in a package's __init__.py, what it imports from its own package (from .pricing import total is a re-export; import os is not). uncovered lists the exports no page attests.

  • sources are the Python files whose docstrings hold examples (see below).

  • setup is a Python module with the runners of cases tables and named facts.

A page

This page documents the small shop library that this package's tests use (tests/fixture/), and this guide checks it inside a copy of that project:

# Pricing

A discount is a whole percentage taken off a price.

```python check
from shoplib import Money, apply_discount

assert apply_discount(Money(1000), 25) == Money(750)
```

The same as an interpreter session:

```pycon check
>>> from shoplib import Money, total
>>> total([Money(1000)], "NL")
Money(cents=1210, currency='EUR')
```

Prices are in `EUR` unless told otherwise. <!-- fact: DEFAULT_CURRENCY -->

Tax is known for these regions: <!-- fact: TAX_RATES -->
- `NL`
- `DE`
- `FR`

<!-- cases: discount -->
| case           | price | percent | result |
|----------------|-------|---------|--------|
| a quarter off  | 1000  | 25      | 750    |
| rounds half up | 999   | 50      | 500    |

Discounts above the maximum are refused. <!-- test: tests/test_pricing.py > "TestTotals" > "test_rejects_big_discounts" -->
docattest check          # exit 1 when a page and the code disagree
docattest uncovered      # exports no page attests
docattest where total    # the pages, lines and sentences that attest a symbol
docattest audit          # lists, tables and values that look copied from the code, with no directive
docattest impact         # after an edit: the exports it affects and the prose that names them

A failing proof is reported with its line, what the page expected and what the code gave. The same project has a page that is wrong on purpose, once for each way a proof can fail:

$ docattest check --quiet docs/broken.md
docs/broken.md
  ✗ L5 example: AssertionError: expected Money(cents=700, currency='EUR'), got Money(cents=750, currency='EUR') (block line 3)
  ✗ L11 example: `quote("NL")`: expected 2, got 1 (block line 2)
  ✗ L17 example: cannot import name 'aply_discount' from 'shoplib' (src/shoplib/__init__.py) (block line 1)
  ✗ L21 example: ShopError: No carrier serves the region (block line 2)
  ✗ L26 example: timed out after 3000 ms
  ✗ L31 example: URLError: <urlopen error network access is disabled for attestations; tag the block `check network` to allow it> (block line 2)
  ! L36 example: example at L36: unknown tag "chekc"; did you mean "check"?
  ✗ L40 fact: expected 60, got 50 from MAX_DISCOUNT
  ✗ L42 fact: missing: DE, FR; unexpected: BE (2 items on the page, 3 in TAX_RATES)
  ! L46 fact: fact `_round(0.5)`: _round is not exported by surface "default" (NameError: name '_round' is not defined)
  ✗ L51 cases: docs/broken.md:51 wrong on purpose: AssertionError: expected '800', got '750'
  ✗ L52 cases: docs/broken.md:52 too much: ShopError: The discount is outside the allowed range
  ! L54 cases: cases runner "nope" at L54 is not in `cases` of docs/docattest_setup.py (known: discount, delivery)
  ! L59 test: tests/test_pricing.py declares no test "test_that_was_renamed"; tests there: "test_discount_rounds_half_up", "TestTotals" > "test_adds_tax", "TestTotals" > "test_rejects_big_discounts"
FAILED
[exit 1]

What each attestation means in Python

Examples: python check, python compile

Blocks tagged python, py, python3, py3 or pycon are the adapter's.

  • check runs the block as a script. The proof is the plain assert statement. A failing assert a == b reports both sides and the line within the block (L5 in the report above); the adapter rewrites comparisons in assert to keep the two values, as pytest does. await may be used at the top level; the block then runs in a new event loop. __name__ is "__main__".

    import asyncio
    
    await asyncio.sleep(0)
    assert __name__ == "__main__"
    

    A block with no assert (and no pytest.raises, self.assert…) runs but is counted as weak.

  • A session is a block tagged pycon , or any block whose first statement is a >>> prompt. It runs the way doctest runs it. Each output must match what the page shows, an expected Traceback must be raised, # doctest: +SKIP and the other doctest directives work, and ... in an expected output matches anything (ELLIPSIS is on; nothing else is). A statement with an output is the session's assertion.

  • compile never runs the block. Python has no compiler to ask, so compile means what can be said honestly from syntax: the block parses and compiles; every import finds its module; a name imported from one of your own modules is bound there (cannot import name 'aply_discount' from 'shoplib'); an attribute read straight off an imported project module exists; and a name the block reads is bound somewhere in it or is a builtin. It is not a type check: a wrong argument or a missing method is not found. check blocks pass through the same test before they run.

  • Isolation. Every block runs in its own process: a fresh __main__, fresh imports of your package, nothing left over from the block before. Blocks of one page share nothing, so each must import what it uses, unless it says continue.

  • continue. Python documentation is often one interpreter session from the top of the page to the bottom: the first block imports, the fifth still uses the import. A block tagged python check continue (or pycon check continue) goes on from the examples before it on its page, back to the nearest one without the word: their statements run first, in the same namespace, and then the block. Of these three blocks, the second goes on from the first and the third starts afresh:

    from shoplib import Money
    
    price = Money(1000)
    assert str(price) == "10.00 EUR"
    
    assert price == Money(1000)
    
    assert "price" not in globals() and "Money" not in globals()
    

    It is still judged alone and still runs in its own process; the earlier blocks are run again for it, and what they prove is their own result, so a session's outputs are compared only in the block that shows them. If an earlier block cannot run, the block fails and says which (the block it continues (L12) did not run: …). compile knows the names the earlier blocks bind, and where credits a block with what it uses of their imports. A first block cannot continue. To bind a page written as one session, tag its first block check and the rest check continue: nothing inside the blocks changes.

  • Renderer attributes in an info string are ignored: ```python title="pricing.py" hl_lines="1 2" check is a check block.

  • Time. Workers are forked from a clean process (os.fork); a block that outlives runtime.timeoutMs has its process group killed. The time counts from when the block is handed to a worker that has started: starting the interpreter is not counted, whether a block is forked from a worker or, where there is no os.fork, runs in a worker of its own. runtime.workers is the number of blocks that run at once.

  • Output. print in attested code goes nowhere; anything written to file descriptor 1 by other means goes to stderr.

  • Network. Internet sockets are refused unless the block is tagged check network (which runs only with DOCATTEST_NETWORK=1). The guard patches socket; an extension module with its own sockets is not stopped.

Docstring examples

Every docstring in a sources file that contains >>> prompts is one example, run as python -m doctest runs it: the session starts with the names of its module, so it needs no import of the thing it documents. The claim it defends is the docstring's description: the text before the first prompt or the first Args:/Parameters/:param section. A function's or class's docstring attests that export; a method's attests its class.

def apply_discount(price: Money, percent: int) -> Money:
    """Take a percentage off a price, rounding half up to a whole cent.

    >>> apply_discount(Money(1000), 25)
    Money(cents=750, currency='EUR')
    """

Facts

A fact expression is a Python expression over the surface's exports and constants:

At most `3` attempts. <!-- fact: RETRY_DEFAULTS["max_attempts"] -->
The rates: <!-- fact column=rate: [f"{r}%" for r in TAX_RATES.values()] -->

It may use the exports, the constants (below), the builtins, snapshot("name"), manifest("path"), file("path"), matched("path", "regex"), manifestField("path", "keys"), the named facts of the setup module, and any standard-library module by its name (math.pi, inspect.signature(f).parameters): a fact cannot import. It may await.

A fact reads a constant from the source of its surface's module, exported or not (_PORT, a name left out of __all__), since a module's most documented values, its port or its default timeout, are often private, or in a script that runs when it is imported. A constant is a name the module assigns once, in a statement of its own top level (not inside an if, try or with), to a constant expression: a literal as ast.literal_eval reads one, the name of a constant assigned before it, + or - before a number, + - * / // % between numbers, or + between two strings, two bytes, two tuples or two lists. Its value is the one that assignment writes; nothing that changes it later runs.

# src/shopd/server.py
import os

PORT = 8080                         # a constant
_TIMEOUT = 30 * 60                  # a constant: 1800
_BASE = "https://" + "shop.example" # a constant
_STARTED = os.getpid()              # a variable: it calls something

A fact that reads only constants does not import its surface, so nothing of the module runs. A fact that reads any other export imports it, and when that import fails, only such facts fail. A function, class or variable that the module declares and does not export is an error that says only constants are read there (_STARTED is a variable that surface "default" does not export; of its unexported names, a fact reads only constants), and so is a name the surface does not have (_round is not exported by surface "default" in the report above): that is what keeps a page honest about what a user can see. Of a program, a __main__.py, a fact reads only constants, exported or not, and audit offers its exported constants. A fact attests the constants it reads, exported or not, as where shows; uncovered lists only exports. So impact lists a change to a constant as it lists a change to an export, with the facts that read it. A value holds the values of the names its initializer uses, so a fact that reads it attests them too, at any depth: a fact over ENV, built from COMMAND_PATH, attests COMMAND_PATH. A private constant used there is credited for where, and uncovered leaves it out. A named fact and a cases runner attest the same of the values they read. A function's body is not followed: a fact over total() attests total, not the names its body reads. impact lists the fact when one of those names changes.

manifest("pyproject.toml") is the data of a project file, read and parsed by the core (JSON, TOML, YAML and go.mod; the manifests page has the details), as dicts and lists: manifest("pyproject.toml")["project"]["requires-python"]. The commands and the Python version at the top of this page are read so, on any Python the package supports, tomllib or not. The path is relative to the project root and written out in the fact: a path built at run time is never read.

file("path") is the text of any other project file, a str, read by the same rules, for the methods of str and for re: the script that runs the adapter from a checkout names its interpreter python3.

matched("path", "regex") and manifestField("path", "keys") take one value out of a file in one call, worked out by the core as for every language (manifests): matched is a str, the text of the regex's first group in its first match, with ^ and $ at the ends of each line; manifestField is the value at a path of keys of a manifest, written as field= writes one, as manifest gives its values: str, int or float, bool, None, list or dict. A regex is written as a raw string, as re takes one: the same script names python3, and the distribution is docattest.

The page's literal is compared with str(value): a value is displayed as its language displays it, and the core knows no spelling of its own. So write values the way Python prints them: True, None, 1.0, ('a', 1). A list on the page is compared with the items of any iterable, each through str. A dict's items are its keys, as iterating it gives them: <!-- fact: TAX_RATES --> above a list checks the keys. A set has no order, so do not combine one with fact ordered.

A fact with field= checks one value of a JSON, TOML or YAML block (facts), which is written as its format writes values. The adapter shows the block's value as Python shows what json reads it as, so it compares with the fact's as the same value: true is True, null is None, 1 is an int and 1.0 a float.

The shop's settings, which match the library's defaults:

<!-- fact field=currency: DEFAULT_CURRENCY -->
<!-- fact field=maxDiscount: MAX_DISCOUNT -->
<!-- fact field=taxed: "NL" in TAX_RATES -->

```json
{ "currency": "EUR", "maxDiscount": 50, "taxed": true }
```

Cases tables and named facts: the setup module

# docs/docattest_setup.py
from shoplib import ERROR_CODES, Money, apply_discount


def discount(row):                      # one call per row; the row is a dict of strings
    got = apply_discount(Money(int(row["price"])), int(row["percent"]))
    assert str(got.cents) == row["result"]


discount.columns = ["price", "percent", "result"]   # optional: columns the table must have

cases = {"discount": discount}
facts = {"error_messages": lambda: list(ERROR_CODES.values())}

cases maps a runner's name to a function; facts maps a name to something a fact expression may use (<!-- fact: error_messages() -->). A runner may be async. Asserts in the setup module report both sides, like asserts in a block.

A runner or a named fact may read what the surface does not export: the setup module imports _PORT, or a name left out of __all__, as any module may. So no name needs exporting only for a page. A runner, and a fact that calls a named fact, attest what the helper reads of the surface, in its own body and in the functions of the setup module it calls: the exports, and the constants, exported or not. A computed private value is neither, so it attests nothing. So where lists the fact under them, uncovered no longer lists them, and impact lists the fact when one of them changes.

A runner gets each cell's text as the page writes it, code spans included: a cell `print(1)` reaches it with its backticks (docs/cases.md). docattest.cells.code_spans takes the code out: the content of every code span in a cell, in order, as a fact over the cell's column compares it.

from docattest.cells import code_spans

assert code_spans("`FOO=1` `BAR=2`") == ["FOO=1", "BAR=2"]
assert code_spans("``a`b`` or `` `c` ``") == ["a`b", "`c`"]
assert code_spans("no code") == []

A span opens with a run of backticks and closes at the next run of as many, and the white space around its content is dropped. As CommonMark has it, a backtick escaped with a backslash opens no span, and neither does one inside an HTML tag or comment, an autolink, or a link's destination or title. The module is part of the docattest distribution, so a setup module imports it from the environment its code runs in: install docattest there, as you do to run it. This guide's runners read their cells so (docattest_setup.py).

A row is named by the page, its line and its first cell. A table's rows run one after another, in the page's order, in one process, which runs the setup module once. Module globals, and anything a row starts and does not stop (threads, and the servers they run; signal handlers), are still there for the rows after it, so a runner stops what it starts before it returns. A row that raises fails, SystemExit too, and the next row runs in the same process. A row that runs out of time or ends the process (os._exit) is the last of its process: the next row starts a fresh one, which runs the setup module again. Tables never share a process, and run side by side, with each other and with blocks: runtime.workers processes at once in all.

Citations

<!-- test: tests/test_pricing.py > "TestTotals" > "test_rejects_big_discounts" --> ties a sentence to a test. A test's title is its function's name: any function or method whose name starts with test, as pytest and unittest find them. Enclosing classes may be named first, outermost first. Citing a class itself is an error that says so ("TestTotals" in tests/test_pricing.py is a class, not a test). The file is read, never run, unless the check is asked to run the tests (below).

The cases of a parametrized test, and the subtests of a test, can be cited too: each is a test inside its test, titled by the id its runner prints for it, so the case that pytest reports as test_total[big discount] is cited as "test_total" > "big discount", the way a test inside a class is.

  • @pytest.mark.parametrize. A case's id is the one written out, in ids=[...] or in pytest.param(..., id="..."), or else the one pytest makes of a literal value: a string or bytes with what is not printable ASCII escaped; a number, True, False or None as str writes it; <argname><index> for a tuple, list, set or dict. A row's ids are joined with -, and so are those of stacked decorators, the one nearest the function first, then those on its classes. The rows are a list or tuple written in the decorator or assigned once to a name of the module.
  • with self.subTest(...). A case is titled by what unittest prints for it: its message (subTest("big discount")), its parameters as unittest writes them (subTest(region="NL") is region='NL'), or both (NL (rate=21)). Each argument is a literal, or comes from the row of a for loop over a literal table, written in the loop or assigned once to a name of the method or of the module: one of the loop's names, an item of one (case["name"], case[0]), or a key of a literal dict's .items(). This guide cites one of this package's own: code_spans reads two spans from a cell that holds a backtick.

What cannot be read so cannot be cited: a value that is not a literal, ids a function makes, a table changed after it is assigned (CASES.append(…)), a subtest inside another, and ids that repeat, which pytest renames by rules that change between its versions. No case of a test under a pytestmark that parametrizes can be cited. The test itself still can, and a citation of a case that is not there names the ones that are (tests/test_p.py declares no test "test_named" > "large"; tests there: "test_named", "test_named" > "small", …). A case attests what its test uses.

Running cited tests

docattest check --run-cited also runs each test a citation names, and the citation passes only when its test ran and passed. The tests run in the project on disk, on the interpreter and with the import path its examples run with (Which Python runs your code), one run per test file and runner, as many at once as runtime.workers. What a run prints is kept from the core. A run that has not ended after ten minutes is killed, with everything it started, and its tests fail. Nothing runs in a project held in memory.

  • pytest, when that interpreter can import it, runs python -m pytest -p no:cacheprovider -q --rootdir=<root> --junitxml=<report> -- <node ids>, each test by its node id: tests/test_a.py::TestA::test_b, and a parametrized case with its id in brackets, tests/test_a.py::test_total[big discount]. A test cited whole runs all its cases. How each ended is read from the JUnit XML report: a failure or an error, in the test or its setup, fails it; a skip, or an expected failure (xfail), skips it; a test cited whole passes when all its cases do; a node id pytest selects nothing by (a class it does not collect) did not run. The report is read as pytest 9.2 writes it. pytest refuses a whole run when one node id selects nothing, so that run is made again, one test at a time.
  • unittest runs otherwise, in a driver of the adapter's, which imports the file as unittest discover does, from the first directory above it that is not a package, by its dotted name from there (tests/test_a.py is test_a from tests), and runs the cited methods in one suite, with the module's and the classes' fixtures. It runs the test methods of a TestCase class at the top of a module; a test function, a method of a nested class or a parametrized case does not run without pytest. An expected failure is skipped; a fixture that fails fails its tests; a module that does not import, or a class that is not a TestCase, runs nothing.
  • A subTest case runs with its test, under unittest whichever runner runs the rest, since no runner selects a subTest alone: it passes when its subTest ran and passed, and fails with its own message when it failed; its test, cited whole, passes when every subTest did. A case its test stopped before ends as the test did, and one it never reached did not run.

What docattest mutate changes

docattest mutate changes the code a proof reads and runs the proof again, to see whether it can fail. What the Python adapter changes are the literals of the value a symbol is assigned, found from syntax, through any re-export, to the module that declares it, one change at a time. They come in source order, at any depth, at most the number the core asks for:

  • A number gains one, written as Python writes its type: 8080 → 8081, 1.5 → 2.5.
  • A string or bytes gains x before its closing quote, its prefix, quotes and escapes kept: 'shop' → 'shopx'. Each part of an implicit concatenation is a literal of its own, and an f-string is none.
  • True and False swap.
  • A list, tuple or set first loses its last item ("B" removed), then its items change. A tuple of one item becomes (), and a set of one set().
  • A dict's literal keys change as its values do.

None and ... stay as they are, and so does anything in a lambda or an annotation. A function or class has nothing to change, and neither has a value with no literal in it, such as os.getpid() or the name of another constant; the report says which. The copies of the project the proofs run in share its __pycache__, so attested code runs with PYTHONDONTWRITEBYTECODE set and writes no bytecode, there or in any run.

Which Python runs your code

The adapter itself only reads syntax. Attested code runs on, in order of preference: the interpreter in DOCATTEST_PYTHON; the active virtualenv (VIRTUAL_ENV); the project's .venv; the interpreter the adapter runs on. So an adapter installed once (with pipx, say) still runs each project's code in that project's environment. DOCATTEST_PYTHON comes first even when the interpreter it names cannot be started:

$ DOCATTEST_PYTHON=/nowhere/python docattest check docs/pricing.md
docattest: cannot start the Python interpreter /nowhere/python that attested code runs on: No such file or directory
[exit 1]
DOCATTEST_PYTHON virtualenv .venv runs on
set active exists DOCATTEST_PYTHON
not set active exists the active virtualenv
not set none exists the project's .venv
not set none none the adapter's own interpreter

What is never your project's own

The adapter tells the core which files and directories to leave alone, wherever they are: __pycache__, site-packages, node_modules, and anything named *.egg-info or *.dist-info. So is any directory that holds a pyvenv.cfg , which is a virtualenv whatever it is called. Hidden directories (.venv, .tox) are left out by the core itself.

Limits

  • No type checking: compile is syntax, imports and names (see above).
  • Exports are read from syntax. An __all__ that is computed at import time is not read; the report warns and the public names are used instead.
  • impact works on top-level functions, classes and assignments. Renaming a function together with its callers reads as a change to all of them.
  • Without os.fork (Windows) every block starts a new interpreter. This path has a test on POSIX but has not been run on Windows.
  • If the adapter is killed with SIGKILL, a block that is still running is not stopped.

Working on this package

CONTRIBUTING.md maps the package's sources, says how to run its tests, lint and type checks, and how this guide is checked.

Metadata

Release files for docattest 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for docattest 0.3.0
File Actions
docattest-0.3.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for docattest-0.3.0-py3-none-win_amd64.whl
docattest-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_1_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64, Linux musl 1.1+ x86-64 Details for docattest-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_1_x86_64.whl
docattest-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64.whl Python 3 none Linux musl 1.1+ ARM64, Linux glibc 2.17+ ARM64 Details for docattest-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64.whl
docattest-0.3.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for docattest-0.3.0-py3-none-macosx_11_0_arm64.whl
docattest-0.3.0-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for docattest-0.3.0-py3-none-macosx_10_12_x86_64.whl

Total release size: 17.1 MB

Release files / docattest-0.3.0-py3-none-win_amd64.whl

Download URL docattest-0.3.0-py3-none-win_amd64.whl
Size 3.5 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
2c9a2c32724480f6b3f9850cf7727586b83a5dceb83d28fe4b1a65ff2bcf9e2b
BLAKE2b-256 checksum
How to use checksums
ec42a703e313d830d81cc71946c0197472a208a83cda4a73d50619fb854ae90f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / docattest-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_1_x86_64.whl

Download URL docattest-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_1_x86_64.whl
Size 3.5 MB
Tags Linux glibc 2.17+ x86-64 Linux musl 1.1+ x86-64 Python 3
SHA-256 checksum
How to use checksums
86fefdf60b4233b46871a3cbf0c6d1153778981cf36ef3ce667dcfb251aa2aaa
BLAKE2b-256 checksum
How to use checksums
4980a4ef60290165e926251a40c0d4873ff0d6ca67d17d9e479602a5228b438e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / docattest-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64.whl

Download URL docattest-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64.whl
Size 3.3 MB
Tags Linux glibc 2.17+ ARM64 Linux musl 1.1+ ARM64 Python 3
SHA-256 checksum
How to use checksums
b02e271d71099ba7ad230e1dd3259f6044a6a578af7a71306e5c64b2ff2ff859
BLAKE2b-256 checksum
How to use checksums
587962cf250bf9c331435ebd3cd98745ff5db0345256b0a2ce9529d47bff6405
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / docattest-0.3.0-py3-none-macosx_11_0_arm64.whl

Download URL docattest-0.3.0-py3-none-macosx_11_0_arm64.whl
Size 3.3 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
f5268bdc38c15a4ffb59c44057654e5676d4c96096acab8438c3932fec901098
BLAKE2b-256 checksum
How to use checksums
a5bfeeffc6f6449b710a624232adec8814f35745ee3b5be10561bf256a184707
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / docattest-0.3.0-py3-none-macosx_10_12_x86_64.whl

Download URL docattest-0.3.0-py3-none-macosx_10_12_x86_64.whl
Size 3.5 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
7b5ba886fd8d97f65fc421b3783fd063dcaebeab456a29a86105e4a76b9488bb
BLAKE2b-256 checksum
How to use checksums
75602de76089e24dce025831f3c96a02596e71617adaa5b3a12f2aa3159b8f5b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for docattest 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for docattest-0.3.0-py3-none-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page