nCoda Lychee Docs

Workflow and Action Management

Program Modules

The lychee.workflow module itself is empty. These submodules manage user sessions and run workflows.

Signals and Slots

Danger

The signals are intended for use by external applications, however their use in Lychee will change significantly in the near future—all of the existing signals should be considered deprecated.

At this time, we recommend against incorporating Lychee in external programs. Please follow task T113 for information on our progress in redesigning this important aspect of Lychee, including our predicted milestone for completion.

Lychee uses the signalslot library (link).

In the future, the Session Management infrastructure will provide the primary means of getting data into Lychee. Signals will be used to send data back to a user interface.

Signal Definitions

lychee.signals.ACTION_START = <signalslot.Signal: ACTION_START>

Danger

Deprecated since version 0.5.4: Use lychee.workflow.session.InteractiveSession.run_workflow, run_inbound, and run_outbound instead.

Emit this signal to start an “action” through Lychee.

Parameters:
lychee.signals.LOG_MESSAGE = <signalslot.Signal: LOG_MESSAGE>

Note

This signal will not be removed.

Connect to this signal to receive log messages from Lychee. DO NOT use this signal to emit log messages; instead, use one of the loggers in lychee.logs.

Parameters:
  • level (str) – The log level of the message (one of “debug”, “info”, or “critical”).
  • logger (str) – Name of the lychee.logs logger sending the message.
  • message (str) – The log message.
  • status (str) – Status of the logged event (one of “begin”, “comment”, “exception”, “end”, “warning”).
  • time (str) – Running time of the logged event as measured by Lychee’s loggers.

Inbound Step

Signals for the “inbound” step.

lychee.signals.inbound.CONVERSION_ERROR = <signalslot.Signal: inbound.CONVERSION_ERROR>

Danger

Deprecated since version 0.5.4: Will become part of CONVERSION_FINISHED, if it is retained.

Emitted when there’s an error during the in bound conversion step.

Parameters:msg (str) – A descriptive error message for the log file.
lychee.signals.inbound.CONVERSION_FINISH = <signalslot.Signal: inbound.CONVERSION_FINISH>

Danger

Deprecated since version 0.5.4: No replacement.

Emitted just before the inbound conversion finishes (i.e., emitting this signal is the last action of an inbound conversion module).

Parameters:converted (xml.etree.ElementTree.Element or xml.etree.ElementTree.ElementTree) – The inbound musical document, converted to Lychee-MEI format.
lychee.signals.inbound.CONVERSION_FINISHED = <signalslot.Signal: inbound.CONVERSION_FINISHED>

Warning

Deprecated since version 0.5.4: May be retained.

Emitted when the inbound conversion is finished, before any “views” information is processed.

lychee.signals.inbound.CONVERSION_START = <signalslot.Signal: inbound.CONVERSION_START>

Danger

Deprecated since version 0.5.4: No replacement.

Emitted when the inbound conversion will start (i.e., this signal is emitted to cause a converter module to start the conversion).

Parameters:document (object) – The inbound musical document. The required type is determined by each converter module individually.
lychee.signals.inbound.CONVERSION_STARTED = <signalslot.Signal: inbound.CONVERSION_STARTED>

Danger

Deprecated since version 0.5.4: No replacement.

Emitted as soon as the inbound conversion has started (i.e., as soon as the converter module has begun to process data).

lychee.signals.inbound.VIEWS_ERROR = <signalslot.Signal: inbound.VIEWS_ERROR>

Danger

Deprecated since version 0.5.4: Will become part of VIEWS_FINISHED, if it is retained.

Emitted by the inbound views processing module, or the module running the workflow, to indicate that an error has occurred while generating views information. The error may be recoverable, or may cause the entire views step to fail, but Lychee may be able to continue the workflow.

Parameters:msg (str) – A descriptive error message for the log file.
lychee.signals.inbound.VIEWS_FINISH = <signalslot.Signal: inbound.VIEWS_FINISH>

Danger

Deprecated since version 0.5.4: No replacement.

Emitted by the inbound views processing module to return views information to its caller.

lychee.signals.inbound.VIEWS_FINISHED = <signalslot.Signal: inbound.VIEWS_FINISHED>

Warning

Deprecated since version 0.5.4: May be retained.

Emitted after inbound views processing by the module running the workflow.

lychee.signals.inbound.VIEWS_START = <signalslot.Signal: inbound.VIEWS_START>

Danger

Deprecated since version 0.5.4: No replacement.

Emit this signal to start the inbound views processing step.

Parameters:
  • converted (lxml.etree.Element or lxml.etree.ElementTree) – The incoming (partial) document, already converted.
  • document (As required by the converter.) – The incoming (partial) document for conversion, as supplied to do_inbound_conversion().
  • session (lychee.workflow.session.InteractiveSession) – A session instance for the ongoing notation session.
  • views_info (str) – The views_info argument from the ACTION_START signal. This is interpreted as the Lychee-MEI @xml:id that should be used for converted. If omitted, assume converted is a new <section> in this document.

By default, this signal is not connected to a views-processing module so you must connect it to the proper function before you emit this signal. This is provided as a signal so that additional modules can be notified of the workflow progress.

For information on writing a views processing module, refer to the lychee.views module documentation.

lychee.signals.inbound.VIEWS_STARTED = <signalslot.Signal: inbound.VIEWS_STARTED>

Danger

Deprecated since version 0.5.4: No replacement.

Emitted by the inbound views processing module as soon as it gains control, thereby confirming that an inbound views processor was correctly chosen.

VCS Step

Signals for the “vcs” step.

Warning

These signals are deprecated. Refer to T110 for more information.

Note

The VCS step is disabled by default. Refer to the InteractiveSession documentation for more information.

lychee.signals.vcs.ADD = <signalslot.Signal: vcs.ADD>

This signal is emitted to cause files to be added to the VCS.

Parameters:
lychee.signals.vcs.COMMIT = <signalslot.Signal: vcs.COMMIT>

This signal is emitted to cause a new commit.

Parameters:
lychee.signals.vcs.ERROR = <signalslot.Signal: vcs.ERROR>

This signal is emitted when an error occurs during the “vcs” stage.

lychee.signals.vcs.FINISHED = <signalslot.Signal: vcs.FINISHED>

This signal is emitted by the WorkflowManager once it gains control flow after the “vcs” step has finished.

lychee.signals.vcs.INIT = <signalslot.Signal: vcs.INIT>

Emit this signal to initialize a repository.

Parameters:session (lychee.workflow.session.InteractiveSession) – A session instance from which to use repository information.
Raises:RepositoryError when the repository could not be initialized.

Note

This signal is emitted before every ADD and COMMIT, so VCS implementation modules (1) can and should use this signal to perform any initialization, rather than doing it on Lychee startup; and (2) must not cause any harm when this signal is emitted with a repository that is already initialized.

The listener for this signal may create a new, empty local repository, clone a remote repository, simply check that an existing repository is sound, or something else.

lychee.signals.vcs.START = <signalslot.Signal: vcs.START>

Emitted by the WorkflowManager to begin the “vcs” stage. This signal is not emitted when the VCS step is disabled.

Parameters:
  • pathnames (list of str) – A list of pathnames that were modified in the most recent write-to-disk.
  • session (lychee.workflow.session.InteractiveSession) – A session instance from which to use repository information.
lychee.signals.vcs.VCS_DISABLED = <signalslot.Signal: vcs.VCS_DISABLED>

Emitted when the VCS system has been disabled by configuration. This should be followed immediately by the FINISHED signal.

Outbound Step

Signals for the “outbound” step.

The structure of the steps module, which contains functions that run the workflow steps, is such that the outbound steps use many fewer signals than the inbound steps. This is a compromise taken to allow the parallel processing in the outbound steps (i.e., more than one outbound data format can be processed at once).

lychee.signals.outbound.CONVERSION_FINISHED = <signalslot.Signal: outbound.CONVERSION_FINISHED>

Note

This signal will not be removed.

Emitted when one of the registered data types has finished outbound processing.

Depending on the environmental factors, the function that emits this signals (lychee.workflow.steps.do_outbound_steps()) may either wait for all conversions to finish before emitting the CONVERSION_FINISHED signal, or may emit the signal at different times, as the conversions finish.

Parameters:
  • dtype (str) – The data type of the “document” argument (“abjad”, “lilypond”, or “mei”). Always in lowercase.
  • placement (object) – Information for the slot about which part of the document is being updated. Offered in a different format depending on the “dtype” of this call.
  • document (object) – The update (partial) document. The type depends on the value of “dtype.”
  • changeset (str) – If the VCS is disabled, this is an empty string. If the VCS is enabled, this is either the tag or the revision number and hash of the most recent changeset. If ACTION_START was emitted with an inbound change, this will always be 'tip' because this tag always points to the most recent changeset. Otherwise it will be the same as “parent” field in hg summary (like '8:713cbfbaffcc' for example).

Type of “Document” Parameter

  • If dtype is 'mei' then document should be an lxml.etree.Element.
lychee.signals.outbound.ERROR = <signalslot.Signal: outbound.ERROR>

Danger

Deprecated since version 0.5.4: This signal will be replaced by CONVERSION_FINISHED.

Emitted when there’s an error during the outbound step.

Parameters:msg (str) – A descriptive error message for the log file.
lychee.signals.outbound.REGISTER_FORMAT = <signalslot.Signal: outbound.REGISTER_FORMAT>

Danger

Deprecated since version 0.5.4: To be replaced by methods on InteractiveSession that are not yet implemented.

To request that Lychee produce output data in a given format, call this signal before calling ACTION_START.

Parameters:
  • dtype (str) – The data type to produce (‘abjad’, ‘lilypond’, ‘mei’, ‘verovio’).
  • who (str) – (Optional). A unique identifier for the component requesting a format.
  • outbound (bool) – (Optional). Whether to run an “outbound” step immediately.

The “outbound” argument causes the outbound step to run immediately, producing data for the whole MEI document. Use this if you do not want to wait for data until an action has been run.

The “who” argument helps Lychee determine how manu user interface components are expecting data in a given format. If three UI components call REGISTER_FORMAT with the same “dtype” argument, then one component sends the UNREGISTER_FORMAT signal for that “dtype,” the other two components will not receive new data. However, if each component registers with a unique “who” argument, Lychee will produce output for that “dtype” until all three components unregister.

Therefore, while it is not required to pass the “who” argument, and while there are some use cases where Lychee may not benefit from such disambiguation (namely “one-shot” mode) we do recommend that long-running applications use a “who” argument.

lychee.signals.outbound.STARTED = <signalslot.Signal: outbound.STARTED>

Danger

Deprecated since version 0.5.4: No replacement.

Emitted when outbound steps begin, before any of the views processing or conversion modules have begun processing, and only once for all registered outbound formats.

lychee.signals.outbound.UNREGISTER_FORMAT = <signalslot.Signal: outbound.UNREGISTER_FORMAT>

Danger

Deprecated since version 0.5.4: To be replaced by methods on InteractiveSession that are not yet implemented.

Tell Lychee that an interface component is no longer expecting output for a specific “dtype”.

Parameters:
  • dtype (str) – The data type to produce (‘abjad’, ‘lilypond’, ‘mei’, ‘verovio’).
  • who (str) – (Optional). A unique identifier for the component requesting a format.

Refer to the discussion above for REGISTER_FORMAT.