Previous topic

music21.sieve

Next topic

music21.stream

Table Of Contents

Table Of Contents

music21.spanner

A spanner is a music21 object that represents a connection usually between two or more music21 objects that might live in different streams but need some sort of connection between them. A slur is one type of spanner – it might connect notes in different Measure objects or even between different parts.

This package defines some of the most common spanners. Other spanners can be found in modules such as music21.dynamics (for things such as crescendos) or in music21.meter (a ritardando, for instance).

Spanner

Inherits from: Music21Object, JSONSerializer

class music21.spanner.Spanner(*arguments, **keywords)

Spanner objects live on Streams in the same manner as other Music21Objects, but represent and store connections between one or more other Music21Objects.

Commonly used Spanner subclasses include the Slur, RepeatBracket, Crescendo, and Diminuendo.

In some cases you will want to subclass Spanner for specific purposes.

In the first demo, we create a spanner to represent a written-out accelerando, such as Elliott Carter uses in his second string quartet (he marks them with an arrow).

>>> from music21 import *
>>> class CarterAccelerandoSign(spanner.Spanner):
...    pass
>>> n1 = note.Note('C4')
>>> n2 = note.Note('D4')
>>> n3 = note.Note('E4')
>>> sp1 = CarterAccelerandoSign(n1, n2, n3) # or as a list: [n1, n2, n3]
>>> sp1.getComponents()
[<music21.note.Note C>, <music21.note.Note D>, <music21.note.Note E>]

Now we put the notes and the spanner into a Stream object. Note that the convention is to put the spanner at the beginning:

>>> s = stream.Stream()
>>> s.append([n1, n2, n3])
>>> s.insert(0, sp1)

Now we can get at the spanner in one of three ways.

  1. it is just a normal element in the stream:
>>> for e in s:
...    print e
<music21.note.Note C>
<music21.spanner.CarterAccelerandoSign <music21.note.Note C><music21.note.Note D><music21.note.Note E>>
<music21.note.Note D>
<music21.note.Note E>
  1. we can get a stream of spanners (equiv. to getElementsByClass(‘Spanner’)) by calling the .spanner property on the stream.
>>> spannerCollection = s.spanners # a stream object
>>> for thisSpanner in spannerCollection:
...     print thisSpanner
<music21.spanner.CarterAccelerandoSign <music21.note.Note C><music21.note.Note D><music21.note.Note E>>
  1. we can get the spanner by looking at the list getSpannerSites() on any object.
>>> n2.getSpannerSites()
[<music21.spanner.CarterAccelerandoSign <music21.note.Note C><music21.note.Note D><music21.note.Note E>>]

In this example we will slur a few notes and then iterate over the stream to see which are slurred:

>>> n1 = note.Note('C4')
>>> n2 = note.Note('D4')
>>> n3 = note.Note('E4')
>>> n4 = note.Note('F4')
>>> n5 = note.Note('G4')
>>> n6 = note.Note('A4')

Create a slur over the second and third notes at instantiation:

>>> slur1 = spanner.Slur([n2, n3])

Slur the fifth and the sixth notes by adding them to an existing slur:

>>> slur2 = spanner.Slur()
>>> slur2.addComponents([n5, n6])

Now add them all to a stream:

>>> part1 = stream.Part()
>>> part1.append([n1, n2, n3, n4, n5, n6])
>>> part1.insert(0, slur1)
>>> part1.insert(0, slur2)

Say we wanted to know which notes in a piece started a slur, here’s how we could do it:

>>> for n in part1.notes:
...    ss = n.getSpannerSites()
...    for thisSpanner in ss:
...       if 'Slur' in thisSpanner.classes:
...            if thisSpanner.isFirst(n):
...                print n.nameWithOctave
D4
G4

Alternatively, you could iterate over the spanners of part1 and get their first elements:

>>> for thisSpanner in part1.spanners:
...     firstNote = thisSpanner.getComponents()[0]
...     print firstNote.nameWithOctave
D4
G4

The second method is shorter, but the first is likely to be useful in cases where you are doing other things to each note object along the way.

Oh, and of course, slurs do print properly in musicxml:

>>> part1.show()
_images/slur1_example.png

(the Carter example would not print an arrow since that element has no corresponding musicxml representation).

Spanner attributes

Attributes without Documentation: isSpanner, idLocal, completeStatus

Attributes inherited from Music21Object: classSortOrder, isStream, isVariant, hideObjectOnPrint, groups, id

Spanner properties

Spanner methods

addComponents(components, *arguments, **keywords)

Associate one or more components with this Spanner.

The order that components is added is retained and may or may not be significant to the spanner.

>>> from music21 import *
>>> n1 = note.Note('g')
>>> n2 = note.Note('f#')
>>> n3 = note.Note('e')
>>> n4 = note.Note('c')
>>> n5 = note.Note('d-')

>>> sl = spanner.Spanner()
>>> sl.addComponents(n1)
>>> sl.addComponents(n2, n3)
>>> sl.addComponents([n4, n5])
>>> sl.getComponentIds() == [id(n) for n in [n1, n2, n3, n4, n5]]
True
freezeIds()

No documentation.

getComponentIds()

Return all id() for all stored objects.

getComponents()

Return all components for this Spanner as objects, without weak-refs.

As this is a Music21Object, the name here is more specific to avoid name clashes.

>>> from music21 import *
>>> n1 = note.Note('g')
>>> n2 = note.Note('f#')
>>> sl = spanner.Spanner()
>>> sl.addComponents(n1)
>>> sl.getComponents() == [n1]
True
>>> sl.addComponents(n2)
>>> sl.getComponents() == [n1, n2]
True
>>> sl.getComponentIds() == [id(n1), id(n2)]
True
>>> c1 = clef.TrebleClef()
>>> sl.addComponents(c1)
>>> sl.getComponents() == [n1, n2, c1] # make sure that not sorting
True
getComponentsByClass(classFilterList)
>>> from music21 import *
>>> n1 = note.Note('g')
>>> n2 = note.Note('f#')
>>> c1 = clef.AltoClef()
>>> sl = spanner.Spanner()
>>> sl.addComponents([n1, n2, c1])
>>> sl.getComponentsByClass('Note') == [n1, n2]
True
>>> sl.getComponentsByClass('Clef') == [c1]
True
getDurationBySite(site)

Return a Duration object representing the value between the first component’s offset and the last components offset plus duration.

getDurationSpanBySite(site)

Return the duration span, or the distnace between the first component’s offset and the last components offset plus duration.

getFirst()

Get the object of the first component

>>> from music21 import *
>>> n1 = note.Note('g')
>>> n2 = note.Note('f#')
>>> n3 = note.Note('e')
>>> n4 = note.Note('c')
>>> n5 = note.Note('d-')

>>> sl = spanner.Spanner()
>>> sl.addComponents(n1, n2, n3, n4, n5)
>>> sl.getFirst() is n1
True
getLast()

Get the object of the first component

>>> from music21 import *
>>> n1 = note.Note('g')
>>> n2 = note.Note('f#')
>>> n3 = note.Note('e')
>>> n4 = note.Note('c')
>>> n5 = note.Note('d-')

>>> sl = spanner.Spanner()
>>> sl.addComponents(n1, n2, n3, n4, n5)
>>> sl.getLast() is n5
True
getOffsetSpanBySite(site)

Return the span, or min and max values, of all offsets for a given site.

getOffsetsBySite(site)

Given a site shared by all components, return a list of offset values.

>>> from music21 import *
>>> n1 = note.Note('g')
>>> n2 = note.Note('f#')
>>> s = stream.Stream()
>>> s.insert(3, n1)
>>> s.insert(11, n2)
>>> sp = spanner.Spanner(n1, n2)
>>> sp.getOffsetsBySite(s)
[3.0, 11.0]
getSpannerStorageId()

Return the object id of the SpannerStorage object

hasComponent(component)

Return True if this Spanner has the component.

isFirst(component)

Given a component, is it first?

>>> from music21 import *
>>> n1 = note.Note('g')
>>> n2 = note.Note('f#')
>>> n3 = note.Note('e')
>>> n4 = note.Note('c')
>>> n5 = note.Note('d-')

>>> sl = spanner.Spanner()
>>> sl.addComponents(n1, n2, n3, n4, n5)
>>> sl.isFirst(n2)
False
>>> sl.isFirst(n1)
True
>>> sl.isLast(n1)
False
>>> sl.isLast(n5)
True
isLast(component)

Given a component, is it last? Returns True or False

purgeLocations(rescanIsDead=False)

No documentation.

purgeOrphans()

No documentation.

replaceComponent(old, new)

When copying a Spanner, we need to update the spanner with new references for copied components (if the Notes of a Slur have beenc copied, that Slur’s Note references need references to the new Notes). Given the old component, this method will replace the old with the new.

The old parameter can be either an object or object id.

>>> from music21 import *
>>> n1 = note.Note('g')
>>> n2 = note.Note('f#')
>>> c1 = clef.AltoClef()
>>> c2 = clef.BassClef()
>>> sl = spanner.Spanner(n1, n2, c1)
>>> sl.replaceComponent(c1, c2)
>>> sl[-1] == c2
True
unfreezeIds()

No documentation.

unwrapWeakref()

Overridden method for unwrapping all Weakrefs.

wrapWeakref()

Overridden method for unwrapping all Weakrefs.

Methods inherited from Music21Object: searchActiveSiteByAttr(), getContextAttr(), setContextAttr(), addContext(), addLocation(), addLocationAndActiveSite(), getAllContextsByClass(), getCommonSiteIds(), getCommonSites(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeUndeclaredIds(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), write()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

Glissando

Inherits from: Spanner, Music21Object, JSONSerializer

class music21.spanner.Glissando(*arguments, **keywords)

A between two Notes specifying a glissando or similar alteration. Different line types can be specified.

Glissando attributes

Attributes inherited from Spanner: isSpanner, idLocal, completeStatus

Attributes inherited from Music21Object: classSortOrder, isStream, isVariant, hideObjectOnPrint, groups, id

Glissando properties

label

Get or set the label property.

lineType

Get or set the lineType property.

Properties inherited from Music21Object: activeSite, beat, beatDuration, beatStr, beatStrength, classes, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds

Properties inherited from JSONSerializer: json

Glissando methods

Methods inherited from Spanner: addComponents(), freezeIds(), getComponentIds(), getComponents(), getComponentsByClass(), getDurationBySite(), getDurationSpanBySite(), getFirst(), getLast(), getOffsetSpanBySite(), getOffsetsBySite(), getSpannerStorageId(), hasComponent(), isFirst(), isLast(), purgeLocations(), purgeOrphans(), replaceComponent(), unfreezeIds(), unwrapWeakref(), wrapWeakref()

Methods inherited from Music21Object: searchActiveSiteByAttr(), getContextAttr(), setContextAttr(), addContext(), addLocation(), addLocationAndActiveSite(), getAllContextsByClass(), getCommonSiteIds(), getCommonSites(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeUndeclaredIds(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), write()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

Line

Inherits from: Spanner, Music21Object, JSONSerializer

class music21.spanner.Line(*arguments, **keywords)

A line or bracket represented as a spanner above two Notes.

Brackets can take many line types.

>>> from music21 import *
>>> b = spanner.Line()
>>> b.lineType = 'dotted'
>>> b.lineType
'dotted'
>>> b = spanner.Line(endHeight=20)
>>> b.endHeight
20

Line attributes

Attributes without Documentation: placement

Attributes inherited from Spanner: isSpanner, completeStatus, idLocal

Attributes inherited from Music21Object: classSortOrder, isStream, isVariant, id, groups, hideObjectOnPrint

Line properties

endHeight

Get or set the endHeight property.

endTick

Get or set the endTick property.

lineType

Get or set the lineType property. Valid line types are “solid”, “dashed”, “dotted”, or “wavy”.

>>> from music21 import *
>>> b = spanner.Line()
>>> b.lineType = 'dotted'
>>> b.lineType = 'junk'
Traceback (most recent call last):
SpannerException: not a valid value: junk
startHeight

Get or set the startHeight property.

startTick

Get or set the startTick property.

tick

Set the start and end tick to the same value

>>> from music21 import *
>>> b = spanner.Line()
>>> b.tick = 'arrow'
>>> b.startTick
'arrow'
>>> b.endTick
'arrow'

Properties inherited from Music21Object: activeSite, beat, beatDuration, beatStr, beatStrength, classes, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds

Properties inherited from JSONSerializer: json

Line methods

getEndParameters()

Return the parameters for the start of this spanner required by MusicXML output.

getStartParameters()

Return the parameters for the start of this spanners required by MusicXML output.

Methods inherited from Spanner: addComponents(), freezeIds(), getComponentIds(), getComponents(), getComponentsByClass(), getDurationBySite(), getDurationSpanBySite(), getFirst(), getLast(), getOffsetSpanBySite(), getOffsetsBySite(), getSpannerStorageId(), hasComponent(), isFirst(), isLast(), purgeLocations(), purgeOrphans(), replaceComponent(), unfreezeIds(), unwrapWeakref(), wrapWeakref()

Methods inherited from Music21Object: searchActiveSiteByAttr(), getContextAttr(), setContextAttr(), addContext(), addLocation(), addLocationAndActiveSite(), getAllContextsByClass(), getCommonSiteIds(), getCommonSites(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeUndeclaredIds(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), write()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

Ottava

Inherits from: Spanner, Music21Object, JSONSerializer

class music21.spanner.Ottava(*arguments, **keywords)

An octave shift line

>>> from music21 import *
>>> os = spanner.Ottava(type='8va')
>>> os.type
'8va'
>>> os.type = 15
>>> os.type
'15ma'
>>> os.type = 8, 'down'
>>> os.type
'8vb'
>>> print os
<music21.spanner.Ottava 8vb >

Ottava attributes

Attributes without Documentation: placement

Attributes inherited from Spanner: isSpanner, idLocal, completeStatus

Attributes inherited from Music21Object: classSortOrder, isStream, isVariant, hideObjectOnPrint, groups, id

Ottava properties

type

Get or set Ottava type. This can be set by as complete string (such as 8va or 15mb) or with a pair specifying size and direction.

>>> from music21 import *
>>> os = spanner.Ottava()
>>> os.type = 15, 'down'
>>> os.type
'15mb'
>>> os.type = '8vb'
>>> os.type
'8vb'

Properties inherited from Music21Object: activeSite, beat, beatDuration, beatStr, beatStrength, classes, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds

Properties inherited from JSONSerializer: json

Ottava methods

getEndParameters()

Return the parameters for the start of this spanner required by MusicXML output.

>>> from music21 import *
>>> os = spanner.Ottava(type=8)
>>> os.getStartParameters()
{'type': 'down', 'size': 8}
>>> os.getEndParameters()
{'type': 'stop', 'size': 8}
getStartParameters()

Return the parameters for the start of this spanners required by MusicXML output.

>>> from music21 import *
>>> os = spanner.Ottava(type='15mb')
>>> os.getStartParameters()
{'type': 'up', 'size': 15}
>>> os.getEndParameters()
{'type': 'stop', 'size': 15}

Methods inherited from Spanner: addComponents(), freezeIds(), getComponentIds(), getComponents(), getComponentsByClass(), getDurationBySite(), getDurationSpanBySite(), getFirst(), getLast(), getOffsetSpanBySite(), getOffsetsBySite(), getSpannerStorageId(), hasComponent(), isFirst(), isLast(), purgeLocations(), purgeOrphans(), replaceComponent(), unfreezeIds(), unwrapWeakref(), wrapWeakref()

Methods inherited from Music21Object: searchActiveSiteByAttr(), getContextAttr(), setContextAttr(), addContext(), addLocation(), addLocationAndActiveSite(), getAllContextsByClass(), getCommonSiteIds(), getCommonSites(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeUndeclaredIds(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), write()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

RepeatBracket

Inherits from: Spanner, Music21Object, JSONSerializer

class music21.spanner.RepeatBracket(*arguments, **keywords)

A grouping of one or more measures, presumably in sequence, that mark an alternate repeat.

These gather what are sometimes called first-time bars and second-time bars.

It is assumed that numbering starts from 1. Numberings above 2 are permitted. The number keyword argument can be used to pass in the desired number.

>>> from music21 import *
>>> m = stream.Measure()
>>> sp = spanner.RepeatBracket(m, number=1)
>>> sp # can be one or more measures
<music21.spanner.RepeatBracket 1 <music21.stream.Measure 0 offset=0.0>>
>>> sp.number = 3
>>> sp # can be one or more measures
<music21.spanner.RepeatBracket 3 <music21.stream.Measure 0 offset=0.0>>
>>> sp.getNumberList() # the list of repeat numbers
[3]
>>> sp.number = '1-3' # range of repeats
>>> sp.getNumberList()
[1, 2, 3]
>>> sp.number = [2,3] # range of repeats
>>> sp.getNumberList()
[2, 3]

RepeatBracket attributes

Attributes inherited from Spanner: isSpanner, idLocal, completeStatus

Attributes inherited from Music21Object: classSortOrder, isStream, isVariant, hideObjectOnPrint, groups, id

RepeatBracket properties

RepeatBracket methods

getNumberList()

Get a contiguous list of repeat numbers that are applicable for this instance.

>>> from music21 import *
>>> rb = spanner.RepeatBracket()
>>> rb.number = '1,2'
>>> rb.getNumberList()
[1, 2]

Methods inherited from Spanner: addComponents(), freezeIds(), getComponentIds(), getComponents(), getComponentsByClass(), getDurationBySite(), getDurationSpanBySite(), getFirst(), getLast(), getOffsetSpanBySite(), getOffsetsBySite(), getSpannerStorageId(), hasComponent(), isFirst(), isLast(), purgeLocations(), purgeOrphans(), replaceComponent(), unfreezeIds(), unwrapWeakref(), wrapWeakref()

Methods inherited from Music21Object: searchActiveSiteByAttr(), getContextAttr(), setContextAttr(), addContext(), addLocation(), addLocationAndActiveSite(), getAllContextsByClass(), getCommonSiteIds(), getCommonSites(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeUndeclaredIds(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), write()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

Slur

Inherits from: Spanner, Music21Object, JSONSerializer

class music21.spanner.Slur(*arguments, **keywords)

A slur represented as a spanner between two Notes.

The idLocal attribute, defined in the Spanner base class, is used to mark start and end tags of potentially overlapping indicators.

Slur attributes

Attributes without Documentation: placement, lineType

Attributes inherited from Spanner: isSpanner, idLocal, completeStatus

Attributes inherited from Music21Object: classSortOrder, isStream, isVariant, hideObjectOnPrint, groups, id

Slur properties

Slur methods

Methods inherited from Spanner: addComponents(), freezeIds(), getComponentIds(), getComponents(), getComponentsByClass(), getDurationBySite(), getDurationSpanBySite(), getFirst(), getLast(), getOffsetSpanBySite(), getOffsetsBySite(), getSpannerStorageId(), hasComponent(), isFirst(), isLast(), purgeLocations(), purgeOrphans(), replaceComponent(), unfreezeIds(), unwrapWeakref(), wrapWeakref()

Methods inherited from Music21Object: searchActiveSiteByAttr(), getContextAttr(), setContextAttr(), addContext(), addLocation(), addLocationAndActiveSite(), getAllContextsByClass(), getCommonSiteIds(), getCommonSites(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeUndeclaredIds(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), write()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

SpannerBundle

class music21.spanner.SpannerBundle(*arguments, **keywords)

A utility object for collecting and processing collections of Spanner objects. This is necessary because often processing routines that happen at many different levels need access to the same collection of spanners.

Because SpannerBundles are so commonly used with Stream objects, the Stream has a spannerBundle property that stores and caches a SpannerBundle of the Stream.

If a Stream or Stream subclass is provided as an argument, all Spanners on this Stream will be accumulated herein.

SpannerBundle properties

list

Return the bundle as a list.

SpannerBundle methods

append(other)

No documentation.

freePendingComponentAssignment(componentCandidate)

No documentation.

getByClass(className)

Given a spanner class, return a bundle of all Spanners of the desired class.

>>> from music21 import *
>>> su1 = spanner.Slur()
>>> su2 = layout.StaffGroup()
>>> sb = spanner.SpannerBundle()
>>> sb.append(su1)
>>> sb.append(su2)
>>> sb.getByClass(spanner.Slur).list == [su1]
True
>>> sb.getByClass('Slur').list == [su1]
True
>>> sb.getByClass('StaffGroup').list == [su2]
True
getByClassComplete(className, completeStatus)

Get all spanner of a specified class className and a completeStatus. Convenience routine for multiple filtering

>>> from music21 import *
>>> su1 = spanner.Slur()
>>> su1.completeStatus = True
>>> su2 = layout.StaffGroup()
>>> su3 = spanner.Slur()
>>> su3.completeStatus = False
>>> sb = spanner.SpannerBundle()
>>> sb.append(su1)
>>> sb.append(su2)
>>> sb.append(su3)
>>> sb.getByClassComplete('Slur', True).list == [su1]
True
>>> sb.getByClassComplete('Slur', False).list == [su3]
True
getByClassIdLocalComplete(className, idLocal, completeStatus)

Get all spanners of a specified class className, an id idLocal, and a completeStatus. This is a convenience routine for multiple filtering when searching for relevant Spanners to pair with.

>>> from music21 import *
>>> su1 = spanner.Slur()
>>> su2 = layout.StaffGroup()
>>> su2.idLocal = 3
>>> sb = spanner.SpannerBundle()
>>> sb.append(su1)
>>> sb.append(su2)
>>> sb.getByClassIdLocalComplete('StaffGroup', 3, False).list == [su2]
True
>>> su2.completeStatus = True
>>> sb.getByClassIdLocalComplete('StaffGroup', 3, False).list == []
True
getByCompleteStatus(completeStatus)

Get spanners by matching status of completeStatus to the same attribute

>>> from music21 import *
>>> su1 = spanner.Slur()
>>> su1.idLocal = 1
>>> su1.completeStatus = True
>>> su2 = spanner.Slur()
>>> su2.idLocal = 2
>>> sb = spanner.SpannerBundle()
>>> sb.append(su1)
>>> sb.append(su2)
>>> sb2 = sb.getByCompleteStatus(True)
>>> len(sb2)
1
>>> sb2 = sb.getByIdLocal(1).getByCompleteStatus(True)
>>> sb2[0] == su1
True
getByComponent(component)

Given a spanner component (an object), return a bundle of all Spanner objects that have this object as a component.

>>> from music21 import *
>>> n1 = note.Note()
>>> n2 = note.Note()
>>> n3 = note.Note()
>>> su1 = spanner.Slur(n1, n2)
>>> su2 = spanner.Slur(n2, n3)
>>> sb = spanner.SpannerBundle()
>>> sb.append(su1)
>>> sb.append(su2)
>>> sb.getByComponent(n1).list == [su1]
True
>>> sb.getByComponent(n3).list == [su2]
True
>>> sb.getByComponent(n2).list == [su1, su2]
True
getByComponentAndClass(component, className)

Get all Spanners that both contain the component and match the provided class.

getByIdLocal(idLocal=None)

Get spanners by idLocal or complete status.

Returns a new SpannerBundle object

>>> from music21 import *
>>> su1 = spanner.Slur()
>>> su1.idLocal = 1
>>> su2 = spanner.Slur()
>>> su2.idLocal = 2
>>> sb = spanner.SpannerBundle()
>>> sb.append(su1)
>>> sb.append(su2)
>>> len(sb)
2
>>> len(sb.getByIdLocal(1))
1
>>> len(sb.getByIdLocal(2))
1
getSpannerStorageIds()

Return all SpannerStorage ids from all contained Spanners

remove(item)

Remove a stored Spanner from the bundle with an instance. Each reference must have a matching id() value.

>>> from music21 import *
>>> su1 = spanner.Slur()
>>> su1.idLocal = 1
>>> su2 = spanner.Slur()
>>> su2.idLocal = 2
>>> sb = spanner.SpannerBundle()
>>> sb.append(su1)
>>> sb.append(su2)
>>> len(sb)
2
>>> sb.remove(su2)
>>> len(sb)
1
replaceComponent(old, new)

Given a spanner component (an object), replace all old components with new components for all Spanner objects contained in this bundle.

The old parameter can be either an object or object id.

If no replacements are found, no errors are raised.

setIdLocalByClass(className, maxId=6)

Automatically set id local values for all members of the provided class. This is necessary in cases where spanners are newly created in potentially overlapping boundaries and need to be tagged for MusicXML or other output. Note that, if some Spanners already have ids, they will be overwritten.

The maxId parameter sets the largest number used in id ass

>>> from music21 import *
>>> su1 = spanner.Slur()
>>> su2 = layout.StaffGroup()
>>> su3 = spanner.Slur()
>>> sb = spanner.SpannerBundle()
>>> sb.append(su1)
>>> sb.append(su2)
>>> sb.append(su3)
>>> [sp.idLocal for sp in sb.getByClass('Slur')]
[None, None]
>>> sb.setIdLocalByClass('Slur')
>>> [sp.idLocal for sp in sb.getByClass('Slur')]
[1, 2]
setIdLocals()

Set all id locals for all classes in this SpannerBundle. This will assure that each class has a unique id local number. This is destructive: existing id local values will be lost.

>>> from music21 import *
>>> su1 = spanner.Slur()
>>> su2 = layout.StaffGroup()
>>> su3 = spanner.Slur()
>>> sb = spanner.SpannerBundle()
>>> sb.append(su1)
>>> sb.append(su2)
>>> sb.append(su3)
>>> [sp.idLocal for sp in sb.getByClass('Slur')]
[None, None]
>>> sb.setIdLocals()
>>> [(sp, sp.idLocal) for sp in sb]
[(<music21.spanner.Slur >, 1), (<music21.layout.StaffGroup >, 1), (<music21.spanner.Slur >, 2)]
setPendingComponentAssignment(sp, className)

No documentation.