Skip to content

Native scripting

Inside FontLab, echopy.fontlab delegates to the original fontlab objects; echopy.fontgate and echopy.fontpr follow the same contract.

from echopy import fontlab as fl

font = fl.CurrentFont()
glyph = fl.CurrentGlyph()
node = fl.flNode(120, 340)

Use flNode and the complete class member indexes to inspect captured signatures and enriched documentation. Any and variadic arguments mark incomplete native signature information. They are not permission to pass arbitrary objects; confirm an uncertain operation against the running host.

The native modules have their own top-level Native API section in the navigation: fontlab, fontgate, fontpr, FL and PythonQt. Each module page starts with an overview and tables of its functions, classes and constants.

Short imports

Fly provides nine lazy module aliases:

Alias Target
fly.fl echopy.fontlab
fly.fg echopy.fontgate
fly.tr typerig
fly.pr echopy.fontpr
fly.qt native PythonQt
fly.ap fontlabapp
fly.qs pythonqtside
fly.gp fontlab_glyport
fly.fp fontlab_fontport

They share the canonical module objects. Documentation names use the live API's natural namespaces, while source and enrichment hashes retain provenance.

Outside FontLab, native construction and operations fail with NativeUnavailable. Documentation builds read source and stubs without invoking these operations.

Read and extend the Font-window selection

These examples use the ordinary development App package 0.2.26.dev159+gb1e905b61. Older versions can clear and rebuild the selection even with add=True. The examples below were checked against the installed artifact with owned native doubles; their FontLab behavior remains unqualified.

Read names bound to one font

Keep the two native identifiers separate. package.id binds App operations to a package; package.fgId identifies the FontGate carrier used by the legacy selection reader. The reader returns selected glyph names in font order. It is not a list of every displayed glyph, nor a record of selected chart cells: one glyph can occur in several cells.

Defining this function does not access FontLab. Calling it reads selection and returns the package identifier with the names. A two-second deadline bounds the Python scan, but cannot interrupt a blocking native call. The final identity check rejects a font switch; it does not prove an atomic snapshot if native state changes and changes back during the scan.

from time import monotonic
from fontlabapp.core.scripting import current_package, names_font_window_selection


def read_font_selection():
    package = current_package()
    if package is None:
        raise ValueError("Open a font before reading its selection.")
    package_id = int(package.id)
    names = names_font_window_selection(
        expected_fg_id=int(package.fgId), deadline=monotonic() + 2.0
    )
    if current_package(package_id) is None:
        raise ValueError("The font changed during the selection read; run again.")
    return package_id, names

An empty selection is a valid empty list. This function does not fall back to the current Glyph-window glyph. Keep the returned package identifier with any report based on these names, so a later action cannot silently target another font.

Add report results without clearing selection

Pass the bound package identifier and the glyph names your report found to this function. Calling it changes the Font-window selection; it does not edit glyph outlines. Activate the regular Font window first. Readable selection data from a Glyph window does not make the legacy selection writers safe there.

from fontlabapp.core.scripting import select_glyphs


def add_report_names(package_id, names):
    selected = select_glyphs(names, package_id=package_id, add=True)
    print(f"Selected {len(selected)} glyph names in total.")
    return selected

The helper validates every requested name before writing and rejects a stale package or unsupported active window. It adds only names that are not already selected, preserving the existing selection. Duplicate names do not cause repeated writes. Empty requests and already-selected names require no selection writes, but still undergo the package/window checks. The returned count is the total number of selected glyph names, not the number just added or the number of selected chart cells. An already-selected glyph's partial cell selection is left untouched.

If a native addition fails, the exception propagates. Earlier additions can remain; this is not atomic rollback. Do not automatically retry, clear selection or apply a global Undo in an error handler. add=False is a different operation: it clears selection before selecting the requested names and does not have the same preservation behavior. Neither route calls UpdateAll().

A displayed filter is a separate scope

Neither helper supplies the Font window's arranged, filtered cell list. A scan of all package glyphs or MCP list_glyphs with request filters is not equivalent to the current UI filter. The inspected C++ chart model has cell data, but its ordinary accessors are absent from the retained PythonQt capture. That bounded finding does not prove that every route is unavailable on every build.

Before adapting a tool that operates on displayed cells, verify an exposed ordered snapshot with package-qualified glyph identities, duplicates and empty encoding cells. Define whether “visible” means included by the chart filter or inside the viewport. Test reads and writes on owned fonts, including font switches, filtered views and multiple cells for one glyph; source examples alone do not establish complete font, history or view-state preservation.

Handle writer results and failures

A successful Python call does not prove that FontLab preserved every unrelated part of a font. Keep the returned counters and warnings, and qualify edits with Apply, Undo, Redo and saved-file reopen on owned copies before relying on a writer. Do not convert an exception into a success message or automatically repeat a failed edit: a partial write can already have changed the font.

The examples below use the development App contract verified in ordinary package 0.2.26.dev158+g55fc09868. This is a source/artifact checkpoint, not a published release or native acceptance claim. Older installed App versions may still refuse queued updates and may not accept the disclosure keyword.

Queued updates are a warning

FontLab can retain glyph IDs in its process-wide update queue after opening an editor or refreshing views. A later write may change those glyphs’ modification dates. Ordinary App writers disclose this as pending_updates and pending_note instead of refusing solely because the queue is nonempty. They do not clear the queue or restore unrelated dates to conceal the change.

Field Meaning
pending_updates Tuple of native glyph IDs captured before the write; these are not names or proof that those glyphs changed.
pending_note Human-readable date caveat, or an empty string.
undo_steps Raise Ascender’s completed changed occurrences, not a guarantee that a later Undo succeeded.
nodes Raise Ascender’s counted node moves across its sequential occurrences.
guides, layers Perpendicular Guides’ reported additions and affected-layer count.

Use the stored note when formatting a result. Reading the native queue again can observe different state and lose the warning that applied to this action.

from fontlabapp.core.edit_guards import append_note


def raise_status(result):
    text = (
        f"Moved {result['nodes']} nodes across {result['occurrences']} occurrences; "
        f"{result['undo_steps']} Undo steps."
    )
    return append_note(text, result)

This formatter runs outside FontLab with an ordinary result dictionary. The helper appends a nonempty note once. A zero-move result is still a valid outcome: it does not mean every selected node required an edit.

Preserve warnings when Raise Ascender fails

Backend.execute() accepts an optional mutable disclosure dictionary. It resets the dictionary at entry and fills it before history, so a caller can display the queue warning even when no result is returned. A failure before queue sampling, or a no-op, leaves an empty disclosure; this does not prove that the native queue is empty. Without a dictionary, the backend prints the warning itself.

This wrapper uses the formatter above. Defining it is safe outside FontLab; calling it requires FontLab and can change the current font.

from fontlabapp.core.edit_guards import append_note
from fontlabapp.contours.raise_ascender.native import Backend


def raise_selected(amount="10", *, all_layers=False):
    disclosure = {"pending_updates": (), "pending_note": ""}
    try:
        result = Backend().execute(
            amount, all_layers, disclosure=disclosure
        )
    except Exception as error:
        print(append_note(f"Raise Ascender failed: {error}", disclosure))
        raise
    print(raise_status(result))
    return result

all_layers=False uses the selected occurrences. True uses every foreground layer of the first selected glyph, including associated auxiliary layers; it is not an all-font operation. The writer retains its bound-font, source-change, automatic-dependent and history-scope checks. A queued-update warning does not waive any of those checks.

On failure, the wrapper preserves the original exception and its Undo guidance. In a dialog, put the same formatted text in an owned status label instead of printing it. Keep the disclosure dictionary for that action only; do not reuse a previous action’s warning after a no-op or an early failure.

Perpendicular Guides uses the same warning

fontlabapp.guides.perpendicular.model.run() plans guides for the first selected layer. When the sampled queue is nonempty, it prints the warning before a possible append. On success it returns guides, layers, messages, pending_updates and pending_note. The warning is already printed; callers need not print it a second time. A no-op reports zero counts and empty disclosure without querying the queue. Source changes, automatic layers or affected automatic dependants still cause refusal.

If an append partially fails, no success dictionary is returned. The warning has already been printed and the append-failure exception directs the user to inspect Edit > Undo. Notification/finalization errors can also propagate; do not infer rollback from an exception. No queue clearing, automatic retry or global Undo belongs in a caller’s error handler.

Preview complete background removal

The background tools remove entire background layer objects, including their stored payload. They do not merely erase contours. Use Clear All Layer Backgrounds or Clear Master Backgrounds for a panel with a preview and an explicit Apply action. The programmatic equivalent below also separates inspection from the write.

masters=False includes mapped backgrounds of all foreground layers in the current font, including auxiliary layers. masters=True restricts the plan to master foreground layers. Neither scope means selected glyphs only. A background shared by a master and an excluded auxiliary layer is refused in master-only mode; silently deleting it would change the excluded layer too.

Defining these functions makes no edit. Call preview_backgrounds() in FontLab, inspect the printed glyph/background names, then explicitly pass its returned value to clear_previewed_backgrounds(). Pass masters=True to preview the master-only scope. A preview is bound to its original font and scope: the writer rechecks it before history and refuses stale facts rather than silently rescanning and applying a different plan.

from fontlabapp.masters.background.clear.model import plan as background_plan
from fontlabapp.masters.background.clear.native import Backend as BackgroundBackend
from fontlabapp.core.edit_guards import append_note


def preview_backgrounds(*, masters=False):
    backend = BackgroundBackend()
    source = backend.capture()
    if source is None:
        raise ValueError("Open a font before previewing backgrounds.")
    for removal in background_plan(source, masters):
        print(f"{removal.glyph}: {removal.mask_name}")
    return backend, source, masters


def clear_previewed_backgrounds(preview):
    backend, source, masters = preview
    disclosure = {"pending_updates": (), "pending_note": ""}
    try:
        result = backend.apply(source, masters, disclosure=disclosure)
    except BaseException as error:
        # Report the action's warning, then propagate interruptions unchanged.
        print(append_note(f"Background clearing failed: {error}", disclosure))
        raise
    print(append_note(
        f"Removed {result['backgrounds']} backgrounds from "
        f"{result['layers']} foreground layers in {result['glyphs']} glyphs.",
        result,
    ))
    return result

backgrounds counts confirmed object removals; layers counts the affected foreground layers, which can differ when backgrounds are shared. glyphs counts owner glyphs. A no-op returns zero counts and empty disclosure without sampling the native queue. A nonempty warning is reported once by this wrapper; the supplied dictionary prevents the backend from printing it separately.

Active or locked backgrounds, invalid ownership/mapping, affected automatic layers or automatic dependants, and unsupported history scope can still cause refusal. Queue disclosure does not waive these guards. A refused domain remains an incomplete compatibility boundary, not proof of equivalent original behavior.

A failure after an attempted removal may leave changes in the font. Ordinary partial-write errors report attempted and confirmed removal counts and direct the user to Undo. Interruptions stop further removals, attempt remaining date updates and notification, then propagate the original interruption with recovery notes. The wrapper preserves those notes by re-raising the same exception. Neither cleanup nor an exception proves rollback, successful Undo, or that native cleanup finished within a deadline. Do not automatically retry the operation.

Verification boundary

The Raise Ascender formatter and caller are checked against the ordinary App artifact. Formatting uses the actual shared helper; wrapper success/no-op/failure tests substitute the native backend. Those tests prove message composition, disclosure forwarding and exception propagation. They do not prove FontLab editing, native window behavior, whole-font preservation or successful Undo/Redo. The writer’s artifact tests and its dedicated native qualification are separate requirements.

The background example is also executed verbatim against the installed App backend and planner. Owned native doubles cover master/auxiliary scope, stale previews, no-op, partial removal and interruption. The backend itself is not replaced. These checks still do not exercise FontLab's compiled object model, native history, saved files, rendered documentation or publication.