music21.musicxml.helpers

Functions

music21.musicxml.helpers.dump(obj)[source]

wrapper around xml.etree.ElementTree that prints a string in every case and indents tags and sorts attributes. (Prints, does not return)

>>> from music21.musicxml.helpers import dump
>>> from xml.etree.ElementTree import Element
>>> e = Element('accidental')

>>> dump(e)
<accidental />

>>> e.text = '∆'
>>> e.text == '∆'
True
>>> dump(e)
<accidental>∆</accidental>
music21.musicxml.helpers.dumpString(obj, *, noCopy=False) → str[source]

wrapper around xml.etree.ElementTree that returns a string in every case and indents tags and sorts attributes.

>>> from music21.musicxml.m21ToXml import Element
>>> from music21.musicxml.helpers import dumpString
>>> e = Element('accidental')

>>> dumpString(e)
'<accidental />'

>>> e.text = '∆'
>>> e.text == '∆'
True
>>> dumpString(e)
'<accidental>∆</accidental>'
music21.musicxml.helpers.indent(elem, level=0)[source]

helper method, indent an element in place:

music21.musicxml.helpers.insertAfterElements(root, insert, tagList=None)[source]

Insert element insert into element root directly after the last instance of any child tag given in tagList. Insert at the beginning if tagList is None or no instance is found.

>>> from xml.etree.ElementTree import fromstring as EL
>>> from music21.musicxml.helpers import insertAfterElements, dump
>>> root = EL('<note><grace /><voice>1</voice></note>')
>>> insert = EL('<unpitched/>')

>>> insertAfterElements(root, insert, tagList=['grace'])
>>> dump(root)
<note>
    <grace />
    <unpitched />
    <voice>1</voice>
</note>

Insert at the beginning when nothing in tagList matches:

>>> insert2 = EL('<foo/>')
>>> insertAfterElements(root, insert2, tagList=['bar'])
>>> dump(root)
<note>
    <foo />
    <grace />
    <unpitched />
    <voice>1</voice>
</note>
music21.musicxml.helpers.insertBeforeElements(root, insert, tagList=None)[source]

Insert element insert into element root at the earliest position of any instance of a child tag given in tagList. Append the element if tagList is None.

>>> from xml.etree.ElementTree import fromstring as EL
>>> from music21.musicxml.helpers import insertBeforeElements, dump
>>> root = EL('<clef><sign>G</sign><line>4</line></clef>')
>>> insert = EL('<foo/>')

>>> insertBeforeElements(root, insert, tagList=['line'])
>>> dump(root)
<clef>
    <sign>G</sign>
    <foo />
    <line>4</line>
</clef>

Now insert another element at the end by not specifying a tag list:

>>> insert2 = EL('<bar/>')
>>> insertBeforeElements(root, insert2)
>>> dump(root)
<clef>
    <sign>G</sign>
    <foo />
    <line>4</line>
    <bar />
</clef>
music21.musicxml.helpers.isFullMeasureRest(r: music21.note.Rest) → bool[source]
music21.musicxml.helpers.measureNumberComesBefore(mNum1: str, mNum2: str) → bool[source]

Determine whether measureNumber1 strictly precedes measureNumber2 given that they could involve suffixes. Equal values return False.

>>> from music21.musicxml.helpers import measureNumberComesBefore
>>> measureNumberComesBefore('23', '24')
True
>>> measureNumberComesBefore('23', '23')
False
>>> measureNumberComesBefore('23', '23a')
True
>>> measureNumberComesBefore('23a', '23b')
True
>>> measureNumberComesBefore('23b', '23a')
False
>>> measureNumberComesBefore('23b', '24a')
True
>>> measureNumberComesBefore('23b', '23b')
False
music21.musicxml.helpers.setM21AttributeFromAttribute(m21El: t.Any, xmlEl: ET.Element, xmlAttributeName: str, attributeName: str | None = None, transform: Callable[[str], t.Any] | None = None) → None[source]

If xmlEl has at least one element of tag==tag with some text. If it does, set the attribute either with the same name (with “foo-bar” changed to “fooBar”) or with attributeName to the text contents.

Pass a function or lambda function as transform to transform the value before setting it

>>> from xml.etree.ElementTree import fromstring as EL
>>> e = EL('<page-layout new-page="yes" page-number="4" />')

>>> setb = musicxml.helpers.setM21AttributeFromAttribute
>>> pl = layout.PageLayout()
>>> setb(pl, e, 'page-number')
>>> pl.pageNumber
'4'

>>> setb(pl, e, 'new-page', 'isNew')
>>> pl.isNew
'yes'

Transform the pageNumber value to an int.

>>> setb(pl, e, 'page-number', transform=int)
>>> pl.pageNumber
4

More complex:

>>> convBool = musicxml.xmlObjects.yesNoToBoolean
>>> setb(pl, e, 'new-page', 'isNew', transform=convBool)
>>> pl.isNew
True
music21.musicxml.helpers.setXMLAttributeFromAttribute(m21El: t.Any, xmlEl: ET.Element, xmlAttributeName: str, attributeName: str | None = None, transform: Callable[[t.Any], t.Any] | None = None)[source]

If m21El has at least one element of tag==tag with some text. If it does, set the attribute either with the same name (with “foo-bar” changed to “fooBar”) or with attributeName to the text contents.

Pass a function or lambda function as transform to transform the value before setting it

>>> from xml.etree.ElementTree import fromstring as EL
>>> e = EL('<page-layout/>')

>>> setb = musicxml.helpers.setXMLAttributeFromAttribute
>>> pl = layout.PageLayout()
>>> pl.pageNumber = 4
>>> pl.isNew = True

>>> setb(pl, e, 'page-number')
>>> e.get('page-number')
'4'

>>> XB = musicxml.m21ToXml.XMLExporterBase()
>>> XB.dump(e)
<page-layout page-number="4" />

>>> setb(pl, e, 'new-page', 'isNew')
>>> e.get('new-page')
'True'

Transform the isNew value to ‘yes’.

>>> convBool = musicxml.xmlObjects.booleanToYesNo
>>> setb(pl, e, 'new-page', 'isNew', transform=convBool)
>>> e.get('new-page')
'yes'
music21.musicxml.helpers.synchronizeIdsToM21(element: ET.Element, m21Object: Music21Object)[source]

MusicXML 3.1 defines the id attribute (%optional-unique-id) on many elements which is perfect for setting as .id on a music21 element.

<fermata id=”hello”><id>bye</id></fermata>

>>> from xml.etree.ElementTree import fromstring as EL
>>> e = EL('<fermata id="fermata1"/>')
>>> f = expressions.Fermata()
>>> musicxml.helpers.synchronizeIdsToM21(e, f)
>>> f.id
'fermata1'

Does not change the id if the id is not specified:

>>> e = EL('<fermata />')
>>> f = expressions.Fermata()
>>> f.id = 'doNotOverwrite'
>>> musicxml.helpers.synchronizeIdsToM21(e, f)
>>> f.id
'doNotOverwrite'
music21.musicxml.helpers.synchronizeIdsToXML(element: ET.Element, m21Object: prebase.ProtoM21Object | None) → None[source]

MusicXML 3.1 defines the id attribute (entity: %optional-unique-id) on many elements which is perfect for getting from .id on a music21 element.

>>> from xml.etree.ElementTree import fromstring as EL
>>> e = EL('<fermata />')
>>> f = expressions.Fermata()
>>> f.id = 'fermata1'
>>> musicxml.helpers.synchronizeIdsToXML(e, f)
>>> e.get('id')
'fermata1'

Does not set attr: id if el.id is not valid or default:

>>> e = EL('<fermata />')
>>> f = expressions.Fermata()
>>> musicxml.helpers.synchronizeIdsToXML(e, f)
>>> e.get('id', None) is None
True
>>> f.id = '123456'  # invalid for MusicXML id
>>> musicxml.helpers.synchronizeIdsToXML(e, f)
>>> e.get('id', None) is None
True

None can be passed in instead of a m21object.

>>> e = EL('<fermata />')
>>> musicxml.helpers.synchronizeIdsToXML(e, None)
>>> e.get('id', 'no idea')
'no idea'