abjad.wf

abjad.wf.check_beamed_lone_notes(argument)	Checks beamed lone notes.
abjad.wf.check_beamed_long_notes(argument)	Checks beamed long notes.
abjad.wf.check_duplicate_ids(argument)	Checks duplicate IDs.
abjad.wf.check_empty_containers(argument)	Checks empty containers.
abjad.wf.check_missing_parents(argument)	Checks missing parents.
abjad.wf.check_notes_on_wrong_clef(argument)	Checks notes and chords on wrong clef.
abjad.wf.check_orphaned_dependent_wrappers(...)	Checks orphaned dependent wrappers.
abjad.wf.check_out_of_range_pitches(argument, *)	Checks out-of-range notes.
abjad.wf.check_overlapping_beams(argument)	Checks overlapping beams.
abjad.wf.check_overlapping_text_spanners(...)	Checks overlapping text spanners.
abjad.wf.check_unmatched_stop_text_spans(...)	Checks unmatched stop text spans.
abjad.wf.check_unterminated_hairpins(argument)	Checks unterminated hairpins.
abjad.wf.check_unterminated_text_spanners(...)	Checks unterminated text spanners.
abjad.wf.is_wellformed(component[, ...])	Is true when component is wellformed.
abjad.wf.tabulate_wellformedness(component)	Tabulates wellformedness of component.

abjad.wf.check_beamed_lone_notes(argument) → tuple[list, int]

Checks beamed lone notes.

The example below feature Abjad voice containers because beams are voice-persistent.

Beamed single notes are not wellformed:

>>> voice = abjad.Voice("c'8 d' e' f'")
>>> abjad.attach(abjad.StartBeam(), voice[0])
>>> abjad.attach(abjad.StopBeam(), voice[0])
>>> abjad.show(voice)  

>>> abjad.wf.check_beamed_lone_notes(voice)
([Note("c'8")], 4)

abjad.wf.check_beamed_long_notes(argument) → tuple[list, int]

Checks beamed long notes.

The examples below feature Abjad voice containers because beams are voice-persistent.

Beamed quarter notes are not wellformed:

>>> voice = abjad.Voice("c'4 d'4 e'4 f'4")
>>> abjad.attach(abjad.StartBeam(), voice[0])
>>> abjad.attach(abjad.StopBeam(), voice[1])
>>> abjad.show(voice)  

>>> abjad.wf.check_beamed_long_notes(voice)
([Note("c'4"), Note("d'4")], 4)

Beamed eighth notes are wellformed:

>>> voice = abjad.Voice("c'8 d'8 e'8 f'8")
>>> abjad.attach(abjad.StartBeam(), voice[0])
>>> abjad.attach(abjad.StopBeam(), voice[1])
>>> abjad.show(voice)  

>>> abjad.wf.check_beamed_long_notes(voice)
([], 4)

abjad.wf.check_duplicate_ids(argument) → tuple[list, int]

Checks duplicate IDs.

abjad.wf.check_empty_containers(argument) → tuple[list, int]

Checks empty containers.

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> staff.append(abjad.Container())

>>> string = abjad.lilypond(staff)
>>> print(string)
\new Staff
{
    c'4
    d'4
    e'4
    f'4
    {
    }
}

>>> violators, total = abjad.wf.check_empty_containers(staff)
>>> violators
[Container()]

abjad.wf.check_missing_parents(argument) → tuple[list, int]

Checks missing parents.

abjad.wf.check_notes_on_wrong_clef(argument) → tuple[list, int]

Checks notes and chords on wrong clef.

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> clef = abjad.Clef("alto")
>>> abjad.attach(clef, staff[0])
>>> violin = abjad.Violin()
>>> abjad.attach(violin, staff[0])
>>> abjad.show(staff)  

>>> abjad.wf.check_notes_on_wrong_clef(staff)
([Note("c'8"), Note("d'8"), Note("e'8"), Note("f'8")], 4)

All instruments allow percussion clef:

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> clef = abjad.Clef("percussion")
>>> abjad.attach(clef, staff[0])
>>> violin = abjad.Violin()
>>> abjad.attach(violin, staff[0])
>>> abjad.show(staff)  

>>> abjad.wf.check_notes_on_wrong_clef(staff)
([], 4)

abjad.wf.check_orphaned_dependent_wrappers(argument) → tuple[list, int]

Checks orphaned dependent wrappers.

This should normally never happen because Abjad manages dependent wrappers behind the scenes.

This check exists to make sure that any new code added to Abjad doesn’t accidentally mangle dependent-wrapper handling.

>>> voice = abjad.Voice("c'8 [ d' e' f'")
>>> assert len(voice._dependent_wrappers) == 1
>>> wrapper = voice._dependent_wrappers[0]
>>> wrapper.component()
Note("c'8")

>>> abjad.wf.check_orphaned_dependent_wrappers(voice)
([], 1)

>>> voice[0:1] = [abjad.Note("cs'8")]
>>> voice._dependent_wrappers
[]

>>> abjad.wf.check_orphaned_dependent_wrappers(voice)
([], 0)

>>> voice._dependent_wrappers.append(wrapper)
>>> assert len(voice._dependent_wrappers) == 1
>>> assert wrapper.component() not in voice

>>> abjad.wf.check_orphaned_dependent_wrappers(voice)
([Wrapper(annotation=None, context_name='Voice', deactivate=False, direction=None, hide=False, indicator=StartBeam(), synthetic_offset=None, tag=Tag(string=''))], 1)

abjad.wf.check_out_of_range_pitches(argument, *, allow_indicators: Sequence[str | Enum] = ()) → tuple[list, int]

Checks out-of-range notes.

Out of range:

>>> staff = abjad.Staff("c'8 r8 <d fs>8 r8")
>>> violin = abjad.Violin()
>>> abjad.attach(violin, staff[0])
>>> abjad.show(staff)  

>>> abjad.wf.check_out_of_range_pitches(staff)
([Chord('<d fs>8')], 2)

Using allow_indicators:

>>> staff = abjad.Staff("c'8 r8 <d fs>8 r8")
>>> violin = abjad.Violin()
>>> abjad.attach(violin, staff[0])
>>> abjad.attach("ALLOW_OUT_OF_RANGE", staff[2])
>>> abjad.show(staff)  

Does not check for indicator:

>>> violators, total = abjad.wf.check_out_of_range_pitches(staff)
>>> violators
[Chord('<d fs>8')]

Does check for indicator:

>>> violators, total = abjad.wf.check_out_of_range_pitches(
...     staff, allow_indicators=["ALLOW_OUT_OF_RANGE"]
... )
>>> violators
[]

abjad.wf.check_overlapping_beams(argument) → tuple[list, int]

Checks overlapping beams.

>>> voice = abjad.Voice("c'8 [ d' [ e' f' ]")
>>> string = abjad.lilypond(voice)
>>> print(string)
\new Voice
{
    c'8
    [
    d'8
    [
    e'8
    f'8
    ]
}

>>> abjad.wf.check_overlapping_beams(voice)
([Note("d'8")], 3)

>>> voice = abjad.Voice("c'8 [ d' [ e' ] f' ]")
>>> string = abjad.lilypond(voice)
>>> print(string)
\new Voice
{
    c'8
    [
    d'8
    [
    e'8
    ]
    f'8
    ]
}

>>> abjad.wf.check_overlapping_beams(voice)
([Note("d'8")], 4)

>>> voice = abjad.Voice("c'8 [ d' e' f' ]")
>>> string = abjad.lilypond(voice)
>>> print(string)
\new Voice
{
    c'8
    [
    d'8
    e'8
    f'8
    ]
}

>>> abjad.wf.check_overlapping_beams(voice)
([], 2)

abjad.wf.check_overlapping_text_spanners(argument) → tuple[list, int]

Checks overlapping text spanners.

Overlapping text spanners are not wellformed:

>>> voice = abjad.Voice("c'4 d' e' f'")
>>> abjad.text_spanner(voice)
>>> abjad.text_spanner(voice[1:3])
>>> string = abjad.lilypond(voice)
>>> print(string)
\new Voice
{
    c'4
    \startTextSpan
    d'4
    \startTextSpan
    e'4
    \stopTextSpan
    f'4
    \stopTextSpan
}

>>> abjad.wf.check_overlapping_text_spanners(voice)
([Note("d'4")], 2)

Overlapping text spanners with different IDs are wellformed:

>>> voice = abjad.Voice("c'4 d' e' f'")
>>> abjad.text_spanner(voice)
>>> command = r"\startTextSpanOne"
>>> start_text_span = abjad.StartTextSpan(command=command)
>>> abjad.attach(start_text_span, voice[1])
>>> command = r"\stopTextSpanOne"
>>> stop_text_span = abjad.StopTextSpan(command=command)
>>> abjad.attach(stop_text_span, voice[2])
>>> string = abjad.lilypond(voice)
>>> print(string)
\new Voice
{
    c'4
    \startTextSpan
    d'4
    \startTextSpanOne
    e'4
    \stopTextSpanOne
    f'4
    \stopTextSpan
}

>>> abjad.wf.check_overlapping_text_spanners(voice)
([], 2)

Enchained text spanners do not overlap (and are wellformed):

>>> voice = abjad.Voice("c'4 d' e' f'")
>>> abjad.text_spanner(voice[:3])
>>> abjad.text_spanner(voice[-2:])
>>> string = abjad.lilypond(voice)
>>> print(string)
\new Voice
{
    c'4
    \startTextSpan
    d'4
    e'4
    \stopTextSpan
    \startTextSpan
    f'4
    \stopTextSpan
}

>>> abjad.wf.check_overlapping_text_spanners(voice)
([], 2)

REGRESSION. Matching start- and stop-text-spans on a single leaf do not overlap (and are wellformed) iff stop-text-span leaks to the right:

>>> voice = abjad.Voice("c'2 d'2 e'2 f'2")
>>> abjad.attach(abjad.StartTextSpan(), voice[0])
>>> stop_text_span = abjad.StopTextSpan(leak=True)
>>> abjad.attach(stop_text_span, voice[0])
>>> abjad.attach(abjad.StartTextSpan(), voice[2])
>>> stop_text_span = abjad.StopTextSpan()
>>> abjad.attach(stop_text_span, voice[3])
>>> abjad.show(voice)  

>>> string = abjad.lilypond(voice)
>>> print(string)
\new Voice
{
    c'2
    \startTextSpan
    <>
    \stopTextSpan
    d'2
    e'2
    \startTextSpan
    f'2
    \stopTextSpan
}

>>> abjad.wf.check_overlapping_text_spanners(voice)
([], 2)

abjad.wf.check_unmatched_stop_text_spans(argument) → tuple[list, int]

Checks unmatched stop text spans.

Unmatched stop text span is not wellformed:

>>> voice = abjad.Voice("c'4 c'4 c'4 c'4")
>>> stop_text_span = abjad.StopTextSpan()
>>> abjad.attach(stop_text_span, voice[-1])
>>> string = abjad.lilypond(voice)
>>> print(string)
\new Voice
{
    c'4
    c'4
    c'4
    c'4
    \stopTextSpan
}

>>> abjad.wf.check_unmatched_stop_text_spans(voice)
([Note("c'4")], 0)

Matched stop text span is wellformed:

>>> voice = abjad.Voice("c'4 c'4 c'4 c'4")
>>> start_text_span = abjad.StartTextSpan()
>>> abjad.attach(start_text_span, voice[0])
>>> stop_text_span = abjad.StopTextSpan()
>>> abjad.attach(stop_text_span, voice[-1])
>>> abjad.show(voice)  

>>> abjad.wf.is_wellformed(voice)
True

abjad.wf.check_unterminated_hairpins(argument) → tuple[list, int]

Checks unterminated hairpins.

Unterminated crescendo is not wellformed:

>>> voice = abjad.Voice("c'4 c'4 c'4 c'4")
>>> start_hairpin = abjad.StartHairpin("<")
>>> abjad.attach(start_hairpin, voice[0])
>>> string = abjad.lilypond(voice)
>>> print(string)
\new Voice
{
    c'4
    \<
    c'4
    c'4
    c'4
}

>>> abjad.wf.check_unterminated_hairpins(voice)
([Note("c'4")], 1)

Even with start dynamic:

>>> voice = abjad.Voice("c'4 c'4 c'4 c'4")
>>> dynamic = abjad.Dynamic("f")
>>> abjad.attach(dynamic, voice[0])
>>> start_hairpin = abjad.StartHairpin("<")
>>> abjad.attach(start_hairpin, voice[0])
>>> string = abjad.lilypond(voice)
>>> print(string)
\new Voice
{
    c'4
    \f
    \<
    c'4
    c'4
    c'4
}

>>> abjad.wf.check_unterminated_hairpins(voice)
([Note("c'4")], 1)

Terminated crescendo is wellformed:

>>> voice = abjad.Voice("c'4 c'4 c'4 c'4")
>>> start_hairpin = abjad.StartHairpin("<")
>>> abjad.attach(start_hairpin, voice[0])
>>> dynamic = abjad.Dynamic("f")
>>> abjad.attach(dynamic, voice[-1])
>>> abjad.show(voice)  

>>> abjad.wf.is_wellformed(voice)
True

Bang-terminated crescendo is wellformed:

>>> voice = abjad.Voice("c'4 c'4 c'4 c'4")
>>> start_hairpin = abjad.StartHairpin("<")
>>> abjad.attach(start_hairpin, voice[0])
>>> stop_hairpin = abjad.StopHairpin()
>>> abjad.attach(stop_hairpin, voice[-1])
>>> abjad.show(voice)  

>>> abjad.wf.is_wellformed(voice)
True

abjad.wf.check_unterminated_text_spanners(argument) → tuple[list, int]

Checks unterminated text spanners.

Unterminated text spanner is not wellformed:

>>> voice = abjad.Voice("c'4 c'4 c'4 c'4")
>>> start_text_span = abjad.StartTextSpan()
>>> abjad.attach(start_text_span, voice[0])
>>> string = abjad.lilypond(voice)
>>> print(string)
\new Voice
{
    c'4
    \startTextSpan
    c'4
    c'4
    c'4
}

>>> abjad.wf.check_unterminated_text_spanners(voice)
([Note("c'4")], 1)

Terminated text span is wellformed:

>>> voice = abjad.Voice("c'4 c'4 c'4 c'4")
>>> start_text_span = abjad.StartTextSpan()
>>> abjad.attach(start_text_span, voice[0])
>>> stop_text_span = abjad.StopTextSpan()
>>> abjad.attach(stop_text_span, voice[-1])
>>> abjad.show(voice)  

>>> abjad.wf.is_wellformed(voice)
True

abjad.wf.is_wellformed(component, do_not_check_beamed_lone_notes: bool = False, do_not_check_beamed_long_notes: bool = False, do_not_check_duplicate_ids: bool = False, do_not_check_empty_containers: bool = False, do_not_check_missing_parents: bool = False, do_not_check_notes_on_wrong_clef: bool = False, do_not_check_orphaned_dependent_wrappers: bool = False, do_not_check_out_of_range_pitches: bool = False, do_not_check_overlapping_beams: bool = False, do_not_check_overlapping_text_spanners: bool = False, do_not_check_unmatched_stop_text_spans: bool = False, do_not_check_unterminated_hairpins: bool = False, do_not_check_unterminated_text_spanners: bool = False) → bool

Is true when component is wellformed.

abjad.wf.tabulate_wellformedness(component, do_not_check_beamed_lone_notes: bool = False, do_not_check_beamed_long_notes: bool = False, do_not_check_duplicate_ids: bool = False, do_not_check_empty_containers: bool = False, do_not_check_missing_parents: bool = False, do_not_check_notes_on_wrong_clef: bool = False, do_not_check_orphaned_dependent_wrappers: bool = False, do_not_check_out_of_range_pitches: bool = False, do_not_check_overlapping_beams: bool = False, do_not_check_overlapping_text_spanners: bool = False, do_not_check_unmatched_stop_text_spans: bool = False, do_not_check_unterminated_hairpins: bool = False, do_not_check_unterminated_text_spanners: bool = False) → tuple[int, str]

Tabulates wellformedness of component.