musicscore.measure

class musicscore.measure.Measure(number, time=None, *args, **kwargs)[source]

Bases: MusicTree, QuantizeMixin, SimplifiedSextuplets, FinalizeMixin, XMLWrapper

Parent type: Part

Child type: Staff

XMLClass: alias of XMLMeasure

add_child(child: Staff) → Staff[source]

Adds a Staff as a child to measure.
If staff number is None, it will determined as length of children + 1.
If staff number is already set an is not equal to length of children + 1 a ValueError is raised.
If staff is the first child default clefs are set.
Clef’s numbers are updated.

Parameters:: child – Staff, required
Returns:: child
Return type:: Staff

add_staff(staff_number: int | None = None) → Staff[source]

Creates and adds a new Staff object as child to measure if it already does not exist.
If staff number is greater than length of children + 1 all missing staves are created and added first.

Parameters:: staff_number – positive int or None. If None staff number it is determined as length of children + 1.
Returns:: new Staff

add_voice(*, staff_number: int | None = None, voice_number: int | None = None) → Voice[source]

Creates and adds a new Voice object as child to the given Staff if it already does not exist.
add_staff() is called to get or create the given staff.
musicscore.staff.Staff.add_voice() is called to add voice to staff.

Parameters:

staff_number – positive int or None. If None staff number it is set to 1.
voice_number – positive int or None. If None voice_numberit is set to 1.

Returns:

new Voice

classmethod create_tree_from_list(tree_list_representation: list[list[Any]], represented_attribute_names: list[str]) → T

fill_with_rests()[source]: If Measure is not completely filled, it will be filled with rest(s)

filter_nodes(key: Callable[[T], Any], return_value: Any) → list[T]

Tree method

>>> root.filter_nodes(lambda node: node.get_level(), 2)
[grandchild1, grandchild2, grandchild3]

finalize()[source]

finalize can only be called once.

It calls the finalize() method of all children.
Following updates are triggered: _update_attributes, _update_divisions, _update_left_barline, _update_accidentals, update_xml_backups_notes_directions, _update_right_barline
All beats with the property get_quantized set to True will get quantized.

get_barline(location: str = 'right') → XMLBarline | None[source]

Parameters:: location – ‘left’ or ‘right’ barline position.
Returns:: None or XMLBarline

get_beat(*args, **kwargs) → Beat

MusicTree method

This method can be used for Score and Part, Measure and Staff and Voice

Parameters:

args – can be used instead of kwargs. A mixture of args and kwargs is not allowed.
kwargs – part_number, measure_number, staff_number, voice_number, beat_number depending on musicscore’s class. A Staff for example needs voice_number and beat_number while a Score needs all keyword arguments.

Return type:

Beat

get_beats() → List[Beat]

MusicTree method

This method can be used for Score and Part, Measure, Staff and Voice.

Returns:: a flat list of all beats.
Return type:: List[Beat]

get_children() → List[Staff][source]

Returns:: list of added children.
Return type:: List[Staff]

get_children_of_type(type_: type) → list[T]

Tree method

Returns:: list of added children of type.d
Return type:: list[Tree]

get_chord(*args, **kwargs) → Chord

MusicTree method

This method can be used for Score and Part, Measure, Staff, Voice and Beat

Parameters:

args – can be used instead of kwargs. A mixture of args and kwargs is not allowed.
kwargs – part_number, measure_number, staff_number, voice_number, beat_number, chord_number depending on musicscore’s class. A Staff for example needs voice_number, beat_number and chord_number while a Score needs all keyword arguments.

Return type:

Chord

get_chords() → List[Chord]

MusicTree method

This method can be used for Score and Part, Measure and Staff, Voice and Beat

Returns:: a flat list of all chords.
Return type:: List[Chord]

get_distance(reference: T | None = None) → int

>>> root.get_distance()
0
>>> greatgrandchild1.get_distance()
3
>>> greatgrandchild1.get_distance(child2)
2

get_divisions() → musicxml.xsd.xsdsimpletype.XSDSimpleTypeInteger[source]

Returns:: value_ of existing XMLDivisions

get_farthest_leaf() → T

>>> root.get_farthest_leaf()
greatgrandchild1

get_layer(level: int, key: Callable[[T], Any] | None = None) → Any

Tree method

Parameters:

level – layer number where 0 is the root.
key – An optional callable for each node in the layer.

Returns:

All nodes on this level. The leaves of branches which are shorter than the given level will be repeated on this and all following layers.

Return type:

list

get_leaves(key: Callable[[T], Any] | None = None) → list[Union[Any, list[Any]]]

Tree method

Parameters:: key – An optional callable to be called on each leaf.
Returns:: nested list of leaves or values of key(leaf) for each leaf

>>> root.get_leaves()
[child1, [[greatgrandchild1, greatgrandchild2], grandchild2], child3, [grandchild3]]

get_level() → int

Tree

Returns:: 0 for root, 1, 2 etc. for each layer of children
Return type:: nonnegative int

>>> root.get_level()
0
>>> child1.get_level()
1
>>> grandchild1.get_level()
2
>>> greatgrandchild1.get_level()
3

get_list_representation(key: Callable[[Tree[T]], Any]) → list[list[Any]]

get_number_of_layers() → int

>>> root.get_number_of_layers()
3

get_parent() → T | None

Tree method

Returns:: parent. None for root.
Return type:: Tree

get_position_in_tree() → str

Tree method

Returns:: 0 for root. 1, 2, … for layer 1. Other layers: x.y.z…. Example: 3.2.2 => third child of secod child of second child of the root.
Return type:: str

>>> print(root.get_tree_representation(key=lambda node: node.get_position_in_tree()))
└── 0
    ├── 1
    ├── 2
    │   ├── 2.1
    │   │   ├── 2.1.1
    │   │   └── 2.1.2
    │   └── 2.2
    ├── 3
    └── 4
        └── 4.1

get_possible_subdivisions(beat_quarter_duration: QuarterDuration | None = None) → List[int]

QuantizeMixin method

This method is used by Beat’s quantize_quarter_durations().

Possible subdivisions dictionary can be set with set_possible_subdivisions(). Keys in the subdivisions dictionary correspond to beat quarter durations (e.g. 1, 1/2 etc.) For example if get_possible_subdivisions()[1] == [3, 5, 8] a beat with a quarter duration of 1 can after quantization consists only of eighth triplets, quintuplets and 32ths. If this dictionary is not set or beat_quarter_duration as key does not exist, the parent’s possible subdivisions dictionary will be checked.

Score has a default POSSIBLE_SUBDIVISIONS dictionary which will be used if no other musicscore node on the path from self to root has its own possible subdivisions dictionary with beat_quarter_duration as a key. For setting possible subdivisions dictionary use always set_possible_subdivisions().

Parameters:: beat_quarter_duration – Used as key in possible subdivisions dictionary. If None and self is a Beat self.quarter_duration is used. If None and self is not a Beat it is set to 1.
Returns:: A list of possible subdivisions of a Beat. This is used by beat’s quantize_quarter_durations()
Return type:: List[int]

get_reversed_path_to_root() → list[T]

Tree method

Returns:: path from self upwards through all ancestors up to the root.

>>> greatgrandchild1.get_reversed_path_to_root()
[greatgrandchild1, grandchild1, child2, root]

get_root() → T

Tree method

Returns:: root (upmost node of a tree which has no parent)
Return type:: Tree

>>> greatgrandchild1.get_root() == root
True
>>> child4.get_root() == root
True
>>> root.get_root() == root
True

get_self_with_key(key: Callable[[T], Any] | None = None) → Any

get_tree_representation(key: Callable[[T], Any] | None = None, space: int = 3) → str

Tree method

Parameters:: key – An optional callable if None string(node) is called.
Returns:: a representation of all nodes as string in tree form.

>>> print(root.get_tree_representation())
└── root
    ├── child1
    ├── child2
    │   ├── grandchild1
    │   │   ├── greatgrandchild1
    │   │   └── greatgrandchild2
    │   └── grandchild2
    ├── child3
    └── child4
        └── grandchild3

iterate_leaves() → Iterator[T]

Tree method

Returns:: A generator iterating over all leaves.

remove(child) → None[source]

Tree method

Child’s parent will be set to None and child will be removed from list of children.

Parameters:: child –
Returns:: None

remove_children() → None

Tree method

Calls remove() on all children.

Returns:: None

replace_child(old: T, new: T, index: int = 0) → None

Tree method

Parameters:

old – child or function
new – child
index – index of old child in the list of its appearances

Returns:

None

set_barline(location: str = 'right', style: str | None = None, **kwargs) → XMLBarline[source]

Parameters:

location – ‘left’ or ‘right’ barline position.
style – ‘regular’, ‘dotted’, ‘dashed’, ‘heavy’, ‘light-light’, ‘light-heavy’, ‘heavy-light’, ‘heavy-heavy’, ‘tick’, ‘short’, ‘none’

Returns:

created XMLBarline

set_possible_subdivisions(subdivisions: list[int], beat_quarter_duration: QuarterDuration | None = None) → None

QuantizeMixin method

This method is used to set or change possible subdivisions dictionary of a beat or its ascendants. For example if get_possible_subdivisions()[1] == [3, 5, 8] a beat with a quarter duration of 1 can after quantization consists only of eighth triplets, quintuplets and 32ths.

Parameters:

subdivisions – list of possible subdivisions to be used in musicscore.beat.Beat.quantize_quarter_durations()
beat_quarter_duration – If None and self is a Beat self.quarter_duration is used. If None and self is not a Beat it is set to 1.

Returns:

None

set_repeat_barline(location: str = 'right', **kwargs) → XMLBarline[source]

If barline does not exist a XMLBarline will be added to location. Than a XMLRepeat will be added to it as child.

Parameters:

location – left or right barline position. If left XMLBarline’s direction is set to forward otherwise to backward
kwargs – passed on to XMLRepeat

Returns:

created or existing XMLBarline

set_repeat_ending(number: str | int, type: str, **kwargs) → XMLEnding[source]

If type == start location is set to left otherwise to right. If barline does not exist a XMLBarline will be added to location. Than a XMLEnding will be added to it as child.

Parameters:

number – XMLEnding’s number
kwargs – passed on to XMLEnding

Returns:

XMLEnding

to_string(*args, **kwargs)

FinalizeMixin method

It triggers finalize() first before calling parent’s xml_object.to_string() method. If no xml_object exists (it means there is no direct MusicXML equavalent of this class) a ClassHasNoMusicXMLEquivalentError is thrown.

traverse() → Iterator[T]

Tree method

Traverse all tree nodes.

Returns:: generator

update_chord_accidentals() → None[source]

Updates musicscore.accidental.Accidental.show attribute of descendent Midis’ accidentals.

Returns:: None

property clefs: List[Clef]

Returns:: Clef objects of children staves.

property content: Any

default_show_accidental_signs = 'modern'

property get_quantized: bool

QuantizeMixin property

If get_quantized is set to None the first get_quantized of ancestors which is False or True will be returned.
If musicscore.score.Score.get_quantized is set to None it will be converted to False
musicscore.measure.Measure.finalize() loops over all beats. If musicscore.beat.Beat.get_quantized returns True musicscore.beat.Beat.quantize_quarter_durations() is called.

Type:: Optional[bool]
Return type:: bool

property is_first_child: bool

property is_last_child: bool

>>> t = TestTree('root')
>>> for node in t.traverse():
...    if node.name in ['root', 'child4', 'grandchild2', 'grandchild3', 'greatgrandchild1']:
...        assert node.is_last_child
...    else:
...        assert not node.is_last_child

property is_leaf: bool

Tree property

Returns:: True if self has no children. False if self has one or more children.
Return type:: bool

property is_root: bool

Tree property

Returns:: True if self has no parent, else False.
Return type:: bool

property key: Key

Type:: Key
Returns:: Key

property new_system: bool: If True: new_system attribute of self.xml_object’s child XMLPrint will be set to yes.

property next: T | None

Tree property

Returns:: next sibling. None if this is the last current child of the parent.
Return type:: Tree

property number

Type:: positive int
Returns:: xml_object’s number as integer
Return type:: positive int

property previous: T | None

Tree property

Returns:: previous sibling. None if this is the first child of the parent.
Return type:: Tree

property quarter_duration: QuarterDuration

Returns:: sum of quarter durations defined via property time’s method get_beats_quarter_durations()
Return type:: QuarterDuration

property show_accidental_signs: str

MusicTree property

If show_accidental_signs is set to None the first get_quantized of ancestors which is False or True will be returned.
If show_accidental_signs is set to None it will be converted to default_show_accidental_signs
Possible show_accidental_signs are: None, ‘modern’, ‘traditional’

Type:: Optional[str]
Return type:: str

property simplified_sextuplets: bool

property time: Time

Set and get time. After setting value, parent_measure is set to self and method musicscore.voice.Voice.update_beats( ) of descendent voices is called.

Type:: Optional[Time]
Type:: Time

property up: T | None

Tree property

Returns:: get_parent()
Return type:: Tree

property xml_object: XMLElement

XMLWrapper method

This musicscore class has an equivalent MusicXML class which can be reached via this property.

If an attribute is not found directly in the main class, it wll be passed on to __get_attribute__ or __set__attribute__ methods of self.xml_object. It can also use the short cut attributes of XMLElement to get or set the first child.

Returns:: wrapped MusicXML element of type XMLClass

musicscore.measure.generate_measures(times, first_number=1)[source]

Parameters:

times ([Time, ratio]) – list containing time objects or ratios (1, 4)
first_number (int) – first measure number

Return [Measure]:

measures