music21.metadata.primitives

Text

class music21.metadata.primitives.Text(data: str | Text = '', language: str | None = None, isTranslated: bool | None = None, encodingScheme: str | None = 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 bases

Text read-only properties

Read-only properties inherited from ProtoM21Object:

Text read/write properties

Text.language

Set the language of the Text stored within.

>>> myText = metadata.Text('my text')
>>> myText.language = 'en'
>>> myText.language
'en'

Text methods

Text.__eq__(other) → bool
>>> t1 = metadata.Text('some text')
>>> t2 = metadata.Text('some text')
>>> t1 == t2
True

Language, isTranslated, and encodingScheme must all exactly match for equality.

>>> t2 = metadata.Text('some text', language='en')
>>> t1 == t2
False
>>> t2 = metadata.Text('some text', isTranslated=True)
>>> t1 == t2
False
>>> t2 = metadata.Text('some text', encodingScheme='scheme42')
>>> t1 == t2
False

Comparison with non-Text types, including bare strings, will always be considered unequal.

>>> t1 == 'some text'
False
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'

Methods inherited from ProtoM21Object:

Date

class music21.metadata.primitives.Date(*, year: int | str | None = None, month: int | str | None = None, day: int | str | None = None, hour: int | str | None = None, minute: int | str | None = None, second: int | float | str | None = None, yearError: str | None = None, monthError: str | None = None, dayError: str | None = None, hourError: str | None = None, minuteError: str | None = None, secondError: str | None = None)

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.

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

>>> d = metadata.Date(year=1805, month=3, monthError='approximate')
>>> str(d)
'1805/03~/--'

Note that milliseconds are not retained, as this is a tool for musicology and not for file timestamps. However, unlike datetime objects, dates in the distant past are supported (though not currently BC/BCE dates).

Date bases

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: function missing required 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

Read-only properties inherited from ProtoM21Object:

Date methods

Date.__eq__(other) → bool

Return self==value.

static Date.errorToSymbol(value)

Convert an error string (approximate, uncertain) into a symbol.

>>> metadata.Date.errorToSymbol('approximate')
'~'

>>> metadata.Date.errorToSymbol('uncertain')
'?'
Date.load(value: Date | datetime | str)

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

If there is an error, a ValueError is raised, but the incorrect values are retained:

>>> d = metadata.Date()
>>> d.load('1999/14/32/25:60:61')
Traceback (most recent call last):
ValueError: Month must be between 1 and 12, not 14.
>>> str(d)
'1999/14/32/25:60:61'
Date.loadDatetime(dt: datetime) → None

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: Date) → None

Load values based on another Date object. (the “Other” in “loadOther” means another Date object, not just anything.

>>> a = metadata.Date(year=1843, month=3, day=3, yearError='approximate')
>>> b = metadata.Date()
>>> b.loadOther(a)
>>> b.year
1843
>>> b.yearError
'approximate'
Date.loadStr(dateStr: str) → None

Load a string date representation, which might have approximate symbols.

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)

Methods inherited from ProtoM21Object:

DateSingle

class music21.metadata.primitives.DateSingle(data: Date | datetime | str = '', 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')
>>> dd
<music21.metadata.primitives.DateSingle 2009/12/31>

>>> str(dd)
'2009/12/31'

>>> dd.relevance
'approximate'

>>> dd = metadata.DateSingle('1805/3/12', 'uncertain')
>>> str(dd)
'1805/03/12'

DateSingle bases

DateSingle read-only properties

Read-only properties inherited from DatePrimitive:

Read-only properties inherited from ProtoM21Object:

DateSingle read/write properties

Read/write properties inherited from DatePrimitive:

DateSingle methods

Methods inherited from DatePrimitive:

Methods inherited from ProtoM21Object:

DateRelative

class music21.metadata.primitives.DateRelative(data: Date | datetime | str = '', 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 DatePrimitive:

Read-only properties inherited from ProtoM21Object:

DateRelative read/write properties

DateRelative.relevance

The relevance attribute takes one of four values, ‘prior’, ‘after’, or ‘onorbefore’ or ‘onorafter’.

DateRelative methods

Methods inherited from DatePrimitive:

Methods inherited from ProtoM21Object:

DateBetween

class music21.metadata.primitives.DateBetween(data: Iterable[Date | datetime | str] = (), 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'

>>> d1 = metadata.Date(year=1605)
>>> d2 = metadata.Date(year=1608, month='11?')
>>> dd = metadata.DateBetween([d1, d2])
>>> str(dd)
'1605/--/-- to 1608/11?/--'

DateBetween bases

DateBetween read-only properties

Read-only properties inherited from DatePrimitive:

Read-only properties inherited from ProtoM21Object:

DateBetween read/write properties

DateBetween.relevance

The relevance attribute takes only one value: ‘between’.

DateBetween methods

Methods inherited from DatePrimitive:

Methods inherited from ProtoM21Object:

DateSelection

class music21.metadata.primitives.DateSelection(data: Iterable[Date | datetime | str] = (), 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'],
...     )
>>> str(dd)
'2009/12/31 or 2010/01/28 or 1894/01/28'

>>> dd = metadata.DateSelection(
...     [1750, '1775/03?'],
...     'and'
...     )
>>> str(dd)
'1750/--/-- and 1775/03?/--'

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

Note that ‘1350 or 1351 and 1375’ is not supported yet.

DateSelection bases

DateSelection read-only properties

Read-only properties inherited from DatePrimitive:

Read-only properties inherited from ProtoM21Object:

DateSelection read/write properties

DateSelection.relevance

The relevance attribute takes only two values: ‘or’ or ‘and’.

DateSelection methods

Methods inherited from DatePrimitive:

Methods inherited from ProtoM21Object:

Contributor

class music21.metadata.primitives.Contributor(*, name: str | Text | None = None, names: Iterable[str | Text] = (), role: str | Text | None = None, birth: None | DateSingle | str = None, death: None | DateSingle | str = None, **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 bases

Contributor read-only properties

Read-only properties inherited from ProtoM21Object:

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'

In case of a Humdrum role abbreviation, the role that is set is the full name:

>>> td.role = 'lor'
>>> td.role
'orchestrator'

Roles can be created on the fly:

>>> td.role = 'court jester'
>>> td.role
'court jester'

Contributor methods

Contributor.__eq__(other) → bool
>>> c1 = metadata.Contributor(
...         role='composer',
...         name='The Composer',
...         birth='1923',
...         death='2013'
... )
>>> c2 = metadata.Contributor(
...         role='composer',
...         name='The Composer',
...         birth='1923',
...         death='2013'
... )

Names, role, birth, and death must all be identical for equality.

>>> c1 == c2
True
>>> c2.role = 'lyricist'
>>> c1 == c2
False
>>> c2 = metadata.Contributor(
...         role='composer',
...         name='A Composer',
...         birth='1923',
...         death='2013'
... )
>>> c1 == c2
False
>>> c2 = metadata.Contributor(
...         role='composer',
...         names=['A Composer', 'The Composer'],
...         birth='1923',
...         death='2013'
... )
>>> c1 == c2
False
>>> c2 = metadata.Contributor(
...         role='composer',
...         name='The Composer',
...         birth='1924',
...         death='2013'
... )
>>> c1 == c2
False
>>> c2 = metadata.Contributor(
...         role='composer',
...         name='The Composer',
...         birth='1923',
...         death='2012'
... )
>>> c1 == c2
False

Comparison with a non-Contributor object always returns False.

>>> c1 == 'The Composer'
False
static Contributor.abbreviationToRole(abbreviation)

Convert abbreviation to role name:

>>> metadata.Contributor.abbreviationToRole('com')
'composer'

>>> metadata.Contributor.abbreviationToRole('lib')
'librettist'
Contributor.age() → timedelta | None

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.birth
<music21.metadata.primitives.DateSingle 1770/12/17>

>>> a.age()
datetime.timedelta(days=20552)

>>> a.age().days
20552

>>> years = a.age().days // 365
>>> years
56

If the composer is still alive, it returns the composer’s current age.

>>> shaw = metadata.Contributor(
...     name='Shaw, Caroline',
...     role='composer',
...     birth='1982/08/01',
...     )
>>> shaw_years = shaw.age().days // 365

This test will fail in 2067:

>>> 36 < shaw_years < 85
True
static Contributor.roleToAbbreviation(roleName)

Convert roleName to role abbreviation:

>>> metadata.Contributor.roleToAbbreviation('composer')
'com'

Methods inherited from ProtoM21Object:

Creator

class music21.metadata.primitives.Creator(*, name: str | Text | None = None, names: Iterable[str | Text] = (), role: str | Text | None = None, birth: None | DateSingle | str = None, death: None | DateSingle | str = None, **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-only properties

Read-only properties inherited from ProtoM21Object:

Creator read/write properties

Read/write properties inherited from Contributor:

Creator methods

Methods inherited from Contributor:

Methods inherited from ProtoM21Object:

DatePrimitive

class music21.metadata.primitives.DatePrimitive(relevance: str = 'certain')

A default class for all date objects, which can have different types and different “relevance” values.

Note that the interaction between uncertainty on an entire DatePrimitive object vs uncertainty on a particular Date value, like month, is ill-defined and needs work.

DatePrimitive bases

DatePrimitive read-only properties

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

Read-only properties inherited from ProtoM21Object:

DatePrimitive read/write properties

DatePrimitive.relevance

The relevance attribute takes one of three values, ‘certain’, ‘approximate’, or ‘uncertain’.

DatePrimitive methods

DatePrimitive.__eq__(other) → bool
>>> dd = metadata.DateSingle('1805/3/12', 'uncertain')
>>> dd2 = metadata.DateSingle('1805/3/12', 'uncertain')
>>> str(dd)
'1805/03/12'
>>> dd == dd2
True
>>> dd2.relevance='certain'
>>> dd == dd2
False

Methods inherited from ProtoM21Object:

Imprint

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

An object representation of imprint, or publication.

Imprint bases

Imprint read-only properties

Read-only properties inherited from ProtoM21Object:

Imprint methods

Methods inherited from ProtoM21Object: