IterationAgent

class agenttools.IterationAgent(client=None)

Iteration agent.

Example. Iterates components:

>>> staff = Staff("c'4 e'4 d'4 f'4")
>>> show(staff) 
>>> for component in iterate(staff).by_class():
...     component
... 
Staff("c'4 e'4 d'4 f'4")
Note("c'4")
Note("e'4")
Note("d'4")
Note("f'4")

Example 2. Iterates leaves:

>>> staff = Staff("c'4 e'4 d'4 f'4")
>>> show(staff) 
>>> for leaf in iterate(staff).by_leaf():
...     leaf
... 
Note("c'4")
Note("e'4")
Note("d'4")
Note("f'4")

Lineage

digraph InheritanceGraph { graph [background=transparent, bgcolor=transparent, color=lightslategrey, fontname=Arial, outputorder=edgesfirst, overlap=prism, penwidth=2, rankdir=LR, root="__builtin__.object", splines=spline, style="dotted, rounded", truecolor=true]; node [colorscheme=pastel19, fontname=Arial, fontsize=12, penwidth=2, style="filled, rounded"]; edge [color=lightsteelblue2, penwidth=2]; subgraph cluster_abctools { graph [label=abctools]; "abjad.tools.abctools.AbjadObject.AbjadObject" [color=1, group=0, label=AbjadObject, shape=box]; "abjad.tools.abctools.AbjadObject.AbstractBase" [color=1, group=0, label=AbstractBase, shape=box]; "abjad.tools.abctools.AbjadObject.AbstractBase" -> "abjad.tools.abctools.AbjadObject.AbjadObject"; } subgraph cluster_agenttools { graph [label=agenttools]; "abjad.tools.agenttools.IterationAgent.IterationAgent" [color=black, fontcolor=white, group=1, label=<<B>IterationAgent</B>>, shape=box, style="filled, rounded"]; } subgraph cluster_builtins { graph [label=builtins]; "builtins.object" [color=3, group=2, label=object, shape=box]; } "abjad.tools.abctools.AbjadObject.AbjadObject" -> "abjad.tools.agenttools.IterationAgent.IterationAgent"; "builtins.object" -> "abjad.tools.abctools.AbjadObject.AbstractBase"; }

Bases

Attribute summary

by_class([prototype, pitched, reverse, ...]) Iterates by class.
by_leaf([prototype, pitched, reverse, ...]) Iterates by leaf.
by_leaf_pair() Iterates by leaf pair.
by_logical_tie([nontrivial, pitched, ...]) Iterates by logical tie.
by_logical_voice(prototype, logical_voice[, ...]) Iterates by logical voice.
by_logical_voice_from_component([prototype, ...]) Iterates by logical voice from client.
by_run([prototype]) Iterates by run.
by_semantic_voice([reverse, start, stop]) Iterates by semantic voice.
by_spanner([prototype, reverse]) Iterates by spanner.
by_timeline([prototype, reverse]) Iterates by timeline.
by_timeline_and_logical_tie([nontrivial, ...]) Iterates by timeline and logical tie.
by_timeline_from_component([prototype, reverse]) Iterates from client by timeline.
by_topmost_logical_ties_and_components() Iterates by topmost logical ties and components.
by_vertical_moment([reverse]) Iterates by vertical moment.
client Gets client of iteration agent.
depth_first([capped, direction, forbid, unique]) Iterates depth first.
__eq__(expr) Is true when ID of expr equals ID of Abjad object.
__format__([format_specification]) Formats Abjad object.
__hash__() Hashes Abjad object.
__ne__(expr) Is true when Abjad object does not equal expr.
__repr__() Gets interpreter representation of Abjad object.

Read-only properties

IterationAgent.client

Gets client of iteration agent.

Example 1. Gets component client:

>>> staff = Staff("c'4 d' e' f'")
>>> agent = iterate(staff)
>>> agent.client
Staff("c'4 d'4 e'4 f'4")

Example 2. Gets selection client:

>>> staff = Staff("c'4 d' e' f'")
>>> agent = iterate(staff[:2])
>>> agent.client
Selection([Note("c'4"), Note("d'4")])

Returns component or selection.

Methods

IterationAgent.by_class(prototype=None, pitched=None, reverse=False, start=0, stop=None, with_grace_notes=False)

Iterates by class.

Example 1. Iterates notes:

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "c'8 d'8"))
>>> staff.append(Measure((2, 8), "e'8 f'8"))
>>> staff.append(Measure((2, 8), "g'8 a'8"))
>>> show(staff) 
>>> for note in iterate(staff).by_class(prototype=Note):
...     note
...
Note("c'8")
Note("d'8")
Note("e'8")
Note("f'8")
Note("g'8")
Note("a'8")

Example 2. Constrains iteration by index:

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "c'8 d'8"))
>>> staff.append(Measure((2, 8), "e'8 f'8"))
>>> staff.append(Measure((2, 8), "g'8 a'8"))
>>> show(staff) 
>>> for note in iterate(staff).by_class(
...     prototype=Note,
...     start=0,
...     stop=3,
...     ):
...     note
...
Note("c'8")
Note("d'8")
Note("e'8")
>>> for note in iterate(staff).by_class(
...     prototype=Note,
...     start=2,
...     stop=4,
...     ):
...     note
...
Note("e'8")
Note("f'8")

Example 3. Reverses direction of iteration:

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "c'8 d'8"))
>>> staff.append(Measure((2, 8), "e'8 f'8"))
>>> staff.append(Measure((2, 8), "g'8 a'8"))
>>> show(staff) 
>>> for note in iterate(staff).by_class(
...     prototype=Note,
...     reverse=True,
...     ):
...     note
...
Note("a'8")
Note("g'8")
Note("f'8")
Note("e'8")
Note("d'8")
Note("c'8")

Example 5. Iterates with grace notes:

>>> voice = Voice("c'8 [ d'8 e'8 f'8 ]")
>>> grace_notes = [Note("cf''16"), Note("bf'16")]
>>> grace = scoretools.GraceContainer(
...     grace_notes,
...     kind='grace',
...     )
>>> attach(grace, voice[1])
>>> show(voice) 
>>> for component in iterate(voice).by_class(
...     with_grace_notes=True,
...     ):
...     component
... 
Voice("c'8 d'8 e'8 f'8")
Note("c'8")
Note("cf''16")
Note("bf'16")
Note("d'8")
Note("e'8")
Note("f'8")

Example 5. Iterates with both grace notes and after grace notes:

>>> voice = Voice("c'8 [ d'8 e'8 f'8 ]")
>>> grace_notes = [Note("cf''16"), Note("bf'16")]
>>> grace = scoretools.GraceContainer(
...     grace_notes,
...     kind='grace',
...     )
>>> attach(grace, voice[1])
>>> after_grace_notes = [Note("af'16"), Note("gf'16")]
>>> after_grace = scoretools.GraceContainer(
...     after_grace_notes,
...     kind='after')
>>> attach(after_grace, voice[1])
>>> show(voice) 
>>> for leaf in iterate(voice).by_class(with_grace_notes=True):
...     leaf
...
Voice("c'8 d'8 e'8 f'8")
Note("c'8")
Note("cf''16")
Note("bf'16")
Note("d'8")
Note("af'16")
Note("gf'16")
Note("e'8")
Note("f'8")

Example 6. Iterates pitched components:

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(Measure((2, 8), "af'8 r8"))
>>> staff.append(Measure((2, 8), "r8 gf'8"))
>>> show(staff) 
>>> for leaf in iterate(staff).by_class(pitched=True):
...     leaf
...
Chord("<c' bf'>8")
Chord("<g' a'>8")
Note("af'8")
Note("gf'8")

Example 7. Iterates nonpitched components:

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(Measure((2, 8), "af'8 r8"))
>>> staff.append(Measure((2, 8), "r8 gf'8"))
>>> show(staff) 
>>> for leaf in iterate(staff).by_class(pitched=False):
...     leaf
...
<Staff{3}>
Measure((2, 8), "<c' bf'>8 <g' a'>8")
Measure((2, 8), "af'8 r8")
Rest('r8')
Measure((2, 8), "r8 gf'8")
Rest('r8')

Returns generator.

IterationAgent.by_leaf(prototype=None, pitched=None, reverse=False, start=0, stop=None, with_grace_notes=False)

Iterates by leaf.

Example 1. Iterates leaves:

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(Measure((2, 8), "af'8 r8"))
>>> staff.append(Measure((2, 8), "r8 gf'8"))
>>> show(staff) 
>>> for leaf in iterate(staff).by_leaf():
...     leaf
...
Chord("<c' bf'>8")
Chord("<g' a'>8")
Note("af'8")
Rest('r8')
Rest('r8')
Note("gf'8")

Example 2. Constrains iteration by index:

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(Measure((2, 8), "af'8 r8"))
>>> staff.append(Measure((2, 8), "r8 gf'8"))
>>> show(staff) 
>>> for leaf in iterate(staff).by_leaf(start=0, stop=3):
...     leaf
...
Chord("<c' bf'>8")
Chord("<g' a'>8")
Note("af'8")
>>> for leaf in iterate(staff).by_leaf(start=2, stop=4):
...     leaf
...
Note("af'8")
Rest('r8')

Example 3. Reverses direction of iteration:

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(Measure((2, 8), "af'8 r8"))
>>> staff.append(Measure((2, 8), "r8 gf'8"))
>>> show(staff) 
>>> for leaf in iterate(staff).by_leaf(reverse=True):
...     leaf
...
Note("gf'8")
Rest('r8')
Rest('r8')
Note("af'8")
Chord("<g' a'>8")
Chord("<c' bf'>8")

Example 4. Iterates with grace notes:

>>> voice = Voice("c'8 [ d'8 e'8 f'8 ]")
>>> grace_notes = [Note("cf''16"), Note("bf'16")]
>>> grace = scoretools.GraceContainer(
...     grace_notes,
...     kind='grace',
...     )
>>> attach(grace, voice[1])
>>> after_grace_notes = [Note("af'16"), Note("gf'16")]
>>> after_grace = scoretools.GraceContainer(
...     after_grace_notes,
...     kind='after')
>>> attach(after_grace, voice[1])
>>> show(voice) 
>>> for leaf in iterate(voice).by_leaf(with_grace_notes=True):
...     leaf
...
Note("c'8")
Note("cf''16")
Note("bf'16")
Note("d'8")
Note("af'16")
Note("gf'16")
Note("e'8")
Note("f'8")

Example 5. Iterates pitched leaves:

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(Measure((2, 8), "af'8 r8"))
>>> staff.append(Measure((2, 8), "r8 gf'8"))
>>> show(staff) 
>>> for leaf in iterate(staff).by_leaf(pitched=True):
...     leaf
...
Chord("<c' bf'>8")
Chord("<g' a'>8")
Note("af'8")
Note("gf'8")

Example 6. Iterates nonpitched leaves:

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(Measure((2, 8), "af'8 r8"))
>>> staff.append(Measure((2, 8), "r8 gf'8"))
>>> show(staff) 
>>> for leaf in iterate(staff).by_leaf(pitched=False):
...     leaf
...
Rest('r8')
Rest('r8')

Returns generator.

IterationAgent.by_leaf_pair()

Iterates by leaf pair.

Example 1. Iterates leaf pairs:

>>> score = Score([])
>>> score.append(Staff("c'8 d'8 e'8 f'8 g'4"))
>>> score.append(Staff("c4 a,4 g,4"))
>>> attach(Clef('bass'), score[1])
>>> show(score) 
>>> for leaf_pair in iterate(score).by_leaf_pair():
...        leaf_pair
... 
(Note("c'8"), Note('c4'))
(Note("c'8"), Note("d'8"))
(Note('c4'), Note("d'8"))
(Note("d'8"), Note("e'8"))
(Note("d'8"), Note('a,4'))
(Note('c4'), Note("e'8"))
(Note('c4'), Note('a,4'))
(Note("e'8"), Note('a,4'))
(Note("e'8"), Note("f'8"))
(Note('a,4'), Note("f'8"))
(Note("f'8"), Note("g'4"))
(Note("f'8"), Note('g,4'))
(Note('a,4'), Note("g'4"))
(Note('a,4'), Note('g,4'))
(Note("g'4"), Note('g,4'))

Iterates leaf pairs left-to-right and top-to-bottom.

Returns generator.

IterationAgent.by_logical_tie(nontrivial=False, pitched=False, reverse=False, parentage_mask=None, with_grace_notes=False)

Iterates by logical tie.

Example 1. Iterates logical ties:

>>> staff = Staff(r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16")
>>> show(staff) 
>>> for logical_tie in iterate(staff).by_logical_tie():
...     logical_tie
...
LogicalTie([Note("c'4"), Note("c'16")])
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'4"), Note("f'16")])

Example 2. Reverses direction of iteration:

>>> staff = Staff(r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16")
>>> show(staff) 
>>> for logical_tie in iterate(staff).by_logical_tie(reverse=True):
...     logical_tie
...
LogicalTie([Note("f'4"), Note("f'16")])
LogicalTie([Note("e'8")])
LogicalTie([Note("d'8")])
LogicalTie([Note("c'4"), Note("c'16")])

Example 3. Iterates pitched logical ties:

>>> staff = Staff(r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16")
>>> show(staff) 
>>> for logical_tie in iterate(staff).by_logical_tie(pitched=True):
...     logical_tie
...
LogicalTie([Note("c'4"), Note("c'16")])
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'4"), Note("f'16")])

Example 4. Iterates nontrivial logical ties:

>>> staff = Staff(r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16")
>>> show(staff) 
>>> for logical_tie in iterate(staff).by_logical_tie(nontrivial=True):
...     logical_tie
...
LogicalTie([Note("c'4"), Note("c'16")])
LogicalTie([Note("f'4"), Note("f'16")])

Example 5. Iterates logical ties masked by parentage.

Note

When iterating logical ties in a container, the yielded logical ties may contain leaves outside that container’s parentage. By specifying a parentage mask, composers can constrain the contents of the yielded logical ties to only those leaves actually within the parentage of the container under iteration.

>>> staff = Staff("{ c'1 ~ } { c'2 d'2 ~ } { d'1 }")
>>> for logical_tie in iterate(staff[1]).by_logical_tie():
...     logical_tie
...
LogicalTie([Note("c'1"), Note("c'2")])
LogicalTie([Note("d'2"), Note("d'1")])
>>> for logical_tie in iterate(staff[1]).by_logical_tie(
...     parentage_mask=staff[1]):
...     logical_tie
...
LogicalTie([Note("c'2")])
LogicalTie([Note("d'2")])

Example 6. Iterates logical ties with grace notes:

>>> voice = Voice("c'8 [ d'8 e'8 f'8 ]")
>>> grace_notes = [Note("cf''16"), Note("bf'16")]
>>> grace = scoretools.GraceContainer(
...     grace_notes,
...     kind='grace',
...     )
>>> attach(grace, voice[1])
>>> show(voice) 
>>> for logical_tie in iterate(voice).by_logical_tie(
...     with_grace_notes=True,
...     ):
...     logical_tie
... 
LogicalTie([Note("c'8")])
LogicalTie([Note("cf''16")])
LogicalTie([Note("bf'16")])
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'8")])

Example 7. Iterates logical ties with after grace notes:

>>> voice = Voice("c'8 [ d'8 e'8 f'8 ]")
>>> after_grace_notes = [Note("af'16"), Note("gf'16")]
>>> after_grace = scoretools.GraceContainer(
...     after_grace_notes,
...     kind='after')
>>> attach(after_grace, voice[1])
>>> show(voice) 
>>> for logical_tie in iterate(voice).by_logical_tie(
...     with_grace_notes=True,
...     ):
...     logical_tie
... 
LogicalTie([Note("c'8")])
LogicalTie([Note("d'8")])
LogicalTie([Note("af'16")])
LogicalTie([Note("gf'16")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'8")])

Example 8. Iterates logical ties with both grace notes and after grace notes:

>>> voice = Voice("c'8 [ d'8 e'8 f'8 ]")
>>> grace_notes = [Note("cf''16"), Note("bf'16")]
>>> grace = scoretools.GraceContainer(
...     grace_notes,
...     kind='grace',
...     )
>>> attach(grace, voice[1])
>>> after_grace_notes = [Note("af'16"), Note("gf'16")]
>>> after_grace = scoretools.GraceContainer(
...     after_grace_notes,
...     kind='after')
>>> attach(after_grace, voice[1])
>>> show(voice) 
>>> for logical_tie in iterate(voice).by_logical_tie(
...     with_grace_notes=True,
...     ):
...     logical_tie
...
LogicalTie([Note("c'8")])
LogicalTie([Note("cf''16")])
LogicalTie([Note("bf'16")])
LogicalTie([Note("d'8")])
LogicalTie([Note("af'16")])
LogicalTie([Note("gf'16")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'8")])

Returns generator.

IterationAgent.by_logical_voice(prototype, logical_voice, reverse=False)

Iterates by logical voice.

Example 1. Iterates notes in logical voice 1:

>>> container_1 = Container([Voice("c'8 d'8"), Voice("e'8 f'8")])
>>> container_1.is_simultaneous = True
>>> container_1[0].name = 'voice 1'
>>> override(container_1[0]).stem.direction = Down
>>> container_1[1].name = 'voice 2'
>>> container_2 = Container([Voice("g'8 a'8"), Voice("b'8 c''8")])
>>> container_2.is_simultaneous = True
>>> container_2[0].name = 'voice 1'
>>> override(container_2[0]).stem.direction = Down
>>> container_2[1].name = 'voice 2'
>>> staff = Staff([container_1, container_2])
>>> show(staff) 
>>> selector = select().by_leaf(flatten=True)
>>> leaves = selector(staff)
>>> leaf = leaves[0]
>>> signature = inspect_(leaf).get_parentage().logical_voice
>>> for note in iterate(staff).by_logical_voice(Note, signature):
...     note
...
Note("c'8")
Note("d'8")
Note("g'8")
Note("a'8")

Returns generator.

IterationAgent.by_logical_voice_from_component(prototype=None, reverse=False)

Iterates by logical voice from client.

Example 1. Iterates from first leaf in score:

>>> container_1 = Container([Voice("c'8 d'8"), Voice("e'8 f'8")])
>>> container_1.is_simultaneous = True
>>> container_1[0].name = 'voice 1'
>>> override(container_1[0]).stem.direction = Down
>>> container_1[1].name = 'voice 2'
>>> container_2 = Container([Voice("g'8 a'8"), Voice("b'8 c''8")])
>>> container_2.is_simultaneous = True
>>> container_2[0].name = 'voice 1'
>>> override(container_2[0]).stem.direction = Down
>>> container_2[1].name = 'voice 2'
>>> staff = Staff([container_1, container_2])
>>> show(staff) 
>>> selector = select().by_leaf(flatten=True)
>>> leaves = selector(staff)
>>> leaf = leaves[0]
>>> for x in iterate(leaf).by_logical_voice_from_component(Note):
...     x
...
Note("c'8")
Note("d'8")
Note("g'8")
Note("a'8")

Example 2. Iterates from second leaf in score:

>>> container_1 = Container([Voice("c'8 d'8"), Voice("e'8 f'8")])
>>> container_1.is_simultaneous = True
>>> container_1[0].name = 'voice 1'
>>> override(container_1[0]).stem.direction = Down
>>> container_1[1].name = 'voice 2'
>>> container_2 = Container([Voice("g'8 a'8"), Voice("b'8 c''8")])
>>> container_2.is_simultaneous = True
>>> container_2[0].name = 'voice 1'
>>> override(container_2[0]).stem.direction = Down
>>> container_2[1].name = 'voice 2'
>>> staff = Staff([container_1, container_2])
>>> show(staff) 
>>> leaf = leaves[1]
>>> for x in iterate(leaf).by_logical_voice_from_component(Note):
...     x
...
Note("d'8")
Note("g'8")
Note("a'8")

Example 3. Iterates all components in logical voice:

>>> container_1 = Container([Voice("c'8 d'8"), Voice("e'8 f'8")])
>>> container_1.is_simultaneous = True
>>> container_1[0].name = 'voice 1'
>>> override(container_1[0]).stem.direction = Down
>>> container_1[1].name = 'voice 2'
>>> container_2 = Container([Voice("g'8 a'8"), Voice("b'8 c''8")])
>>> container_2.is_simultaneous = True
>>> container_2[0].name = 'voice 1'
>>> override(container_2[0]).stem.direction = Down
>>> container_2[1].name = 'voice 2'
>>> staff = Staff([container_1, container_2])
>>> show(staff) 
>>> leaf = leaves[0]
>>> for x in iterate(leaf).by_logical_voice_from_component():
...     x
...
Note("c'8")
Voice("c'8 d'8")
Note("d'8")
Voice("g'8 a'8")
Note("g'8")
Note("a'8")

Example 4. Reverses direction of iteration:

>>> container_1 = Container([Voice("c'8 d'8"), Voice("e'8 f'8")])
>>> container_1.is_simultaneous = True
>>> container_1[0].name = 'voice 1'
>>> override(container_1[0]).stem.direction = Down
>>> container_1[1].name = 'voice 2'
>>> container_2 = Container([Voice("g'8 a'8"), Voice("b'8 c''8")])
>>> container_2.is_simultaneous = True
>>> container_2[0].name = 'voice 1'
>>> override(container_2[0]).stem.direction = Down
>>> container_2[1].name = 'voice 2'
>>> staff = Staff([container_1, container_2])
>>> show(staff) 
>>> leaf = leaves[-1]
>>> for x in iterate(leaf).by_logical_voice_from_component(
...     Note,
...     reverse=True,
...     ):
...     x
... 
Note("c''8")
Note("b'8")
Note("f'8")
Note("e'8")
>>> leaf = leaves[-1]
>>> for x in iterate(leaf).by_logical_voice_from_component(
...     reverse=True,
...     ):
...     x
... 
Note("c''8")
Voice("b'8 c''8")
Note("b'8")
Voice("e'8 f'8")
Note("f'8")
Note("e'8")

Returns generator.

IterationAgent.by_run(prototype=None)

Iterates by run.

Example 1. Iterates runs of notes and chords at only the top level of score:

>>> staff = Staff(r"\times 2/3 { c'8 d'8 r8 }")
>>> staff.append(r"\times 2/3 { r8 <e' g'>8 <f' a'>8 }")
>>> staff.extend("g'8 a'8 r8 r8 <b' d''>8 <c'' e''>8")
>>> show(staff) 
>>> for group in iterate(staff[:]).by_run((Note, Chord)):
...     group
...
(Note("g'8"), Note("a'8"))
(Chord("<b' d''>8"), Chord("<c'' e''>8"))

Example 2. Iterates runs of notes and chords at all levels of score:

>>> staff = Staff(r"\times 2/3 { c'8 d'8 r8 }")
>>> staff.append(r"\times 2/3 { r8 <e' g'>8 <f' a'>8 }")
>>> staff.extend("g'8 a'8 r8 r8 <b' d''>8 <c'' e''>8")
>>> show(staff) 
>>> leaves = iterate(staff).by_class(scoretools.Leaf)
>>> for group in iterate(leaves).by_run((Note, Chord)):
...     group
...
(Note("c'8"), Note("d'8"))
(Chord("<e' g'>8"), Chord("<f' a'>8"), Note("g'8"), Note("a'8"))
(Chord("<b' d''>8"), Chord("<c'' e''>8"))

Returns generator.

IterationAgent.by_semantic_voice(reverse=False, start=0, stop=None)

Iterates by semantic voice.

Todo

Deprecated. Use IterationAgent.by_class(Voice) instead.

Example 1. Iterates semantic voices:

>>> pairs = [(3, 8), (5, 16), (5, 16)]
>>> measures = scoretools.make_spacer_skip_measures(pairs)
>>> time_signature_voice = Voice(measures)
>>> time_signature_voice.name = 'TimeSignatureVoice'
>>> time_signature_voice.is_nonsemantic = True
>>> music_voice = Voice("c'4. d'4 e'16 f'4 g'16")
>>> music_voice.name = 'MusicVoice'
>>> staff = Staff([time_signature_voice, music_voice])
>>> staff.is_simultaneous = True
>>> show(staff) 

Example 2. Reverses direction of iteration:

>>> pairs = [(3, 8), (5, 16), (5, 16)]
>>> measures = scoretools.make_spacer_skip_measures(pairs)
>>> time_signature_voice = Voice(measures)
>>> time_signature_voice.name = 'TimeSignatureVoice'
>>> time_signature_voice.is_nonsemantic = True
>>> music_voice = Voice("c'4. d'4 e'16 f'4 g'16")
>>> music_voice.name = 'MusicVoice'
>>> staff = Staff([time_signature_voice, music_voice])
>>> staff.is_simultaneous = True
>>> show(staff) 
>>> for voice in iterate(staff).by_semantic_voice(reverse=True):
...   voice
...
Voice("c'4. d'4 e'16 f'4 g'16")

Returns generator.

IterationAgent.by_spanner(prototype=None, reverse=False)

Iterates by spanner.

Example 1. Iterates spanners:

>>> staff = Staff("c'8 d'8 e'8 f'8 g'8 a'8 f'8 b'8 c''8")
>>> attach(Slur(), staff[:4])
>>> attach(Slur(), staff[4:])
>>> attach(Beam(), staff[:])
>>> show(staff) 
>>> for spanner in iterate(staff).by_spanner():
...     spanner
...
Beam("c'8, d'8, ... [5] ..., b'8, c''8")
Slur("c'8, d'8, e'8, f'8")
Slur("g'8, a'8, f'8, b'8, c''8")

Example 2. Reverses direction of iteration:

>>> staff = Staff("c'8 d'8 e'8 f'8 g'8 a'8 f'8 b'8 c''8")
>>> attach(Slur(), staff[:4])
>>> attach(Slur(), staff[4:])
>>> attach(Beam(), staff[:])
>>> show(staff) 
>>> for spanner in iterate(staff).by_spanner(reverse=True):
...     spanner
...
Beam("c'8, d'8, ... [5] ..., b'8, c''8")
Slur("g'8, a'8, f'8, b'8, c''8")
Slur("c'8, d'8, e'8, f'8")

Returns generator.

IterationAgent.by_timeline(prototype=None, reverse=False)

Iterates by timeline.

Example 1. Iterates leaves by timeline.

>>> score = Score([])
>>> score.append(Staff("c'4 d'4 e'4 f'4"))
>>> score.append(Staff("g'8 a'8 b'8 c''8"))
>>> show(score) 
>>> for leaf in iterate(score).by_timeline():
...     leaf
...
Note("c'4")
Note("g'8")
Note("a'8")
Note("d'4")
Note("b'8")
Note("c''8")
Note("e'4")
Note("f'4")

Example 2. Reverses direction of iteration:

>>> score = Score([])
>>> score.append(Staff("c'4 d'4 e'4 f'4"))
>>> score.append(Staff("g'8 a'8 b'8 c''8"))
>>> show(score) 
>>> for leaf in iterate(score).by_timeline(reverse=True):
...     leaf
...
Note("f'4")
Note("e'4")
Note("d'4")
Note("c''8")
Note("b'8")
Note("c'4")
Note("a'8")
Note("g'8")

Example 3. Iterates with grace notes:

>>> voice = Voice("c'8 [ d'8 e'8 f'8 ]")
>>> grace_notes = [Note("cf''16"), Note("bf'16")]
>>> grace = scoretools.GraceContainer(
...     grace_notes,
...     kind='grace',
...     )
>>> attach(grace, voice[1])
>>> show(voice) 
>>> for component in iterate(voice).by_timeline():
...     component
... 
Note("c'8")
Note("d'8")
Note("e'8")
Note("f'8")

Todo

Incorrect because grace notes are not included.

Iterates leaves when prototype is none.

IterationAgent.by_timeline_and_logical_tie(nontrivial=False, pitched=False, reverse=False)

Iterates by timeline and logical tie.

>>> score = Score([])
>>> score.append(Staff("c''4 ~ c''8 d''8 r4 ef''4"))
>>> score.append(Staff("r8 g'4. ~ g'8 r16 f'8. ~ f'8"))
>>> show(score) 
>>> for logical_tie in iterate(score).by_timeline_and_logical_tie():
...     logical_tie
...
LogicalTie([Note("c''4"), Note("c''8")])
LogicalTie([Rest('r8')])
LogicalTie([Note("g'4."), Note("g'8")])
LogicalTie([Note("d''8")])
LogicalTie([Rest('r4')])
LogicalTie([Rest('r16')])
LogicalTie([Note("f'8."), Note("f'8")])
LogicalTie([Note("ef''4")])

Example 2. Reverses direction of iteration:

>>> score = Score([])
>>> score.append(Staff("c''4 ~ c''8 d''8 r4 ef''4"))
>>> score.append(Staff("r8 g'4. ~ g'8 r16 f'8. ~ f'8"))
>>> show(score) 
>>> for logical_tie in iterate(score).by_timeline_and_logical_tie(
...     reverse=True,
...     ):
...     logical_tie
...
LogicalTie([Note("ef''4")])
LogicalTie([Note("f'8."), Note("f'8")])
LogicalTie([Rest('r4')])
LogicalTie([Rest('r16')])
LogicalTie([Note("g'4."), Note("g'8")])
LogicalTie([Note("d''8")])
LogicalTie([Note("c''4"), Note("c''8")])
LogicalTie([Rest('r8')])

Example 3. Iterates pitched logical ties by timeline:

>>> for logical_tie in iterate(score).by_timeline_and_logical_tie(
...     pitched=True,
...     ):
...     logical_tie
...
LogicalTie([Note("c''4"), Note("c''8")])
LogicalTie([Note("g'4."), Note("g'8")])
LogicalTie([Note("d''8")])
LogicalTie([Note("f'8."), Note("f'8")])
LogicalTie([Note("ef''4")])

Example 4. Iterates nontrivial logical ties by timeline:

>>> for logical_tie in iterate(score).by_timeline_and_logical_tie(
...     nontrivial=True,
...     ):
...     logical_tie
...
LogicalTie([Note("c''4"), Note("c''8")])
LogicalTie([Note("g'4."), Note("g'8")])
LogicalTie([Note("f'8."), Note("f'8")])
IterationAgent.by_timeline_from_component(prototype=None, reverse=False)

Iterates from client by timeline.

Example 1. Iterates from note by timeline:

>>> score = Score([])
>>> score.append(Staff("c'4 d'4 e'4 f'4"))
>>> score.append(Staff("g'8 a'8 b'8 c''8"))
>>> show(score) 
>>> for leaf in iterate(score[1][2]).by_timeline_from_component():
...     leaf
...
Note("b'8")
Note("c''8")
Note("e'4")
Note("f'4")

Example 2. Reverses direction of iteration:

>>> score = Score([])
>>> score.append(Staff("c'4 d'4 e'4 f'4"))
>>> score.append(Staff("g'8 a'8 b'8 c''8"))
>>> show(score) 
>>> for leaf in iterate(score[1][2]).by_timeline_from_component(
...     reverse=True):
...     leaf
...
Note("b'8")
Note("c'4")
Note("a'8")
Note("g'8")

Yields components sorted backward by score offset stop time when reverse is true.

Iterates leaves when prototype is none.

IterationAgent.by_topmost_logical_ties_and_components()

Iterates by topmost logical ties and components.

Example 1. Iterates topmost logical ties and components:

>>> string = r"c'8 ~ c'32 d'8 ~ d'32 \times 2/3 { e'8 f'8 g'8 } "
>>> string += "a'8 ~ a'32 b'8 ~ b'32"
>>> staff = Staff(string)
>>> show(staff) 
>>> for item in iterate(staff).by_topmost_logical_ties_and_components():
...     item
...
LogicalTie([Note("c'8"), Note("c'32")])
LogicalTie([Note("d'8"), Note("d'32")])
Tuplet(Multiplier(2, 3), "e'8 f'8 g'8")
LogicalTie([Note("a'8"), Note("a'32")])
LogicalTie([Note("b'8"), Note("b'32")])

Returns generator.

IterationAgent.by_vertical_moment(reverse=False)

Iterates by vertical moment.

Example 1. Iterates vertical moments:

>>> score = Score([])
>>> staff = Staff(r"\times 4/3 { d''8 c''8 b'8 }")
>>> score.append(staff)
>>> staff_group = StaffGroup([])
>>> staff_group.context_name = 'PianoStaff'
>>> staff_group.append(Staff("a'4 g'4"))
>>> staff_group.append(Staff(r"""\clef "bass" f'8 e'8 d'8 c'8"""))
>>> score.append(staff_group)
>>> show(score) 
>>> for vertical_moment in iterate(score).by_vertical_moment():
...     vertical_moment.leaves
...
(Note("d''8"), Note("a'4"), Note("f'8"))
(Note("d''8"), Note("a'4"), Note("e'8"))
(Note("c''8"), Note("a'4"), Note("e'8"))
(Note("c''8"), Note("g'4"), Note("d'8"))
(Note("b'8"), Note("g'4"), Note("d'8"))
(Note("b'8"), Note("g'4"), Note("c'8"))
>>> for vertical_moment in iterate(staff_group).by_vertical_moment():
...     vertical_moment.leaves
...
(Note("a'4"), Note("f'8"))
(Note("a'4"), Note("e'8"))
(Note("g'4"), Note("d'8"))
(Note("g'4"), Note("c'8"))

Example 2. Reverses direction of iteration:

>>> score = Score([])
>>> staff = Staff(r"\times 4/3 { d''8 c''8 b'8 }")
>>> score.append(staff)
>>> staff_group = StaffGroup([])
>>> staff_group.context_name = 'PianoStaff'
>>> staff_group.append(Staff("a'4 g'4"))
>>> staff_group.append(Staff(r"""\clef "bass" f'8 e'8 d'8 c'8"""))
>>> score.append(staff_group)
>>> show(score) 
>>> for vertical_moment in iterate(score).by_vertical_moment(reverse=True):
...     vertical_moment.leaves
...
(Note("b'8"), Note("g'4"), Note("c'8"))
(Note("b'8"), Note("g'4"), Note("d'8"))
(Note("c''8"), Note("g'4"), Note("d'8"))
(Note("c''8"), Note("a'4"), Note("e'8"))
(Note("d''8"), Note("a'4"), Note("e'8"))
(Note("d''8"), Note("a'4"), Note("f'8"))
>>> for vertical_moment in iterate(staff_group).by_vertical_moment(reverse=True):
...     vertical_moment.leaves
...
(Note("g'4"), Note("c'8"))
(Note("g'4"), Note("d'8"))
(Note("a'4"), Note("e'8"))
(Note("a'4"), Note("f'8"))

Returns generator.

IterationAgent.depth_first(capped=True, direction=Left, forbid=None, unique=True)

Iterates depth first.

Example 1. Iterates depth first:

>>> score = Score([])
>>> score.append(Staff("c''4 ~ c''8 d''8 r4 ef''4"))
>>> score.append(Staff("r8 g'4. ~ g'8 r16 f'8. ~ f'8"))
>>> show(score) 
>>> for component in iterate(score).depth_first():
...     component
...
<Score<<2>>>
Staff("c''4 ~ c''8 d''8 r4 ef''4")
Note("c''4")
Note("c''8")
Note("d''8")
Rest('r4')
Note("ef''4")
Staff("r8 g'4. ~ g'8 r16 f'8. ~ f'8")
Rest('r8')
Note("g'4.")
Note("g'8")
Rest('r16')
Note("f'8.")
Note("f'8")

Example 2. Reverses direction of iteration:

>>> score = Score([])
>>> score.append(Staff("c''4 ~ c''8 d''8 r4 ef''4"))
>>> score.append(Staff("r8 g'4. ~ g'8 r16 f'8. ~ f'8"))
>>> show(score) 
>>> for component in iterate(score).depth_first(direction=Right):
...     component
...
<Score<<2>>>
Staff("r8 g'4. ~ g'8 r16 f'8. ~ f'8")
Note("f'8")
Note("f'8.")
Rest('r16')
Note("g'8")
Note("g'4.")
Rest('r8')
Staff("c''4 ~ c''8 d''8 r4 ef''4")
Note("ef''4")
Rest('r4')
Note("d''8")
Note("c''8")
Note("c''4")

Example 3. Iterates with grace notes:

>>> voice = Voice("c'8 [ d'8 e'8 f'8 ]")
>>> grace_notes = [Note("cf''16"), Note("bf'16")]
>>> grace = scoretools.GraceContainer(
...     grace_notes,
...     kind='grace',
...     )
>>> attach(grace, voice[1])
>>> after_grace_notes = [Note("af'16"), Note("gf'16")]
>>> after_grace = scoretools.GraceContainer(
...     after_grace_notes,
...     kind='after')
>>> attach(after_grace, voice[1])
>>> show(voice) 
>>> for component in iterate(voice).depth_first():
...     component
...
Voice("c'8 d'8 e'8 f'8")
Note("c'8")
Note("d'8")
GraceContainer("cf''16 bf'16")
Note("cf''16")
Note("bf'16")
GraceContainer("af'16 gf'16")
Note("af'16")
Note("gf'16")
Note("e'8")
Note("f'8")

Note

Reverse-iteration does not yet support grace notes. (Relatively straightforward to implement when the need arises.)

Returns generator.

Special methods

(AbjadObject).__eq__(expr)

Is true when ID of expr equals ID of Abjad object. Otherwise false.

Returns true or false.

(AbjadObject).__format__(format_specification='')

Formats Abjad object.

Set format_specification to ‘’ or ‘storage’. Interprets ‘’ equal to ‘storage’.

Returns string.

(AbjadObject).__hash__()

Hashes Abjad object.

Required to be explicitly redefined on Python 3 if __eq__ changes.

Returns integer.

(AbjadObject).__ne__(expr)

Is true when Abjad object does not equal expr. Otherwise false.

Returns true or false.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.