InspectionAgent

class agenttools.InspectionAgent(client=None)

Inspection agent.

>>> import abjad
>>> staff = abjad.Staff("c'4 e'4 d'4 f'4")
>>> show(staff) 
>>> abjad.inspect(staff)
InspectionAgent(client=Staff("c'4 e'4 d'4 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.InspectionAgent.InspectionAgent" [color=black, fontcolor=white, group=1, label=<<B>InspectionAgent</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.InspectionAgent.InspectionAgent"; "builtins.object" -> "abjad.tools.abctools.AbjadObject.AbstractBase"; }

Bases

Attribute summary

client Client of inspection agent.
get_after_grace_container() Gets after grace containers attached to leaf.
get_annotation(name[, default]) Gets annotation attached to client.
get_badly_formed_components() Gets badly formed components in client.
get_components([prototype, include_self]) Gets all components of prototype in the descendants of client.
get_contents([include_self]) Gets contents of client.
get_descendants([include_self]) Gets descendants of client.
get_duration([in_seconds]) Gets duration of client.
get_effective([prototype, unwrap, n]) Gets effective indicator that matches prototype and governs client.
get_effective_staff() Gets effective staff of client.
get_grace_container() Gets grace container attached to leaf.
get_indicator([prototype, default, unwrap]) Gets indicator of prototype attached to client.
get_indicators([prototype, unwrap]) Get all indicators matching prototype attached to client.
get_leaf([n]) Gets leaf n.
get_lineage() Gets lineage of client.
get_logical_tie() Gets logical tie that governs leaf.
get_markup([direction]) Gets all markup attached to client.
get_parentage([include_self, with_grace_notes]) Gets parentage of client.
get_piecewise([prototype, default]) Gets piecewise indicators attached to client.
get_sounding_pitch() Gets sounding pitch of client.
get_sounding_pitches() Gets sounding pitches of client.
get_spanner([prototype, default, in_parentage]) Gets spanner of prototype attached to client.
get_spanners([prototype, in_parentage]) Gets spanners attached to client.
get_timespan([in_seconds]) Gets timespan of client.
get_vertical_moment([governor]) Gets vertical moment starting with client.
get_vertical_moment_at(offset) Gets vertical moment at offset.
has_effective_indicator([prototype]) Is true when indicator that matches prototype is in effect for client.
has_indicator([prototype]) Is true when client has one or more indicators that match prototype.
has_spanner([prototype, in_parentage]) Is true when client has one or more spanners that match prototype.
is_bar_line_crossing() Is true when client crosses bar line.
is_well_formed() Is true when client is well-formed.
report_modifications() Reports modifications of client.
tabulate_well_formedness_violations([…]) Tabulates well-formedness violations in client.
__eq__(argument) Is true when ID of argument equals ID of Abjad object.
__format__([format_specification]) Formats Abjad object.
__hash__() Hashes Abjad object.
__ne__(argument) Is true when Abjad object does not equal argument.
__repr__() Gets interpreter representation of Abjad object.

Read-only properties

InspectionAgent.client

Client of inspection agent.

Returns component.

Methods

InspectionAgent.get_after_grace_container()

Gets after grace containers attached to leaf.

Get after grace container attached to note:

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> note = abjad.Note("ds'16")
>>> container = abjad.AfterGraceContainer([note])
>>> abjad.attach(container, staff[1])
>>> show(staff) 
>>> abjad.inspect(staff[1]).get_after_grace_container()
AfterGraceContainer("ds'16")

Returns after grace container or none.

InspectionAgent.get_annotation(name, default=None)

Gets annotation attached to client.

Gets named indicator:

>>> note = abjad.Note("c'4")
>>> abjad.annotate(note, 'bow_direction', Down)
>>> abjad.inspect(note).get_annotation('bow_direction')
Down

Returns none when no annotation is found:

>>> abjad.inspect(note).get_annotation('bow_fraction') is None
True

Returns default when no annotation is found:

>>> abjad.inspect(note).get_annotation('bow_fraction', 2)
2

Returns annotation or default.

InspectionAgent.get_badly_formed_components()

Gets badly formed components in client.

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> staff[1].written_duration = (1, 4)
>>> beam = abjad.Beam()
>>> abjad.attach(beam, staff[:])
>>> abjad.inspect(staff).get_badly_formed_components()
[Note("d'4")]

(Beamed quarter notes are not well formed.)

Returns list.

InspectionAgent.get_components(prototype=None, include_self=True)

Gets all components of prototype in the descendants of client.

Returns client selection.

InspectionAgent.get_contents(include_self=True)

Gets contents of client.

Returns sequential selection.

InspectionAgent.get_descendants(include_self=True)

Gets descendants of client.

Returns descendants.

InspectionAgent.get_duration(in_seconds=False)

Gets duration of client.

Returns duration.

InspectionAgent.get_effective(prototype=None, unwrap=True, n=0)

Gets effective indicator that matches prototype and governs client.

Gets components’ effective clef:

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> clef = abjad.Clef('alto')
>>> abjad.attach(clef, staff[0])
>>> note = abjad.Note("fs'16")
>>> container = abjad.AcciaccaturaContainer([note])
>>> abjad.attach(container, staff[-1])
>>> show(staff) 
>>> for leaf in abjad.iterate(staff).by_class(
...     with_grace_notes=True,
...     ):
...     agent = abjad.inspect(leaf)
...     clef = agent.get_effective(abjad.Clef)
...     print(leaf, clef)
...
Staff("c'4 d'4 e'4 f'4") Clef(name='alto')
c'4 Clef(name='alto')
d'4 Clef(name='alto')
e'4 Clef(name='alto')
fs'16 Clef(name='alto')
f'4 Clef(name='alto')

Returns indicator or none.

InspectionAgent.get_effective_staff()

Gets effective staff of client.

Returns staff or none.

InspectionAgent.get_grace_container()

Gets grace container attached to leaf.

Get acciaccatura container attached to note:

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> note = abjad.Note("cs'16")
>>> container = abjad.AcciaccaturaContainer([note])
>>> abjad.attach(container, staff[1])
>>> show(staff) 
>>> abjad.inspect(staff[1]).get_grace_container()
AcciaccaturaContainer("cs'16")

Returns grace container, acciaccatura container, appoggiatura container or none.

InspectionAgent.get_indicator(prototype=None, default=None, unwrap=True)

Gets indicator of prototype attached to client.

Raises exception when more than one indicator of prototype attach to client.

Returns default when no indicator of prototype attaches to client.

Returns indicator or default.

InspectionAgent.get_indicators(prototype=None, unwrap=True)

Get all indicators matching prototype attached to client.

Returns tuple.

InspectionAgent.get_leaf(n=0)

Gets leaf n.

Example score:

>>> staff = abjad.Staff()
>>> staff.append(abjad.Voice("c'8 d'8 e'8 f'8"))
>>> staff.append(abjad.Voice("g'8 a'8 b'8 c''8"))
>>> show(staff) 

Gets leaf n from client of inspection agent when client of inspection agent is a leaf.

With positive indices:

>>> first_leaf = staff[0][0]
>>> first_leaf
Note("c'8")
>>> for n in range(8):
...     leaf = abjad.inspect(first_leaf).get_leaf(n)
...     print(n, leaf)
...
0 c'8
1 d'8
2 e'8
3 f'8
4 None
5 None
6 None
7 None

With negative indices:

>>> last_leaf = staff[0][-1]
>>> last_leaf
Note("f'8")
>>> for n in range(0, -8, -1):
...     leaf = abjad.inspect(last_leaf).get_leaf(n)
...     print(n, leaf)
...
0 f'8
-1 e'8
-2 d'8
-3 c'8
-4 None
-5 None
-6 None
-7 None

Gets leaf n in client of inspection agent when client of inspection agent is a container.

With positive indices:

>>> first_voice = staff[0]
>>> first_voice
Voice("c'8 d'8 e'8 f'8")
>>> for n in range(8):
...     leaf = abjad.inspect(first_voice).get_leaf(n)
...     print(n, leaf)
...
0 c'8
1 d'8
2 e'8
3 f'8
4 None
5 None
6 None
7 None

With negative indices:

>>> first_voice = staff[0]
>>> first_voice
Voice("c'8 d'8 e'8 f'8")
>>> for n in range(-1, -9, -1):
...     leaf = abjad.inspect(first_voice).get_leaf(n)
...     print(n, leaf)
...
-1 f'8
-2 e'8
-3 d'8
-4 c'8
-5 None
-6 None
-7 None
-8 None

Returns leaf or none.

InspectionAgent.get_lineage()

Gets lineage of client.

Returns lineage.

InspectionAgent.get_logical_tie()

Gets logical tie that governs leaf.

Returns logical tie.

InspectionAgent.get_markup(direction=None)

Gets all markup attached to client.

Returns tuple.

InspectionAgent.get_parentage(include_self=True, with_grace_notes=False)

Gets parentage of client.

Gets parentage without grace notes:

>>> voice = abjad.Voice("c'4 d'4 e'4 f'4")
>>> container = abjad.GraceContainer("c'16 d'16")
>>> abjad.attach(container, voice[1])
>>> show(voice) 
>>> abjad.inspect(container[0]).get_parentage()
Parentage([Note("c'16"), GraceContainer("c'16 d'16")])

Gets parentage with grace notes:

>>> voice = abjad.Voice("c'4 d'4 e'4 f'4")
>>> container = abjad.GraceContainer("c'16 d'16")
>>> abjad.attach(container, voice[1])
>>> show(voice) 
>>> agent = abjad.inspect(container[0])
>>> agent.get_parentage(with_grace_notes=True)
Parentage([Note("c'16"), GraceContainer("c'16 d'16"), Note("d'4"), Voice("c'4 d'4 e'4 f'4")])

Returns parentage.

InspectionAgent.get_piecewise(prototype=None, default=None)

Gets piecewise indicators attached to client.

>>> staff = abjad.Staff("c'4 d'4 e'4 f'4")
>>> spanner = abjad.TextSpanner()
>>> abjad.attach(spanner, staff[:])
>>> spanner.attach(abjad.Markup('pont.'), staff[0])
>>> spanner.attach(abjad.Markup('ord.'), staff[-1])
>>> spanner.attach(abjad.ArrowLineSegment(), staff[0])
>>> abjad.override(staff).text_script.staff_padding = 1.25
>>> abjad.override(staff).text_spanner.staff_padding = 2
>>> show(staff) 
>>> for leaf in staff:
...     leaf, abjad.inspect(leaf).get_piecewise(abjad.Markup)
...
(Note("c'4"), Markup(contents=['pont.']))
(Note("d'4"), None)
(Note("e'4"), None)
(Note("f'4"), Markup(contents=['ord.']))

Returns indicator or default.

InspectionAgent.get_sounding_pitch()

Gets sounding pitch of client.

>>> staff = abjad.Staff("d''8 e''8 f''8 g''8")
>>> piccolo = abjad.instrumenttools.Piccolo()
>>> abjad.attach(piccolo, staff[0])
>>> abjad.Instrument.transpose_from_sounding_pitch(staff)
>>> show(staff) 

Returns named pitch.

InspectionAgent.get_sounding_pitches()

Gets sounding pitches of client.

>>> staff = abjad.Staff("<c''' e'''>4 <d''' fs'''>4")
>>> glockenspiel = abjad.instrumenttools.Glockenspiel()
>>> abjad.attach(glockenspiel, staff[0])
>>> abjad.Instrument.transpose_from_sounding_pitch(staff)
>>> show(staff) 
>>> abjad.inspect(staff[0]).get_sounding_pitches()
(NamedPitch("c'''"), NamedPitch("e'''"))

Returns tuple.

InspectionAgent.get_spanner(prototype=None, default=None, in_parentage=False)

Gets spanner of prototype attached to client.

Raises exception when more than one spanner of prototype attaches to client.

Returns default when no spanner of prototype attaches to client.

Returns spanner or default.

InspectionAgent.get_spanners(prototype=None, in_parentage=False)

Gets spanners attached to client.

Returns set.

InspectionAgent.get_timespan(in_seconds=False)

Gets timespan of client.

Gets timespan of grace notes:

>>> voice = abjad.Voice("c'8 [ d'8 e'8 f'8 ]")
>>> grace_notes = [abjad.Note("c'16"), abjad.Note("d'16")]
>>> container = abjad.GraceContainer(grace_notes)
>>> abjad.attach(container, voice[1])
>>> container = abjad.AfterGraceContainer("e'16 f'16")
>>> abjad.attach(container, voice[1])
>>> show(voice) 
>>> for leaf in abjad.iterate(voice).by_leaf(
...     with_grace_notes=True,
...     ):
...     timespan = abjad.inspect(leaf).get_timespan()
...     print(str(leaf) + ':')
...     f(timespan)
...
c'8:
abjad.Timespan(
    start_offset=abjad.Offset(0, 1),
    stop_offset=abjad.Offset(1, 8),
    )
c'16:
abjad.Timespan(
    start_offset=abjad.Offset(
        (1, 8),
        grace_displacement=abjad.Duration(-1, 8),
        ),
    stop_offset=abjad.Offset(
        (1, 8),
        grace_displacement=abjad.Duration(-1, 16),
        ),
    )
d'16:
abjad.Timespan(
    start_offset=abjad.Offset(
        (1, 8),
        grace_displacement=abjad.Duration(-1, 16),
        ),
    stop_offset=abjad.Offset(1, 8),
    )
d'8:
abjad.Timespan(
    start_offset=abjad.Offset(1, 8),
    stop_offset=abjad.Offset(1, 4),
    )
e'16:
abjad.Timespan(
    start_offset=abjad.Offset(
        (1, 4),
        grace_displacement=abjad.Duration(-1, 8),
        ),
    stop_offset=abjad.Offset(
        (1, 4),
        grace_displacement=abjad.Duration(-1, 16),
        ),
    )
f'16:
abjad.Timespan(
    start_offset=abjad.Offset(
        (1, 4),
        grace_displacement=abjad.Duration(-1, 16),
        ),
    stop_offset=abjad.Offset(1, 4),
    )
e'8:
abjad.Timespan(
    start_offset=abjad.Offset(1, 4),
    stop_offset=abjad.Offset(3, 8),
    )
f'8:
abjad.Timespan(
    start_offset=abjad.Offset(3, 8),
    stop_offset=abjad.Offset(1, 2),
    )

Returns timespan.

InspectionAgent.get_vertical_moment(governor=None)

Gets vertical moment starting with client.

>>> score = abjad.Score()
>>> tuplet = abjad.Tuplet((4, 3), "d''8 c''8 b'8")
>>> score.append(abjad.Staff([tuplet]))
>>> staff_group = abjad.StaffGroup(context_name='PianoStaff')
>>> staff_group.append(abjad.Staff("a'4 g'4"))
>>> staff_group.append(abjad.Staff("f'8 e'8 d'8 c'8"))
>>> clef = abjad.Clef('bass')
>>> abjad.attach(clef, staff_group[1][0])
>>> score.append(staff_group)
>>> agent = abjad.inspect(staff_group[1][1])
>>> moment = agent.get_vertical_moment(governor=staff_group)
>>> moment.leaves
Selection([Note("a'4"), Note("e'8")])
>>> agent = abjad.inspect(staff_group[1][2])
>>> moment = agent.get_vertical_moment(governor=staff_group)
>>> moment.leaves
Selection([Note("g'4"), Note("d'8")])
>>> agent = abjad.inspect(staff_group[1][3])
>>> moment = agent.get_vertical_moment(governor=staff_group)
>>> moment.leaves
Selection([Note("g'4"), Note("c'8")])

Returns vertical moment.

InspectionAgent.get_vertical_moment_at(offset)

Gets vertical moment at offset.

Returns vertical moment.

InspectionAgent.has_effective_indicator(prototype=None)

Is true when indicator that matches prototype is in effect for client. Otherwise false.

Returns true or false.

InspectionAgent.has_indicator(prototype=None)

Is true when client has one or more indicators that match prototype. Otherwise false.

Returns true or false.

InspectionAgent.has_spanner(prototype=None, in_parentage=False)

Is true when client has one or more spanners that match prototype. Otherwise false.

Returns true or false.

InspectionAgent.is_bar_line_crossing()

Is true when client crosses bar line. Otherwise false.

>>> staff = abjad.Staff("c'4 d'4 e'4")
>>> time_signature = abjad.TimeSignature((3, 8))
>>> abjad.attach(time_signature, staff[0])
>>> show(staff) 
>>> for note in staff:
...     result = abjad.inspect(note).is_bar_line_crossing()
...     print(note, result)
...
c'4 False
d'4 True
e'4 False

Returns true or false.

InspectionAgent.is_well_formed()

Is true when client is well-formed. Otherwise false.

Returns false.

InspectionAgent.report_modifications()

Reports modifications of client.

Report modifications of container in selection:

>>> container = abjad.Container("c'8 d'8 e'8 f'8")
>>> abjad.override(container).note_head.color = 'red'
>>> abjad.override(container).note_head.style = 'harmonic'
>>> show(container) 
>>> report = abjad.inspect(container).report_modifications()
>>> print(report)
{
    \override NoteHead.color = #red
    \override NoteHead.style = #'harmonic
    %%% 4 components omitted %%%
    \revert NoteHead.color
    \revert NoteHead.style
}

Returns string.

InspectionAgent.tabulate_well_formedness_violations(allow_percussion_clef=None)

Tabulates well-formedness violations in client.

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> staff[1].written_duration = (1, 4)
>>> beam = abjad.Beam()
>>> abjad.attach(beam, staff[:])
>>> agent = abjad.inspect(staff)
>>> result = agent.tabulate_well_formedness_violations()
>>> print(result)
1 /	4 beamed quarter notes
0 /	1 conflicting clefs
0 /	1 discontiguous spanners
0 /	5 duplicate ids
0 /	1 empty containers
0 /	0 intermarked hairpins
0 /	0 misdurated measures
0 /	0 misfilled measures
0 /	0 mismatched enchained hairpins
0 /	0 mispitched ties
0 /	4 misrepresented flags
0 /	5 missing parents
0 /	0 nested measures
0 /	4 notes on wrong clef
0 /	4 out of range notes
0 /	1 overlapping beams
0 /	0 overlapping glissandi
0 /	0 overlapping hairpins
0 /	0 overlapping octavation spanners
0 /	0 overlapping ties
0 /	0 short hairpins
0 /	0 tied rests

Beamed quarter notes are not well formed.

Returns string.

Special methods

(AbjadObject).__eq__(argument)

Is true when ID of argument 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__(argument)

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

Returns true or false.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.