nCoda Lychee Docs

Document Metadata

Export MEI document metadata as JSON objects.

Warning

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.

Tip

We recommend that you use the converters indirectly. Refer to How to Use the Converters for more information.

Note

This is an outbound converter that does not emit signals directly. Refer to the lychee.signals.outbound module for more information.

Output Sample

Here is a sample of the data outputted from this module. This includes all possible values, but a real score is unlikely to do so.

{
    'headers': {
        'fileDesc': {
            'titleStmt': {
                'title': {
                    'main': 'This is the Main Title',
                    'subordinate': 'This is a subtitle',
                    'abbreviated': 'Main Title',
                    'alternative': 'Sample Document for You',
                }
            },
            'respStmt': [
                {
                    'id': 'p1234',
                    'full': 'Danceathon W. Smith',
                    'given': 'Danceathon',
                    'other': 'Wilfreda',
                    'family': 'Smith'
                },
                {
                    'id': 'p5678',
                    'full': '卓文萱',
                    'given': '文萱',
                    'other': 'Genie',
                    'family': '卓'
                },
            ],
            'arranger': {
                'full': 'Robert W. Smith'
            },
            'composer': {
                'id': 'p5678'
            },
            'author': { ... },
            'editor': { ... },
            'funder': { ... },
            'librettist': { ... },
            'lyricist': { ... },
            'sponsor': { ... }
            'pubStmt': {
                'unpub': 'This is an unpublished Lychee-MEI document.'
            }
        }
    },
    'sections': {
        'score_order': ['Sme-s-m-l-e1234567', 'Sme-s-m-l-e9029823'],
        'Sme-s-m-l-e1234567': {
            # things about the section with this "id"
            # NOTE: many more things will be exported later
            'label': 'A',
            # NOTE: in <staffGrp> only @n and @label are exported at the moment
            'staffGrp': [
                [{'n': '1', 'label': 'Violin I'}, {'n': '2', 'label': 'Violin II'}],
                {'n': '3', 'label': 'Viola'},
                [{'n': '4', 'label': 'Violoncello'}, {'n': '5', 'label': 'Contrabasso'}]
            ],
            'last_changeset': '34e92f3e7b17'
        },
        'Sme-s-m-l-e9029823': {
            'label': 'B',
            'staffGrp': [
                [{'n': '1', 'label': 'Right Hand'}, {'n': '2', 'label': 'Left Hand'}]
            ],
            'last_changeset': '01d9ce76929b'
        },
        'Sme-s-m-l-e9176572': {
            # NOTE: this section has nested sections
            'label': 'C',
            'last_changeset': '8e552c8c9c2f',
            'sections': {
            'score_order': ['Sme-s-m-l-e9029823', 'Sme-s-m-l-e1795937'],
                'Sme-s-m-l-e9029823': {
                    # NOTE: this section is linked to the one earlier with the same @xml:id
                    'label': 'a',
                    'staffGrp': [
                        [{'n': '1', 'label': 'Right Hand'}, {'n': '2', 'label': 'Left Hand'}]
                    ],
                    'last_changeset': '6074c498c731'
                },
                'Sme-s-m-l-e1795937': {
                    'label': 'b',
                    'staffGrp': [
                        [{'n': '1', 'label': 'Right Hand'}, {'n': '2', 'label': 'Left Hand'}]
                    ],
                    'last_changeset': 'fac50d50a9d3'
                }
            }
        }
    }
}

Notes about Header Information

Following Lychee-MEI, the different members of “title” may be one of the following: main, subordinate, abbreviated, alternative, translated, uniform. The “main” title will always be included, though it may be a placeholder.

The “roles” members (“arranger,” “composer,” and so on) refer to people. They may either use an “id” field to refer to a user described in the “respStmt” section, or they may contain names.

While the “pubStmt” section is virtually useless at the moment (because Lychee is not aware when one of its documents becomes published) it is included for completeness. It is required for a complete and valid MEI document.

Data from the “workDesc” and “revisionDesc” MEI elements will be added later, as peers to the “fileDesc” member, once they are implemented in Lychee.

Notes about Section Information

The nesting of <staffGrp> information reflects the nesting of the original elements. The top-level “staffGrp” member is a list; its elements are either a dict (with at least “n” and “label” members) or another list (which will likewise contain dicts and lists).

The 'last_changeset' member holds the changeset ID of the most recent changeset in which that <section> was modified.

lychee.converters.outbound.document.convert(repo_dir, **kwargs)[source]

Prepare document metadata in a useful format for clients.

Parameters:repo_dir (str) – The absolute pathname to the repository for which to produce data.
Returns:Information from the internal LMEI document in the format described above.
Return type:dict
Raises:lychee.exceptions.OutboundConversionError when there is a forseeable error.
lychee.converters.outbound.document.find_last_changeset(section_id, revlog)[source]

Find the hash of the most changeset in which a file was modified.

Parameters:
  • section_id (str) – The @xml:id of a <section>.
  • revlog (dict) – The outpuf of vcs.convert_helper()
Returns:

The hash of the that file’s last changeset.

Return type:

str

If the file is not found in a changeset, an empty string is returned.

lychee.converters.outbound.document.format_person(elem)[source]

Given a <persName> Element, prepare it for output as a dictionary.

Parameters:elem (lxml.etree._Element) – A <persName> element to convert.
Returns:The converted stuff or None.
Return type:dict or NoneType

This function also accepts None to help simplify functions that call it. The only time None is returned is when elem is None to begin with.

lychee.converters.outbound.document.format_title_stmt(elem)[source]

Given a <titleStmt> Element, prepare it for output as a dictionary.

Parameters:elem (lxml.etree._Element) – A <titleStmt> element to convert.
Returns:The converted stuff or None.
Return type:dict or NoneType

This function also accepts None to help simplify functions that call it. The only time None is returned is when elem is None to begin with.

lychee.converters.outbound.document.parse_staffGrp(sect_id, staffGrp)[source]
lychee.converters.outbound.document.prepare_headers(doc)[source]

Given a Document, prepare the “headers” portion of this module’s output.

Parameters:doc (lychee.document.Document) – The Document from which to extract MEI header data.
Returns:A dictionary with relevant header data.
Return type:dict

This function returns the “headers” dictionary described at the top of document_outbound.

lychee.converters.outbound.document.prepare_sections(doc, repo_dir)[source]

Given a Document, prepare the “sections” portion of this module’s output.

Parameters:
  • doc (lychee.document.Document) – The Document from which to extract MEI header data.
  • repo_dir (str) – The absolute pathname to the repository for which to produce data.
Returns:

A dictionary with relevant header data.

Return type:

dict

This function returns the “sections” dictionary described at the top of document_outbound.

lychee.converters.outbound.document.prepare_sections_inner(doc, section_ids, vcs_data)[source]

Helper function for prepare_sections() that can be called recursively when the hierarchy of <section> elements is not flat.

Parameters:
  • doc (lychee.document.Document) – The Document from which to extract MEI header data.
  • section_ids (list of str) – The @xml:id attributes of the <section> elements, in score order.
  • vcs_data (dict) – The output of lychee.converters.vcs.convert_helper().
Returns:

A dictionary with relevant header data.

Return type:

dict

Note

Do not call this function directly; use prepare_sections().