meta_package_manager.docstring_corpus module

Harvest the CLI-session samples documented in manager source docstrings.

Every query method (and the version_regexes attribute) documents a sample invocation and its output in a MyST {code-block} shell-session fence sitting right next to the regex (or JSON parser) that consumes it. This module reads those blocks straight from the source and exposes them, with a shared notion of which ones are literal, replayable fixtures.

It has two consumers:

• tests.test_docstring_corpus replays each literal block back through the parser it illustrates, asserting the documented example still yields well-formed packages.

• meta_package_manager._docs renders the literal blocks as the reference traces of a class-based manager’s documentation page, the config-defined twin of the [samples] fixtures shipped alongside TOML-defined managers.

Blocks are harvested from raw source, not the escape-processed __doc__: inspect.cleandoc() expands tabs and the compiler collapses \\, either of which would rewrite a tab-delimited or escaped-JSON fixture into something the parser rejects. Everything here reads static source through ast/inspect, so it is host-independent: safe to call at documentation build time on any machine.

meta_package_manager.docstring_corpus.FENCE_OPENERS = ('```{code-block} shell-session', '```{code-block} pwsh-session')

MyST fence openers introducing a captured CLI session.

PowerShell sessions use > as their prompt, which the dissector already recognizes, so both flavors share one extraction path.

Important

These two openers are the fixture fences: every installed / outdated / orphans / version_regexes block written under one is a complete sample that must parse (the corpus round-trip enforces it) and is rendered as a reference trace. An illustration that is not a literal fixture (a human-readable variant, an interactive prompt, a narrative before/after transcript) uses a non-harvested {code-block} console fence instead, so it stays out of the corpus and the traces while still rendering in the API docs.

meta_package_manager.docstring_corpus.extract_blocks(docstring)

Return the dedented body of every shell-session fence in a docstring.

A fence body runs from the opener to the first closing ` ` ` line, and shares the fence's indentation. The blank line the MyST syntax puts between a ``{code-block} opener and its content is stripped along with the common indentation.

Return type:

list[str]

meta_package_manager.docstring_corpus.dissect(block)

Split a shell-session block into its command tokens and its output.

$ starts a command and > continues it (the shell’s secondary prompt). A command may also continue onto unprefixed lines via a trailing backslash, so those are absorbed too. Every remaining line is output.

Return type:

tuple[list[str], str]

meta_package_manager.docstring_corpus.split_session(block)

Return just the command output of a shell-session block.

Return type:

str

meta_package_manager.docstring_corpus.block_commands(block)

Return each documented command of a block as its own token list.

Unlike dissect(), which pools every command of a block, this keeps commands separate so a block documenting several invocations (an apt cleanup running autoremove then autoclean) yields one list each. Prompt flavor is per-block: $-primary with > continuations for shell sessions, >-primary for PowerShell sessions.

Return type:

list[list[str]]

meta_package_manager.docstring_corpus.block_language(block)

Return the fenced-code language matching a block’s prompt flavor.

A shell session opens on a $ prompt, a PowerShell session on >. The documented reference traces are re-fenced with the flavor they were captured under so their prompts keep highlighting correctly.

Return type:

str

meta_package_manager.docstring_corpus.class_blocks(cls: type) → dict[str, list[str]]

Map {member: [blocks]} kept in raw source form for the corpus.

Escapes and tabs survive verbatim so the round-trip feeds each block to the parser exactly as the CLI emits it. Rendered documentation wants the terminal-facing form instead: see class_display_blocks().

Return type:

dict[str, list[str]]

meta_package_manager.docstring_corpus.class_display_blocks(cls: type) → dict[str, list[str]]

Map {member: [blocks]} in compiled form for rendered documentation.

The reference-traces generator reads these so a transcript shows single backslashes and resolved escapes, matching what a reader would see running the command, rather than the doubled source escapes class_blocks() preserves for the parser.

Return type:

dict[str, list[str]]

meta_package_manager.docstring_corpus.is_fixture(output)

A block is a fixture when it carries sample output to parse.

A shell-session block showing only a command (no output, an empty system) illustrates an invocation but has nothing for a parser to consume, so it is not a fixture.

Return type:

bool

meta_package_manager.docstring_corpus.literal_blocks(cls, members)

Return (member, index, block) for a class’s replayable fixture blocks.

A block qualifies when it carries sample output (is_fixture()). The index is its position within the member’s full block list. Blocks come in compiled, terminal-facing form (class_display_blocks()): the escape/tab differences from the raw corpus form never touch a directive, so the same blocks are selected either way.

Return type:

list[tuple[str, int, str]]

meta_package_manager.docstring_corpus.version_trace(cls)

Return the raw --version output documented for a class, or None.

The first version_regexes block’s output, mirroring the version [samples] fixture a TOML-defined manager ships.

Return type:

str | None