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'

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', 'en')
>>> str(td)
'Ale is Dear, The'

>>> td.getNormalizedArticle()
'The Ale is Dear'

>>> 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 datetime property 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 DateSingle and 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: Required argument 'day' (pos 3) not found

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

DateRelative

class music21.metadata.primitives.DateRelative(data='', relevance='after')

Store a relative date, sometime prior or sometime after.

>>> dd = metadata.DateRelative('2009/12/31', 'prior')
>>> str(dd)
'2009/12/31'

>>> dd = metadata.DateRelative('2009/12/31', 'certain')
Traceback (most recent call last):
MetadataException: Relevance value is not supported by this object: 'certain'

DateRelative bases

• DateSingle

DateRelative read-only properties

Read-only properties inherited from DateSingle:

datetime

DateRelative read/write properties

DateRelative.relevance

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):
MetadataException: Relevance value is not supported by this object: 'certain'

DateBetween bases

• DateSingle

DateBetween read-only properties

Read-only properties inherited from DateSingle:

datetime

DateBetween read/write properties

DateBetween.relevance

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):
MetadataException: Relevance value is not supported by this object: 'certain'

DateSelection bases

• DateSingle

DateSelection read-only properties

Read-only properties inherited from DateSingle:

datetime

DateSelection read/write properties

DateSelection.relevance

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'

Contributor read-only properties

Contributor.names

Returns all names in a list.

>>> td = metadata.Contributor(
...     role='composer',
...     names=['Chopin, Fryderyk', 'Chopin, Frederick'],
...     )
>>> td.names
['Chopin, Fryderyk', 'Chopin, Frederick']

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.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'

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()
datetime.timedelta(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(*args, **keywords)

An object representation of copyright.

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

• Contributor

Creator read-only properties

Read-only properties inherited from Contributor:

names

Creator read/write properties

Read/write properties inherited from Contributor:

name

role

Creator methods

Methods inherited from Contributor:

abbreviationToRole()

age()

roleToAbbreviation()

Imprint

class music21.metadata.primitives.Imprint(*args, **keywords)

An object representation of imprint, or publication.