3j˕6UdZddlmZgdZddlmZddlZddlZddlZddl Z ddl m Z ddl m Z ddl mZdd lmZmZdd l mZdd l mZdd l mZdd l mZddlmZddlmZddlmZddlmZmZmZmZmZm Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&ddlm'Z'ddl(m)Z)e jTrddl m+Z+ddl m,Z,ddl m-Z-ej\dZ/Gdde j`Z1Gdde jdZ3Gdde3Z4e3e4e1gZ5de6d<e7d k(rddl Z e jpyy)!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) AmbitusShortMetadata RichMetadata Contributor CopyrightCreatorDate DateBetween DatePrimitive DateRelative DateSelection DateSingleImprintText ValueTypePropertyDescriptionbundlescaching primitives properties)IterableN)overload)base)common)DocOrderOffsetQL)defaults) environment) exceptions21)interval)r)r)r) rrr r r r r rrrrr)r)rkeymetertempometadatac:eZdZUdZded<ded<ded<ded<y) rz A namedtuple representing the ambitus (range) using ints and strings >>> metadata.AmbitusShort(7, 'P5', 'B3', 'F#4') AmbitusShort(semitones=7, diatonic='P5', pitchLowest='B3', pitchHighest='F#4') int semitonesstrdiatonic pitchLowest pitchHighestN)__name__ __module__ __qualname____doc____annotations__F/DATA/.local/lib/python3.12/site-packages/music21/metadata/__init__.pyrrs NMr6rc:eZdZdZdZdQfd Z dRdZdSdZdTdZdTdZ e dUdZ e dVd Z e dWd Z dXd ZedYd ZedZd ZedZej&d[dZddddd d\dZdZd]fd Ze d^dZe d_dZed`dZdadZdbdZdcdZdddZ de dfdZedZej&d[dZed Zej&d[d!Zed"Zej&dgd#Zed$Z e j&d[d%Z edhd&Z!e!j&d[d'Z!edhd(Z"e"j&d[d)Z"edhd*Z#e#j&d[d+Z#edhd,Z$e$j&d[d-Z$ed.Z%e%j&d[d/Z%ed0Z&e&j&d[d1Z&ed2Z'e'j&dgd3Z'ed4Z(e(j&d[d5Z(ed6Z)e)j&dgd7Z)ed8Z*e*j&d[d9Z*edhd:Z+e+j&d[d;Z+edhd<Z,e,j&d[d=Z,edhd>Z-e-j&d[d?Z-ed@Z.e.j&d[dAZ.edhdBZ/dVdCZ0didDZ1djdEZ2dkdFZ3dldGZ4e dmdHZ5e dldIZ6e dmdJZ7e dmdKZ8e dndLZ9dodMZ:dpdNZ;dpdOZS)rra 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 i}i}|jD]"\}}|tjvr|||<|||<$t|di|i|_|jD]\}}t |||tjg|d<y)Nsoftwarer5) itemsrALL_LEGAL_ATTRIBUTESsuper__init__ _contentssetattrrr:)selfkeywordsm21BaseKeywords myKeywordsattrvalue __class__s r7r>zMetadata.__init__s,.') $>>+KD%z666#( 4 (-% , +?+57%++-KD% D$ &.%--.Zr6c,|j||dy)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_addrAnamerFs r7addz Metadata.add3sN $ .r6c(|j|dS)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 (, ) TrI)_getrArNs r7 getCustomzMetadata.getCustom\s2yyy--r6c,|j||dy)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 (, , ) TrINrKrMs r7 addCustomzMetadata.addCustomws6 $ -r6c,|j||dy)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 (, ) TrIN)_setrMs r7 setCustomzMetadata.setCustoms4 $ -r6cBtjj|dS)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 r7uniqueNameToNamespaceNamez"Metadata.uniqueNameToNamespaceNames077;;JMMr6cBtjj|dS)a 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_NAMEr[) namespaceNames r7namespaceNameToUniqueNamez"Metadata.namespaceNameToUniqueNames.77;;M4PPr6cf|sytjj|d}|y|jS)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_DESCRIPTIONr[ isContributorr\props r7isContributorUniqueNamez Metadata.isContributorUniqueNames;8  : : > >z4 P  <!!!r6cL|j|ry|j|ryy)ac 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_isStandardUniqueNamerRs r7isStandardNamezMetadata.isStandardName s).  ( ( .  % %d +r6c$|jdS)aE 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:_getPluralAttributerAs r7r:zMetadata.software.s0'' 33r6cvg}|jdddD]\}}|j|t|S)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)rAoutput_contribs r7 contributorszMetadata.contributorsHsH0%'(($(!%"#$JAw MM' " $ V}r6c$|jdS)u} 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_getSingularAttributerps r7r~zMetadata.copyrighthsf))+66r6c||_yz7 For type checking only. Does not run. N)r~rArFs r7r~zMetadata.copyright r6FTskipContributorsrsrtruc4g}|jjD]Y\}}|j|}|r|r|r|s!|D]4} |r|j|| f|j|t | f6[|rt t |St |S)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', )) )r?r;_isContributorUniqueNamerwr,rxsorted) rArrsrtruallOutr\ valueListrerFs r7rvz Metadata.allsF+-&*^^%9%9%; !J "&"?"? "KMM"=##MM:u"56MM:s5z":; #&< ( (V}r6c$|j|S)ac 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()' rrRs r7 __getattr__zMetadata.__getattr__sx))$//r6c|tjvr4|2t|tr"t|tst d|d|d|tj vr/t|trt|trt d|d|tjvr&|jtj||dy|tjvr&|jtj||dy|tjvr&|jtj||dy|dvr|dd }|j||dyt|1||y) a 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).FrI) composers librettists lyricists) rALL_SINGLE_ATTRIBUTE_NAMES isinstancerr, ValueErrorALL_PLURAL_ATTRIBUTE_NAMESrZrW!MUSIC21_WORK_ID_TO_NAMESPACE_NAME&MUSIC21_ABBREVIATION_TO_NAMESPACE_NAMEr= __setattr__)rArNrFr\rGs r7rzMetadata.__setattr__;s|0 :88 8!"5(3&uc2 3tf-++/&0M"OPP :88 8eX.*UC2H $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 strFrI)rr,KeyErrorrQrs r7rzMetadata.__getitem__s.T#s#56 6yyuy--r6cbt|ts td|j||dy)ao "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' rFrIN)rr,rrW)rAr#rFs r7 __setitem__zMetadata.__setitem__s,(#s#56 6 #uu -r6ct|tstjd||j |j }|j ||dy)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: FrIN)rrr MetadataException_contributorRoleToUniqueNamerolerL)rAcr\s r7addContributorzMetadata.addContributorsRP![)008<> >;;AFFC  *a% 0r6cg}|jdddD]&\}}|j|k(s|j|(t|S)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' TFrr)rvrrwrx)rArresultrzr{s r7getContributorsByRolezMetadata.getContributorsByRolesUH%'(($(!%"#$JAw||t# g& $ V}r6c d}g}||sy||r|j\}||j}d} |j|}|r|D]}|j||fd}|s|j dD]\} }|j | s|| jvr|j|| fd}ntjj| d} | d|| jvsw|j|| fd}nAn?|j dD]*\} }|j | s|j|| f,|j dddD]\} } |W| j|jdk7r(| j+|j| jjvr_| jD](} |jt| | jf*d}ttjrd}}nKttr;t!fdd Dr'd}t#j$t"j& }|r7|5|D]/\}}t|ts|j)|}|+d|fcSyt+r|D]\}}|sd|fcSy|D]\}}t|tr1tj|jvrd|fcSt|t,r!t/d rj0|k(rd|fcS|k(s~d|fcSy#t$rYwxYw) 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)rrr contributorc3&K|]}|v ywrr5).0 characterquerys r7 z"Metadata.search..sD)Yi5()sz*.|+?{})flagssharps)popitemlowerrorwAttributeErrorrvrkrUNIQUE_NAME_TO_MUSIC21_WORK_IDr[rnamesr,rtPatternanyrecompile IGNORECASEsearchcallabler*hasattrr)rArfieldrBreQueryvalueFieldPairsmatchvaluesrFr\workIdrzr{rNuseRegex innerField matchReSearchs ` r7rzMetadata.search>soJ#' =U]8 ]u}#++-LE5  KKMEE 11%8!''..u~>"( E)-4)H%J55jA  0 0 22'..z/BC $(2'P'P'T'T"D(F~  .'..v? $5*I8&*XXtX%D! E--j9#**E:+>?&E(($(!%"#$JAw <<'EKKM],J<<+ W\\EWEWEY0Y &&D 7<<'@A&$  eQYY 'HG$D)DDHjjbmm>> md = metadata.Metadata(popularTitle='Eroica') >>> md.alternativeTitle = 'Heroic Symphony' >>> md.alternativeTitle 'Heroic Symphony' alternativeTitlerrps r7rzMetadata.alternativeTitles))*<==r6c||_yr)rrs r7rzMetadata.alternativeTitles !&r6c$|jdS)a 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' composerrrps r7rzMetadata.composers2))*55r6c||_yr)rrs r7rzMetadata.composer4  r6c$|jdS)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 () rrnrps r7rzMetadata.composers;s6'' 33r6c||_yr)rrs r7rzMetadata.composersXrr6c$|jdS)a 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' dateCreatedrrps r7rzMetadata.dateCreated_s0))-88r6c||_yr)rrs r7rzMetadata.dateCreatedy !r6c$|jdS)z= Get or set the file format that was parsed. fileFormatrrps r7rzMetadata.fileFormat )),77r6c||_yr)rrs r7rzMetadata.fileFormat  r6c$|jdS)z Get or set the file path that was parsed. This returns a string, not a Path object that is deliberate for caching. filePathrrps r7rzMetadata.filePaths ))*55r6c||_yr)rrs r7rzMetadata.filePathrr6c$|jdS)zH Get or set the path within the corpus that was parsed. corpusFilePathrrps r7rzMetadata.corpusFilePaths ))*:;;r6c||_yr)rrs r7rzMetadata.corpusFilePath $r6c$|jdS)z= Get or set the file number that was parsed. fileNumberrrps r7rzMetadata.fileNumberrr6c||_yr)rrs r7rzMetadata.fileNumberrr6c$|jdS)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' localeOfCompositionrrps r7rzMetadata.localeOfCompositions))*?@@r6c||_yr)rrs r7rzMetadata.localeOfCompositions $) r6c$|jdS)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. librettistrrps r7rzMetadata.librettists)),77r6c||_yr)rrs r7rzMetadata.librettistrr6c$|jdS)aQ 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. rrnrps r7rzMetadata.librettistss'' 55r6c||_yr)rrs r7rzMetadata.librettistsrr6c$|jdS)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' lyricistrrps r7rzMetadata.lyricists"))*55r6c||_yr)rrs r7rzMetadata.lyricist rr6c$|jdS)ao 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. rrnrps r7rzMetadata.lyricistss'' 33r6c||_yr)rrs r7rzMetadata.lyricists rr6c$|jdS)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. movementNamerrps r7rzMetadata.movementName's)).99r6c||_yr)rrs r7rzMetadata.movementName7s "r6c$|jdS)a7 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' movementNumberrrps r7rzMetadata.movementNumber>s))*:;;r6c||_yr)rrs r7rzMetadata.movementNumberNrr6c$|jdS)a 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' numberrrps r7rzMetadata.numberUs*))(33r6c||_yr)rrs r7rzMetadata.numberls  r6c$|jdS)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' opusNumberrrps r7rzMetadata.opusNumberss*)),77r6c||_yr)rrs r7rzMetadata.opusNumberrr6c$|jdS)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 titlerrps r7rzMetadata.titles))'22r6c||_yr)rrs r7rzMetadata.titles  r6cfd}|D]*}|jtj|}|s(|cSy)a# 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: property 'bestTitle' of 'Metadata' object has no setter )r popularTitlerrN)_getStringValueByNamespaceNamerrZ)rAsearchIdr\ titleSummarys r7 bestTitlezMetadata.bestTitlesDB  #J%)%H%H88D&L## #r6c*|tjvry|j|d}|sy|j|rkt |dk(rt |dSt |dk(r t |ddzt |dzSt |ddt |dz dzS|j |rFd }t|D]4\}}t|tsJ|dkDr|d z }||jz }6|Sd jd |DS) aa 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' NFrIrz and z othersz, c32K|]}t|ywrr,rrFs r7rz:Metadata._getStringValueByNamespaceName..s8U) rALL_NAMESPACE_NAMESrQ_isContributorNamespaceNamelenr,'_namespaceNameNeedsArticleNormalization enumeraterrgetNormalizedArticlejoin)rAr`rryirFs r7rz'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') FrIc32K|]}t|ywrrrs r7rz;Metadata._getStringValuesByNamespaceName..<s4VESZVr) rrrxrQrrrrwr)rAr`rryrFs r7_getStringValuesByNamespaceNamez(Metadata._getStringValuesByNamespaceNames:  > > >7N(, -% (P7N  7 7 F "F!%... e88:; = 4V444r6cV|tjvr"|jtj|S|tjvr"|jtj|S|tjvr"|jtj|St d|)aA 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: )rrZrrrrrA attributeNames r7rozMetadata._getPluralAttribute>sF JDD D7788G  JHH H77<<]K  JMM M77AA-P 6}oFGGr6c|tjvr"|jtj|S|tjvr"|jtj|S|tjvr"|jtj|St |j jd|)ab 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: )rrZrrrrrGr0r s r7rzMetadata._getSingularAttributets@ JDD D6688G  JHH H66<<]K  JMM M66AA-P ~~&&))CMCT U  r6c&|tjvS)a 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 )rrd)rAr\s r7rkzMetadata._isStandardUniqueNamesDZKKKKr6cJtjj|d}|yy)aV 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_DESCRIPTIONr[r`rgs r7rjz!Metadata._isStandardNamespaceNames.F  = = A A-QU V  <r6c^tjj|}|y|jS)a2 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 Frcrfs r7rz!Metadata._isContributorUniqueNames4@  : : > >z J  <!!!r6c^tjj|}|y|jS)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)rr%r[rer&s r7rz$Metadata._isContributorNamespaceNames4V  = = A A- P  <!!!r6c^tjj|}|y|jS)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)rr%r[needsArticleNormalizationr&s r7rz0Metadata._namespaceNameNeedsArticleNormalizationPs3>  = = A A- P  <---r6cj|ytjj|}|y|jsy|S)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' otherContributorrc)rrgs r7rz%Metadata._contributorRoleToUniqueNamevsB: <%  : : > >t D  <%!!% r6c|sU|}|j|r tjj|d}|j |st d|d|}|j j|}|s tSt|S)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. rName=V is not a standard metadata name. Call addCustom/setCustom/getCustom for custom names.)rjrr_r[rkrr?rx)rArNrJr\rs r7rQz Metadata._gets"J,,T2'EEII$PRS --j9D8$LLMMD*...*<*,0>>+=+=dD+I $3DNN4 $.#?DNN4 r6c|sU|}|j|r tjj|d}|j |st d|d|}|j j|d||j|||yy)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... rr.r/N) rjrr_r[rkrr?poprL)rArNrFrJr\s r7rWz Metadata._setsF"J,,T2'EEII$PRS --j9D8$LLMMD 4&   IIdE8 , r6ctjj|d}|}|t}t ||r|S|tur/t |t r t|Stt |S|t urat |t r t |St |tr t |Stjdt|j|turt |tr t |}t |tr|St |t tjtfr t|Stjdt|j|t urct |t r t|}t |tr t!||Stjdt|j|t"ur t#|Stjd#t$rtt |cYSwxYw#t$r1}tjdt|j|d}~wwxYw)a% Converts a value (string, date, etc.) to the appropriate ValueType (defined by uniqueName and metadata.proporties.UNIQUE_NAME_TO_VALUE_TYPE). Converts certain named values to Text: >>> metadata.Metadata.convertValue('title', 'Density 21.5') Non-string values can often be converted automatically >>> metadata.Metadata.convertValue('title', 21.5) If it is already the appropriate type, no change is made >>> md_text = metadata.Text('The Desert Music') >>> metadata.Metadata.convertValue('title', md_text) >>> metadata.Metadata.convertValue('title', md_text) is md_text True Converts copyright named values to Copyright: >>> metadata.Metadata.convertValue('copyright', 'copyright-as-string') >>> metadata.Metadata.convertValue('copyright', metadata.Text('copyright-as-text')) >>> metadata.Metadata.convertValue('copyright', metadata.Copyright('2025 Ariadne Press')) Converts composer or other named values to Contributors: >>> metadata.Metadata.convertValue('composer', 'Kayleigh Rose Amstutz') >>> metadata.Metadata.convertValue('librettist', metadata.Text('Da Ponte')) Unusual roles need to be passed with "otherContributor" and role already defined. (Essentially, make your own) >>> metadata.Metadata.convertValue('otherContributor', ... metadata.Contributor(role='conceptual-artist', name='Robert Wilson')) Converts certain named values to DateSingle: >>> metadata.Metadata.convertValue('dateCreated', '1938') >>> metadata.Metadata.convertValue('dateCreated', metadata.Text('1938/02')) Datetime objects, like this one for the Rite of Spring riot, also get converted. >>> from datetime import datetime >>> dt = datetime(1913, 5, 29) >>> metadata.Metadata.convertValue('dateCreated', dt) For DateBetween objects one must pass their own already created primitive (so no need to use this) >>> metadata.Metadata.convertValue('dateCreated', ... metadata.DateBetween(['1938', '1939'])) * Added in v10 -- newly exposed as a public function (was private) Nzinvalid type for Copyright: zinvalid type for DateSingle: )rrNzinvalid type for Contributor: zinvalid type for int: z!internal error: invalid valueType)rUNIQUE_NAME_TO_VALUE_TYPEr[rrr,rr rtyper0r datetimer rrrr*)r\rF valueType originalValuees r7r1zMetadata.convertValue s:L+5*N*N*R*R +  %  I eY 'L  %%E{"E # #  !%% ''%& ''00.tE{/C/C.DEG G  %%&E %/ %#x'8'8$!?@4%e,, 00/U 0D0D/EFH H  #%%U %&" ??000e1E1E0FGI I   L5z! ,,-PQQ1"4M 2334( L"44,T%[-A-A,BCEJKL Ls*4 G> H!>HH! I*,IIreturnNone)rNr,rFt.Any | Iterable[t.Any]r?r@)rNr,r?tuple[ValueType, ...])rNr,rFrA)r\r,r? str | None)r`r,r?rC)r\rCr?bool)rNr,r?rDr?tuple[str, ...])r?tuple[Contributor, ...])rFr,r?r@ rrDrsrDrtrDrurDr?ztuple[tuple[str, t.Any], ...])rNr,rFt.Any)r#z4t.Literal['movementName', 'movementNumber', 'title']r?tuple[Text, ...])r#zt.Literal['copyright',]r?ztuple[Copyright, ...])r#r,r?rJ)r#r,r?z(tuple[ValueType, ...] | tuple[Text, ...])r#r,rFrA)rr)rrCr?rG)NN)rz0str | t.Pattern | t.Callable[[str], bool] | NonerrCr?ztuple[bool, str | None])rFz Iterable[str]r?r@)r?rC)r`r,r?rF)r!r,r?rF)r!r,r?rCr\r,r?rD)r`r,r?rD)rrCr?r,)rNr,rJrDr?rB)rNr,rFrArJrD)r\r,rFrIr?r)?r0r1r2r3classSortOrderr>rOrSrUrX staticmethodr]rarhrlpropertyr:r|r~setterrvrrrrrrrrrrrrrrrrrrrrrrrrrrr rrrorrkrjrrrrrQrLrWr1 __classcell__rGs@r7rrs7vN/2'/'/('/'/R.6.:.>NN2QQ0#"#"JD442>2727h&+(-%*!% V#V"& V # V  V 'Vp<0|I)X  +     0    -.^.2,1\+^=Am9mm  mP > >&& 664__ 448 992!! 88   66__ << $$ 88    A A) )  8 8   6 6!! 66$__  4 4  : :""  < <$$ 44, ]] 88,   3 3 \\ --d59n+5Z4Hl3 j"LH''R$"$"L/"/"b#.#.J++Z <&@R/-bHRHRr6rceZdZdZdZd fd Zdfd ZddZddZdZ dddd d  dfd Z dfd Z xZ S)ra 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', 'scoreQuarterLength', 'sourcePath', 'tempoFirst', 'tempos', 'timeSignatureFirst', 'timeSignatures') * Changed in v10: renamed `quarterLength` to `scoreQuarterLength`. Because RichMetadata is a Music21Object, `quarterLength` is a property that must return the length of the RichMetadata object itself and should not have been ovewritten ) ambituskeySignatureFirst keySignatures noteCount numberOfPartsr/r.scoreQuarterLength sourcePath tempoFirsttempostimeSignatureFirsttimeSignaturesc t|di|d|_d|_g|_d|_d|_d|_d|_d|_ d|_ d|_ g|_ d|_ g|_y)Ngrr5)r=r>rSrTrUrVrWr/r.rXrYrZr[r\r])rArBrGs r7r>zRichMetadata.__init__ sv $8$*. 8<57#'!&*%),/6:35 <@9;r6ct||jvrt||}| tS|fSt||Sr) additionalRichMetadataAttributesgetattrrxr=ro)rAr!rFrGs r7roz RichMetadata._getPluralAttribute sD DAA AD-0E}w8Ow*=99r6Fcdg}tjdg|D]1}t||}||r |t||}| t|||3y#t$rY@wxYw)ao 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' r?zRichMetadata: calling merge()N) environLocal printDebugrar@r)rAother favorSelf localNamesrN localValue otherValues r7mergezRichMetadata.merge s$   !@ ABD t,J%)(%,UD%9 %1#D$ ;&sA AAc|jsy|j}|jr |jS|j}|syt|tj st j |} |j tj}|jS#t$r|jcYSwxYw)a% 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' r) r(rrrpathlibPath relative_torgetCorpusFilePathas_posixr)rA streamObjmdstreamFp relativePaths r7 getSourcePathzRichMetadata.getSourcePath s!!     $$ $;;(GLL1||H-H '#//0H0H0JKL((* * '$$& & 's12B$$C?Ccddlm}ddlm}ddlm}tj dg|j j}t|j|_ d|_ g|_ d|_ g|_d|_g|_|j#||_|D]}t'||j(r7|j*}||j vs4|j j-|Pt'||j.r?|j0|jvs|jj-|j0t'||j2st5|}||jvs|jj-||j r|j d|_|jr|jd|_ |jr|jd|_ t|j6|_|j:|_ddlm } d|_!d|_"d|_#| jI|} | jJB| jL6| jJjN|_#| jLjN|_"| jQ|} | tSjTd} tW| jX| jZj\|jF|jD |_!y) 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 rr"r$r&zRichMetadata: update(): startN)discreteP1)r+r-r.r/)/music21r#r%r'rcrdflattenrrpartsrWrTrUrZr[r\r]rurYr TimeSignature ratioStringrw KeySignaturerTempoIndicationr, notesAndRestsrV highestTimerXmusic21.analysisrwrSr/r.Ambitus minPitchObj maxPitchObjnameWithOctave getSolutionr!Intervalrr+r- simpleName) rArqr#r%r'flatelementr}tempoIndicationStringrwanalysisObjectambitusIntervals r7updatezRichMetadata.update? s{& !!!@ AB  "))+ 1!% "& ,,Y7G'5#6#67%11 d&9&99''..{;GS%5%56>>););;&&--gnn=GU%:%:;(+G %( ;KK&&'<=   &*&9&9!&>> 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)listr=rvrxr`rwrar)rArrsrtrurrNrGs r7rvzRichMetadata.all st+/uw{- 3-% 0;0'+( = 99D MM4t!45 6: ( (V}r6cDt||ry||jvryy)a 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)r=rkr`)rAr\rGs r7rkz"RichMetadata._isStandardUniqueName s*B 7 ( 4 >> >r6r>rE)F)r?r,rHrK) r0r1r2r3r`r>rorjrurrvrkrPrQs@r7rr sB($$< :"H'>W&x&+(-%*!% K#K"& K # K  K 'KZ%%r6rr _DOC_ORDER__main__)9r3 __future__r__all__collections.abcrr:rlrtypingrrryrrmusic21.common.typesrrrrr r!music21.metadatarrrmusic21.metadata.primitivesrrr r r r r rrrrrrmusic21.metadata.propertiesr TYPE_CHECKINGr#r%r' Environmentrc NamedTupler Music21Objectrrrr4r0mainTestr5r6r7rsul# 4% 3 $$'    (;??'{&&z2  1<< K#Rt!!K#R^Fa8aL !, = H= zGr6