👃 source_maps#

Records where every generated line came from, and maps it once the build is done.

PACKAGING_PLUGINS: tuple[str, ...] = ('stewbeet.plugins.archive', 'stewbeet.plugins.merge_smithed_weld', 'stewbeet.plugins.copy_to_destination', 'stewbeet.plugins.compute_sha1')[source]#

StewBeet plugins that read the finished pack. A map written after one of them ran is a map it did not see, which is the only reason to say anything about writing one late.

beet_default(
ctx: Context,
) → Generator[None][source]#

Record where every generated line came from, and map it once the build is done.

Belongs in require, next to stewbeet itself, and that is the whole configuration. Everything there runs before the pack is even loaded, so no write can happen before capture is installed, and beet unwinds require last, so what mecha compiled is mapped from here too.

Parameters:

ctx – The beet context.

write_mecha_maps(
ctx: Context,
) → int[source]#

Map what mecha compiled, when mecha is part of the build.

Done from here rather than from a pipeline entry of its own, because here is where it works: beet unwinds require last, so mecha has compiled, auto.headers has prepended its headers, and mecha’s compilation units are still in its database. A bolt or mecha project with no StewBeet writes in it needs nothing more than this plugin either.

Parameters:

ctx – The beet context.

Returns:

How many sidecars this wrote.

packaged(ctx: Context) → bool[source]#

Whether a plugin that reads the finished pack ran in this build.

Read off the plugins beet resolved rather than by importing each of them, since the question is only worth a name comparison. A packaging plugin of your own is not recognised, so nothing is said about a build that has one.

Parameters:

ctx – The beet context.

attribution#

class Declared(*args, **kwargs)[source]#

Bases: Protocol

Anything carrying the origin captured when it was declared, in practice an Item or a Block.

origin: SourceOrigin | None[source]#
attribute_to(
definition: Declared,
) → Generator[None][source]#

Attribute everything written inside this scope to a declaration’s own site.

Needed because a plugin generating from Mem.definitions has no project frame on the stack at all: the declaration returned long before, leaving only beet’s pipeline and the user’s entry point above the write. The declaration captured its own origin when it was constructed, and this hands that origin to every write inside the block.

>>> from stewbeet.plugins.source_maps.model import SourceOrigin
>>> class Fake: origin = SourceOrigin(file="/p/blocks.py", line=11, column=0)
>>> with attribute_to(Fake()):
...     Mem.attribution[-1].origin.line
11
>>> Mem.attribution
[]
attributed(
definitions: Iterable[tuple[str, T]],
) → Generator[tuple[str, T]][source]#

Iterate definitions, attributing everything each iteration writes to that declaration.

A generation loop wraps its iterable in this instead of indenting its whole body into a with. The scope opens before the body runs and closes when the loop asks for the next item, or when it breaks and the generator is closed, so it always matches the iteration exactly.

>>> from stewbeet.plugins.source_maps.model import SourceOrigin
>>> class Fake: origin = SourceOrigin(file="/p/blocks.py", line=11, column=0)
>>> [Mem.attribution[-1].origin.line for _ in attributed([("a", Fake())])]
[11]
>>> Mem.attribution
[]

capture#

PATH_ATTR: str = '__stewbeet_source_maps_path__'[source]#

Attribute StewBeet tags onto a beet Function so a patched write knows which path it feeds.

ORIGINALS: dict[str, Callable[[...], Any]] = {}[source]#

The unpatched beet methods, restored at teardown.

tag(
func: Function,
path: str,
) → Function[source]#

Record which resource location a Function belongs to.

A beet Function does not know its own path, and the patched writers below only receive the object. Tagging is done from the two places that have both: write_function and Resource.obj.

record(
path: str,
content: str,
mode: str,
origin: SourceOrigin | None = None,
) → None[source]#

Record one contribution to a function, mirroring write_function’s own semantics.

Append adds a chunk, prepend inserts at the front, and a developer’s overwrite clears what it replaced. A library overwrite deliberately does not clear: auto.headers rewrites every function with overwrite=True as a transformation rather than as a replacement, and wiping the author’s chunks there would destroy every mapping in the pack. Alignment handles that case.

record_from(
func: Function,
other: Function | Iterable[str] | str,
mode: str,
) → None[source]#

Record a write made straight through a beet Function, the modern .obj.append(...) path.

record_assignment(
container: NamespaceContainer[Any],
key: str,
value: Any,
) → None[source]#

Record ctx.data.functions[path] = Function(...), which no other hook sees.

beet’s own way of writing a function builds the object and puts it in the pack, so there is no append to catch and no StewBeet helper to tag it. Tagging happens for every insertion, which is what makes a later .append(...) on the same path work; recording happens only when the caller is genuinely assigning, because write_function’s overwrite branch assigns too and records itself one frame further down.

install() → None[source]#

Patch beet’s Function writers so every incremental write is captured.

Function.append and .prepend are the single choke point every incremental write flows through, including write_function’s own. The deprecated Block.on_place was replaced by .functions.place_secondary.obj.append(...), which never touches write_function at all, which is why the hook lives here.

NamespaceContainer.process is the other one. Every way of putting a function into a pack ends there with both the namespace and the key in hand, so ctx.data.functions[p] = Function(...), ctx.data["ns"].functions[p] = ... and ctx.data[Function][p] = ... are one hook rather than three.

uninstall() → None[source]#

Restore beet’s own methods, so a watch rebuild does not stack patches.

origin#

CONTENT_PARAMETER: str = 'content'[source]#

The name every StewBeet write helper gives its mcfunction body, and all write_helpers looks for.

WRITE_METHODS: frozenset[str] = frozenset({'append', 'prepend'})[source]#

Methods on a beet Function that author content, reached through Resource.obj.

GENERATED_INIT: str = '<string>'[source]#

Filename of the __init__ a dataclass generates, the one frame between a definition and its declaration.

INDEX_CACHE_NAME: str = 'source_maps_index'[source]#

Beet cache slot keeping each source file’s write calls from one build to the next.

INDEX_FORMAT: str = '3'[source]#

Part of the index signature: bump it when write_call_spans finds calls differently, so every file is parsed again.

Span = Span[source]#

Start line, end line, start column and end column of an expression, in the order co_positions() gives them.

class WriteCall(
line: int,
column: int,
templates: tuple[Template, ...],
kind: str = 'write',
forwards: str | None = None,
)[source]#

Bases: object

A write call found in a source file, and where its content argument starts.

kind separates the two ways a function gets content. write is a StewBeet helper or an append, which record themselves. assign is ctx.data.functions[path] = Function(...), beet’s own idiom, which nothing records until the container hook does, and which must not be recorded twice when a helper is the one doing the assigning.

line: int[source]#
column: int[source]#
templates: tuple[Template, ...][source]#
kind: str[source]#
forwards: str | None[source]#

The parameter annotated McFunction the content is, when the write passes on what its caller handed over.

write_helpers() → dict[str, int][source]#

StewBeet’s write helpers, mapped to the position of their content argument.

Read off the signatures in core.utils.io.functions rather than listed here, so adding a helper there is enough for the source_maps plugin to record it. The convention it reads is the parameter name: write_function(path, content, ...) gives 1 and write_load_file(content, ...) gives 0, while write_tag, having no content argument, is not a write helper at all.

>>> write_helpers()["write_function"], write_helpers()["write_load_file"]
(1, 0)
>>> "write_tag" in write_helpers(), "read_function" in write_helpers()
(False, False)
project_roots() → tuple[str, ...][source]#

Roots under which a file counts as the project’s own source, defaulting to beet’s project directory.

reset_caches() → None[source]#

Drop the caches whose inputs only hold still within one build.

project_roots reads Mem.ctx, which is a different project on the next build, and the shared source filter is built on top of it. AST_CACHE and PARSED hold a file as it was parsed, which the author has been free to edit between one build and the next.

index_write_calls(
path: str,
) → dict[int, WriteCall][source]#

Map every line of a source file that holds a write call to that call’s content position.

Being inside project code is not evidence of authorship; being at a write call is. That is what stops a plugin-generated write from attributing to the project’s entry point, which passes the project-source filter while having authored nothing.

write_call_spans(
path: str,
) → list[tuple[int, int, WriteCall]][source]#

Every write call of a source file with the first and last lines it spans, in the order calls_by_line expects.

calls_by_line(
spans: list[tuple[int, int, WriteCall]],
) → dict[int, WriteCall][source]#

The write call each line belongs to, the first call spanning it winning, as an outer call comes before the ones inside it.

>>> outer, inner = WriteCall(line=0, column=0, templates=()), WriteCall(line=1, column=4, templates=())
>>> calls_by_line([(1, 3, outer), (2, 2, inner)]) == {1: outer, 2: outer, 3: outer}
True
written_call(
node: Call,
helpers: dict[str, int],
literals: LiteralIndex,
) → WriteCall | None[source]#

A StewBeet write helper or a .append/.prepend call, None for any other call.

Parameters:

helpers – Each write helper’s name and the position of its content argument, see write_helpers.

assigned_function(
node: Assign,
literals: LiteralIndex,
) → WriteCall | None[source]#

A ... [path] = Function(content) assignment, which is how a plain beet plugin writes.

The target has to be a subscript so that func = Function(...) on its own is not read as a write: nothing has been given a path yet at that point. All three spellings beet offers end up here, since ctx.data.functions[p], ctx.data["ns"].functions[p] and ctx.data[Function][p] differ only in what precedes the subscript.

AST_CACHE: dict[str, dict[int, WriteCall]] = {}[source]#

Parsed write-call index per file, held for one build and dropped by reset_caches. Nobody edits a file halfway through a build, and beet watch starts a new one. The alternative is a stat on every project frame of every write, which is the plugin’s single biggest cost.

class PersistedIndex(
files: dict[str, list[object]],
loaded: bool = False,
dirty: bool = False,
)[source]#

Bases: object

The write calls of every source file seen by earlier builds, with the size and modification time they were read at.

files: dict[str, list[object]][source]#
loaded: bool[source]#
dirty: bool[source]#
PERSISTED: PersistedIndex = PersistedIndex(files={}, loaded=False, dirty=False)[source]#

Parsing a file is the bulk of the plugin’s time, and most files do not change between two builds.

write_calls_of(
path: str,
) → dict[int, WriteCall][source]#

Cached index_write_calls, for as long as the build lasts, and from one build to the next for an unchanged file.

persisted_spans(
path: str,
) → list[tuple[int, int, WriteCall]][source]#

write_call_spans, taken from the persisted index when the file has the size and modification time recorded there.

read_templates(
rows: list[Any],
) → tuple[Template, ...][source]#

The templates of a write call as persisted_spans stores them, each as its lines and their starts.

index_signature() → str[source]#

What the persisted index depends on besides the files: its format and how write calls are recognized.

load_index() → dict[str, list[object]][source]#

The persisted index, read from the beet cache the first time, empty when missing, unreadable or made otherwise.

store_index() → None[source]#

Write the persisted index back when this build parsed anything, dropping the files that no longer exist.

declaration_origin() → SourceOrigin | None[source]#

Where a definition was declared, or None when a library declared it.

Called from a dataclass __post_init__, so the frames above are the construction’s own: the caller’s file, the definition dataclasses (block.py for a Block), and the __init__ the dataclass generated. Unlike resolve_origin this consults no AST index, because a constructor’s caller is the declaration site, with no plugin in between to be mistaken for it.

The case that must not be attributed is a StewBeet plugin building an Item itself: the walk stops at the first frame that is not the construction’s, so it lands on the plugin and returns None rather than continuing out to the user’s entry point, which declared nothing.

>>> declaration_origin() is None   # a doctest frame is nobody's declaration
True
is_constructor_frame(frame: FrameType) → bool[source]#

Whether a frame belongs to a definition being built rather than to whoever asked for it.

definition_root() → str[source]#

Directory holding the definition dataclasses of items and recipes, resolved from a module rather than spelled out.

call_position(frame: FrameType) → tuple[int, int][source]#

Line and column of the call a frame is executing, both 0-based.

co_positions() carries the exact span of every instruction since Python 3.11, so the column of a Block( call is available without parsing anything. A frame built without position tables yields no column, and 0 is the honest answer there.

>>> def probe() -> tuple[int, int]:
...     return call_position(sys._getframe())
>>> probe()[1]
11
resolve_origin() → SourceOrigin | None[source]#

Where the content being written was authored, or None when nothing in the project authored it.

Three tiers, first hit wins:

  1. The innermost stack frame that is project source and sits on a write call, or the call that handed

    that write its content when the content is a parameter annotated McFunction, see forwarded_origin.

  2. The top of the ambient attribution stack, for content a plugin generates from a declaration.

  3. Nothing, so the lines are emitted unmapped.

resolve_site() → tuple[SourceOrigin | None, str][source]#

resolve_origin, plus what kind of call site answered.

The kind is write for a StewBeet helper or an append, assign for beet’s own ... [path] = Function(...), and "" when nothing in the project answered. Only the container hook needs it, to tell an author assigning a function from a helper doing the same thing one frame further down, which records itself.

forwarded_origin(
frame: FrameType,
parameter: str,
) → SourceOrigin | None[source]#

Where the project code calling frame spelled what it handed over as parameter, None when no project code did.

A function writing a parameter annotated McFunction holds none of the commands: the call to it does, or the call to its caller when that call passes on a parameter of its own.

executing(
frame: FrameType,
) → Span[source]#

The span of the instruction a frame runs, as co_positions() gives it: the whole call for a frame waiting on its callee.

argument_of(
call: Call,
callee: CodeType,
parameter: str,
) → expr | None[source]#

The expression a call passes for one parameter of the function it runs, by keyword or by position.

PARSED: dict[str, tuple[dict[Span, Call], LiteralIndex]] = {}[source]#

Each file a forwarded write was followed into, as its calls by span and the literals of its writes, for one build.

parsed(
filename: str,
) → tuple[dict[Span, Call], LiteralIndex][source]#

The calls of a source file keyed as executing reports them, with an index of its literals, parsed once per build.