Python API

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 in the Glyphs documentation.

`GSFont.lt_document_state: DocumentState`

Returns the state of the font’s document which describes whether Light Table can be used with the font.

Example

import lighttable as lt
if Font.lt_document_state == lt.DocumentState.OPERATIONAL:
    # the font is stored in a working Git repository

`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 are 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.

Never modify the font object of the version, only read data from it. Create a copy of the font and modify that, if needed.

Example

def some_callback(version, error):
    if version is not None:
        # inspect `version.font`, but do not modify
        font = version.font.copy()
        # inspect and modify `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

`GSFont.lt_glyph_changeset_of_record(record)`

Returns the set of glyphs that were added or modified in the given record.

Parameters

record:: Record

Returns

Dict[GSGlyph, List[GSLayer]] | None

Each glyph maps to a list of the layers that were added or modified in the record. A layer list is empty if the glyph was modified in ways that do not affect the layers, like changing the glyph color label. An empty dictionary is returned if no glyph was added or modified in the record.

Glyphs and layers that were deleted in the record are not included, as they no longer exist in the current GSFont.

Light Table creates and caches an index of the glyph changesets in the background as soon as a font document is opened. This method returns None if the changeset of the given record has not yet been indexed.

None is also returned if the file type of the document is not supported. Currently, .glyphspackage, .glyphs, and .ufo files are supported.

Example

if changeset := Font.lt_glyph_changeset_of_record(some_record):
    for glyph, layers in changeset.items():
        print(glyph.name, layers)
else:
    print("changeset not yet indexed or unsupported document file type")

GSGlyph

Learn more about the GSGlyph type in the Glyphs documentation.

`GSGlyph.lt_status: ObjectStatus`

Returns the status of the glyph as compared to the latest document version.

Example

import lighttable as lt
if Layer.parent.lt_status == lt.ObjectStatus.ADDED:
    # glyph has been added since the latest version

`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 in the Glyphs documentation.

`GSLayer.lt_status: ObjectStatus`

Returns the status of the layer as compared to the latest document version.

Example

import lighttable as lt
if Layer.lt_status == lt.ObjectStatus.ADDED:
    # layer has been added since the latest version

`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

DocumentState

The document state of a font describes whether Light Table can be used with the font. You can get the document state from a font using GSFont.lt_document_state.

`DocumentState.UNKNOWN`

The document state is unknown. This is the case just after the document was opened and Light Table did not yet have time to evaluate the document state.

`DocumentState.NO_FILE`

The document has not yet been saved to a file.

`DocumentState.NO_REPOSITORY`

The file of the document is not located in a Git repository.

`DocumentState.ERROR`

An error occurred when interacting with the Git repository.

`DocumentState.OPERATIONAL`

The document is saved to a file which is placed in a working Git repository. Light Table can be used to interact with the font.

ObjectStatus

The status of a glyph or layer as compared to the latest document version. You can get the status using either GSGlyph.lt_status or GSLayer.lt_status.

`ObjectStatus.UNKNOWN`

The object status is unknown. This is the case when the document is not part of a Git repository or if there was an error assessing the object status. The status is also unknown shortly after opening a document as Light Table is still gathering information about the latest document version.

`ObjectStatus.UNMODIFIED`

The object did not change since the latest document version.

`ObjectStatus.ADDED`

The object has been added since the latest document version.

`ObjectStatus.MODIFED`

The object has changed since the latest document version.

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.

GSFont.lt_document_state: DocumentState

GSFont.lt_selected_version: Version | None

GSFont.lt_available_records: List[Record] | None

GSFont.lt_load_version(record, callback)

GSFont.lt_glyph_changeset_of_record(record)

GSGlyph.lt_status: ObjectStatus

GSGlyph.lt_restoration_info: RestorationInfo | None

GSLayer.lt_status: ObjectStatus

GSLayer.lt_restoration_info: RestorationInfo | None

DocumentState.UNKNOWN

DocumentState.NO_FILE

DocumentState.NO_REPOSITORY

DocumentState.ERROR

DocumentState.OPERATIONAL

ObjectStatus.UNKNOWN

ObjectStatus.UNMODIFIED

ObjectStatus.ADDED

ObjectStatus.MODIFED

Version.font: GSFont

Version.record: Record

Record.commit: Commit

Record.filepath: str

Commit.id: str

Commit.summary: str

Commit.author: Signature

Commit.committer: Signature

Signature.name: str

Signature.email_address: str

Signature.datetime: datetime

RestorationInfo.base_layer: GSLayer

RestorationInfo.base_glyph: GSGlyph

RestorationInfo.base_font: GSFont

RestorationInfo.restoration_layer: GSLayer

RestorationInfo.restoration_glyph: GSGlyph

RestorationInfo.restoration_font: GSFont

RestorationInfo.restore_glyph_as_replacement(component_integration_plan=None) RestorationInfo.restore_glyph_as_alternative(component_integration_plan=None)

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)

ComponentIntegrationPlan(strategies, fallback)

ComponentIntegrationStrategy.USE_BASE_COMPONENT_GLYPH

ComponentIntegrationStrategy.INTEGRATE_COMPONENT_GLYPH

ComponentIntegrationStrategy.INTEGRATE_AS_PATHS

`GSFont.lt_document_state: DocumentState`

`GSFont.lt_selected_version: Version | None`

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

`GSFont.lt_load_version(record, callback)`

`GSFont.lt_glyph_changeset_of_record(record)`

`GSGlyph.lt_status: ObjectStatus`

`GSGlyph.lt_restoration_info: RestorationInfo | None`

`GSLayer.lt_status: ObjectStatus`

`GSLayer.lt_restoration_info: RestorationInfo | None`

`DocumentState.UNKNOWN`

`DocumentState.NO_FILE`

`DocumentState.NO_REPOSITORY`

`DocumentState.ERROR`

`DocumentState.OPERATIONAL`

`ObjectStatus.UNKNOWN`

`ObjectStatus.UNMODIFIED`

`ObjectStatus.ADDED`

`ObjectStatus.MODIFED`

`Version.font: GSFont`

`Version.record: Record`

`Record.commit: Commit`

`Record.filepath: str`

`Commit.id: str`

`Commit.summary: str`

`Commit.author: Signature`

`Commit.committer: Signature`

`Signature.name: str`

`Signature.email_address: str`

`Signature.datetime: datetime`

`RestorationInfo.base_layer: GSLayer`

`RestorationInfo.base_glyph: GSGlyph`

`RestorationInfo.base_font: GSFont`

`RestorationInfo.restoration_layer: GSLayer`

`RestorationInfo.restoration_glyph: GSGlyph`

`RestorationInfo.restoration_font: GSFont`

`RestorationInfo.restore_glyph_as_replacement(component_integration_plan=None)`

`RestorationInfo.restore_glyph_as_alternative(component_integration_plan=None)`

`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)`

`ComponentIntegrationPlan(strategies, fallback)`

`ComponentIntegrationStrategy.USE_BASE_COMPONENT_GLYPH`

`ComponentIntegrationStrategy.INTEGRATE_COMPONENT_GLYPH`

`ComponentIntegrationStrategy.INTEGRATE_AS_PATHS`