rhH%SrSSKJr /SQrSSKJr SSKJr SSKrSSK J r SSK r SSK r SSK r SSKrSSKJr SSKrSS KJr SS KJr SS KJr SS KJr SS KJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJ r SSKJ!r! SSK"J#r#J$r$J%r%J&r&J'r'J(r(J)r)J*r*J+r+J,r,J-r-J.r. \R^"S5r0\"S/SQ5r1"SS\Rd5r3"SS\35r4/r5S\6S'\7S:XaSSKr\Rp"5 gg) a Classes and functions for creating and processing metadata associated with scores, works, and fragments, such as titles, movements, authors, publishers, and regions. The :class:`~music21.metadata.Metadata` object is the main public interface to metadata components. A Metadata object can be added to a Stream and used to set common score attributes, such as title and composer. A Metadata object found at offset zero can be accessed through a Stream's :attr:`~music21.stream.Stream.metadata` property. The following example creates a :class:`~music21.stream.Stream` object, adds a :class:`~music21.note.Note` object, and configures and adds the :attr:`~music21.metadata.Metadata.title` and :attr:`~music21.metadata.Metadata.composer` properties of a Metadata object. >>> s = stream.Score() >>> p = stream.Part() >>> m = stream.Measure() >>> m.append(note.Note()) >>> p.append(m) >>> s.append(p) >>> s.insert(0, metadata.Metadata()) >>> s.metadata.title = 'title' >>> s.metadata.composer = 'composer' >>> #_DOCS_SHOW s.show() .. image:: images/moduleMetadata-01.* :width: 600 A guide to the v8+ Dublin Core implementation: The class Metadata has been completely rewritten in music21 v8 to support significant new functionality. The previous Metadata implementation had a list of supported workIds, and also a list of standard contributor roles. More than one of each contributor role could exist, but only one of each workId. And while there was some support for custom contributor roles, there was no support for other custom metadata, only the specified list of workIds. In the v8 implementation, contributor roles are treated the same as other non-contributor metadata. Music21 includes a list of supported property terms, which are pulled from Dublin Core (namespace = 'dcterms'), MARC Relator codes (namespace = 'marcrel'), and Humdrum (namespace = 'humdrum'). Each property term is assigned a unique name (e.g. 'composer', 'alternativeTitle', etc.). Each metadata property can be specified by 'uniqueName' or by 'namespace:name'. For example: `md['composer']` and `md['marcrel:CMP']` are equivalent, as are `md['alternativeTitle']` and `md['dcterms:alternative']`. There can be more than one of any such item (not just contributors). And you can also have metadata items with custom names. For simple metadata items, like a single title, there is an easy way to get/set them: use an attribute-style get operation (e.g. `t = md.title`). This will always return a single string. If there is more than one item of that name, a summary string will be returned. To see the full list of metadata items in their native value type, use a dictionary-style get operation (e.g. `titles = md['title']`). If an item or list of items is set (whether attribute-style or dictionary-style), any existing items of that name are deleted. To add an item or list of items without deleting existing items, use the `md.add()` API. See the examples below: Set a title (overwrites any existing titles): >>> md = metadata.Metadata() >>> md.title = 'A Title' >>> md.title 'A Title' >>> md['title'] (,) Set two titles (overwrites any existing titles): >>> md['title'] = ['The Title', 'A Second Title'] >>> md['title'] (, ) >>> md.title 'The Title, A Second Title' Add a third title (leaves any existing titles in place): >>> md.add('title', 'Third Title, A') >>> md['title'] (, , ) >>> md.title 'The Title, A Second Title, A Third Title' You can also set/add/get free-form custom metadata items: >>> md.setCustom('modification description', 'added missing sharp in measure 27') >>> md.getCustom('modification description') (,) Adding another custom element for the same description creates a second entry. >>> md.addCustom('modification description', 'deleted redundant natural in measure 28') >>> md.getCustom('modification description') (, ) Metadata does not explicitly support client-specified namespaces, but by using getCustom/addCustom/setCustom, clients can set anything they want. For instance, to embed the old SoundTracker .MOD format's sample name, a .MOD file parser could use `md.addCustom('soundtracker:SampleName', 'Bassoon')`, and a .MOD file writer that understood 'soundtracker:' metadata could then write it back accurately to one of those files. Custom metadata (whether namespaced this way, or free form) can also be written to various other file formats without interpretation, as long as there is a place for it (e.g. in the '' tag in MusicXML). In music21 v8, primitives.Text has been updated to add `isTranslated` to keep track of whether the text has been translated, as well as an encoding scheme, that specifies which standard should be used to parse the string. See metadata/primitives.py for more information. ) annotations)Metadata RichMetadata AmbitusShort) namedtuple)IterableN) dataclass)overload)base)common) deprecated)defaults) environment) exceptions21)interval) properties)PropertyDescription)bundles)caching) primitives) Date DatePrimitive DateSingle DateRelative DateBetween DateSelectionText ContributorCreatorImprint Copyright ValueTypemetadatar semitonesdiatonic pitchLowest pitchHighestc^\rSrSrSrSrSUU4SjjrSVSjrSWSjrSXSjr SXSjr \ SYS j5r \ SZS j5r \ S[S j5rS\S jr\S]S j5r\S^Sj5r\S5r\R(S_Sj5rSSSSS.S`SjjrSrSaU4Sjjr\SbSj5r\ScSj5r\SdSj5rSeSjrSfSjrSgSjrShSjrSiSjSjjr\S5r\R(S_S j5r\S!5r\R(S_S"j5r\S#5r \ R(SkS$j5r \S%5r!\!R(S_S&j5r!\S'5r"\"R(S_S(j5r"\SlS)j5r#\#R(S_S*j5r#\SlS+j5r$\$R(S_S,j5r$\SlS-j5r%\%R(S_S.j5r%\SlS/j5r&\&R(S_S0j5r&\S15r'\'R(S_S2j5r'\S35r(\(R(S_S4j5r(\S55r)\)R(SkS6j5r)\S75r*\*R(S_S8j5r*\S95r+\+R(SkS:j5r+\S;5r,\,R(S_S<j5r,\SlS=j5r-\-R(S_S>j5r-\SlS?j5r.\.R(S_S@j5r.\SlSAj5r/\/R(S_SBj5r/\SC5r0\0R(S_SDj5r0\SlSEj5r1SZSFjr2SmSGjr3SnSHjr4SoSIjr5SpSJjr6\ SqSKj5r7\ SpSLj5r8\ SqSMj5r9\ SqSNj5r:\ SrSOj5r;SsSPjr\ SuSSj5r?STr@U=rA$)vra Metadata objects contain information about a work, including title, composer, dates, and other relevant information. Metadata objects can also cover a fragment of a Score such as individual parts or a range of measures. Metadata is a :class:`~music21.base.Music21Object` subclass, meaning that it can be positioned on a Stream by offset and have a :class:`~music21.duration.Duration`. In many cases, each Stream will have a single Metadata object at the zero-offset position. To get a simple string, use attribute-style access by unique name. Some workIds from music21 v7 have been renamed (e.g. 'date' has been renamed to 'dateCreated'). The old music21 v7 name in these cases is still supported when you use attribute-style access. >>> md = metadata.Metadata(title='Concerto in F') >>> md.title 'Concerto in F' Attribute access also works with three-letter workId abbreviations (these are grandfathered in from music21 v7; abbreviations have not been added for new-in-v8 metadata items): >>> md = metadata.Metadata(otl='Concerto in F') >>> md.otl 'Concerto in F' >>> md.title 'Concerto in F' It is also possible to set a list/tuple of values or get a tuple full of (richer-typed) values using dictionary-style access. >>> md = metadata.Metadata() >>> md['composer'] = ['Billy Strayhorn', 'Duke Ellington'] >>> md['composer'] (, ) >>> md.composer 'Billy Strayhorn and Duke Ellington' >>> md.contributors (, ) Here is the list of grandfathered v7 synonyms, which may disappear in a future version: >>> sorted(metadata.properties.ALL_MUSIC21_WORK_IDS) ['commission', 'date', 'dedication', 'volume'] And here are their new v8 standard unique names: >>> sorted(metadata.properties.MUSIC21_WORK_ID_TO_UNIQUE_NAME.values()) ['commissionedBy', 'dateCreated', 'dedicatedTo', 'volumeNumber'] ic >0n0nUR5H#upEU[R;aXSU'MXRU'M% [TU]"S0UD6 0UlUR5HupE[ XU5 M [R/US'g)Nsoftware) itemsrALL_LEGAL_ATTRIBUTESsuper__init__ _contentssetattrrr,)selfkeywordsm21BaseKeywords myKeywordsattrvalue __class__s S/home/james-whalen/.local/lib/python3.13/site-packages/music21/metadata/__init__.pyr1Metadata.__init__s,.') $>>+KDz666#(4 (-% , +?+57%++-KD D &.%--.Zc$URXSS9 g)u Adds a single item or multiple items with this name, leaving any existing items with this name in place. The name can be the item's uniqueName or 'namespace:name'. If it is not the uniqueName or namespaceName of one of the standard metadata properties, KeyError will be raised. >>> md = metadata.Metadata() >>> md.add('average duration', '180 minutes') Traceback (most recent call last): KeyError: "Name='average duration' is not a standard metadata name... Example of adding a composer and two titles: >>> md.add('composer', 'Houcine Slaoui') >>> md['composer'] (,) >>> md.add('title', metadata.Text('الماريكان', language='ar')) >>> md.add('title', metadata.Text('The Americans', language='en')) >>> titles = md['title'] >>> titles (, ) >>> titles[0].language 'ar' >>> titles[1].language 'en' If you do in fact want to overwrite any existing items with this name, you can use dictionary-style or attribute-style setting instead. See :meth:`~music21.metadata.Metadata.__setitem__` and :meth:`~music21.metadata.Metadata.__setattr__` for details. FisCustomN_addr4namer9s r;add Metadata.add sN $ .r=c"URUSS9$)a Gets any custom-named metadata items. The name can be free-form, or it can be a custom 'namespace:name'. getCustom always returns tuple[Text, ...], which may be empty. >>> md = metadata.Metadata() >>> md.setCustom('measure with 2nd ending', 'measure 128') >>> md.getCustom('measure with 2nd ending') (,) A second item can also be added. >>> md.addCustom('measure with 2nd ending', 'measure 192') >>> measures = md.getCustom('measure with 2nd ending') >>> isinstance(measures, tuple) True >>> len(measures) 2 >>> measures (, ) Tr?)_getr4rDs r; getCustomMetadata.getCustom2s2yyy--r=c$URXSS9 g)a  Adds any custom-named metadata items. The name can be free-form, or it can be a custom 'namespace:name'. addCustom takes a single object of any type, or a list/tuple of objects of any type. The object(s) will be converted to Text. >>> md = metadata.Metadata() >>> md.addCustom('measure with 2nd ending', 'measure 128') >>> md.getCustom('measure with 2nd ending') (,) An item list can also be added. >>> md.addCustom('measure with 2nd ending', ['measure 192', 'measure 256']) >>> measures = md.getCustom('measure with 2nd ending') >>> isinstance(measures, tuple) True >>> len(measures) 3 >>> measures (, , ) Tr?NrArCs r; addCustomMetadata.addCustomMs6 $ -r=c$URXSS9 g)a Sets any custom-named metadata items (deleting any existing such items). The name can be free-form, or it can be a custom 'namespace:name'. setCustom takes a single object of any type, or a list/tuple of objects of any type. The object(s) will be converted to Text. >>> md = metadata.Metadata() >>> md.setCustom('measure with 2nd ending', 'measure 128') >>> md.getCustom('measure with 2nd ending') (,) An item list can also be set. >>> md.setCustom('measure with 2nd ending', ['measure 192', 'measure 256']) >>> measures = md.getCustom('measure with 2nd ending') >>> isinstance(measures, tuple) True >>> len(measures) 2 >>> measures (, ) Tr?N)_setrCs r; setCustomMetadata.setCustomjs4 $ -r=cB[RRUS5$)a Translates a unique name to the associated standard property's namespace name (i.e. the property's name in the form 'namespace:name'). An example from the MARC Relators namespace: the namespace name of 'librettist' is 'marcrel:LBT'. >>> metadata.Metadata.uniqueNameToNamespaceName('librettist') 'marcrel:LBT' Returns None if no such associated standard property can be found. >>> metadata.Metadata.uniqueNameToNamespaceName('average duration') is None True An example from the Dublin Core namespace: the namespace name of 'alternativeTitle' is 'dcterms:alternative'. >>> metadata.Metadata.uniqueNameToNamespaceName('alternativeTitle') 'dcterms:alternative' N)rUNIQUE_NAME_TO_NAMESPACE_NAMEget) uniqueNames r;uniqueNameToNamespaceName"Metadata.uniqueNameToNamespaceNames077;;JMMr=cB[RRUS5$)aj Translates a standard property namespace name ('namespace:name') to that standard property's uniqueName. An example from the MARC Relators namespace: the unique name of 'marcrel:LBT' is 'librettist'. >>> metadata.Metadata.namespaceNameToUniqueName('marcrel:LBT') 'librettist' Returns None if no such standard property exists. >>> metadata.Metadata.namespaceNameToUniqueName('soundtracker:SampleName') is None True An example from the Dublin Core namespace: the unique name of 'dcterms:alternative' is 'alternativeTitle'. >>> metadata.Metadata.namespaceNameToUniqueName('dcterms:alternative') 'alternativeTitle' N)rNAMESPACE_NAME_TO_UNIQUE_NAMErU) namespaceNames r;namespaceNameToUniqueName"Metadata.namespaceNameToUniqueNames.77;;M4PPr=crU(dg[RRUS5nUcgUR$)a Determines if a unique name is associated with a standard contributor property. Returns False if no such associated standard contributor property can be found. We allow uniqueName == None, since None is a valid custom contributor role. Example: 'librettist' and 'otherContributor' are unique names of standard contributors. >>> metadata.Metadata.isContributorUniqueName('librettist') True >>> metadata.Metadata.isContributorUniqueName('otherContributor') True Example: 'alternativeTitle' is the unique name of a standard property, but it is not a contributor. >>> metadata.Metadata.isContributorUniqueName('alternativeTitle') False Example: 'average duration' is not the unique name of a standard property. >>> metadata.Metadata.isContributorUniqueName('average duration') False FNr#UNIQUE_NAME_TO_PROPERTY_DESCRIPTIONrU isContributorrVprops r;isContributorUniqueName Metadata.isContributorUniqueNames;8  : : > >z4 P  <!!!r=c`URU5(agURU5(agg)a Determines if name is either a 'namespace:name' or a 'uniqueName' associated with a standard property. Returns False if no such associated standard property can be found. >>> md = metadata.Metadata() >>> md.isStandardName('librettist') True 'marcrel:LBT' is the namespace name of 'librettist' >>> md.isStandardName('marcrel:LBT') True Some examples of non-standard (custom) names. >>> md.isStandardName('average duration') False >>> md.isStandardName('soundtracker:SampleName') False TF)_isStandardNamespaceName_isStandardUniqueNamerIs r;isStandardNameMetadata.isStandardNames/.  ( ( . .  % %d + +r=c$URS5$)a Returns a tuple of software names/versions. Returns an empty tuple if no software names/versions exist, but this is rare, since music21 adds its own version when initializing a Metadata object. >>> md = metadata.Metadata() >>> md.software ('music21 v...',) >>> md.add('software', 'Finale for Macintosh') >>> md.software ('music21 v...', 'Finale for Macintosh') >>> md['software'] (, ) Note that `.software` is an exception to the general rule that singular looking properties return a string. In fact, it is always plural and returns a tuple of strings. There is no singular version r,_getPluralAttributer4s r;r,Metadata.softwares0'' 33r=cr/nURSSSS9Hup#URU5 M [U5$)a Returns a tuple of all the Contributors found in the metadata. Returns an empty tuple if no Contributors exist. >>> md = metadata.Metadata() >>> md.composer = 'Richard Strauss' >>> md.librettist = 'Oscar Wilde' When we add something that is not a person, such as a title (whether through `.attribute` setting, `[item]` setting, or the :meth:`~music21.metadata.Metadata.add` method), it will not show up in the list of contributors. >>> md.add('title', 'Salome') >>> contribs = md.contributors >>> contribs (, ) Note that `.contributors` cannot be set. Add them separately via specific setters or the `.addContributor()` method. TFskipNonContributorsreturnPrimitives returnSorted)allappendtuple)r4output_contribs r; contributorsMetadata.contributorssF0%'(($(!%"#$JA MM' " $ V}r=c$URS5$)uU Returns the copyright as a str. Returns None if no copyright exists in the metadata. Returns all the copyright values in one string (with ', ' between them) if multiple copyrights exist in the metadata. Use md['copyright'] to get all the copyrights as Copyright objects. >>> md = metadata.Metadata() >>> md.copyright is None True >>> md.copyright = 'Copyright © 1896, Éditions Durand (expired)' >>> md.copyright 'Copyright © 1896, Éditions Durand (expired)' Using dictionary-style access, you can use either the uniqueName ('copyright') or the namespaceName ('dcterms:rights'). Here you can see how multiple copyrights are handled. >>> md.copyright = 'Copyright © 1984 All Rights Reserved' >>> md.copyright 'Copyright © 1984 All Rights Reserved' To add another copyright to the list, call md.add(). >>> md.add('copyright', 'Lyrics copyright © 1987 All Rights Reserved') md.copyright will now return both copyrights in one string >>> md.copyright 'Copyright © 1984 All Rights Reserved, Lyrics copyright © 1987 All Rights Reserved' md['copyright'] will return a tuple containing both Copyright objects. >>> md['copyright'] (, ) You can set str, Text, or Copyright values, and they will be converted to Copyright automatically if necessary. Note that 'dcterms:rights' is Dublin Core terminology for 'copyright', and can be used interchangeably with 'copyright' as a metadata dictionary-style key. >>> md.copyright = metadata.Text('Copyright © 1984') >>> md['copyright'] (,) >>> md.copyright = metadata.Copyright('Copyright © 1985', role='something') >>> md['dcterms:rights'] (,) copyright_getSingularAttributerns r;r~Metadata.copyright>sf))+66r=c[USU5 g)' For type checking only. Does not run. r~Nr3r4r9s r;r~rs k5)r=FTskipContributorsrrrsrtcz/nURR5HvupgURU5nU(a U(aM&U(a U(dM6UH:n U(aURXi45 MURU[ U 545 M< Mx U(a[ [ U55$[ U5$)u Returns the values stored in this metadata as a Tuple of (uniqueName, value) pairs. There are four bool options. The three that are new in v8 (skipNonContributors, returnPrimitives, returnSorted) are defaulted to behave like v7. If skipContributors is True, only non-contributor metadata will be returned. If skipNonContributors is True, only contributor metadata will be returned. If both of these are True, the returned Tuple will be empty. If returnPrimitives is False (default), values are all converted to str. If returnPrimitives is True, the values will retain their original ValueType (e.g. Text, Contributor, Copyright, etc.). If returnSorted is False, the returned Tuple will not be sorted by uniqueName (the default behavior is to sort). Note that we cannot properly type-hint the return value, since derived classes (such as RichMetadata) are allowed to return their own typed values that might not be str or ValueType. >>> c = corpus.parse('corelli/opus3no1/1grave') >>> c.metadata.all() (('arranger', 'Michael Scott Cuthbert'), ('composer', 'Arcangelo Corelli'), ('copyright', '© 2014, Creative Commons License (CC-BY)'), ('corpusFilePath', 'corelli/opus3no1/1grave.xml'), ('fileFormat', 'musicxml'), ('filePath', '...corpus/corelli/opus3no1/1grave.xml'), ('movementName', 'Sonata da Chiesa, No. I (opus 3, no. 1)'), ('software', 'Dolet...'), ('software', 'Finale...'), ('software', 'music21 v...')) >>> c.metadata.date = metadata.DateRelative('1689', 'onOrBefore') >>> c.metadata.localeOfComposition = 'Rome' >>> c.metadata.all(skipContributors=True) (('copyright', '© 2014, Creative Commons License (CC-BY)'), ('corpusFilePath', 'corelli/opus3no1/1grave.xml'), ('dateCreated', '1689/--/-- or earlier'), ('fileFormat', 'musicxml'), ('filePath', '...corpus/corelli/opus3no1/1grave.xml'), ('localeOfComposition', 'Rome'), ('movementName', 'Sonata da Chiesa, No. I (opus 3, no. 1)'), ('software', 'Dolet...'), ('software', 'Finale...'), ('software', 'music21 v...')) >>> c.metadata.all(returnPrimitives=True, returnSorted=False) (('software', ), ('software', ), ('software', ), ('movementName', <...Text Sonata da Chiesa, No. I (opus 3, no. 1)>), ('composer', ), ... ('dateCreated', ), ('localeOfComposition', )) >>> c.metadata.all(skipNonContributors=True, returnPrimitives=True, returnSorted=True) (('arranger', ), ('composer', )) )r2r._isContributorUniqueNamervstrrwsorted) r4rrrrsrtallOutrV valueListrar9s r;ru Metadata.all{sF+-&*^^%9%9%; !J"&"?"? "KMM"=##MM:"56MM:s5z":; #&< ( (V}r=c$URU5$)a[ Utility attribute access for all uniqueNames, grandfathered workIds, and grandfathered workId abbreviations. Many grandfathered workIds have explicit property definitions, so they won't end up here. These always return str or None. If there is more than one item for a particular name, we will try to summarize or list them all in one returned string. If name is not a valid attribute (uniqueName, grandfathered workId, or grandfathered workId abbreviation), then AttributeError is raised. >>> md = metadata.Metadata() An example of setting an attribute by uniqueName ('description'). >>> md.description = metadata.Text('A description set via uniqueName', language='en') An example of setting an attribute by grandfathered workId ('dedication') >>> md.dedication = 'A dedication set via grandfathered workId' An example of setting an attribute by grandfathered workId abbreviation ('otl') >>> md.otl = metadata.Text('A title set via grandfathered workId abbreviation') See how we can get all three attributes by uniqueName, even though two of them were set by other names. An example of getting (by uniqueName) an attribute that was set by uniqueName. >>> md.description 'A description set via uniqueName' An example of getting (by uniqueName) an attribute that was set by workId. The uniqueName for the grandfathered workId 'dedication' is 'dedicatedTo'. >>> md.dedicatedTo 'A dedication set via grandfathered workId' An example of getting (by uniqueName) an attribute that was set by abbreviation. The uniqueName for the grandfathered workId abbreviation 'otl' is 'title'. >>> md.title 'A title set via grandfathered workId abbreviation' An example of getting an attribute for which there are multiple values. >>> md.add('description', 'A description added via md.add()') >>> md.description 'A description set via uniqueName, A description added via md.add()' rrIs r; __getattr__Metadata.__getattr__sx))$//r=c>U[R;a?Ub<[U[5(a'[U[5(d[ SUSUS35eU[R ;a9[U[5(a[U[5(a[ SUS35eU[R;a#UR[RUUSS9 gU[R;a#UR[RUUSS9 gU[R;a#UR[RUUSS9 gUS;aUSS nURX2SS9 g[TU]1X5 g) as Attribute setter for all uniqueNames, grandfathered workIds, and grandfathered workId abbreviations, as well as the plural properties ('composers', 'librettists', 'lyricists') and the three new fileInfo properties. These can take a single value of any type (or, if appropriate, an iterable of any type of value), and will convert to the appropriate internal valueType. Nzmd.z+ can only be set to a single value; set md[z] to multiple values instead.z: can only be set to an iterable (e.g. a list, tuple, etc).Fr?) composers librettists lyricists) rALL_SINGLE_ATTRIBUTE_NAMES isinstancerr ValueErrorALL_PLURAL_ATTRIBUTE_NAMESrTrP!MUSIC21_WORK_ID_TO_NAMESPACE_NAME&MUSIC21_ABBREVIATION_TO_NAMESPACE_NAMEr0 __setattr__)r4rDr9rVr:s r;rMetadata.__setattr__s0 :88 8!"5(33&uc22 3tf-++/&0M"OPP :88 8eX..*UC2H2H $YZ :;; ; II88>    :?? ? II<>> md = metadata.Metadata() >>> md['average duration'] Traceback (most recent call last): KeyError: "Name='average duration' is not a standard metadata name... Example: setting, then getting (dictionary style) a single value. Note that it must be set as a single element list/tuple, and is always returned as a single element tuple. >>> md['description'] = [ ... metadata.Text('For the coronation of Catherine the Great.', language='en') ... ] >>> descs = md['description'] >>> descs (,) A second description can also be added. >>> md.add('description', 'In five sections, unique for its time.') >>> descs = md['description'] >>> isinstance(descs, tuple) True >>> len(descs) 2 >>> descs (, ) >>> descs[0].language 'en' >>> descs[1].language is None True metadata key must be strFr?)rrKeyErrorrHrs r;rrqs1T#s##56 6yyuy--r=cd[U[5(d [S5eURXSS9 g)a "Dictionary key" access for all standard uniqueNames and standard keys of the form 'namespace:name'. If key is not a standard uniqueName or standard 'namespace:name', then KeyError is raised. >>> md = metadata.Metadata() >>> md['average duration'] = ['180 minutes'] Traceback (most recent call last): KeyError: "Name='average duration' is not a standard metadata name... KeyError is also raised for non-str keys. >>> md[3] = ['180 minutes'] Traceback (most recent call last): KeyError: 'metadata key must be str' rFr?N)rrrrP)r4rr9s r; __setitem__Metadata.__setitem__s-(#s##56 6 #u -r=c[U[5(d[R"SU35eUR UR 5nUR X!SS9 g)a Assign a :class:`~music21.metadata.Contributor` object to this Metadata. >>> md = metadata.Metadata(title='Gaelic Symphony') >>> c = metadata.Contributor() >>> c.name = 'Beach, Amy' >>> c.role = 'composer' >>> md.addContributor(c) >>> md.composer 'Beach, Amy' Add maiden name as an alternative composer name: >>> c_alt = metadata.Contributor() >>> c_alt.name = 'Cheney, Amy Marcy' >>> c_alt.role = 'composer' >>> md.addContributor(c_alt) >>> md.composers ('Beach, Amy', 'Cheney, Amy Marcy') >>> md.search('Beach') (True, 'composer') >>> md.search('Cheney') (True, 'composer') Note that in this case, a "composerAlias" would probably be a more appropriate role than a second composer. All contributor roles are searchable, even if they are not standard roles: >>> dancer = metadata.Contributor() >>> dancer.names = ['Merce Cunningham', 'Martha Graham'] >>> dancer.role = 'interpretive dancer' >>> md.addContributor(dancer) >>> md.search('Cunningham') (True, 'interpretive dancer') z&supplied object is not a Contributor: Fr?N)rrrMetadataException_contributorRoleToUniqueNamerolerB)r4crVs r;addContributorMetadata.addContributorsSP![))008<> >;;AFFC  *% 0r=c/nURSSSS9H(up4URU:XdMURU5 M* [U5$)a Return a :class:`~music21.metadata.Contributor` if defined for a provided role. We allow role == None, since None is a valid custom contributor role. >>> md = metadata.Metadata(title='Violin Concerto') >>> c = metadata.Contributor() >>> c.name = 'Price, Florence' >>> c.role = 'composer' >>> md.addContributor(c) >>> cTuple = md.getContributorsByRole('composer') >>> cTuple (,) >>> cTuple[0].name 'Price, Florence' Some musicxml files have contributors with no role defined. To get these contributors, search for getContributorsByRole(None). N.B. upon output to MusicXML, music21 gives these contributors the generic role of "creator" >>> c2 = metadata.Contributor() >>> c2.name = 'Baron van Swieten' >>> md.add('otherContributor', c2) >>> noRoleTuple = md.getContributorsByRole(None) >>> len(noRoleTuple) 1 >>> noRoleTuple[0].role is None True >>> noRoleTuple[0].name 'Baron van Swieten' TFrq)rurrvrw)r4rresultryrzs r;getContributorsByRoleMetadata.getContributorsByRolesSH%'(($(!%"#$JA||t# g& $ V}r=c ^Sn/nTc UcU(dgTcUcU(aUR5unmUbUR5nSnURU5nU(aUHnURX45 M SnU(dUR SS9HupUR U 5(dMX)R5;aURX45 Sn O[RRU S5n U cMkX*R5;dMURX45 Sn OE OBUR SS9H/upUR U 5(dMURX45 M1 UR SSSS9HupUb^U RcUR5S:waM+U Rb.UR5U RR5;aMfU RH)n UR[U 5U R45 M+ M Sn[T[R5(aSnTnOT[T[5(a?[!U4SjS 55(a%Sn["R$"T["R&S 9nU(a@Ub=UH6up[U[5(dMUR)U5nUcM2SU4s $ g[+T5(aUHupT"U5(dMSU4s $ gUHup[U[5(a3[T5mTR5UR5;aSU4s $[U[,5(a'[/TS 5(aTR0U:XaSU4s $TU:XdMSU4s $ g![a GN>f=f) a/ Search one or all fields with a query, given either as a string or a regular expression match. >>> md = metadata.Metadata() >>> md.composer = 'Joplin, Scott' >>> md.title = 'Maple Leaf Rag' >>> md.search( ... 'joplin', ... field='composer', ... ) (True, 'composer') Note how the incomplete field name in the following example is still matched: >>> md.search( ... 'joplin', ... field='compos', ... ) (True, 'composer') These don't work (Richard didn't have the sense of rhythm to write this!) >>> md.search( ... 'Wagner', ... field='composer', ... ) (False, None) >>> md.search('Wagner') (False, None) >>> md.search('leaf') (True, 'title') >>> md.search( ... 'leaf', ... field='composer', ... ) (False, None) >>> md.search( ... 'leaf', ... field='title', ... ) (True, 'title') >>> md.search('leaf|entertainer') (True, 'title') >>> md.search('opl(.*)cott') (True, 'composer') * New in v4: use a keyword argument to search that field directly: >>> md.search(composer='Joplin') (True, 'composer') N)FNFT)rrq contributorc3,># UH oT;v M g7frr-).0 characterquerys r; "Metadata.search..sD)Y5()sz*.|+?{})flagssharps)popitemlowerrmrvAttributeErrorrurhrUNIQUE_NAME_TO_MUSIC21_WORK_IDrUrnamesrrtPatternanyrecompile IGNORECASEsearchcallableinthasattrr)r4rfieldr5reQueryvalueFieldPairsmatchvaluesr9rVworkIdryrzrDuseRegex innerField matchReSearchs ` r;rMetadata.searchswN#' =U]8 ]u}#++-LE5  KKMEE 11%8!''..~>"( E)-4)H%J55jAA  0 0 22'../BC $(2'P'P'T'T"D(F~  .'..? $5*I8&*XXtX%D! --j99#**E+>?&E(($(!%"#$JA <<'EKKM],J<<+ W\\EWEWEY0Y &&D 7<<'@A&$  eQYY ' 'HG$$D)DDDHjjbmm=N>c$URS5$)z Get or set the alternative title. >>> md = metadata.Metadata(popularTitle='Eroica') >>> md.alternativeTitle = 'Heroic Symphony' >>> md.alternativeTitle 'Heroic Symphony' alternativeTitlerrns r;rMetadata.alternativeTitles))*<==r=c[USU5 g)rrNrrs r;rrs (%0r=c$URS5$)av Get or set the composer of this work. Only the first composer can be got or set via properties. The composer attribute does not live in Metadata, but creates a :class:`~music21.metadata.Contributor` object in the .contributors object. >>> md = metadata.Metadata( ... title='...(Iphigenia)', ... ) >>> md.composer = 'Shorter, Wayne' You can set multiple composers by setting them dictionary-style or by using `md.add`. >>> md.add('composer', 'Spalding, Esperanza') The `Metadata.composer` attribute returns a summary string if there is more than one composer. >>> md.composer 'Shorter, Wayne and Spalding, Esperanza' composerrrns r;rMetadata.composers2))*55r=c[USU5 g)rrNrrs r;rr  j%(r=c$URS5$)a Get a tuple or set an iterable of strings of all composer roles. >>> md = metadata.Metadata(title='Yellow River Concerto') >>> md.composers = ['Xian Xinghai', 'Yin Chengzong'] (Yin Chengzong might be better called "Arranger" but this is for illustrative purposes) >>> md.composers ('Xian Xinghai', 'Yin Chengzong') Might as well add a third composer to the concerto committee? >>> contrib3 = metadata.Contributor(role='composer', name='Chu Wanghua') >>> md.add('composer', contrib3) >>> md.composers ('Xian Xinghai', 'Yin Chengzong', 'Chu Wanghua') If there are no composers, returns an empty list: >>> md = metadata.Metadata(title='Sentient Algorithmic Composition') >>> md.composers () rrlrns r;rMetadata.composerss6'' 33r=c[USU5 g)rrNrrs r;rr0rr=cUR$)za The `.date` property is deprecated in v8 and will be removed in v10. Use `dateCreated` instead. ) dateCreatedrns r;date Metadata.date7s r=c[USU5 g)rrNrrs r;rr?s fe$r=c$URS5$)a7 Get or set the creation date of this work as one of the following date objects: :class:`~music21.metadata.DateSingle`, :class:`~music21.metadata.DateRelative`, :class:`~music21.metadata.DateBetween`, :class:`~music21.metadata.DateSelection`, >>> md = metadata.Metadata( ... title='Third Symphony', ... popularTitle='Eroica', ... composer='Beethoven, Ludwig van', ... ) >>> md.dateCreated = '1805' >>> md.dateCreated '1805/--/--' >>> md.dateCreated = metadata.DateBetween(['1803/01/01', '1805/04/07']) >>> md.dateCreated '1803/01/01 to 1805/04/07' rrrns r;rMetadata.dateCreatedFs0))-88r=c[USU5 g)rrNrrs r;rr` mU+r=c$URS5$)z- Get or set the file format that was parsed. fileFormatrrns r;rMetadata.fileFormatg )),77r=c[USU5 g)rrNrrs r;rrn lE*r=c$URS5$)zu Get or set the file path that was parsed. This returns a string, not a Path object that is deliberate for caching. filePathrrns r;rMetadata.filePathus ))*55r=c[USU5 g)rrNrrs r;rr}rr=c$URS5$)z8 Get or set the path within the corpus that was parsed. corpusFilePathrrns r;rMetadata.corpusFilePaths ))*:;;r=c[USU5 g)rrNrrs r;rr &.r=c$URS5$)z- Get or set the file number that was parsed. fileNumberrrns r;rMetadata.fileNumberrr=c[USU5 g)rrNrrs r;rrrr=c$URS5$)z Get or set the locale of composition, or origin, of the work. >>> md = metadata.Metadata(popularTitle='Eroica') >>> md.localeOfComposition = 'Paris, France' >>> md.localeOfComposition 'Paris, France' localeOfCompositionrrns r;rMetadata.localeOfCompositions))*?@@r=c[USU5 g)rrNrrs r;rrs +U3r=c$URS5$)a[ Gets or sets a single librettist for this work: >>> md = metadata.Metadata(title='Death of Klinghoffer, The') >>> md.librettist = 'Goodman, Alice' >>> md.librettist 'Goodman, Alice' To preserve continuity with Humdrum, library catalogues, etc., librettists should be distinguished from lyricists etc., but sometimes the line is not 100% clear. librettistrrns r;r Metadata.librettists)),77r=c[USU5 g)rr Nrrs r;r r rr=c$URS5$)a Gets a tuple or sets an iterable of librettists for this work: >>> md = metadata.Metadata(title='Madama Butterfly') >>> md.librettists = ['Illica, Luigi', 'Giacosa, Giuseppe'] >>> md.librettists ('Illica, Luigi', 'Giacosa, Giuseppe') Should be distinguished from lyricists etc. r rlrns r;rMetadata.librettistss'' 55r=c[USU5 g)rrNrrs r;rr rr=c$URS5$)a Gets or sets a single lyricist for this work: >>> md = metadata.Metadata(title='Girlfriend') >>> md.lyricist = 'Keys, Alicia' To preserve continuity with Humdrum, library catalogues, etc., lyricists should be distinguished from librettists etc., but sometimes the line is not 100% clear: >>> md = metadata.Metadata(title='West Side Story') >>> md.lyricist = 'Sondheim, Stephen' >>> md.lyricist 'Sondheim, Stephen' lyricistrrns r;rMetadata.lyricists"))*55r=c[USU5 g)rrNrrs r;rrrr=c$URS5$)a7 Gets a tuple or sets an iterable of lyricists for this work: >>> md = metadata.Metadata(title='Rumors') >>> md.lyricists = ['Buckingham, Lindsey', 'McVie, Christine', 'Nicks, Stevie'] >>> md.lyricists ('Buckingham, Lindsey', 'McVie, Christine', 'Nicks, Stevie') Should be distinguished from librettists etc. rrlrns r;rMetadata.lyricistss'' 33r=c[USU5 g)rrNrrs r;rrrr=c$URS5$)a= Get or set the movement title. >>> md = metadata.Metadata() >>> md.movementName = 'Vivace' >>> md.movementName 'Vivace' Note that a number of pieces from various MusicXML datasets have the piece title as the movement title. For instance, the Bach Chorales, since they are technically movements of larger cantatas. movementNamerrns r;rMetadata.movementNames)).99r=c[USU5 g)rrNrrs r;rrs ne,r=c$URS5$)z Get or set the movement number as a string (or None) >>> md = metadata.Metadata(title='Ode to Joy') >>> md.movementNumber = 4 Note that movement numbers are always returned as strings! This may change in the future. >>> md.movementNumber '4' movementNumberrrns r;rMetadata.movementNumber%s))*:;;r=c[USU5 g)rrNrrs r;rr5rr=c$URS5$)ax Get or set the number of the work within a collection of pieces, as a string. (for instance, the number within a collection of ABC files) >>> md = metadata.Metadata() >>> md.number = '4' Note that numbers are always returned as strings! This may change in the future. >>> md.number '4' However, it is acceptable to set it as an int: >>> md.number = 2 >>> md.number '2' numberrrns r;rMetadata.number<s*))(33r=c[USU5 g)rrNrrs r;rr Ss h&r=c$URS5$)a Get or set the opus number. >>> md = metadata.Metadata() >>> md.opusNumber = 56 Note that opusNumbers are always returned as strings! This may change in the future, however, it is less likely to change than `.number` or `.movementNumber` since Opus numbers such as `18a` are common. >>> md.opusNumber '56' There is no enforcement that only numbers actually called "opus" are used, and it could be used for other catalogue numbers. >>> md.opusNumber = 'K.622' opusNumberrrns r;r#Metadata.opusNumberZs*)),77r=c[USU5 g)rr#Nrrs r;r#r$qrr=c$URS5$)z Get the title of the work. >>> md = metadata.Metadata(title='Third Symphony') >>> md.title 'Third Symphony' >>> md = metadata.Metadata(popularTitle='Eroica') >>> md.title is None True titlerrns r;r'Metadata.titlexs))'22r=c[USU5 g)rr'Nrrs r;r'r(s gu%r=ctSnUH0nUR[RU5nU(dM.Us $ g)aE Get the title of the work, or the next-matched title string available from a related parameter fields. >>> md = metadata.Metadata(title='Third Symphony') >>> md.bestTitle 'Third Symphony' >>> md = metadata.Metadata(popularTitle='Eroica') >>> md.bestTitle 'Eroica' >>> md = metadata.Metadata( ... title='Third Symphony', ... popularTitle='Eroica', ... ) >>> md.bestTitle 'Third Symphony' >>> md.popularTitle 'Eroica' >>> md.otp 'Eroica' bestTitle cannot be set: >>> md.bestTitle = 'Bonaparte' Traceback (most recent call last): AttributeError: ...'bestTitle'... )r' popularTitlerrN)_getStringValueByNamespaceNamerrT)r4searchIdrV titleSummarys r; bestTitleMetadata.bestTitlesFH  #J%)%H%H88D&L|## #r=cVU[R;agURUSS9nU(dgURU5(am[ U5S:Xa[ US5$[ U5S:Xa [ US5S-[ US5-$[ US5S[ U5S- S3-$UR U5(aLS n[U5H9upE[U[5(deUS:aUS - nX5R5- nM; U$S RS U55$) a Gets a single str value (a summary if necessary) for a supported 'namespace:name'. >>> md = metadata.Metadata() >>> md['title'] = ['The Title', 'A Second Title'] >>> md._getStringValueByNamespaceName('dcterms:title') 'The Title, A Second Title' Returns None (rather than raising KeyError) if namespaceName is not a supported 'namespace:name'. >>> md.setCustom('average duration', '180 minutes') >>> md._getStringValueByNamespaceName('average duration') is None True Returns None if the namespaceName is supported, but no such metadata item exists. >>> md._getStringValueByNamespaceName('dcterms:alternative') is None True Performs article normalization on metadata properties that are declared as needing it (generally, title-like properties). >>> md['alternativeTitle'] = ['Alternative Title, The', 'Second Alternative Title, A'] >>> md._getStringValueByNamespaceName('dcterms:alternative') 'The Alternative Title, A Second Alternative Title' NFr?rz and z othersz, c38# UHn[U5v M g7frrrr9s r;r:Metadata._getStringValueByNamespaceName..s8U) rALL_NAMESPACE_NAMESrH_isContributorNamespaceNamelenr'_namespaceNameNeedsArticleNormalization enumeraterrgetNormalizedArticlejoin)r4r[rrxir9s r;r,'Metadata._getStringValueByNamespaceNames <  > > >(, -% (P  + +M : :6{a6!9~%6{a6!9~/#fQi.@@vay>eCK!O+>> md = metadata.Metadata() >>> md['title'] = ['The Title', 'A Second Title'] >>> md._getStringValuesByNamespaceName('dcterms:title') ('The Title', 'A Second Title') Returns an empty tuple (rather than raising KeyError) if namespaceName is not a supported 'namespace:name'. >>> md.setCustom('average duration', '180 minutes') >>> md._getStringValuesByNamespaceName('average duration') () Returns an empty tuple if the namespaceName is supported, but no such metadata item exists. >>> md._getStringValuesByNamespaceName('dcterms:alternative') () Performs article normalization on metadata properties that are declared as needing it (generally, title-like properties). >>> md['alternativeTitle'] = ['Alternative Title, The', 'Second Alternative Title, A'] >>> md._getStringValuesByNamespaceName('dcterms:alternative') ('The Alternative Title', 'A Second Alternative Title') Fr?c38# UHn[U5v M g7frr6r7s r;r;Metadata._getStringValuesByNamespaceName..&s4VESZZVr9) rr:rwrHr=rrrvr?)r4r[rrxr9s r;_getStringValuesByNamespaceName(Metadata._getStringValuesByNamespaceNames:  > > >7N(, -% (P7N  7 7 F F "F!%.... e88:; = 4V444r=cbU[R;a"UR[RU5$U[R;a"UR[RU5$U[R;a"UR[RU5$[ SU35e)a This does what __getattr__ would do if we supported plural attributeNames (but it takes singular attributeNames, of course). It returns a tuple of strings (perhaps empty) for supported uniqueNames, grandfathered workIds, and grandfathered workId abbrevations. It is used in search, as well as in the various plural properties, such as md.composers, etc. >>> md = metadata.Metadata() >>> md['dedicatedTo'] = ('The First Dedicatee', 'A Second Dedicatee') Example: _getPluralAttribute by uniqueName >>> md._getPluralAttribute('dedicatedTo') ('The First Dedicatee', 'A Second Dedicatee') Example: _getPluralAttribute by grandfathered workId >>> md._getPluralAttribute('dedication') ('The First Dedicatee', 'A Second Dedicatee') Example: _getPluralAttribute by grandfathered workId abbreviation >>> md._getPluralAttribute('ode') ('The First Dedicatee', 'A Second Dedicatee') It raises AttributeError if attributeName is not a valid uniqueName, workId, or workId abbreviation. Example: _getPluralAttribute by 'namespace:name' >>> md._getPluralAttribute('humdrum:ODE') Traceback (most recent call last): AttributeError: invalid attributeName: humdrum:ODE zinvalid attributeName: )rrTrFrrrr4 attributeNames r;rmMetadata._getPluralAttribute(sF JDD D7788G  JHH H77<<]K  JMM M77AA-P 6}oFGGr=cU[R;a"UR[RU5$U[R;a"UR[RU5$U[R;a"UR[RU5$[ UR R<SU<35e)a This returns a single string (perhaps a summary) for supported uniqueNames, grandfathered workIds, and grandfathered workId abbrevations. >>> md = metadata.Metadata() >>> md['dedicatedTo'] = ('The First Dedicatee', 'A Second Dedicatee') Example: _getSingularAttribute by uniqueName >>> md._getSingularAttribute('dedicatedTo') 'The First Dedicatee, A Second Dedicatee' Example: _getSingularAttribute by grandfathered workId >>> md._getSingularAttribute('dedication') 'The First Dedicatee, A Second Dedicatee' Example: _getSingularAttribute by grandfathered workId abbreviation >>> md._getSingularAttribute('ode') 'The First Dedicatee, A Second Dedicatee' It raises AttributeError if attributeName is not a valid uniqueName, workId, or workId abbreviation. Example: _getSingularAttribute by 'namespace:name' >>> md._getSingularAttribute('humdrum:ODE') Traceback (most recent call last): AttributeError: 'Metadata' object has no attribute: 'humdrum:ODE' z object has no attribute: )rrTr,rrrr:__name__rIs r;rMetadata._getSingularAttribute^s@ JDD D6688G  JHH H66<<]K  JMM M66AA-P ~~&&))CMCT U  r=c(U[R;$)a1 Determines if a unique name is associated with a standard property. Returns False if no such associated standard property can be found. Example: a standard contributor uniqueName returns True >>> md = metadata.Metadata() >>> md._isStandardUniqueName('librettist') True Example: a standard 'namespace:name' returns False (it is a standard namespaceName, but not a standard uniqueName) >>> md._isStandardUniqueName('marcrel:LBT') False Example: a standard non-contributor uniqueName returns True >>> md._isStandardUniqueName('alternativeTitle') True Example: a custom (non-standard) name returns False (it is not a standard name of any sort) >>> md._isStandardUniqueName('average duration') False Example: a RichMetadata additional attribute name returns False >>> md._isStandardUniqueName('ambitus') False )rr`)r4rVs r;rhMetadata._isStandardUniqueNamesDZKKKKr=cL[RRUS5nUcgg)a Determines if a 'namespace:name' is associated with a standard property. Returns False if no such associated standard property can be found. Example: a standard 'namespace:name' returns True >>> metadata.Metadata._isStandardNamespaceName('marcrel:LBT') True Example: a standard contributor uniqueName returns False (it is a standard uniqueName, but not a standard namespaceName) >>> metadata.Metadata._isStandardNamespaceName('librettist') False Example: a namespaceName with a non-standard namespace returns False >>> metadata.Metadata._isStandardNamespaceName('nonstandardnamespace:LBT') False Example: a namespaceName with a standard namespace, but a non-standard name returns False >>> metadata.Metadata._isStandardNamespaceName('marcrel:nonstandardname') False Example: a custom (non-standard) name returns False (it is not a standard name of any sort) >>> metadata.Metadata._isStandardNamespaceName('average duration') False NFT)r&NAMESPACE_NAME_TO_PROPERTY_DESCRIPTIONrUr[rcs r;rg!Metadata._isStandardNamespaceNames.F  = = A A-QU V  <r=c`[RRU5nUcgUR$)a Determines if a uniqueName is associated with a standard contributor property. Returns False if no such associated standard property can be found, or if the associated standard property is not a contributor property. Example: 'librettist' returns True ('librettist' is a standard contributor property). >>> metadata.Metadata._isContributorUniqueName('librettist') True Example: 'alternativeTitle' returns False (it is a standard namespaceName, but it is not a contributor). >>> metadata.Metadata._isContributorUniqueName('alternativeTitle') False Example: 'marcrel:LBT' returns False (it is a standard contributor namespaceName, but not a standard contributor uniqueName) >>> metadata.Metadata._isContributorUniqueName('marcrel:LBT') False Example: a custom (non-standard) name returns False (it is not a standard name of any sort) >>> metadata.Metadata._isContributorUniqueName('average duration') False Fr_rbs r;r!Metadata._isContributorUniqueNames4@  : : > >z J  <!!!r=c`[RRU5nUcgUR$)a Determines if a 'namespace:name' is associated with a standard contributor property. Returns False if no such associated standard property can be found, or if the associated standard property is not a contributor property. Example: 'marcrel:LBT' returns True ('marcrel:LBT' is a standard contributor property: the librettist). >>> metadata.Metadata._isContributorNamespaceName('marcrel:LBT') True Example: 'dcterms:alternative' returns False (it is a standard namespaceName, but it is not a contributor). >>> metadata.Metadata._isContributorNamespaceName('dcterms:alternative') False Example: 'librettist' returns False (it is a standard contributor uniqueName, but not a standard contributor namespaceName) >>> metadata.Metadata._isContributorNamespaceName('librettist') False Example: a namespaceName with a non-standard namespace returns False >>> metadata.Metadata._isContributorNamespaceName('nonstandardnamespace:LBT') False Example: a namespaceName with a standard namespace, but a non-standard name returns False >>> metadata.Metadata._isContributorNamespaceName('marcrel:nonstandardname') False Example: a custom (non-standard) name returns False (it is not a standard name of any sort) >>> metadata.Metadata._isContributorNamespaceName('average duration') False F)rrRrUrarSs r;r;$Metadata._isContributorNamespaceNames4V  = = A A- P  <!!!r=c`[RRU5nUcgUR$)a Determines if a 'namespace:name' is associated with a standard property that needs article normalization (generally title-like properties). Returns False if no such associated standard property can be found, or if the associated standard property is not a contributor property. Example: 'dcterms:title' returns True >>> metadata.Metadata._namespaceNameNeedsArticleNormalization('dcterms:title') True Example: 'title' returns False ('title' is the uniqueName of a standard property that needs article normalization, but it is not a namespaceName). >>> metadata.Metadata._namespaceNameNeedsArticleNormalization('title') False Example: 'marcrel:LBT' (the librettist) returns False (it doesn't need article normalization) >>> metadata.Metadata._namespaceNameNeedsArticleNormalization('marcrel:LBT') False Example: 'average duration' returns False (it is not a standard name) >>> metadata.Metadata._namespaceNameNeedsArticleNormalization('average duration') False F)rrRrUneedsArticleNormalizationrSs r;r=0Metadata._namespaceNameNeedsArticleNormalization:s3>  = = A A- P  <---r=cxUcg[RRU5nUcgUR(dgU$)a Translates a contributor role to a standard uniqueName that should be used to store that contributor. For standard contributor roles, this simply returns role, because standard roles are their own standard uniqueNames. But for non-standard roles, 'otherContributor' is returned. This is the standard uniqueName that should be used for contributors with custom roles. Example: 'composer' and 'lyricist' are standard contributor roles whose uniqueNames are 'composer' and 'lyricist', respectively. >>> metadata.Metadata._contributorRoleToUniqueName('composer') 'composer' >>> metadata.Metadata._contributorRoleToUniqueName('lyricist') 'lyricist' Example: 'interpretive dancer' is a non-standard contributor role, so 'otherContributor' is returned. >>> metadata.Metadata._contributorRoleToUniqueName('interpretive dancer') 'otherContributor' Example: None is a non-standard contributor role, so 'otherContributor' is returned. >>> metadata.Metadata._contributorRoleToUniqueName(None) 'otherContributor' otherContributorr_)rrcs r;r%Metadata._contributorRoleToUniqueName`sB: <%  : : > >t D  <%!!% r=c>U(d`UnURU5(a [RRUS5nUR U5(d[ SU<S35eUnUR RU5nU(d [5$[U5$)a` Returns all the items stored in metadata with this name. The returned value is always a Tuple. If there are no items, an empty Tuple is returned. If isCustom is True, then the name will be used unconditionally as a custom name. If isCustom is False, and the name is not a standard uniqueName or a standard 'namespace:name', KeyError will be raised. r4Name=V is not a standard metadata name. Call addCustom/setCustom/getCustom for custom names.)rgrrZrUrhrr2rw)r4rDr@rVrs r;rH Metadata._gets"J,,T22'EEII$PRS --j99D8$LLMMD*...*<* ?,0>>+=+=dD+I $3NN4 $.#?DNN4 r=c6U(d`UnURU5(a [RRUS5nUR U5(d[ SU<S35eUnUR RUS5 UbURXU5 gg)u/ Sets a single item or multiple items with this name, replacing any existing items with this name. If isCustom is False, the name must be a standard uniqueName or a standard 'namespace:name'. If isCustom is True, the name can be any custom name. >>> md = metadata.Metadata() Example: set the librettist >>> md._set('librettist', metadata.Text('Marie Červinková-Riegrová'), isCustom=False) >>> md['librettist'] (,) Example: replace that librettist with two other librettists >>> md._set('librettist', ['Melissa Li', 'Kit Yan Win'], isCustom=False) >>> md['marcrel:LBT'] (, ) If isCustom is True, then the name will be used unconditionally as a custom name. >>> md._set('average duration', '180 minutes', isCustom=True) >>> md._get('average duration', isCustom=True) (,) If isCustom is False, and the name is not a standard uniqueName or a standard 'namespace:name', KeyError will be raised. >>> md._set('average duration', '180 minutes', isCustom=False) Traceback (most recent call last): KeyError: "Name='average duration' is not a standard metadata name... r4r`raN) rgrrZrUrhrr2poprB)r4rDr9r@rVs r;rP Metadata._setsF"J,,T22'EEII$PRS --j99D8$LLMMD 4&   IId8 , r=c[RRUS5nUnUc[n[ X5(aU$U[La4[ U[ 5(a [U5$[[ U55$U[ Lal[ U[ 5(a [ U5$[ U[5(a [ U5$[R"S[U5R35eU[La[ U[5(a [ U5n[ U[5(aU$[ U[ [R[45(a [U5$[R"S[U5R35eU[Laj[ U[ 5(a [U5n[ U[5(a [XS9$[R"S[U5R35eU[ La [!U5$[R"S5e! [[ U55s$=f! [R"S[U5R35e=f)a Converts a value to the appropriate valueType (looked up in STDPROPERTIES by uniqueName). Converts certain named values to Text >>> metadata.Metadata._convertValue('title', 3.4) >>> metadata.Metadata._convertValue('title', '3.4') >>> metadata.Metadata._convertValue('title', metadata.Text('3.4')) Converts certain named values to Copyright >>> metadata.Metadata._convertValue('copyright', 'copyright str') >>> metadata.Metadata._convertValue('copyright', metadata.Text('copyright text')) >>> metadata.Metadata._convertValue('copyright', metadata.Copyright('copyright')) Converts certain named values to Contributor >>> metadata.Metadata._convertValue('composer', 'composer str') >>> metadata.Metadata._convertValue('composer', metadata.Text('composer text')) >>> metadata.Metadata._convertValue('composer', ... metadata.Contributor(role='random', name='Joe')) Converts certain named values to DateSingle >>> metadata.Metadata._convertValue('dateCreated', '1938') >>> metadata.Metadata._convertValue('dateCreated', metadata.Text('1938')) >>> metadata.Metadata._convertValue('dateCreated', ... metadata.DateBetween(['1938', '1939'])) Nzinvalid type for Copyright: zinvalid type for DateSingle: )rrDzinvalid type for Contributor: zinvalid type for int: z!internal error: invalid valueType)rUNIQUE_NAME_TO_VALUE_TYPErUrrrr!rrtyperMrdatetimerrrr)rVr9 valueType originalValues r;rdMetadata._convertValue s8X+5*N*N*R*R +  %  I e ' 'L  %%%E{"E # #  !%%% ''%&& ''00.tE{/C/C.DEG G  %%&&E %// %#x'8'8$!?@@4%e,, 00/U 0D0D/EFH H  #%%%U %&&" ??000e1E1E0FGI I   E5z! ,,-PQQ74M 233( E"44,T%[-A-A,BCEEs H0 I 0I .I9)r2)returnNone)rDrr9t.Any | Iterable[t.Any]rsrt)rDrrstuple[ValueType, ...])rDrr9ru)rVrrs str | None)r[rrsrw)rVrwrsbool)rDrrsrxrstuple[str, ...])rstuple[Contributor, ...])r9rrsrt rrxrrrxrsrxrtrxrsztuple[tuple[str, t.Any], ...])rDrr9t.Any)rz4t.Literal['movementName', 'movementNumber', 'title']rstuple[Text, ...])rzt.Literal['copyright',]rsztuple[Copyright, ...])rrrsr~)rrrsz(tuple[ValueType, ...] | tuple[Text, ...])rrr9ru)rr)rrwrsr{)NN)rz0str | t.Pattern | t.Callable[[str], bool] | Nonerrwrsztuple[bool, str | None])r9z Iterable[str]rsrt)rsrw)r[rrsrz)rJrrsrz)rJrrsrwrVrrsrx)r[rrsrx)rrwrsr)rDrr@rxrsrv)rDrr9rur@rx)rVrr9r}rsr")BrM __module__ __qualname____firstlineno____doc__classSortOrderr1rErJrMrQ staticmethodrWr\rdripropertyr,r{r~setterrurrr rrrrrrrrrrrrrrrr rrrrrrr#r'r/r,rFrmrrhrgrr;r=rrHrBrPrd__static_attributes__ __classcell__r:s@r;rrs 7vN/2'/'/('/'/R.6.:.>NN2QQ0#"#"JD442>2727h**&+(-%*!% V#V"& V # V  V 'Vp<0|I)X  +     0    -.^.2,1\+^=Ao9oo  oT > >11 664__)) 448**    [[%% 992,, 88 ++ 66__)) << // 88 ++  A A4 4  8 8++  6 6,, 66$__))  4 4**  : :--  < <// 44, ]]'' 88,++  3 3 \\&& 00j59n+5Z4Hl3 j"LH''R$"$"L/"/"b#.#.J++Z <&@R/-bsRsRr=rc^\rSrSrSrSrU4SjrSU4SjjrSSjrSSjr S r SSSS S .SU4S jjjr SU4S jjr Sr U=r$)ri~ a RichMetadata adds to Metadata information about the contents of the Score it is attached to. TimeSignature, KeySignature and related analytical is stored. RichMetadata are generally only created in the process of creating stored JSON metadata. >>> richMetadata = metadata.RichMetadata(title='Concerto in F') >>> richMetadata.title 'Concerto in F' >>> richMetadata.keySignatureFirst = key.KeySignature(-1) >>> 'keySignatureFirst' in richMetadata.additionalRichMetadataAttributes True RichMetadata objects contain all the usual Metadata items, plus some observed musical information analyzed from the score. Here is a list of what information is added: >>> richMetadata.additionalRichMetadataAttributes ('ambitus', 'keySignatureFirst', 'keySignatures', 'noteCount', 'numberOfParts', 'pitchHighest', 'pitchLowest', 'quarterLength', 'sourcePath', 'tempoFirst', 'tempos', 'timeSignatureFirst', 'timeSignatures') ) ambituskeySignatureFirst keySignatures noteCount numberOfPartsr(r' quarterLength sourcePath tempoFirsttempostimeSignatureFirsttimeSignaturesc >[TU]"S0UD6 SUlSUl/UlSUlSUlSUlSUlSUl SUl SUl /Ul SUl /Ulg)Nr4r-)r0r1rrrrrr(r'rrrrrr)r4r5r:s r;r1RichMetadata.__init__ sv $8$ !%! ! "& r=cv>XR;a[X5nUc [5$U4$[TU]U5$r) additionalRichMetadataAttributesgetattrrwr0rm)r4rJr9r:s r;rm RichMetadata._getPluralAttribute s@ AA AD0E}w8Ow*=99r=FcS/n[RS/5 UH<n[X5nUb U(aMUb[X5nUb[XU5 M:M<M> g![a MNf=f)a Given another Metadata or RichMetadata object, combine all attributes and return a new object. >>> md = metadata.Metadata(title='Concerto in F') >>> md.title 'Concerto in F' >>> richMetadata = metadata.RichMetadata() >>> richMetadata.merge(md) >>> richMetadata.title 'Concerto in F' r2zRichMetadata: calling merge()N) environLocal printDebugrr3r)r4other favorSelf localNamesrD localValue otherValues r;mergeRichMetadata.merge s$   !@ ABD ,J%)(%,U%9 %1#D ;2)&sA A+*A+cUR(dgURnUR(a UR$URnU(dg[U[R 5(d[R "U5nUR [R"55nUR5$![a UR5s$f=f)z Get a string of the path after the corpus for the piece. Useful for searching on corpus items without proper composer data. >>> rmd = metadata.RichMetadata() >>> b = corpus.parse('bwv66.6') >>> rmd.getSourcePath(b) 'bach/bwv66.6.mxl' r4) r#rrrpathlibPath relative_tor getCorpusFilePathas_posixr)r4 streamObjmdstreamFp relativePaths r; getSourcePathRichMetadata.getSourcePath s!!     $$ $;;(GLL11||H-H '#//0H0H0JKL((* * '$$& & 's3B::CCchSSKJn SSKJn SSKJn [R S/5 UR 5R5n[UR5Ul SUl /Ul SUl /UlSUl/UlUR#U5UlUGHn['XcR(5(a:UR*nXpR ;aUR R-U5 MVMX['XbR.5(aCUR0UR;a'URR-UR05 MM['XdR25(dM[5U5nXR;dMURR-U5 GM UR (aUR SUlUR(aURSUl UR(aURSUl [UR65UlUR:UlSSKJ n SUl!SUl"SUl#U RIU5n U RJbCU RLb6U RJRNUl#U RLRNUl"U RQU5n U c[RRT"S5n [WU RXU RZR\URFURDS 9Ul!g) a, Given a Stream object, update attributes with stored objects. >>> rmd = metadata.RichMetadata() >>> rmd.keySignatureFirst is None True >>> rmd.sourcePath '' >>> b = corpus.parse('bwv66.6') >>> rmd.update(b) >>> rmd.keySignatureFirst 3 >>> rmd.sourcePath 'bach/bwv66.6.mxl' >>> rmd.numberOfParts 4 r)r)meter)tempozRichMetadata: update(): startN)discreteP1r$)/music21rrrrrflattenrr<partsrrrrrrrrrr TimeSignature ratioStringrv KeySignaturerTempoIndicationr notesAndRestsr highestTimermusic21.analysisrrr(r'Ambitus minPitchObj maxPitchObjnameWithOctave getSolutionrIntervalrr%r& simpleName) r4rrrrflatelementrtempoIndicationStringranalysisObjectambitusIntervals r;updateRichMetadata.update s& !!!@ AB  "))+ 1!% "& ,,Y7G'#6#677%11 &9&99''..{;:G%5%566>>););;&&--gnn=<G%:%:;;(+G %( ;KK&&'<=   &*&9&9!&[[TU] UUUUS95nU(a [U5$URHnUR U[ X545 M! U(a[[U55$[U5$)u Returns all values stored in this RichMetadata as a Tuple of Tuples. Each individual Metadata Tuple is (uniqueName, value) and each additional RichMetadata tuple is (name, richAttributeValue). >>> rmd = metadata.RichMetadata() >>> c = corpus.parse('corelli/opus3no1/1grave') >>> rmd.merge(c.metadata) >>> rmd.update(c) >>> rmd.all() (('ambitus', AmbitusShort(semitones=48, diatonic='P1', pitchLowest='C2', pitchHighest='C6')), ('arranger', 'Michael Scott Cuthbert'), ('composer', 'Arcangelo Corelli'), ... ('sourcePath', 'corelli/opus3no1/1grave.xml'), ('tempoFirst', ''), ('tempos', ['']), ('timeSignatureFirst', '4/4'), ('timeSignatures', ['4/4'])) >>> rmd.dateCreated = metadata.DateRelative('1689', 'onOrBefore') >>> rmd.localeOfComposition = 'Rome' >>> rmd.all(skipContributors=True) (('ambitus', AmbitusShort(semitones=48, diatonic='P1', pitchLowest='C2', pitchHighest='C6')), ('copyright', '© 2014, Creative Commons License (CC-BY)'), ('corpusFilePath', 'corelli/opus3no1/1grave.xml'), ('dateCreated', '1689/--/-- or earlier'), ('fileFormat', 'musicxml'), ... ('keySignatures', [-1]), ('localeOfComposition', 'Rome'), ('movementName', 'Sonata da Chiesa, No. I (opus 3, no. 1)'), ... ('timeSignatures', ['4/4'])) >>> rmd.all(returnPrimitives=True, returnSorted=False) (('software', ), ('software', ), ('software', ), ('movementName', <...Text Sonata da Chiesa, No. I (opus 3, no. 1)>), ('composer', ), ... ('timeSignatures', ['4/4'])) >>> rmd.all(skipNonContributors=True, returnPrimitives=True, returnSorted=True) (('arranger', ), ('composer', )) r)listr0rurwrrvrr)r4rrrrsrtrrDr:s r;ruRichMetadata.ally st+/uw{- 3-% 0;0'+( = 99D MM4!45 6: ( (V}r=cP>[TU]U5(agXR;agg)a8 Determines if a unique name is associated with a standard property. Returns False if no such associated standard property can be found. Example: a RichMetadata additional attribute name returns True >>> rmd = metadata.RichMetadata() >>> rmd._isStandardUniqueName('ambitus') True Example: a standard contributor uniqueName returns True >>> rmd._isStandardUniqueName('librettist') True Example: a standard 'namespace:name' returns False (it is a standard namespaceName, but not a standard uniqueName) >>> rmd._isStandardUniqueName('marcrel:LBT') False Example: a standard non-contributor uniqueName returns True >>> rmd._isStandardUniqueName('alternativeTitle') True Example: a custom (non-standard) name returns False (it is not a standard name of any sort) >>> rmd._isStandardUniqueName('average duration') False TF)r0rhr)r4rVr:s r;rh"RichMetadata._isStandardUniqueName s+B 7 ( 4 4 >> >r=ry)F)rsrr|r)rMrrrrrr1rmrrrrurhrrrs@r;rr~ s6($$! :"H'>i&\&+(-%*!% K#K"& K # K  K 'KKZ%%r=rz list[type] _DOC_ORDER__main__)9r __future__r__all__ collectionsrcollections.abcrcopy dataclassesr rorrtypingrr unittestrr r music21.commonr rrrrmusic21.metadatarmusic21.metadata.propertiesrrrrmusic21.metadata.primitivesrrrrrrrrrr r!r" Environmentrr Music21Objectrrr__annotations__rMmainTestr-r=r;rsul#  #$ ! % ';$$'HHHH &&z2 .RT J#Rt!!J#R\Fm8md  J z r=