Key

Key(
    tonic: TonalVector | None,
    signature: KeySignature | None,
    tones: ToneCollection = ToneCollection(),
    mode: ModePattern | None = None,
    name: str | None = None,
)

A key in the tonal or modal system: WSMN’s ModalContext.

tonic is None when no tonality is asserted. That is either “no key” (atonal music, unpitched parts: symbols.NoKey, which also has no signature, corresponding to MusicXML <mode>none</mode>), or a bare signature such as “three flats” that is not saying E-flat major or C minor (see from_signature). The two differ under transposition: a bare signature moves with the music; no key stays no key.

>>> from openmusickit.systems.wsmn.tonal.symbols import D, Major, NoKey
>>> d = Key.of(D, Major)
>>> d.name, d.signature
('D Major', KeySignature(c=1, f=1))
>>> [format(t) for t in d.tones]
['D', 'E', 'F♯', 'G', 'A', 'B', 'C♯']
>>> NoKey.tonic is None, NoKey.name
(True, 'No Key')

Attributes

Name	Description
__slots__
tonic
signature
tones
mode
name

Methods

Name	Description
of	Convenience constructor for Key.
from_signature	A key signature asserting no tonality: the alterations, and nothing else.
transform	Returns a new Key made by applying operation to this key’s tonic

of

of(tonic: TonalVector, mode: ModePattern, signature: KeySignature | None = None)

Convenience constructor for Key.

The key’s tones are the mode pattern transposed to the tonic. If signature is not given, it is derived from those tones: each letter takes the alteration of its tone in the key, and letters not present in the mode (e.g. in a pentatonic mode) stay natural.

Raises ValueError if the same letter occurs with different alterations (e.g. a mode containing both F and F#); pass signature explicitly in that case.

Examples

>>> from openmusickit.systems.wsmn.tonal.symbols import C, Eb, Fx, Major, Minor

>>> c = Key.of(C, Major)
>>> c.name, c.mode.name, c.signature
('C Major', 'Major', KeySignature())
>>> [t.pitch.unicode for t in c.tones]
['C', 'D', 'E', 'F', 'G', 'A', 'B']

>>> Key.of(Eb, Major).signature
KeySignature(e=-1, a=-1, b=-1)

>>> fs = Key.of(Fx, Minor)
>>> fs.name, fs.signature.fifths
('F♯ Minor', 3)
>>> fs.tones.root is Fx
True

An explicit signature is used as given, without inspection:

>>> Key.of(C, Major, KeySignature.from_alts(-1)).signature
KeySignature(b=-1)

from_signature

from_signature(signature: KeySignature)

A key signature asserting no tonality: the alterations, and nothing else.

>>> three_flats = Key.from_signature(KeySignature.from_alts(-3))
>>> three_flats.name, three_flats.tonic, len(three_flats.tones)
('3 flats', None, 0)

An empty signature is still a signature, unlike NoKey:

>>> from openmusickit.systems.wsmn.tonal.symbols import NoKey
>>> Key.from_signature(KeySignature()).name, NoKey.signature
('no sharps or flats', None)

transform

transform(operation: Callable[..., TonalVector], *args, **kwargs)

Returns a new Key made by applying operation to this key’s tonic (and to its tones and signature).

If the key has a mode pattern, the new key is that mode on the new tonic (as in Key.of), with the signature transformed alongside so that an explicitly given signature is carried over. Otherwise the tones and signature are transformed directly. A bare signature (no tonic) is transformed letter by letter; NoKey has nothing to transform and is returned as it is.

For operations other than transposition, “keep the mode” and “transform the tones” can disagree (C Major inverted about C is C Major by the first rule and C Phrygian by the second); the mode is kept.

Examples

>>> from openmusickit.systems.wsmn.tonal.symbols import C, M2, Major, NoKey
>>> Key.of(C, Major).transform(TonalVector.transpose, M2).name
'D Major'
>>> NoKey.transform(TonalVector.transpose, M2) == NoKey
True
>>> from openmusickit.systems.wsmn.tonal.symbols import m3
>>> Key.from_signature(KeySignature()).transform(TonalVector.transpose, m3).signature
KeySignature(e=-1, a=-1, b=-1)