Previous topic

music21.metadata.caching

Next topic

music21.meter

Table Of Contents

Table Of Contents

This Page

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.

>>> from music21 import metadata
>>> 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.

>>> from music21 import metadata
>>> 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.

>>> from music21 import metadata
>>> 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

>>> from music21 import metadata
>>> 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:

>>> from music21 import metadata
>>> 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:

>>> from music21 import metadata
>>> 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.

>>> from music21 import metadata
>>> metadata.Date.errorToSymbol('approximate')
'~'
>>> metadata.Date.errorToSymbol('uncertain')
'?'
Date.load(value)

Load values by string, datetime object, or Date object:

>>> from music21 import metadata
>>> 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)
>>> from music21 import metadata
>>> m21mdDate = metadata.Date()
>>> m21mdDate.loadDatetime(dt)
>>> str(m21mdDate)
'2005/02/01'
Date.loadOther(other)

Load values based on another Date object:

>>> from music21 import metadata
>>> 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:

>>> from music21 import metadata
>>> d = metadata.Date()
>>> d.loadStr('3030?/12~/?4')
>>> d.month, d.monthError
(12, 'approximate')
>>> d.year, d.yearError
(3030, '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.

>>> from music21 import metadata
>>> 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.

>>> from music21 import metadata
>>> 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.

>>> from music21 import metadata
>>> 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

DateRelative read-only properties

Read-only properties inherited from DateSingle:

DateRelative read/write properties

DateRelative.relevance

DateBetween

class music21.metadata.primitives.DateBetween(data=[], relevance='between')

Store a relative date, sometime between two dates:

>>> from music21 import metadata
>>> 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

DateBetween read-only properties

Read-only properties inherited from DateSingle:

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

>>> from music21 import metadata
>>> 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

DateSelection read-only properties

Read-only properties inherited from DateSingle:

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.

>>> from music21 import metadata
>>> 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.

>>> from music21 import metadata
>>> 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.

>>> from music21 import metadata
>>> 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.

>>> from music21 import metadata
>>> 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:

>>> from music21 import metadata
>>> 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.

>>> from music21 import metadata
>>> 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:

>>> from music21 import metadata
>>> metadata.Contributor.roleToAbbreviation('composer')
'com'

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.

>>> from music21 import metadata
>>> td = metadata.Creator(role='composer', name='Chopin, Fryderyk')
>>> td.role
'composer'
>>> td.name
'Chopin, Fryderyk'
>>> td.relevance
'creator'

Creator bases

Creator read-only properties

Read-only properties inherited from Contributor:

Creator read/write properties

Read/write properties inherited from Contributor:

Creator methods

Methods inherited from Contributor:

Imprint

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

An object representation of imprint, or publication.