fontlabapp.core.history.glyphs
glyphs
One native Undo step for a script edit, with auto-layer refusals.
What: commit runs a script's font change as ONE FontLab Undo step, in the
order that the reviewed App writers use:
- Refuse before any write (
ValueError, nothing touched): queued native glyph updates only withsettled=True(FontLab issue 8537; otherwise disclose them); optionally a missing Font window or an open Glyph editor (Unicode writers); a Glyph window as the active canvas when an owner glyph is not in that canvas (FontLab issue 8573: the Undo step would cover only the shown glyphs; seeedit_guards.require_history_scope); an auto layer in the edit list or among the retained objects; a glyph that the operation policy refuses. checkInitHistoryState(0)on every layer, then every glyph.mutate(). It may return the new native objects it made (for example new layers); they join the notification after the declared layers.- One shared UTC
lastModifiedstamp on every glyph. - ONE
notifyChangesApplied(title, layers + created + glyphs). With retained objects: ONEnotifyChangesApplied(title, retain + layers + created + glyphs, True). - The same stamp again: window observers re-stamp after the history capture.
read_back(): the caller compares the font with its plan.
Retained objects (retain=): a script that removes a component gives
the ORIGINAL shape, its shapeData and the builder, read BEFORE the removal
(component_history(shape)). They go first in the notification, before the
layers, and the third argument True asks for deep history. Glyport does
the same (fontlab_backend._retain_component_history and _notify): its
docstring says FontLab 9784 needs this to restore a removed component on Undo
(fl#7641). Without retain the call is the two-argument call, unchanged.
Steps 4 to 6 run also after a failed mutate, so a partial edit stays on the
Undo stack. Every failure is collected and raised as PartialWriteError
(a RuntimeError) whose text says "Native changes may remain; use Edit >
Undo". No rollback is tried: Edit > Undo is the recovery.
Why the refusals: notifying a list that holds an auto layer makes FontLab re-resolve every default-recipe auto layer in the font, and a change to a base glyph rebuilds its auto composites. Anchors and locks can change and Undo does not restore them (measured; see the workspace AGENTS.md). The policy depends on the operation:
"rename","unicode","geometry": refuse glyphs that own an auto layer and glyphs that are a base of an auto composite (also through a chain of manual composites).allow_bases=Truelets a base through after the user agreed to the rebuild; an auto owner is never let through."metadata"(notes, tags, mark colours): refuse only glyphs that own an auto layer.
How to use::
import fly.ap.core.history.glyphs as history
facts = history.scan_auto_facts(package)
result = history.commit(
"Round Advances", layers, glyphs, lambda: edit(layers),
operation="geometry", facts=facts, read_back=check,
)
report(result.mismatches)
The module imports only the standard library at load time; FontLab modules and
fontlabapp.guides.inspect.model load when a function runs. Offline tests prove the call
order only, not native Undo/Redo/reopen behaviour.
Classes
Complete member index
Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.
| Member | Kind | Signature | Summary |
|---|---|---|---|
CHECK_TEXT |
attribute | ||
NOT_STORED |
attribute | ||
OPERATIONS |
attribute | ||
Operation |
attribute | ||
Record |
attribute | ||
SHOWN_MISMATCHES |
attribute | ||
STRUCTURAL |
attribute | ||
UNDO_HINT |
attribute | ||
auto_facts |
function | (records: Iterable[Record]) -> AutoFacts |
Build <code>AutoFacts</code> from dependency records, one record per layer. |
commit |
function | (title: str, layers: Sequence[Any], glyphs: Sequence[Any], mutate: Callable[[], Iterable[Any] | None], *, ope⦠|
Run <code>mutate</code> as ONE native Undo step. |
component_history |
function | (shape: Any) -> tuple[Any, ...] |
Return the native objects to retain when a script removes <code>shape</code>. |
refusal |
function | (facts: AutoFacts, name: str, operation: str, *, allow_bases: bool=False) -> str |
Return why <code>operation</code><code> must not edit glyph </code><code>name</code><code>, or </code><code>""</code>. |
refusals |
function | (facts: AutoFacts, names: Iterable[str], operation: str, *, allow_bases: bool=False) -> dict[str, str] |
Return <code>{refused name: reason}</code><code> for </code><code>names</code>, in their order. |
scan_auto_facts |
function | (package: Any) -> AutoFacts |
Read every layer of <code>package</code><code> and return its </code><code>AutoFacts</code>. |
unstored_error |
function | (missed: Sequence[str], advice: str='') -> RuntimeError |
Return the error for values that FontLab did not keep after a commit. |