nCoda Lychee Docs

Workflow Steps

Functions to combine as “steps” in a workflow action.


This module is intended for internal Lychee use only, so the API may change without notice. If you wish to use this module outside Lychee, please contact us to discuss the best way.

The module defines several “steps,” which follow a determinate order but are not all mandatory:

  1. inbound conversion
  2. inbound views
  3. document
  4. VCS
  5. outbound views
  6. outbound conversion

Also note that the steps need not necessarily happen in order, sequentially, or only once per Lychee “action.” For example, the VCS step can happen simultaneously with most of the outbound views/conversion steps. The views/conversion steps themselves are likely to happen several times, possibly simultaneously, depending on which outbound formats are registered.

lychee.workflow.steps.do_document(session, converted, views_info)[source]

Run the “document” step.


A list of the pathnames in this Lychee-MEI document.

Return type:

list of str


This function is only partially implemented. At the moment, it simply replaces the active score with a new one containing only the just-converted <section>.

lychee.workflow.steps.do_inbound_conversion(session, dtype, document, user_settings=None)[source]

Run the “inbound conversion” step.


This function chooses an inbound converter then runs it. Resulting data is emitted from the converter with the CONVERSION_FINISH signal and not returned by this function. If an error occurs during conversion, this function emits the CONVERSION_ERROR signal with an error message, then the CONVERSION_FINISH signal with None.

lychee.workflow.steps.do_inbound_views(session, dtype, document, converted, views_info)[source]

Run the “inbound views” step.


This function chooses an inbound views-processor then runs it. Resulting data is emitted from the processor with the VIEWS_FINISH signal and not returned by this function. If an error occurs during processing, this function emits the VIEWS_ERROR signal with an error message, then the VIEWS_FINISH signal with None.

lychee.workflow.steps.do_outbound_steps(repo_dir, views_info, dtype, user_settings=None)[source]

Run the outbound veiws and conversion steps for a single outbound “dtype.”

  • repo_dir (str) – Absolute pathname to the repository directory.
  • views_info (str) – The @xml:id attribute of the smallest possible Lychee-MEI document portion that contains all the information required to be exported.
  • dtype (str) – The data type to use for outbound conversion, as specified in lychee.converters.OUTBOUND_CONVERTERS.
  • user_settings – A dictionary of user settings.

Post-conversion data as described below.

Return type:



lychee.exceptions.InvalidDataTypeError when there is no module available for outbound conversion to dtype.


lychee.exceptions.SectionNotFoundError when the <section> to send out is unavailable. For example, if the <score> has no <section> elements yet, no <section> element is currently selected, or rarely if the selected <section> has gone missing between the VCS step and this step.


ViewsError from _do_outbound_views() if there is a problem while processing the view.

The outbound steps are designed to be run in parallel—whether or not they are. That’s why all the parameter types are easily serializable, control is not given up between the views and conversion steps, and the result is returned rather than provided with a signal.

Loading From Save Directory

If the “dtype” is in the DTYPES_CAN_LOAD_FROM_SAVE_DIR constant, this function tries to load the data from there rather than converting. If the right file is not present, this function automatically falls back to converting.

Returned Data

This function returns the data required for the outbound CONVERSION_FINISHED signal. The actual return is a dictionary with three keys: dtype, document, and placement. The values are defined in that signal’s documentation.

lychee.workflow.steps.do_vcs(session, pathnames)[source]

Run the “VCS” step.



If the VCS step is disabled in the Session instance given as session, then the VCS step is skipped.


Clear any inbound converters that may be connected.


Clear any inbound views processors that may be connected.