attach

abjad.top.attach.attach(attachable, target, context=None, deactivate=None, synthetic_offset=None, tag=None, wrapper=None)

Attaches attachable to target.

First form attaches indicator attachable to single leaf target.

Second form attaches spanner attachable to leaf selection target.

Third for attaches grace container attachable to leaf target.

Fourth form attaches time signature attachable to measure target.

Fifth form attaches wrapper attachable to unknown (?) target.

Attaches clef to first note in staff:

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

Attaches accent to last note in staff:

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> abjad.attach(abjad.Articulation('>'), staff[-1])
>>> abjad.show(staff) 

Works with context names:

>>> voice = abjad.Voice("c'4 d' e' f'", name='MusicVoice')
>>> staff = abjad.Staff([voice], name='MusicStaff')
>>> abjad.attach(abjad.Clef('alto'), voice[0], context='MusicStaff')
>>> abjad.show(staff) 
>>> for leaf in abjad.select(staff).leaves():
...     leaf, abjad.inspect(leaf).effective(abjad.Clef)
... 
(Note("c'4"), Clef('alto'))
(Note("d'4"), Clef('alto'))
(Note("e'4"), Clef('alto'))
(Note("f'4"), Clef('alto'))

Derives context from default attachable context when context is none.

Two contexted indicators can not be attached at the same offset if both indicators are active:

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> abjad.attach(abjad.Clef('treble'), staff[0])
>>> abjad.attach(abjad.Clef('alto'), staff[0])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/josiah/Source/github.com/Abjad/abjad/abjad/top/attach.py", line 308, in attach
    wrapper_._bind_to_component(component)
  File "/Users/josiah/Source/github.com/Abjad/abjad/abjad/system/Wrapper.py", line 327, in _bind_to_component
    self._warn_duplicate_indicator(component)
  File "/Users/josiah/Source/github.com/Abjad/abjad/abjad/system/Wrapper.py", line 505, in _warn_duplicate_indicator
    raise abjad.PersistentIndicatorError(message)
abjad.exceptions.PersistentIndicatorError: 

Can not attach ...

abjad.Clef('alto')

... to Note("c'4") in None because ...

abjad.Wrapper(
    context='Staff',
    indicator=abjad.Clef('treble'),
    tag=abjad.Tag(),
    )

... is already attached to the same leaf.

But simultaneous contexted indicators are allowed if only one is active (and all others are inactive):

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> abjad.attach(abjad.Clef('treble'), staff[0])
>>> abjad.attach(
...     abjad.Clef('alto'),
...     staff[0],
...     deactivate=True,
...     tag='+PARTS_1',
...     )
>>> abjad.attach(
...     abjad.Clef('tenor'),
...     staff[0],
...     deactivate=True,
...     tag='+PARTS_2',
...     )
>>> abjad.show(staff) 

Active indicator is always effective when competing inactive indicators are present:

>>> for note in staff:
...     clef = abjad.inspect(staff[0]).effective(abjad.Clef)
...     note, clef
... 
(Note("c'4"), Clef('treble'))
(Note("d'4"), Clef('treble'))
(Note("e'4"), Clef('treble'))
(Note("f'4"), Clef('treble'))

But a lone inactivate indicator is effective when no active indicator is present:

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> abjad.attach(
...     abjad.Clef('alto'),
...     staff[0],
...     deactivate=True,
...     tag='+PARTS',
...     )
>>> abjad.show(staff) 
>>> for note in staff:
...     clef = abjad.inspect(staff[0]).effective(abjad.Clef)
...     note, clef
... 
(Note("c'4"), Clef('alto'))
(Note("d'4"), Clef('alto'))
(Note("e'4"), Clef('alto'))
(Note("f'4"), Clef('alto'))

Tag must exist when deactivate is true:

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> abjad.attach(abjad.Clef('alto'), staff[0], deactivate=True)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/josiah/Source/github.com/Abjad/abjad/abjad/top/attach.py", line 230, in attach
    raise Exception(f'tag must exist when deactivate is true.')
Exception: tag must exist when deactivate is true.

Returns wrapper when wrapper is true:

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> wrapper = abjad.attach(abjad.Clef('alto'), staff[0], wrapper=True)
>>> abjad.f(wrapper)
abjad.Wrapper(
    context='Staff',
    indicator=abjad.Clef('alto'),
    tag=abjad.Tag(),
    )

Otherwise returns none.