music21.metadata.primitives¶
Text¶
-
class
music21.metadata.primitives.Text(data='', language=None)¶ One unit of text data: a title, a name, or some other text data. Store the string and a language name or code. This object can be used and/or subclassed for a variety for of text storage.
>>> td = metadata.Text('concerto in d', 'en') >>> str(td) 'concerto in d' >>> td.language 'en'
Text read/write properties
-
Text.language¶ Set the language of the Text stored within.
>>> t = metadata.Text('my text') >>> t.language = 'en' >>> t.language 'en'
Text methods
-
Text.getNormalizedArticle()¶ Return a string representation with normalized articles.
>>> td = metadata.Text('Ale is Dear, The', language='en') >>> str(td) 'Ale is Dear, The'
>>> td.getNormalizedArticle() 'The Ale is Dear'
The language will determine whether the article is moved:
>>> td.language = 'de' >>> td.getNormalizedArticle() 'Ale is Dear, The'
Date¶
-
class
music21.metadata.primitives.Date(*args, **keywords)¶ A single date value, specified by year, month, day, hour, minute, and second. Note that this class has been created, instead of using Python’s datetime, to provide greater flexibility for processing unconventional dates, ancient dates, dates with error, and date ranges.
The
datetimeproperty can be used to retrieve a datetime object when necessary.Additionally, each value can be specified as uncertain or approximate; if None, assumed to be certain.
Data objects are fundamental components of
DateSingleand related subclasses that represent single dates and date ranges.>>> a = metadata.Date(year=1843, yearError='approximate') >>> a.year 1843
>>> a.yearError 'approximate'
>>> a = metadata.Date(year='1843?') >>> a.yearError 'uncertain'
Date read-only properties
-
Date.datetime¶ Get a datetime object from a metadata.Date() object
>>> a = metadata.Date(year=1843, month=3, day=3) >>> str(a) '1843/03/03'
>>> a.datetime datetime.datetime(1843, 3, 3, 0, 0)
Lack of a required date element raises an exception:
>>> a = metadata.Date(year=1843, month=3) >>> str(a) '1843/03/--'
>>> a.datetime Traceback (most recent call last): TypeError: ...argument 'day' (pos 3)...
-
Date.hasError¶ Return True if any data points have error defined:
>>> a = metadata.Date( ... year=1843, ... month=3, ... day=3, ... dayError='approximate', ... ) >>> a.hasError True
>>> b = metadata.Date( ... year=1843, ... month=3, ... day=3, ... minute=3, ... ) >>> b.hasError False
-
Date.hasTime¶ Return True if any time elements are defined:
>>> a = metadata.Date(year=1843, month=3, day=3) >>> a.hasTime False
>>> b = metadata.Date(year=1843, month=3, day=3, minute=3) >>> b.hasTime True
Date methods
-
static
Date.errorToSymbol(value)¶ Convert an error string (approximate, uncertain) into a symbol.
>>> metadata.Date.errorToSymbol('approximate') '~'
>>> metadata.Date.errorToSymbol('uncertain') '?'
-
Date.load(value)¶ Load values by string, datetime object, or Date object:
>>> a = metadata.Date(year=1843, month=3, day=3) >>> b = metadata.Date() >>> b.load(a) >>> b.year 1843
-
Date.loadDatetime(dt)¶ Load time data from a datetime object:
>>> import datetime >>> dt = datetime.datetime(2005, 2, 1) >>> dt datetime.datetime(2005, 2, 1, 0, 0)
>>> m21mdDate = metadata.Date() >>> m21mdDate.loadDatetime(dt) >>> str(m21mdDate) '2005/02/01'
-
Date.loadOther(other)¶ Load values based on another Date object:
>>> a = metadata.Date(year=1843, month=3, day=3) >>> b = metadata.Date() >>> b.loadOther(a) >>> b.year 1843
-
Date.loadStr(dateStr)¶ Load a string date representation.
Assume year/month/day/hour:minute:second:
>>> d = metadata.Date() >>> d.loadStr('1030?/12~/?4') >>> d.month, d.monthError (12, 'approximate')
>>> d.year, d.yearError (1030, 'uncertain')
>>> d.month, d.monthError (12, 'approximate')
>>> d.day, d.dayError (4, 'uncertain')
>>> d = metadata.Date() >>> d.loadStr('1834/12/4/4:50:32') >>> d.minute, d.second (50, 32)
DateSingle¶
-
class
music21.metadata.primitives.DateSingle(data='', relevance='certain')¶ Store a date, either as certain, approximate, or uncertain relevance.
The relevance attribute is limited within each DateSingle subclass depending on the design of the class. Alternative relevance types should be configured as other DateSingle subclasses.
>>> dd = metadata.DateSingle('2009/12/31', 'approximate') >>> str(dd) '2009/12/31'
>>> dd.relevance 'approximate'
>>> dd = metadata.DateSingle('1805/3/12', 'uncertain') >>> str(dd) '1805/03/12'
DateSingle read-only properties
-
DateSingle.datetime¶ Get a datetime object.
>>> a = metadata.DateSingle('1843/03/03') >>> str(a) '1843/03/03'
>>> a.datetime datetime.datetime(1843, 3, 3, 0, 0)
>>> a = metadata.DateSingle('1843/03') >>> str(a) '1843/03/--'
DateSingle read/write properties
-
DateSingle.relevance¶ The relevance attribute takes one of three values, ‘certain’, ‘approximate’, or ‘uncertain’.
DateRelative¶
-
class
music21.metadata.primitives.DateRelative(data='', relevance='after')¶ Store a relative date, sometime prior or sometime after, onorbefore, or onorafter`.
>>> dd = metadata.DateRelative('2009/12/31', 'prior') >>> str(dd) 'prior to 2009/12/31' >>> dd.relevance = 'after' >>> str(dd) 'after 2009/12/31'
>>> dd = metadata.DateRelative('2009/12/31', 'certain') Traceback (most recent call last): music21.exceptions21.MetadataException: Relevance value is not supported by this object: 'certain'
DateRelative bases
DateRelative read-only properties
Read-only properties inherited from DateSingle:
DateRelative read/write properties
-
DateRelative.relevance¶ The relevance attribute takes one of four values, ‘prior’, ‘after’, or ‘onorbefore’ or ‘onorafter’.
DateBetween¶
-
class
music21.metadata.primitives.DateBetween(data=None, relevance='between')¶ Store a relative date, sometime between two dates:
>>> dd = metadata.DateBetween(['2009/12/31', '2010/1/28']) >>> str(dd) '2009/12/31 to 2010/01/28'
>>> dd = metadata.DateBetween(['2009/12/31', '2010/1/28'], 'certain') Traceback (most recent call last): music21.exceptions21.MetadataException: Relevance value is not supported by this object: 'certain'
DateBetween bases
DateBetween read-only properties
Read-only properties inherited from DateSingle:
DateBetween read/write properties
-
DateBetween.relevance¶ The relevance attribute takes only one value: ‘between’.
DateSelection¶
-
class
music21.metadata.primitives.DateSelection(data='', relevance='or')¶ Store a selection of dates, or a collection of dates that might all be possible
>>> dd = metadata.DateSelection( ... ['2009/12/31', '2010/1/28', '1894/1/28'], ... 'or', ... ) >>> str(dd) '2009/12/31 or 2010/01/28 or 1894/01/28'
>>> dd = metadata.DateSelection( ... ['2009/12/31', '2010/1/28'], ... 'certain', ... ) Traceback (most recent call last): music21.exceptions21.MetadataException: Relevance value is not supported by this object: 'certain'
DateSelection bases
DateSelection read-only properties
Read-only properties inherited from DateSingle:
DateSelection read/write properties
-
DateSelection.relevance¶ The relevance attribute takes only one value: ‘or’.
Contributor¶
-
class
music21.metadata.primitives.Contributor(*args, **keywords)¶ A person that contributed to a work. Can be a composer, lyricist, arranger, or other type of contributor. In MusicXML, these are “creator” elements.
>>> td = metadata.Contributor(role='composer', name='Chopin, Fryderyk') >>> td.role 'composer'
>>> td.name 'Chopin, Fryderyk'
>>> td.relevance 'contributor'
>>> td <music21.metadata.primitives.Contributor composer:Chopin, Fryderyk>
Contributor read/write properties
-
Contributor.name¶ Returns the text name, or the first of many names entered.
>>> td = metadata.Contributor( ... role='composer', ... names=['Chopin, Fryderyk', 'Chopin, Frederick'], ... ) >>> td.name 'Chopin, Fryderyk'
>>> td.names ['Chopin, Fryderyk', 'Chopin, Frederick']
-
Contributor.names¶ Returns all names in a list.
>>> td = metadata.Contributor( ... role='composer', ... names=['Chopin, Fryderyk', 'Chopin, Frederick'], ... ) >>> td.names ['Chopin, Fryderyk', 'Chopin, Frederick']
>>> td.names = ['Czerny', 'Spohr'] >>> td.names ['Czerny', 'Spohr']
-
Contributor.role¶ The role is what part this Contributor plays in the work. Both full roll strings and roll abbreviations may be used.
>>> td = metadata.Contributor() >>> td.role = 'composer' >>> td.role 'composer'
>>> td.role = 'lor' >>> td.role 'orchestrator'
Roles can be created on the fly:
>>> td.role = 'court jester' >>> td.role 'court jester'
Contributor methods
-
static
Contributor.abbreviationToRole(abbreviation)¶ Convert abbreviation to role name:
>>> metadata.Contributor.abbreviationToRole('com') 'composer'
>>> metadata.Contributor.abbreviationToRole('lib') 'librettist'
-
Contributor.age()¶ Calculate the age at death of the Contributor, returning a datetime.timedelta object.
>>> a = metadata.Contributor( ... name='Beethoven, Ludwig van', ... role='composer', ... birth='1770/12/17', ... death='1827/3/26', ... ) >>> a.role 'composer'
>>> a.age().days 20552
>>> str(a.age()) '20552 days, 0:00:00'
>>> a.age().days // 365 56
-
static
Contributor.roleToAbbreviation(roleName)¶ Convert roleName to role abbreviation:
>>> metadata.Contributor.roleToAbbreviation('composer') 'com'
Copyright¶
-
class
music21.metadata.primitives.Copyright(data='', language=None, *, role=None)¶ A subclass of text that can also have a role
>>> copyleft = metadata.primitives.Copyright('Copyright 1969 Cuthbert', ... role='fictitious') >>> copyleft <music21.metadata.primitives.Copyright Copyright 1969 Cuthbert> >>> copyleft.role 'fictitious' >>> str(copyleft) 'Copyright 1969 Cuthbert'
Copyright bases
Copyright read/write properties
Read/write properties inherited from Text:
Copyright methods
Methods inherited from Text:
Creator¶
-
class
music21.metadata.primitives.Creator(*args, **keywords)¶ A person that created a work. Can be a composer, lyricist, arranger, or other type of contributor.
In MusicXML, these are “creator” elements.
>>> td = metadata.Creator(role='composer', name='Chopin, Fryderyk') >>> td.role 'composer'
>>> td.name 'Chopin, Fryderyk'
>>> td.relevance 'creator'
Creator bases
Creator read/write properties
Read/write properties inherited from Contributor:
Creator methods
Methods inherited from Contributor: