KeySignature

KeySignature()

Representation of the flat or sharp alterations of a key signature, in semitones up or down from natural: - Sharps are positive, flats are negative - Handles double and triple sharps and flats - Use a Fraction for a microtone: f=Fraction(1, 2) is a quarter-tone sharp

An alteration is exact, so a float is refused; a whole-number Fraction is stored as the int it equals.

Positional order is C, D, E, F, G, A, B; each letter name is also available as a property.

Examples

>>> ks = KeySignature()
>>> ks.c, ks.b
(0, 0)

>>> ks = KeySignature(c=1, f=1)
>>> ks.f, ks.g
(1, 0)

>>> ks = KeySignature(e=-1, a=-1, b=-1)
>>> ks.e, ks.d
(-1, 0)

>>> ks = KeySignature(c=-1, d=-1, e=-2, f=-1, g=-1, a=-2, b=-2) # double flats
>>> ks.e, ks.f
(-2, -1)

>>> ks = KeySignature(f=1, b=-1) # non-standard key signatures
>>> ks.f, ks.b
(1, -1)

Beyond a triple sharp or flat there is no signature:

>>> KeySignature(f=4)
Traceback (most recent call last):
...
ValueError: Key signature alterations must be between -3 and 3

>>> KeySignature(f=Fraction(1, 2)).f, KeySignature(f=Fraction(2, 2)).f
(Fraction(1, 2), 1)
>>> KeySignature(f=0.5)
Traceback (most recent call last):
...
TypeError: A key signature alteration cannot be a float (0.5); use an int or a Fraction.

Raises

Name	Type	Description
	TypeError	if an alteration is a float.
	ValueError	if an alteration is beyond a triple sharp or flat.

Attributes

Name	Description
c
d
e
f
g
a
b
fifths	Returns the MusicXML representation of the key signature, which walks around the circle of fifths.

Methods

Name	Description
__new__
from_alts	Create a key signature by specifying the number of sharps (positive int) or flats (negative int).
transform	Returns a new KeySignature made by applying operation to each of the
transpose	Returns this key signature transposed by the interval x: each letter
__repr__	Only non-zero alterations are shown, matching how a KeySignature is typically constructed.

__new__

__new__(
    c: int | Fraction = 0,
    d: int | Fraction = 0,
    e: int | Fraction = 0,
    f: int | Fraction = 0,
    g: int | Fraction = 0,
    a: int | Fraction = 0,
    b: int | Fraction = 0,
)

from_alts

from_alts(alts: int)

Create a key signature by specifying the number of sharps (positive int) or flats (negative int). Assumes normal ordering (F C G D A E B | B E A D G C F) and should be symmetrical to fifths.

Examples

>>> KeySignature.from_alts(2)
KeySignature(c=1, f=1)

>>> KeySignature.from_alts(-3)
KeySignature(e=-1, a=-1, b=-1)

>>> KeySignature.from_alts(-10)
KeySignature(c=-1, d=-1, e=-2, f=-1, g=-1, a=-2, b=-2)

>>> KeySignature.from_alts(5).fifths
5

transform

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

Returns a new KeySignature made by applying operation to each of the seven letters, taken as the pitches C, D, E, F, G, A, B with this signature’s alterations, and reading the new alteration of each letter from the result.

operation is called as operation(tone, *args, **kwargs) and must return a TonalVector, or a TypeError is raised. If two letters are sent to the same letter, the result is not a key signature and a ValueError is raised. Alterations must be integers (the letter-pitches must be expressible as TonalVectors); otherwise a ValueError is raised.

Examples

>>> from openmusickit.systems.wsmn.tonal.symbols import M2

Transposition, including of a non-standard signature (C D E F♯ G A B♭ up a major second is D E F♯ G♯ A B C):

>>> KeySignature().transform(TonalVector.transpose, M2)
KeySignature(c=1, f=1)
>>> KeySignature(f=1, b=-1).transform(TonalVector.transpose, M2)
KeySignature(f=1, g=1)

An operation that needs no operand:

>>> def sharpen(tv):
...     return tv + TonalVector((0, 1))
>>> KeySignature().transform(sharpen)
KeySignature(c=1, d=1, e=1, f=1, g=1, a=1, b=1)

An operation that does not produce a TonalVector is rejected:

>>> KeySignature().transform(str)
Traceback (most recent call last):
    ...
TypeError: ...

transpose

transpose(x: TonalVector, direction: TonalDirection = TonalDirection.UP)

Returns this key signature transposed by the interval x: each letter moves by x, so a standard signature moves around the circle of fifths as if it were the signature of a key whose tonic is transposed by x. (Since relative keys share a signature, this is equally correct for any mode.)

Examples

>>> from openmusickit.systems.wsmn.tonal.symbols import M2, m3, P5, a4
>>> KeySignature().transpose(M2)
KeySignature(c=1, f=1)

>>> KeySignature().transpose(m3)
KeySignature(e=-1, a=-1, b=-1)

>>> KeySignature(f=1).transpose(P5, TonalDirection.DOWN)
KeySignature()

>>> KeySignature.from_alts(3).transpose(a4).fifths
9

>>> KeySignature(f=1, b=-1).transpose(M2)
KeySignature(f=1, g=1)

__repr__

__repr__()

Only non-zero alterations are shown, matching how a KeySignature is typically constructed.

Examples

>>> KeySignature()
KeySignature()

>>> KeySignature(c=1, f=1)
KeySignature(c=1, f=1)

>>> KeySignature(e=-1, a=-1, b=-1)
KeySignature(e=-1, a=-1, b=-1)