Parentage
=========


Parentage shows containment
---------------------------

Many objects in the Abjad model of the musical score may contain other objects.
A score may contain staves or staff groups.
Staves may contain notes, rests, chords, tuplets or independent
voices containing these components.

Abjad uses the idea of :term:`parentage` to model these different
cases of containment in a uniform way.


An example
----------

Consider this score beginning with c'8.

::

	abjad> tuplet = FixedDurationTuplet((2, 8), construct.run(3))
	abjad> staff = Staff(tuplet * 2)
	abjad> score = Score([staff])
	abjad> pitchtools.diatonicize(score)
	abjad> score.leaves[0]
	abjad> show(score)

.. image:: images/parentage-example-1.png

::

   abjad> note = score.leaves[0]
   abjad> note
   Note(c', 8)

The parentage interface serves information about the parentage of every 
Abjad component. ::

   abjad> note.parentage
   <_Parentage>

The immediate parent of the first note in the score is the first is a tuplet.
The complete parentage of the first note in score is longer. ::

   abjad> note.parentage.parent
   FixedDurationTuplet(1/4, [c'8, d'8, e'8])

::

   abjad> note.parentage.parentage
   [Note(c', 8), FixedDurationTuplet(1/4, [c'8, d'8, e'8]), Staff{2}, Score<<1>>]

Note that the `parent` attribute returns a reference to a single component
while the `parentage` attribute returns a list of components.


Parentage attributes
--------------------

The parentage interface implements a number of read-only attributes.

Depth gives a measure of nesting. Depth always equals the length of
parentage minus 1. ::

   abjad> note.parentage.depth
   3

::

   abjad> len(note.parentage.parentage) - 1
   3

Other parentage-related attributes include layer, orphan and root.

.. seealso:: The API entry for the 
   :class:`~abjad.parentage.parentage._Parentage` interface.
