nCoda Lychee Docs

Session Management

Manage a document editing session through several workflow actions.

class lychee.workflow.session.InteractiveSession(*args, **kwargs)[source]

Manage the Lychee-MEI Document, Mercurial repository, and other related data for an interactive music notation session.

Version control is disabled by default, and must be enabled with the vcs parameter. Do note that most documentation referring to the Lychee “repository” refers to the directory in which the music document is stored, whether or not the directory is a VCS repository.

document

Get a Document for this session’s repository.

Returns:The Document for this session.
Return type:lychee.document.Document
Raises:RepositoryError as per set_repo_dir().

Do be aware that, if the repository directory is changed or unset, the Document returned by this method will no longer be valid—but it won’t know that.

Note

If no repository directory has been set, this method creates a new repository in a temporary directory.

get_repo_dir()[source]

Return the absolute pathname for the directory holding Lychee’s repository.

Returns:The repository pathname.
Return type:str

Note

If no repository pathname has been set, this function will initialize an empty repository in a temporary directory and return its path.

hug

Return the active mercurial-hug.Hug instance.

static make_save_path(repo_dir, sect_id, dtype)[source]

Makes the absolute pathname where s “text editor” file should be saved.

Parameters:
  • repo_dir (str) – Root directory of the Session’s LMEI document.
  • sect_id (str) – The @xml:id of the section data.
  • dtype (str) – Data type of the “doc” argument (e.g., “lilypond”). This should be a “dtype” recognized by run_workflow().
Returns:

Tuple with the directory name and full pathname for the file.

Return type:

str

Raises:

TypeError if one of the arguments is not a string.

Raises:

ValueError if we cannot make a valid filesystem path to save.

read_user_settings()[source]

Read from this repo’s user settings XML file.

registrar

Return the active Registrar instance.

run_inbound(dtype, doc, sect_id=None)[source]

Run the inbound (conversion and views), document, and (if enabled) VCS workflow steps.

Parameters:
  • dtype (str) – The format (data type) of the inbound musical document. This must correspond to the name of a converter module in lychee.converters.inbound.
  • doc (object) – The inbound musical document. The required type is determined by each converter module itself.
  • sect_id (str) – The Lychee-MEI @xml:id attribute of the <section> contained in the “doc” argument. If omitted, “converted” will become a new <section>.
Raises:

lychee.exceptions.InboundConversionError when the conversion or views processing steps fail.

run_outbound(views_info=None, revision=None)[source]

Run the outbound workflow steps (views and conversion).

Parameters:
  • views_info (str) – As per lychee.workflow.steps.do_outbound_steps()
  • revision (str) – Checkout a specific changeset before running the outbound steps. This may be a revision number, but we recommend using the changeset hash when possible. This argument is ignored when version control is not enabled.

You may request only (a portion of) a <section> for outbound conversion by providing the @xml:id attribute of that element. You may also request data from an arbitrary changeset that is by including the revision identifier as the revision argument.

For example:

>>> session.run_outbound()

This causes the most recent version of the full score to be converted for all registered outbound data types. On the other hand:

>>> session.run_outbound(views_info='Sme-s-m-l-e1182873')

This causes only the <section> with @xml:id="Sme-s-m-l-e1182873" to be sent for outbound conversion. And:

>>> session.run_outbound(revision='40:964b28acc4ee')

This will checkout changeset r40, output the full score, then checkout the most recent changeset again. Finally:

>>> session.run_outbound(views_info='Sme-s-m-l-e1182873', revision='40:964b28acc4ee')

This will checkout changeset r40, output only the <section> with @xml:id="Sme-s-m-l-e1182873", then checkout the most recent changeset.

run_workflow(dtype, doc, sect_id=None)[source]

Run a full Lychee workflow, including the inbound, document, VCS (if enabled), and outbund steps.

Parameters:
  • dtype (str) – The format (data type) of the inbound musical document. This must correspond to the name of a converter module in lychee.converters.inbound.
  • doc (object) – The inbound musical document. The required type is determined by each converter module itself.
  • sect_id (str) – The Lychee-MEI @xml:id attribute of the <section> contained in the “doc” argument. If omitted, “converted” will become a new <section>.

Emits the lychee.signals.outbound.CONVERSION_FINISHED signal on completion. May also cause a bunch of different error signals if there’s a problem.

save_text_editor(sect_id, dtype, doc)[source]

Save the contents of a text editor, in any format, without checking validity.

Parameters:
  • sect_id (str) – The @xml:id of the section data.
  • dtype (str) – Data type of the “doc” argument (e.g., “lilypond”). This should be a “dtype” recognized by run_workflow().
  • doc (str) – The text editor’s contents to save.
Returns:

Pathname of the newly saved file.

Return type:

str

Raises:

TypeError if one of the arguments is not a string.

Raises:

ValueError if we cannot make a valid filesystem path to save.

Raises:

IOError if the method cannot save for another reason.

set_repo_dir(path, run_outbound=False)[source]

Change the pathname to Lychee’s repository then optionally run registered outbound converters.

Parameters:
  • path (str) – The pathname of the directory of the repository. This should either be an absolute path or something that will become absolute with os.path.abspath().
  • run_outbound (bool) – Whether to run conversions for all registered outbound formats after setting the repository directory. Defaults to False.
Returns:

The absolute pathname to the repository directory.

Return type:

str

Raises:

RepositoryError when path exists and contains files but is not a Mercurial repository, or is a repository but cannot be written to.

Raises:

RepositoryError when path does not exist and cannot be created.

If path does not exist, it will be created.

If path is '' (an empty string) the repository will be initialized in a new temporary directory that should be automatically deleted when the InteractiveSession instance is garbage collected.

If VCS is enabled for this InteractiveSession, a hug.Hug instance will be created on the :prop:`hug` property.

Warning

If this InteractiveSession instance already has a repository in a temporary directory, it will be deleted before the new repository directory is set.

unset_repo_dir()[source]

Unset the repository directory, deleting the repository if it’s in a temporary directory, and do not set a new repository.

vcs_enabled

Return True if the VCS is enabled in this InteractiveSession.

write_user_settings(user_settings)[source]

Write to this repo’s user settings XML file.