research_helpers.build

This module covers the registry of generated artefacts and the drift checks over them. See Adding a generated table for the end-to-end workflow.

class research_helpers.build.Kind(name, suffix, directory, label_prefix, setting, reference, block, float_is_generated, binary=False)

Bases: object

A class of generated artefact (and how the paper refers to it).

Parameters:

• name (str)

• suffix (str)

• directory (str)

• label_prefix (str)

• setting (str)

• reference (Pattern[str])

• block (Pattern[str])

• float_is_generated (bool)

• binary (bool)

stem(label)

Return the filename that ‘label’ is written to (without extension).

Return type:

str

Parameters:

label (str)

filename(label)

Return the filename that ‘label’ is written to.

Return type:

str

Parameters:

label (str)

referenced(paper)

Return the stems the paper pulls in with any extension removed.

Return type:

set[str]

Parameters:

paper (str)

hand_written(paper)

Return the floats the paper carries with no emitter behind them, keyed by label.

Where the emitter produces the float itself, any literal float is hand-written. Where it produces only the contents, a float counts as hand-written when nothing inside it is pulled in from this kind’s directory.

Return type:

dict[str, str]

Parameters:

paper (str)

read(path)

Read a built or installed artefact for comparison.

Return type:

str | bytes

Parameters:

path (Path)

write(path, content)

Write one artefact, creating the parent directory.

Return type:

None

Parameters:

• path (Path)

• content (str | bytes)

class research_helpers.build.Artefact(label, emitter, description='', metadata=<factory>)

Bases: object

A registered artefact.

Parameters:

• label (str)

• emitter (Callable[[], str | bytes])

• description (str)

• metadata (dict[str, Any])

class research_helpers.build.Drift(stale, missing, ungenerated)

Bases: NamedTuple

The three ways a paper and its emitters can disagree.

Parameters:

• stale (list[str])

• missing (list[str])

• ungenerated (list[str])

stale: list[str]

Alias for field number 0

missing: list[str]

Alias for field number 1

ungenerated: list[str]

Alias for field number 2

class research_helpers.build.Registry(kind)

Bases: object

The emitters for one kind of artefact and the checks over them.

Parameters:

kind (Kind)

register(label, *, description='', **metadata)

Register the decorated function as the emitter for ‘label’.

Parameters:

• label (str) – the ‘\label’ the paper cites this artefact as, e.g. ‘tab:scores’. Must carry the kind’s prefix, since the filename is the label without it.

• description (str, default: '') – one line, shown by ‘–list’.

• **metadata (Any) – kept on the ‘artefact’ for a project’s own use.

Return type:

Callable[[TypeVar(EmitterT, bound= Callable[[], str | bytes])], TypeVar(EmitterT, bound= Callable[[], str | bytes])]

Returns:

The decorator, which returns the emitter unchanged so it stays directly callable.

Raises:

ValueError – if the label is already registered or lacks the kind’s prefix.

property labels: list[str]

Return every registered label, in registration order.

build_dir(directory=None)

Return where artefacts are built, defaulting to the project’s build directory.

Return type:

Path

Parameters:

directory (Path | str | None)

install_dir(destination=None)

Return where the paper reads artefacts from, defaulting to the project’s setting.

Return type:

Path

Parameters:

destination (Path | str | None)

write_all(directory=None)

Build every artefact into ‘directory’, one file per label, and return the paths.

Return type:

list[Path]

Parameters:

directory (Path | str | None)

install(destination=None, source=None)

Copy built artefacts to where the paper reads them.

Parameters:

• destination (Path | str | None, default: None) – where the paper reads from. Defaults to the project’s setting.

• source (Path | str | None, default: None) – where the artefacts were built. Defaults to the project’s build directory.

Return type:

list[Path]

Returns:

The paths written.

Raises:

FileNotFoundError – if an artefact has not been built.

drift(paper=None, destination=None)

Compare what the paper carries against what the emitters produce.

Parameters:

• paper (Path | str | None, default: None) – the manuscript. Defaults to the project’s ‘paper.main’.

• destination (Path | str | None, default: None) – where the paper reads artefacts from. Defaults to the project’s setting.

Return type:

Drift

Returns:

The three ways they disagree; falsy when they do not.

report(found)

Return a description of what drifted, and what to do about it.

Return type:

str

Parameters:

found (Drift)

main(argv=None)

Run the build command line.

Parameters:

argv (list[str] | None, default: None) – command line arguments, or None to read ‘sys.argv’.

Return type:

int

Returns:

A process exit status – 0 on success, 1 if ‘–check’ found drift.