Light Table — Formkunft

The Light Table Python API allows you to use Light Table’s functionality from Glyphs macros and scripts. To use the API, import the lighttable module:

import lighttable

Light Table adds additional methods and properties to Glyphs objects such as GSFont and GSLayer. See the Glyphs Extensions section for details. Light Table’s own types are described in the Light Table Types part of the API documentation.

Glyphs Extensions

GSFont

Learn more about the GSFont type on the Glyphs documentation.

`GSFont.lt_selected_version: Version | None`

Returns the version that is currently selected in the Light Table palette, or None, if no version is selected.

Example

if version := Font.lt_selected_version:
    print(version.font)

`GSFont.lt_available_records: List[Record] | None`

Returns a list of the currently available records of the font. Records are wrapper objects around Git commits.

These are the same records that are also visible in the Light Table palette. When a document is opened, Light Table quickly fetches a small number of the most recent records. Once those are available, Light Table fetches the remaining records (with a limit in the thousands, which should be sufficient for most projects).

Note that a record is not a version, meaning that it does not contain a GSFont object. Use GSFont.lt_load_version to get the version for a record.

Returns None if the font is not part of a Git repository. Otherwise, if no records available, returns an empty list.

Example

if records := Font.lt_available_records:
    for record in records:
        print(record.commit.id)

`GSFont.lt_load_version(record, callback)`

Loads the version (containing a GSFont object) for the given record asynchronously.

Parameters

record:: Record
callback:: callable

Returns

bool

The callback function is called once the load has completed. It is passed two arguments: A version (Version) and an error (NSError). If the version was loaded successfully, the error is None, otherwise the version is None and the error object describes what went wrong.

If the method returns False, then the font is not part of a Git repository and the callback will not be called. Otherwise, True is returned and the callback will be called with either a version or an error.

Example

def some_callback(version, error):
    if version is not None:
        print(version.font)
    else:
        print(error)

if Font.lt_load_version(some_record, some_callback):
    # version is loading and some_callback will be called
else:
    # the font is not in a Git repository

GSGlyph

Learn more about the GSGlyph type on the Glyphs documentation.

`GSGlyph.lt_restoration_info: RestorationInfo | None`

Creates a restoration info object for the glyph.

Light Table tries to find the glyph that matches the given glyph most closely in the selected version. If a matching glyph is found, a restoration info object is created and returned.

If no version is currently selected, no match is found, or the info object cannot be created for some other reason, None is returned.

Example

if info := Layer.parent.lt_restoration_info:
    # inspect and restore glyph in `info` object

GSLayer

Learn more about the GSLayer type on the Glyphs documentation.

`GSLayer.lt_restoration_info: RestorationInfo | None`

Creates a restoration info object for the layer.

Light Table tries to find the layer that matches the given layer most closely in the selected version. If a matching layer is found, a restoration info object is created and returned.

If no version is currently selected, no match is found, or the info object cannot be created for some other reason, None is returned.

Example

if info := Layer.lt_restoration_info:
    # inspect and restore layer in `info` object

Light Table Types

Version

A version contains the GSFont object for a source file in a Git commit. You can get a version from GSFont.lt_selected_version or from GSFont.lt_load_version.

`Version.font: GSFont`

The font object of the version.

`Version.record: Record`

Metadata about the file and the commit of the version.

Record

A record is a wrapper of a Git commit with some additional metadata. You can get a record from a version or from GSFont.lt_available_records.

`Record.commit: Commit`

The Git commit of the record.

`Record.filepath: str`

The file path for the source file of the font. The path is relative to the Git repository working tree. For example, "Source/Font.glyphspackage" instead of "/Users/Florian/Projects/Some Repository/Source/Font.glyphspackage".

Commit

A commit is the state of a Git repository at a specific moment in time. You can get a commit from a record.

`Commit.id: str`

The full commit hash (SHA-1 digest as base 16). For example: 06ce02bc02ca1887012c9485cfbea7b3315aeea1.

`Commit.summary: str`

The first line of the commit message.

`Commit.author: Signature`

Metadata about the commit author. This is typically the person that created the commit.

`Commit.committer: Signature`

Metadata about the commit committer. This is typically the same as the author. However, there are cases where the author and committer differ. For example, when a commit is merged by another person in a pull request, that person then becomes the committer.

Signature

A signature is metadata about either an author or committer of a Git commit. You can get a signature from a commit.

`Signature.name: str`

The name of the person or system that worked on the commit.

`Signature.email_address: str`

The email address of the person or system that worked on the commit. Might be an invalid email address.

`Signature.datetime: datetime`

The date and time of the signature.

RestorationInfo

A restoration info object is used to inspect and restore a glyph or layer from a previous version of the font. You can get a restoration info from GSGlyph.lt_restoration_info or GSLayer.lt_restoration_info.

`RestorationInfo.base_layer: GSLayer`

The layer on which lt_restoration_info was accessed, if the restoration info was created from a layer. If the restoration info was created from glyph instead, then the base layer is the first layer of that glyph.

`RestorationInfo.base_glyph: GSGlyph`

The glyph on which lt_restoration_info was accessed, if the restoration info was created from a glyph. If the restoration info was created from layer instead, then the base glyph is the glyph of that layer.

`RestorationInfo.base_font: GSFont`

The font of the base glyph.

`RestorationInfo.restoration_layer: GSLayer`

The layer that corresponds most closely to the base layer in the selected version at the time the restoration info was created.

`RestorationInfo.restoration_glyph: GSGlyph`

The glyph of the restoration layer.

`RestorationInfo.restoration_font: GSFont`

The font of the restoration glyph.

Restoration

The following methods restore the glyph or layer from the selected version into the current font.

`RestorationInfo.restore_glyph_as_replacement(component_integration_plan=None)`

`RestorationInfo.restore_glyph_as_alternative(component_integration_plan=None)`

These two methods restore the glyph from the selected version (the restoration glyph) into the current font (the base font).

Parameters

component_integration_plan:: ComponentIntegrationPlan | ComponentIntegrationStrategy | None

Returns

GSGlyph | None

restore_glyph_as_replacement first checks if the restoration glyph has the same name as the base glyph. If it does, the base glyph is renamed to an alternative name (for example, from A to A.001). Then, the restoration glyph is integrated into the base font.

restore_glyph_as_alternative does not modify the base glyph. Instead, the restoration glyph is renamed to an alternative name, if necessary, and then integrated into the base font.

Both functions create a copy of the glyph before integrating it. If the restoration is successful, this copy is returned. Otherwise, None is returned, and an error is logged.

`RestorationInfo.restore_layer_as_replacement(component_integration_plan=None)`

`RestorationInfo.restore_layer_as_backup_layer(component_integration_plan=None)`

`RestorationInfo.restore_layer_as_background(component_integration_plan=None)`

These three methods restore the layer from the selected version (the restoration layer) into the current font (the base font).

Parameters

component_integration_plan:: ComponentIntegrationPlan | ComponentIntegrationStrategy | None

Returns

GSLayer | None

restore_layer_as_replacement first converts the base layer to a backup layer. Then, the restoration layer is integrated into the base glyph, replacing the base layer.

restore_layer_as_backup_layer does not modify the base layer. Instead, the restoration layer is integrated into the base glyph as a backup layer.

restore_layer_as_background first deletes all shapes, anchors, and other elements from the background of the base layer. Then, the restoration layer is integrated as the background of the base layer.

All three functions create a copy of the layer before integrating it. If the restoration is successful, this copy is returned. Otherwise, None is returned, and an error is logged.

ComponentIntegrationPlan

A component integration plan defines how components are handled when restoring a glyph or layer into a different font. A plan uses integration strategies to describe how different components are integrated. See ComponentIntegrationStrategy for details.

`ComponentIntegrationPlan(strategies, fallback)`

Parameters

strategies:: Dict[str, ComponentIntegrationStrategy]
fallback:: ComponentIntegrationStrategy

Use the strategies parameter to define the integration strategy for specific components by name. Use the fallback parameter to define the integration strategy for all components not mentioned in the strategies dictionary.

The strategies dictionary can be empty ({}) in which case the fallback strategy is used for all components.

ComponentIntegrationStrategy

Component integration strategies define how components are handled when restoring a glyph or layer into a different font. There are three different strategies:

`ComponentIntegrationStrategy.USE_BASE_COMPONENT_GLYPH`

This strategy uses the current version of the glyph referenced by the component. The visual appearance of the component may differ if the component glyph has changed between the restoration font and the base font.

`ComponentIntegrationStrategy.INTEGRATE_COMPONENT_GLYPH`

This strategy restores the glyph referenced by the component (and also restores the glyphs of nested components, if any) from the selected version. This maintains the visual appearance of the component.

`ComponentIntegrationStrategy.INTEGRATE_AS_PATHS`

This strategy decomposes components to paths before the restoration which maintains the visual appearance of the component without adding any additional glyphs.