Skip to content

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:

  1. Refuse before any write (ValueError, nothing touched): queued native glyph updates only with settled=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; see edit_guards.require_history_scope); an auto layer in the edit list or among the retained objects; a glyph that the operation policy refuses.
  2. checkInitHistoryState(0) on every layer, then every glyph.
  3. mutate(). It may return the new native objects it made (for example new layers); they join the notification after the declared layers.
  4. One shared UTC lastModified stamp on every glyph.
  5. ONE notifyChangesApplied(title, layers + created + glyphs). With retained objects: ONE notifyChangesApplied(title, retain + layers + created + glyphs, True).
  6. The same stamp again: window observers re-stamp after the history capture.
  7. 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=True lets 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>&quot;&quot;</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.