iterate

---

Functions

components	Iterates components in argument.
leaves	Iterates leaves in argument.
logical_ties	Iterates logical ties in argument.
pitches	Iterates pitches in argument.
timeline	Iterates leaves in argument in timeline order.

abjad.iterate.components(argument, prototype=None, *, exclude=None, grace=None, reverse=None)

Iterates components in argument.

Grace iteration is controlled by a ternary flag.

>>> music_voice = abjad.Voice("c'4 d' e' f'", name="MusicVoice")
>>> container = abjad.BeforeGraceContainer("cs'16")
>>> abjad.attach(container, music_voice[1])
>>> container = abjad.on_beat_grace_container("g'16 gs' a' as'", music_voice[2:3])
>>> abjad.attach(abjad.Articulation(">"), container[0])
>>> container = abjad.AfterGraceContainer("fs'16")
>>> abjad.attach(container, music_voice[3])
>>> staff = abjad.Staff([music_voice])
>>> lilypond_file = abjad.LilyPondFile([r'\include "abjad.ily"', staff])
>>> abjad.show(lilypond_file)  

Leave grace unset to iterate grace and nongrace components together:

>>> for component in abjad.iterate.components(staff):
...     component
... 
Staff("{ c'4 d'4 { { <e' g'>16 gs'16 a'16 as'16 } { e'4 } } f'4 }")
Voice("c'4 d'4 { { <e' g'>16 gs'16 a'16 as'16 } { e'4 } } f'4", name='MusicVoice')
Note("c'4")
BeforeGraceContainer("cs'16")
Note("cs'16")
Note("d'4")
Container("{ <e' g'>16 gs'16 a'16 as'16 } { e'4 }")
OnBeatGraceContainer("<e' g'>16 gs'16 a'16 as'16")
Chord("<e' g'>16")
Note("gs'16")
Note("a'16")
Note("as'16")
Voice("e'4", name='MusicVoice')
Note("e'4")
Note("f'4")
AfterGraceContainer("fs'16")
Note("fs'16")

>>> for component in abjad.iterate.components(staff, reverse=True):
...     component
... 
Staff("{ c'4 d'4 { { <e' g'>16 gs'16 a'16 as'16 } { e'4 } } f'4 }")
Voice("c'4 d'4 { { <e' g'>16 gs'16 a'16 as'16 } { e'4 } } f'4", name='MusicVoice')
AfterGraceContainer("fs'16")
Note("fs'16")
Note("f'4")
Container("{ <e' g'>16 gs'16 a'16 as'16 } { e'4 }")
Voice("e'4", name='MusicVoice')
Note("e'4")
OnBeatGraceContainer("<e' g'>16 gs'16 a'16 as'16")
Note("as'16")
Note("a'16")
Note("gs'16")
Chord("<e' g'>16")
Note("d'4")
BeforeGraceContainer("cs'16")
Note("cs'16")
Note("c'4")

Set grace=True to iterate only grace components:

>>> for component in abjad.iterate.components(staff, grace=True):
...     component
... 
BeforeGraceContainer("cs'16")
Note("cs'16")
OnBeatGraceContainer("<e' g'>16 gs'16 a'16 as'16")
Chord("<e' g'>16")
Note("gs'16")
Note("a'16")
Note("as'16")
AfterGraceContainer("fs'16")
Note("fs'16")

>>> for component in abjad.iterate.components(staff, grace=True, reverse=True):
...     component
... 
AfterGraceContainer("fs'16")
Note("fs'16")
OnBeatGraceContainer("<e' g'>16 gs'16 a'16 as'16")
Note("as'16")
Note("a'16")
Note("gs'16")
Chord("<e' g'>16")
BeforeGraceContainer("cs'16")
Note("cs'16")

Set grace=False to iterate only nongrace components:

>>> for component in abjad.iterate.components(staff, grace=False):
...     component
... 
Staff("{ c'4 d'4 { { <e' g'>16 gs'16 a'16 as'16 } { e'4 } } f'4 }")
Voice("c'4 d'4 { { <e' g'>16 gs'16 a'16 as'16 } { e'4 } } f'4", name='MusicVoice')
Note("c'4")
Note("d'4")
Container("{ <e' g'>16 gs'16 a'16 as'16 } { e'4 }")
Voice("e'4", name='MusicVoice')
Note("e'4")
Note("f'4")

>>> for component in abjad.iterate.components(staff, grace=False, reverse=True):
...     component
... 
Staff("{ c'4 d'4 { { <e' g'>16 gs'16 a'16 as'16 } { e'4 } } f'4 }")
Voice("c'4 d'4 { { <e' g'>16 gs'16 a'16 as'16 } { e'4 } } f'4", name='MusicVoice')
Note("f'4")
Container("{ <e' g'>16 gs'16 a'16 as'16 } { e'4 }")
Voice("e'4", name='MusicVoice')
Note("e'4")
Note("d'4")
Note("c'4")

abjad.iterate.leaves(argument, prototype=None, *, exclude=None, grace=None, pitched=None, reverse=None)

Iterates leaves in argument.

Set exclude=<annotation> to exclude leaves with annotation:

>>> staff = abjad.Staff()
>>> score = abjad.Score([staff], name="Score")
>>> staff.extend("<c' bf'>8 <g' a'>8")
>>> staff.extend("af'8 r8")
>>> staff.extend("r8 gf'8")
>>> abjad.attach(abjad.TimeSignature((2, 8)), staff[0])
>>> abjad.attach("RED", staff[0])
>>> abjad.attach("BLUE", staff[1])
>>> abjad.attach("GREEN", staff[2])
>>> abjad.attach("RED", staff[3])
>>> abjad.attach("BLUE", staff[4])
>>> abjad.attach("GREEN", staff[5])
>>> abjad.show(staff)  

>>> for leaf in abjad.iterate.leaves(staff, exclude=["RED", "BLUE"]):
...     leaf
... 
Note("af'8")
Note("gf'8")

Excludes leaves to which 'RED' or 'BLUE' attaches.

Grace iteration is controlled by a ternary flag.

>>> music_voice = abjad.Voice("c'4 d' e' f'", name="MusicVoice")
>>> container = abjad.BeforeGraceContainer("cs'16")
>>> abjad.attach(container, music_voice[1])
>>> container = abjad.on_beat_grace_container("g'16 gs' a' as'", music_voice[2:3])
>>> abjad.attach(abjad.Articulation(">"), container[0])
>>> container = abjad.AfterGraceContainer("fs'16")
>>> abjad.attach(container, music_voice[3])
>>> staff = abjad.Staff([music_voice])
>>> lilypond_file = abjad.LilyPondFile([r'\include "abjad.ily"', staff])
>>> abjad.show(lilypond_file)  

Leave grace unset to iterate grace and nongrace leaves together:

>>> for leaf in abjad.iterate.leaves(staff):
...     leaf
... 
Note("c'4")
Note("cs'16")
Note("d'4")
Chord("<e' g'>16")
Note("gs'16")
Note("a'16")
Note("as'16")
Note("e'4")
Note("f'4")
Note("fs'16")

Set grace=True to iterate only grace leaves:

>>> for leaf in abjad.iterate.leaves(staff, grace=True):
...     leaf
... 
Note("cs'16")
Chord("<e' g'>16")
Note("gs'16")
Note("a'16")
Note("as'16")
Note("fs'16")

Set grace=False to iterate only nongrace leaves:

>>> for leaf in abjad.iterate.leaves(staff, grace=False):
...     leaf
... 
Note("c'4")
Note("d'4")
Note("e'4")
Note("f'4")

Pitched iteration is controlled by a ternary flag.

>>> staff = abjad.Staff()
>>> score = abjad.Score([staff], name="Score")
>>> staff.extend("<c' bf'>8 <g' a'>8")
>>> staff.extend("af'8 r8")
>>> staff.extend("r8 gf'8")
>>> abjad.attach(abjad.TimeSignature((2, 8)), staff[0])
>>> abjad.show(staff)  

Leaves pitched unset to iterate pitched and unpitched leaves together:

>>> for leaf in abjad.iterate.leaves(staff):
...     leaf
... 
Chord("<c' bf'>8")
Chord("<g' a'>8")
Note("af'8")
Rest('r8')
Rest('r8')
Note("gf'8")

>>> for leaf in abjad.iterate.leaves(staff, reverse=True):
...     leaf
... 
Note("gf'8")
Rest('r8')
Rest('r8')
Note("af'8")
Chord("<g' a'>8")
Chord("<c' bf'>8")

Set pitched=True to iterate pitched leaves only:

>>> for leaf in abjad.iterate.leaves(staff, pitched=True):
...     leaf
... 
Chord("<c' bf'>8")
Chord("<g' a'>8")
Note("af'8")
Note("gf'8")

>>> for leaf in abjad.iterate.leaves(staff, pitched=True, reverse=True):
...     leaf
... 
Note("gf'8")
Note("af'8")
Chord("<g' a'>8")
Chord("<c' bf'>8")

Set pitched=False to iterate unpitched leaves only:

>>> for leaf in abjad.iterate.leaves(staff, pitched=False):
...     leaf
... 
Rest('r8')
Rest('r8')

>>> for leaf in abjad.iterate.leaves(staff, pitched=False):
...     leaf
... 
Rest('r8')
Rest('r8')

Return type:

Iterator

abjad.iterate.logical_ties(argument, *, exclude=None, grace=None, nontrivial=None, pitched=None, reverse=None)

Iterates logical ties in argument.

Iterates logical ties:

>>> string = r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16"
>>> staff = abjad.Staff(string)
>>> abjad.show(staff)  

>>> for logical_tie in abjad.iterate.logical_ties(staff):
...     logical_tie
... 
LogicalTie(items=[Note("c'4"), Note("c'16")])
LogicalTie(items=[Note("d'8")])
LogicalTie(items=[Note("e'8")])
LogicalTie(items=[Note("f'4"), Note("f'16")])

Grace iteration is controlled by a ternary flag.

>>> music_voice = abjad.Voice("c'4 d' e' f'", name="MusicVoice")
>>> container = abjad.BeforeGraceContainer("cs'16")
>>> abjad.attach(container, music_voice[1])
>>> container = abjad.on_beat_grace_container("g'16 gs' a' as'", music_voice[2:3])
>>> abjad.attach(abjad.Articulation(">"), container[0])
>>> container = abjad.AfterGraceContainer("fs'16")
>>> abjad.attach(container, music_voice[3])
>>> staff = abjad.Staff([music_voice])
>>> lilypond_file = abjad.LilyPondFile([r'\include "abjad.ily"', staff])
>>> abjad.show(lilypond_file)  

Leave grace unset to iterate grace and nongrace logical ties together:

>>> for lt in abjad.iterate.logical_ties(staff):
...     lt
... 
LogicalTie(items=[Note("c'4")])
LogicalTie(items=[Note("cs'16")])
LogicalTie(items=[Note("d'4")])
LogicalTie(items=[Chord("<e' g'>16")])
LogicalTie(items=[Note("gs'16")])
LogicalTie(items=[Note("a'16")])
LogicalTie(items=[Note("as'16")])
LogicalTie(items=[Note("e'4")])
LogicalTie(items=[Note("f'4")])
LogicalTie(items=[Note("fs'16")])

>>> for lt in abjad.iterate.logical_ties(staff, reverse=True):
...     lt
... 
LogicalTie(items=[Note("fs'16")])
LogicalTie(items=[Note("f'4")])
LogicalTie(items=[Note("e'4")])
LogicalTie(items=[Note("as'16")])
LogicalTie(items=[Note("a'16")])
LogicalTie(items=[Note("gs'16")])
LogicalTie(items=[Chord("<e' g'>16")])
LogicalTie(items=[Note("d'4")])
LogicalTie(items=[Note("cs'16")])
LogicalTie(items=[Note("c'4")])

Set grace=True to iterate grace logical ties only:

>>> for lt in abjad.iterate.logical_ties(staff, grace=True):
...     lt
... 
LogicalTie(items=[Note("cs'16")])
LogicalTie(items=[Chord("<e' g'>16")])
LogicalTie(items=[Note("gs'16")])
LogicalTie(items=[Note("a'16")])
LogicalTie(items=[Note("as'16")])
LogicalTie(items=[Note("fs'16")])

>>> for lt in abjad.iterate.logical_ties(staff, grace=True, reverse=True):
...     lt
... 
LogicalTie(items=[Note("fs'16")])
LogicalTie(items=[Note("as'16")])
LogicalTie(items=[Note("a'16")])
LogicalTie(items=[Note("gs'16")])
LogicalTie(items=[Chord("<e' g'>16")])
LogicalTie(items=[Note("cs'16")])

Set grace=False to iterate nongrace logical ties only:

>>> for lt in abjad.iterate.logical_ties(staff, grace=False):
...     lt
... 
LogicalTie(items=[Note("c'4")])
LogicalTie(items=[Note("d'4")])
LogicalTie(items=[Note("e'4")])
LogicalTie(items=[Note("f'4")])

>>> for lt in abjad.iterate.logical_ties(staff, grace=False, reverse=True):
...     lt
... 
LogicalTie(items=[Note("f'4")])
LogicalTie(items=[Note("e'4")])
LogicalTie(items=[Note("d'4")])
LogicalTie(items=[Note("c'4")])

Logical tie triviality is controlled by a ternary flag.

>>> string = r"c'4 ~ \times 2/3 { c'8 d'4 }"
>>> string += r" e'4 ~ \times 2/3 { e'8 f' }"
>>> staff = abjad.Staff(string)
>>> abjad.show(staff)  

Leave nontrivial unset to iterate trivial and nontrivial logical ties together:

>>> for lt in abjad.iterate.logical_ties(staff):
...     lt
... 
LogicalTie(items=[Note("c'4"), Note("c'8")])
LogicalTie(items=[Note("d'4")])
LogicalTie(items=[Note("e'4"), Note("e'8")])
LogicalTie(items=[Note("f'8")])

>>> for lt in abjad.iterate.logical_ties(staff, reverse=True):
...     lt
... 
LogicalTie(items=[Note("f'8")])
LogicalTie(items=[Note("e'4"), Note("e'8")])
LogicalTie(items=[Note("d'4")])
LogicalTie(items=[Note("c'4"), Note("c'8")])

Set nontrivial=True to iterate nontrivial logical ties only:

>>> for lt in abjad.iterate.logical_ties(staff, nontrivial=True):
...     lt
... 
LogicalTie(items=[Note("c'4"), Note("c'8")])
LogicalTie(items=[Note("e'4"), Note("e'8")])

>>> for lt in abjad.iterate.logical_ties(staff, nontrivial=True, reverse=True):
...     lt
... 
LogicalTie(items=[Note("e'4"), Note("e'8")])
LogicalTie(items=[Note("c'4"), Note("c'8")])

Set nontrivial=False to iterate trivial logical ties only:

>>> for lt in abjad.iterate.logical_ties(staff, nontrivial=False):
...     lt
... 
LogicalTie(items=[Note("d'4")])
LogicalTie(items=[Note("f'8")])

>>> for lt in abjad.iterate.logical_ties(staff, nontrivial=False, reverse=True):
...     lt
... 
LogicalTie(items=[Note("f'8")])
LogicalTie(items=[Note("d'4")])

Logical tie pitchedness is controlled by a ternary flag.

>>> string = r"c'4 ~ \times 2/3 { c'8 r4 }"
>>> string += r"d'4 ~ \times 2/3 { d'8 r4 }"
>>> staff = abjad.Staff(string)
>>> abjad.show(staff)  

Leave pitched unset to iterate pitched and unpitched logical ties together:

>>> for lt in abjad.iterate.logical_ties(staff):
...     lt
... 
LogicalTie(items=[Note("c'4"), Note("c'8")])
LogicalTie(items=[Rest('r4')])
LogicalTie(items=[Note("d'4"), Note("d'8")])
LogicalTie(items=[Rest('r4')])

>>> for lt in abjad.iterate.logical_ties(staff, reverse=True):
...     lt
... 
LogicalTie(items=[Rest('r4')])
LogicalTie(items=[Note("d'4"), Note("d'8")])
LogicalTie(items=[Rest('r4')])
LogicalTie(items=[Note("c'4"), Note("c'8")])

Set pitched=True to iterate pitched logical ties only:

>>> for lt in abjad.iterate.logical_ties(staff, pitched=True):
...     lt
... 
LogicalTie(items=[Note("c'4"), Note("c'8")])
LogicalTie(items=[Note("d'4"), Note("d'8")])

>>> for lt in abjad.iterate.logical_ties(staff, pitched=True, reverse=True):
...     lt
... 
LogicalTie(items=[Note("d'4"), Note("d'8")])
LogicalTie(items=[Note("c'4"), Note("c'8")])

Set pitched=False to iterate unpitched logical ties only:

>>> for lt in abjad.iterate.logical_ties(staff, pitched=False):
...     lt
... 
LogicalTie(items=[Rest('r4')])
LogicalTie(items=[Rest('r4')])

>>> for lt in abjad.iterate.logical_ties(staff, pitched=False, reverse=True):
...     lt
... 
LogicalTie(items=[Rest('r4')])
LogicalTie(items=[Rest('r4')])

REGRESSION. Yields logical tie even when leaves are missing in input:

>>> voice = abjad.Voice("c'8 [ ~ c' ~ c' d' ]")
>>> abjad.show(voice)  

>>> selection = voice[:2]
>>> for logical_tie in abjad.iterate.logical_ties(selection):
...     logical_tie
... 
LogicalTie(items=[Note("c'8"), Note("c'8"), Note("c'8")])

Return type:

Iterator[LogicalTie]

abjad.iterate.pitches(argument)

Iterates pitches in argument.

Iterates pitches in container:

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> abjad.show(staff)  

>>> for pitch in abjad.iterate.pitches(staff):
...     pitch
... 
NamedPitch("c'")
NamedPitch("d'")
NamedPitch("e'")
NamedPitch("f'")

Iterates pitches in pitch set:

>>> pitch_set = abjad.PitchSet([0, 2, 4, 5])

>>> for pitch in abjad.iterate.pitches(pitch_set):
...     pitch
... 
NumberedPitch(0)
NumberedPitch(2)
NumberedPitch(4)
NumberedPitch(5)

Iterates different types of object in tuple:

>>> argument = (
...     abjad.NamedPitch("c'"),
...     abjad.Note("d'4"),
...     abjad.Chord("<e' fs' g>4"),
... )

>>> for pitch in abjad.iterate.pitches(argument):
...     pitch
... 
NamedPitch("c'")
NamedPitch("d'")
NamedPitch('g')
NamedPitch("e'")
NamedPitch("fs'")

Return type:

Iterator[NamedPitch]

abjad.iterate.timeline(argument, prototype=None, *, exclude=None, reverse=None)

Iterates leaves in argument in timeline order.

Timeline-iterates leaves:

>>> score = abjad.Score()
>>> score.append(abjad.Staff("c'4 d'4 e'4 f'4"))
>>> score.append(abjad.Staff("g'8 a'8 b'8 c''8"))
>>> abjad.show(score)  

>>> for leaf in abjad.iterate.timeline(score):
...     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")

>>> for component in abjad.iterate.timeline(score, reverse=True):
...     component
... 
Note("f'4")
Note("e'4")
Note("c''8")
Note("b'8")
Note("d'4")
Note("a'8")
Note("g'8")
Note("c'4")

REGRESSION. Works with grace note (and containers):

>>> music_voice = abjad.Voice("c'4 d' e' f'", name="MusicVoice")
>>> container = abjad.BeforeGraceContainer("cs'16")
>>> abjad.attach(container, music_voice[1])
>>> container = abjad.on_beat_grace_container("g'16 gs' a' as'", music_voice[2:3])
>>> abjad.attach(abjad.Articulation(">"), container[0])
>>> container = abjad.AfterGraceContainer("fs'16")
>>> abjad.attach(container, music_voice[3])
>>> staff = abjad.Staff([music_voice])
>>> lilypond_file = abjad.LilyPondFile([r'\include "abjad.ily"', staff])
>>> abjad.show(lilypond_file)  

>>> for leaf in abjad.iterate.timeline(staff):
...     leaf
... 
Note("c'4")
Note("cs'16")
Note("d'4")
Chord("<e' g'>16")
Note("gs'16")
Note("a'16")
Note("as'16")
Note("e'4")
Note("f'4")
Note("fs'16")

>>> for leaf in abjad.iterate.timeline(staff, reverse=True):
...     leaf
... 
Note("fs'16")
Note("f'4")
Note("e'4")
Note("as'16")
Note("a'16")
Note("gs'16")
Chord("<e' g'>16")
Note("d'4")
Note("cs'16")
Note("c'4")

Iterates leaves when prototype is none.

Return type:

tuple[Component, ...]