👃 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,
Record where every generated line came from, and map it once the build is done.
Belongs in
require, next tostewbeetitself, 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 unwindsrequirelast, so what mecha compiled is mapped from here too.- Parameters:
ctx – The beet context.
- write_mecha_maps(
- ctx: Context,
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
requirelast, so mecha has compiled,auto.headershas 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:
ProtocolAnything carrying the origin captured when it was declared, in practice an Item or a Block.
- attribute_to(
- definition: Declared,
Attribute everything written inside this scope to a declaration’s own site.
Needed because a plugin generating from
Mem.definitionshas 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]],
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,
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_functionandResource.obj.
- record(
- path: str,
- content: str,
- mode: str,
- origin: SourceOrigin | None = None,
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.headersrewrites every function withoverwrite=Trueas 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,
Record a write made straight through a beet Function, the modern
.obj.append(...)path.
- record_assignment(
- container: NamespaceContainer[Any],
- key: str,
- value: Any,
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, becausewrite_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.appendand.prependare the single choke point every incremental write flows through, includingwrite_function’s own. The deprecatedBlock.on_placewas replaced by.functions.place_secondary.obj.append(...), which never toucheswrite_functionat all, which is why the hook lives here.NamespaceContainer.processis the other one. Every way of putting a function into a pack ends there with both the namespace and the key in hand, soctx.data.functions[p] = Function(...),ctx.data["ns"].functions[p] = ...andctx.data[Function][p] = ...are one hook rather than three.
origin#
- CONTENT_PARAMETER: str = 'content'[source]#
The name every StewBeet write helper gives its mcfunction body, and all
write_helperslooks 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_spansfinds 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,
Bases:
objectA write call found in a source file, and where its content argument starts.
kindseparates the two ways a function gets content.writeis a StewBeet helper or an append, which record themselves.assignisctx.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.
- 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.functionsrather 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 andwrite_load_file(content, ...)gives 0, whilewrite_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_rootsreadsMem.ctx, which is a different project on the next build, and the shared source filter is built on top of it.AST_CACHEandPARSEDhold 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,
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,
Every write call of a source file with the first and last lines it spans, in the order
calls_by_lineexpects.
- calls_by_line(
- spans: list[tuple[int, int, WriteCall]],
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,
A StewBeet write helper or a
.append/.prependcall, 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,
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, sincectx.data.functions[p],ctx.data["ns"].functions[p]andctx.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, andbeet watchstarts a new one. The alternative is astaton 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,
Bases:
objectThe write calls of every source file seen by earlier builds, with the size and modification time they were read at.
- 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,
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,
write_call_spans, taken from the persisted index when the file has the size and modification time recorded there.
- read_templates(
- rows: list[Any],
The templates of a write call as
persisted_spansstores 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.pyfor aBlock), and the__init__the dataclass generated. Unlikeresolve_originthis 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
Itemitself: 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 aBlock(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:
- 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.
The top of the ambient attribution stack, for content a plugin generates from a declaration.
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
writefor a StewBeet helper or an append,assignfor 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,
Where the project code calling
framespelled what it handed over asparameter, 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,
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,
The expression a call passes for one parameter of the function it runs, by keyword or by position.