GraceContainer

class scoretools.GraceContainer(music=None, kind='grace')

A grace container.

Example 1. Grace notes:

>>> voice = Voice("c'4 d'4 e'4 f'4")
>>> grace_notes = [Note("c'16"), Note("d'16")]
>>> grace_container = scoretools.GraceContainer(
...     grace_notes,
...     kind='grace',
...     )
>>> attach(grace_container, voice[1])
>>> show(voice) 

Example 2. After-grace notes:

>>> voice = Voice("c'4 d'4 e'4 f'4")
>>> grace_notes = [Note("c'16"), Note("d'16")]
>>> grace_container = scoretools.GraceContainer(
...     grace_notes,
...     kind='after',
...     )
>>> attach(grace_container, voice[1])
>>> show(voice) 

Fill grace containers with notes, rests or chords.

Attach grace containers to notes, rests or chords.

Example 3. Detaches all grace containers:

>>> voice = Voice("c'4 d'4 e'4 f'4")
>>> note = Note("cs'16")
>>> grace_container = scoretools.GraceContainer(
...     [note],
...     kind='grace',
...     )
>>> attach(grace_container, voice[1])
>>> note = Note("ds'16")
>>> after_grace_container = scoretools.GraceContainer(
...     [note],
...     kind='after',
...     )
>>> attach(after_grace_container, voice[1])
>>> show(voice) 
>>> detach(scoretools.GraceContainer, voice[1])
(GraceContainer(), GraceContainer())
>>> show(voice) 

Example 4. Detaches (proper) grace container but leaves after grace container attached:

>>> voice = Voice("c'4 d'4 e'4 f'4")
>>> note = Note("cs'16")
>>> grace_container = scoretools.GraceContainer(
...     [note],
...     kind='grace',
...     )
>>> attach(grace_container, voice[1])
>>> note = Note("ds'16")
>>> after_grace_container = scoretools.GraceContainer(
...     [note],
...     kind='after',
...     )
>>> attach(after_grace_container, voice[1])
>>> show(voice) 
>>> detach(grace_container, voice[1])
(GraceContainer(),)
>>> show(voice) 

Example 5. Detaches after grace container but leaves (proper) grace container attached:

>>> voice = Voice("c'4 d'4 e'4 f'4")
>>> note = Note("cs'16")
>>> grace_container = scoretools.GraceContainer(
...     [note],
...     kind='grace',
...     )
>>> attach(grace_container, voice[1])
>>> note = Note("ds'16")
>>> after_grace_container = scoretools.GraceContainer(
...     [note],
...     kind='after',
...     )
>>> attach(after_grace_container, voice[1])
>>> show(voice) 
>>> detach(after_grace_container, voice[1])
(GraceContainer(),)
>>> show(voice) 

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_scoretools { graph [label=scoretools]; "abjad.tools.scoretools.Component.Component" [color=3, group=2, label=Component, shape=oval, style=bold]; "abjad.tools.scoretools.Container.Container" [color=3, group=2, label=Container, shape=box]; "abjad.tools.scoretools.GraceContainer.GraceContainer" [color=black, fontcolor=white, group=2, label=<<B>GraceContainer</B>>, shape=box, style="filled, rounded"]; "abjad.tools.scoretools.Component.Component" -> "abjad.tools.scoretools.Container.Container"; "abjad.tools.scoretools.Container.Container" -> "abjad.tools.scoretools.GraceContainer.GraceContainer"; } subgraph cluster_builtins { graph [label=builtins]; "builtins.object" [color=2, group=1, label=object, shape=box]; } "abjad.tools.abctools.AbjadObject.AbjadObject" -> "abjad.tools.scoretools.Component.Component"; "builtins.object" -> "abjad.tools.abctools.AbjadObject.AbstractBase"; }

Bases

Attribute summary

append(component) Appends component to container.
extend(expr) Extends container with expr.
index(component) Returns index of component in container.
insert(i, component[, fracture_spanners]) Inserts component at index i in container.
is_simultaneous Is true when container is simultaneous.
kind Gets and sets kind.
name Gets and sets name of container.
pop([i]) Pops component from container at index i.
remove(component) Removes component from container.
reverse() Reverses contents of container.
__contains__(expr) Is true when expr appears in container.
__copy__(\*args) Copies component with indicators but without children of component or spanners attached to component.
__delitem__(i) Deletes components(s) at index i in container.
__eq__(expr) Is true when ID of expr equals ID of Abjad object.
__format__([format_specification]) Formats component.
__getitem__(i) Gets container i.
__graph__([spanner]) Graphviz graph representation of container.
__hash__() Hashes Abjad object.
__illustrate__() Illustrates component.
__iter__() Iterates container.
__len__() Gets number of items in container.
__mul__(n) Copies component n times and detaches spanners.
__ne__(expr) Is true when Abjad object does not equal expr.
__repr__() Gets interpreter representation of leaf.
__rmul__(n) Copies component n times and detach spanners.
__setitem__(i, expr) Sets container i equal to expr.

Read/write properties

(Container).is_simultaneous

Is true when container is simultaneous. Otherwise false.

Example 1. Gets simultaneity status of container:

>>> container = Container()
>>> container.append(Voice("c'8 d'8 e'8"))
>>> container.append(Voice('g4.'))
>>> show(container) 
>>> container.is_simultaneous
False

Example 2. Sets simultaneity status of container:

>>> container = Container()
>>> container.append(Voice("c'8 d'8 e'8"))
>>> container.append(Voice('g4.'))
>>> show(container) 
>>> container.is_simultaneous = True
>>> show(container) 

Defaults to false.

Set to true or false.

Returns true or false.

GraceContainer.kind

Gets and sets kind.

Example 1. Grace notes:

>>> voice = Voice("c'4 d'4 e'4 f'4")
>>> grace_container = scoretools.GraceContainer(
...     [Note("e'16")],
...     kind='grace',
...     )
>>> attach(grace_container, voice[1])
>>> show(voice) 

LilyPond positions grace notes immediately before main notes.

LilyPond formats grace notes with neither a slashed nor a slur.

Example 2. Acciaccatura:

>>> voice = Voice("c'4 d'4 e'4 f'4")
>>> grace_container = scoretools.GraceContainer(
...     [Note("e'16")],
...     kind='acciaccatura',
...     )
>>> attach(grace_container, voice[1])
>>> show(voice) 

Acciaccaturas are played before the beat.

LilyPond positions acciaccaturas immediately before main notes.

LilyPond formats one-note acciaccaturas with a slashed stem and a slur.

Note

LilyPond fails to format multinote acciaccaturas with a slashed stem. This means that multinote acciaccaturas look exactly like appoggiaturas.

Example 3. Appoggiatura:

>>> voice = Voice("c'4 d'4 e'4 f'4")
>>> grace_container = scoretools.GraceContainer(
...     [Note("e'16")],
...     kind='appoggiatura',
...     )
>>> attach(grace_container, voice[1])
>>> show(voice) 

Appoggiaturas are played on the beat.

LilyPond positions appoggiaturas immediately before main notes.

LilyPond formats appoggiaturas with a slur but without a slashed stem.

Example 4. After-grace notes:

>>> voice = Voice("c'4 d'4 e'4 f'4")
>>> string = '#(define afterGraceFraction (cons 15 16))'
>>> command = indicatortools.LilyPondCommand(string)
>>> attach(command, voice[0])
>>> grace_container = scoretools.GraceContainer(
...     [Note("g'16")],
...     kind='after',
...     )
>>> attach(grace_container, voice[-1])
>>> show(voice) 

After-grace notes are played at the very end of the note they follow.

Use after-grace notes when you need to end a piece of music with grace notes.

LilyPond positions after-grace notes at a point 3/4 of the way after the note they follow. The resulting spacing is usually too loose.

Customize aftterGraceFraction as shown above.

Defaults to 'grace'.

Set to 'grace', 'acciaccatura', 'appoggiatura' or 'after'.

Returns 'grace', 'acciaccatura', 'appoggiatura' or 'after'.

(Container).name

Gets and sets name of container.

Example 1. Gets container name:

>>> container = Container("c'4 d'4 e'4 f'4")
>>> show(container) 
>>> container.name is None
True

Example 2. Sets container name:

>>> container = Container("c'4 d'4 e'4 f'4", name='Special')
>>> show(container) 
>>> container.name
'Special'

Container name does not appear in LilyPond output:

>>> f(container)
{
    c'4
    d'4
    e'4
    f'4
}

Defaults to none.

Set to string or none.

Returns string or none.

Methods

(Container).append(component)

Appends component to container.

Example 1. Appends note to container:

>>> container = Container("c'4 ( d'4 f'4 )")
>>> show(container) 
>>> container.append(Note("e'4"))
>>> show(container) 

Returns none.

(Container).extend(expr)

Extends container with expr.

Example 1. Extends container with three notes:

>>> container = Container("c'4 ( d'4 f'4 )")
>>> show(container) 
>>> notes = [Note("e'32"), Note("d'32"), Note("e'16")]
>>> container.extend(notes)
>>> show(container) 

Returns none.

(Container).index(component)

Returns index of component in container.

Example 1. Gets index of last element in container:

>>> container = Container("c'4 d'4 f'4 e'4")
>>> show(container) 
>>> note = container[-1]
>>> note
Note("e'4")
>>> container.index(note)
3

Returns nonnegative integer.

(Container).insert(i, component, fracture_spanners=False)

Inserts component at index i in container.

Example 1. Inserts note. Does not fracture spanners:

>>> container = Container([])
>>> container.extend("fs16 cs' e' a'")
>>> container.extend("cs''16 e'' cs'' a'")
>>> container.extend("fs'16 e' cs' fs")
>>> slur = spannertools.Slur(direction=Down)
>>> attach(slur, container[:])
>>> show(container) 
>>> container.insert(-4, Note("e'4"), fracture_spanners=False)
>>> show(container) 

Example 2. Inserts note. Fractures spanners:

>>> container = Container([])
>>> container.extend("fs16 cs' e' a'")
>>> container.extend("cs''16 e'' cs'' a'")
>>> container.extend("fs'16 e' cs' fs")
>>> slur = spannertools.Slur(direction=Down)
>>> attach(slur, container[:])
>>> show(container) 
>>> container.insert(-4, Note("e'4"), fracture_spanners=True)
>>> show(container) 

Returns none.

(Container).pop(i=-1)

Pops component from container at index i.

Example 1. Pops last element from container:

>>> container = Container("c'4 ( d'4 f'4 ) e'4")
>>> show(container) 
>>> container.pop()
Note("e'4")
>>> show(container) 

Returns component.

(Container).remove(component)

Removes component from container.

Example 1. Removes note from container:

>>> container = Container("c'4 ( d'4 f'4 ) e'4")
>>> show(container) 
>>> note = container[2]
>>> note
Note("f'4")
>>> container.remove(note)
>>> show(container) 

Returns none.

(Container).reverse()

Reverses contents of container.

Example 1. Reverses staff:

>>> staff = Staff("c'8 [ d'8 ] e'8 ( f'8 )")
>>> show(staff) 
>>> staff.reverse()
>>> show(staff) 

Returns none.

Special methods

(Container).__contains__(expr)

Is true when expr appears in container. Otherwise false.

Returns true or false.

(Component).__copy__(*args)

Copies component with indicators but without children of component or spanners attached to component.

Returns new component.

(Container).__delitem__(i)

Deletes components(s) at index i in container.

Example 1. Deletes first tuplet in voice:

>>> voice = Voice()
>>> voice.append(Tuplet((2, 3), "c'4 d'4 e'4"))
>>> voice.append(Tuplet((2, 3), "e'4 d'4 c'4"))
>>> leaves = iterate(voice).by_class(scoretools.Leaf)
>>> attach(Slur(), list(leaves))
>>> show(voice) 
>>> tuplet_1 = voice[0]
>>> del(voice[0])

First tuplet no longer appears in voice:

>>> show(voice) 
>>> inspect_(voice).is_well_formed()
True

First tuplet is no longer slurred but is still well-formed:

>>> show(tuplet_1) 
>>> inspect_(tuplet_1).is_well_formed()
True

Withdraws component(s) from crossing spanners.

Preserves spanners that component(s) cover(s).

Returns none.

(AbjadObject).__eq__(expr)

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

Returns true or false.

(Component).__format__(format_specification='')

Formats component.

Set format_specification to ‘’, ‘lilypond’ or ‘storage’.

Returns string.

(Container).__getitem__(i)

Gets container i.

Traverses top-level items only.

Returns component.

(Container).__graph__(spanner=None, **kwargs)

Graphviz graph representation of container.

Returns Graphviz graph.

(AbjadObject).__hash__()

Hashes Abjad object.

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

Returns integer.

(Component).__illustrate__()

Illustrates component.

Returns LilyPond file.

(Container).__iter__()

Iterates container.

Example 1. Abjad containers are iterables:

>>> import collections
>>> container = Container()
>>> isinstance(container, collections.Iterable)
True

Example 2. Abjad containers are not sequences:

>>> import collections
>>> container = Container()
>>> isinstance(container, collections.Sequence)
False

Yields container elements.

Returns generator.

(Container).__len__()

Gets number of items in container.

Returns nonnegative integer.

(Component).__mul__(n)

Copies component n times and detaches spanners.

Returns list of new components.

(AbjadObject).__ne__(expr)

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

Returns true or false.

(Component).__repr__()

Gets interpreter representation of leaf.

Returns string.

(Component).__rmul__(n)

Copies component n times and detach spanners.

Returns list of new components.

(Container).__setitem__(i, expr)

Sets container i equal to expr. Finds spanners that dominate self[i] and children of self[i]. Replaces contents at self[i] with ‘expr’. Reattaches spanners to new contents. Always leaves score tree in tact.

Returns none.