def __init__(self, bassNote = 'C3', notationString = None, fbScale = None, fbRules = rules.Rules(), numParts = 4, maxPitch = 'B5', listOfPitches = None):
        ''' 
        A Segment corresponds to a 1:1 realization of a bassNote and notationString of a :class:`~music21.figuredBass.realizer.FiguredBassLine`.
        It is created by passing six arguments: a :class:`~music21.figuredBass.realizerScale.FiguredBassScale`, a bassNote, a notationString,
        a :class:`~music21.figuredBass.rules.Rules` object, a number of parts and a maximum pitch. Realizations of a Segment are represented 
        as possibility tuples (see :mod:`~music21.figuredBass.possibility` for more details). 
        
        Methods in Python's `itertools <http://docs.python.org/library/itertools.html>`_ module are used extensively. Methods 
        which generate possibilities or possibility progressions return iterators, which are turned into lists in the examples 
        for display purposes only.
        
        if fbScale is None, a realizerScale.FiguredBassScale() is created

        if fbRules is None, a rules.Rules() instance is created.  Each Segment gets its own deepcopy of the one given.
        
        
        Here, a Segment is created using the default values: a FiguredBassScale in C, a bassNote of C3, an empty notationString, and a default
        Rules object.
        
        >>> from music21.figuredBass import segment
        >>> s1 = segment.Segment()
        >>> s1.bassNote
        <music21.note.Note C>
        >>> s1.numParts
        4
        >>> s1.pitchNamesInChord
        ['C', 'E', 'G']
        >>> [str(p) for p in s1.allPitchesAboveBass]
        ['C3', 'E3', 'G3', 'C4', 'E4', 'G4', 'C5', 'E5', 'G5']
        >>> s1.segmentChord
        <music21.chord.Chord C3 E3 G3 C4 E4 G4 C5 E5 G5>
        '''
        if common.isStr(bassNote):
            bassNote = note.Note(bassNote)
        if common.isStr(maxPitch):
            maxPitch = pitch.Pitch(maxPitch)
        
        if fbScale is None:
            global _defaultRealizerScale
            if _defaultRealizerScale is None:
                _defaultRealizerScale = realizerScale.FiguredBassScale()
            fbScale = _defaultRealizerScale # save making it
        
        if fbRules is None:
            self.fbRules = rules.Rules()
        else:
            self.fbRules = copy.deepcopy(fbRules)
        
        self.bassNote = bassNote
        self.numParts = numParts
        self._maxPitch = maxPitch
        if notationString == None and listOfPitches != None: #must be a chord symbol or roman numeral....
            self.pitchNamesInChord = listOfPitches
        #!---------- Added to accommodate harmony.ChordSymbol and roman.RomanNumeral objects --------!
        else:
            self.pitchNamesInChord = fbScale.getPitchNames(self.bassNote.pitch, notationString)
        
        self.allPitchesAboveBass = getPitches(self.pitchNamesInChord, self.bassNote.pitch, self._maxPitch)
        self.segmentChord = chord.Chord(self.allPitchesAboveBass, quarterLength = bassNote.quarterLength)
        self._environRules = environment.Environment(_MOD)

    def __init__(self, value = None):
        music21.Music21Object.__init__(self)

        if not common.isStr(value):
            # assume it is a number, try to convert
            value = dynamicStrFromDecimal(value)

        self.value = value

        if self.value in longNames:
            self.longName = longNames[self.value]
        else:
            self.longName = None

        if self.value in englishNames:
            self.englishName = englishNames[self.value]
        else:
            self.englishName = None

        # for position, as musicxml, all units are in tenths of interline space
        # position is needed as default positions are often incorrect
        self.posDefaultX = None
        self.posDefaultY = None
        self.posRelativeX = -36 # this value provides good 16th note alignment
        self.posRelativeY = None
        self.posPlacement = 'below' # attr in mxDirection, below or above

    def _filterNodeId(self, id):
        '''Given a node id, return the edge coordinates.

        Node 1 is the first node, even though the edge coordinates are 'start' and 0.

        >>> edgeList = ['M2', 'M2', 'm2', 'M2', 'M2', 'M2', 'm2']
        >>> net = IntervalNetwork()
        >>> net.setEdges(edgeList)
        >>> net._filterNodeId(1)
        ('start', 0)
        >>> net._filterNodeId([3,4])
        (3, 4)
        >>> net._filterNodeId('last')
        (5, 'end')
        >>> net._filterNodeId('first')
        ('start', 0)
        '''
        if common.isNum(id):
            # assume counting nodes from 1
            return self._nodesOrdered[id-1 % len(self._nodesOrdered)]
        if common.isStr(id):
            if id.lower() in ['start', 'first']:
                return self._getFirstNode()
            elif id.lower() in ['end', 'last']:
                return self._getLastNode()

        else: # match coords
            if tuple(id) in self._nodesOrdered:
                return tuple(id)

    def __init__(self, value=None):
        base.Music21Object.__init__(self)

        # the scalar is used to calculate the final output of a note
        # under this dynamic. if this property is set, it will override 
        # use of a default. 
        self._volumeScalar = None
        self.longName = None
        self.englishName = None
        self._value = None

        if not common.isStr(value):
            # assume it is a number, try to convert
            self._volumeScalar = value
            self.value = dynamicStrFromDecimal(value)
        else:
            self.value = value # will use property

        # for position, as musicxml, all units are in tenths of interline space
        # position is needed as default positions are often incorrect
        self._positionDefaultX = -36
        self._positionDefaultY = -80 # below top line
        # this value provides good 16th note alignment
        self._positionRelativeX = None
        self._positionRelativeY = None
        # this does not do anything if default y is defined
        self._positionPlacement = None

    def parseData(self, tnData, number=None):
        '''Open TinyNotation data from a string

        >>> tnData = "3/4 E4 r f# g=lastG trip{b-8 a g} c"
        >>> c = converter.subConverters.ConverterTinyNotation()
        >>> s = c.parseData(tnData)
        >>> c.stream.show('text')
        {0.0} <music21.stream.Measure 1 offset=0.0>
            {0.0} <music21.clef.TrebleClef>
            {0.0} <music21.meter.TimeSignature 3/4>
            {0.0} <music21.note.Note E>
            {1.0} <music21.note.Rest rest>
            {2.0} <music21.note.Note F#>
        {3.0} <music21.stream.Measure 2 offset=3.0>
            {0.0} <music21.note.Note G>
            {1.0} <music21.note.Note B->
            {1.3333} <music21.note.Note A>
            {1.6667} <music21.note.Note G>
            {2.0} <music21.note.Note C>
            {2.5} <music21.bar.Barline style=final>
        '''
        if common.isStr(tnData):
            tnStr = tnData
        else: # assume a 2 element sequence
            raise SubConverterException(
                "TinyNotation no longer supports two-element calls; put the time signature " + 
                "in the stream")
        from music21 import tinyNotation
        self.stream = tinyNotation.Converter(tnStr, **self.keywords).parse().stream

    def parseData(self, tnData, number=None):
        '''Open TinyNotation data from a string or list

        >>> tnData = ["E4 r f# g=lastG trip{b-8 a g} c", "3/4"]
        >>> c = converter.subConverters.ConverterTinyNotation()
        >>> s = c.parseData(tnData)
        >>> c.stream.show('text')
        {0.0} <music21.meter.TimeSignature 3/4>
        {0.0} <music21.note.Note E>
        {1.0} <music21.note.Rest rest>
        {2.0} <music21.note.Note F#>
        {3.0} <music21.note.Note G>
        {4.0} <music21.note.Note B->
        {4.3333} <music21.note.Note A>
        {4.6667} <music21.note.Note G>
        {5.0} <music21.note.Note C>        
        '''
        if common.isStr(tnData):
            tnStr = tnData
            tnTs = None
        else: # assume a 2 element sequence
            tnStr = tnData[0]
            tnTs = tnData[1]
        from music21 import tinyNotation
        self.stream = tinyNotation.TinyNotationStream(tnStr, tnTs)

    def printDebug(self, msg, statusLevel=common.DEBUG_USER, debugFormat=None):
        '''
        Format one or more data elements into string, and print it 
        to stderr. The first arg can be a list of strings or a string; 
        lists are concatenated with common.formatStr(). 
        '''
        #if not common.isNum(statusLevel):
        #    raise EnvironmentException('bad statusLevel argument given: %s' % statusLevel)
#         if self.__getitem__('debug') >= statusLevel:
#             if common.isStr(msg):
#                 msg = [msg] # make into a list
#             if msg[0] != self.modNameParent and self.modNameParent != None:
#                 msg = [self.modNameParent + ':'] + msg
#             # pass list to common.formatStr
#             msg = common.formatStr(*msg, format=debugFormat)
#             sys.stderr.write(msg)

        if _environStorage['instance'].__getitem__('debug') >= statusLevel:
            if common.isStr(msg):
                msg = [msg] # make into a list
            if msg[0] != self.modNameParent and self.modNameParent != None:
                msg = [self.modNameParent + ':'] + msg
            # pass list to common.formatStr
            msg = common.formatStr(*msg, format=debugFormat)
            sys.stderr.write(msg)

def _getKeyAndPrefix(rtKeyOrString):
    '''Given an RTKey specification, return the Key and a string prefix based
    on the tonic:

    >>> romanText.translate._getKeyAndPrefix('c')
    (<music21.key.Key of c minor>, 'c: ')
    >>> romanText.translate._getKeyAndPrefix('F#')
    (<music21.key.Key of F# major>, 'F#: ')
    >>> romanText.translate._getKeyAndPrefix('Eb')
    (<music21.key.Key of E- major>, 'E-: ')
    >>> romanText.translate._getKeyAndPrefix('Bb')
    (<music21.key.Key of B- major>, 'B-: ')
    >>> romanText.translate._getKeyAndPrefix('bb')
    (<music21.key.Key of b- minor>, 'b-: ')
    >>> romanText.translate._getKeyAndPrefix('b#')
    (<music21.key.Key of b# minor>, 'b#: ')
    '''
    from music21 import key
    if common.isStr(rtKeyOrString):
        rtKeyOrString = key.convertKeyStringToMusic21KeyString(rtKeyOrString)
        k = key.Key(rtKeyOrString)
    else:
        k = rtKeyOrString.getKey()
    tonicName = k.tonic.name
    if k.mode == 'minor':
        tonicName = tonicName.lower()
    prefix = tonicName + ": "
    return k, prefix

    def getDoc(self, partName):
        element = self.getElement(partName)

        if hasattr(self.srcNameEval, '_DOC_ATTR'):
            docAttr = self.srcNameEval._DOC_ATTR
        else:
            docAttr = {}

        match = None
                
        if partName in docAttr.keys():
            match = docAttr[partName]
        # if its an undocumented public attribute and basic python
        # data structure, we do not want to show that documentation
        elif (element.kind in ['data'] and (
            common.isStr(element.object) or 
            common.isListLike(element.object) or
            common.isNum(element.object)
            )):
            pass
        else:
            try:
                match = element.object.__doc__
            except AttributeError:
                match = None

        if match == None:
            return NO_DOC
        else:
            return match

def romanTextToStreamOpus(rtHandler, inputM21=None):
    '''The main processing routine for RomanText objects that may or may not
    be multi movement.
    
    Takes in a romanText.base.RTFile() object, or a string as rtHandler.
    
    Runs `romanTextToStreamScore()` as its main work.
    
    If inputM21 is None then it will create a Score or Opus object.
    
    Return either a Score object, or, if a multi-movement work is defined, an
    Opus object.
    '''
    from music21 import romanText as romanTextModule

    from music21 import stream
    if common.isStr(rtHandler):
        rtf = romanTextModule.RTFile()
        rtHandler = rtf.readstr(rtHandler) # return handler, processes tokens

    if rtHandler.definesMovements(): # create an opus
        if inputM21 == None:
            s = stream.Opus()
        else:
            s = inputM21
        # copy the common header to each of the sub-handlers
        handlerBundles = rtHandler.splitByMovement(duplicateHeader=True)
        # see if we have header information
        for h in handlerBundles:
            #print h, len(h)
            # append to opus
            s.append(romanTextToStreamScore(h))
        return s # an opus
    else: # create a Score
        return romanTextToStreamScore(rtHandler, inputM21=inputM21)

    def antiParallelMotion(self, simpleName = None):
        '''
        Returns true if the simple interval before is the same as the simple
        interval after and the motion is contrary. if simpleName is
        specified as an Interval object or a string then it only returns
        true if the simpleName of both intervals is the same as simpleName
        (i.e., use to find antiParallel fifths) 

        >>> from music21 import *
        >>> n11 = note.Note("C4")
        >>> n12 = note.Note("D3") # descending 7th
        >>> n21 = note.Note("G4")
        >>> n22 = note.Note("A4") # ascending 2nd
        >>> vlq1 = voiceLeading.VoiceLeadingQuartet(n11, n12, n21, n22)
        >>> vlq1.antiParallelMotion()
        True
        >>> vlq1.antiParallelMotion('M2')
        False
        >>> vlq1.antiParallelMotion('P5')
        True
        
        We can also use interval objects
        >>> p5Obj = interval.Interval("P5")
        >>> p8Obj = interval.Interval('P8')
        >>> vlq1.antiParallelMotion(p5Obj)
        True
        >>> p8Obj = interval.Interval('P8')
        >>> vlq1.antiParallelMotion(p8Obj)
        False

        >>> n1 = note.Note('G4')
        >>> n2 = note.Note('G4')
        >>> m1 = note.Note('G4')
        >>> m2 = note.Note('G3')
        >>> vl2 = VoiceLeadingQuartet(n1, n2, m1, m2)
        >>> vl2.antiParallelMotion()
        False
        '''
        if not self.contraryMotion():
            return False
        else:
            if self.vIntervals[0].simpleName == self.vIntervals[1].simpleName:
                if simpleName is None:
                    return True
                else:
                    if common.isStr(simpleName):
                        if self.vIntervals[0].simpleName == simpleName:
                            return True
                        else:
                            return False
                    else: # assume Interval object
                        if self.vIntervals[0].simpleName == simpleName.simpleName:
                            return True
                        else:
                            return False
            else:
                return False

def pitchToSharps(value, mode=None):
    '''Given a pitch or :class:`music21.pitch.Pitch` object, return the number of sharps found in the major key.

    The `mode` parameter can be None (=Major), 'major', or 'minor'.

    >>> from music21 import *

    >>> key.pitchToSharps('c')
    0
    >>> key.pitchToSharps('c', 'minor')
    -3
    >>> key.pitchToSharps('a', 'minor')
    0
    >>> key.pitchToSharps('d')
    2
    >>> key.pitchToSharps('e-')
    -3
    >>> key.pitchToSharps('a')
    3
    >>> key.pitchToSharps('e', 'minor')
    1
    >>> key.pitchToSharps('f#', 'major')
    6
    >>> key.pitchToSharps('g-', 'major')
    -6
    >>> key.pitchToSharps('c#')
    7
    >>> key.pitchToSharps('g#')
    8
    '''
    if common.isStr(value):
        p = pitch.Pitch(value)
    else:
        p = value
    # start at C and continue in both directions
    sharpSource = [0]
    for i in range(1,13):
        sharpSource.append(i)
        sharpSource.append(-i)

    minorShift = interval.Interval('-m3')

    # NOTE: this may not be the fastest approach
    match = None
    for i in sharpSource:
        pCandidate = sharpsToPitch(i)
        if mode in [None, 'major']:
            if pCandidate.name == p.name:
                match = i
                break
        else: # match minor pitch
            pMinor = pCandidate.transpose(minorShift)
            if pMinor.name == p.name:
                match = i
                break
    return match

 def warn(self, msg):
     '''To print a warning to the user, send a list of strings to this
     method. 
     '''
     if common.isStr(msg):
         msg = [msg] # make into a list
     if msg[0] != self.modNameParent and self.modNameParent != None:
         msg = [self.modNameParent + ': WARNING:'] + msg
     msg = common.formatStr(*msg)
     sys.stderr.write(msg)

 def __init__(self, text=None, number=1, syllabic=None):
     if not common.isStr(text):
         # do not want to do this unless we are sure this is not a string
         # possible might alter unicode or other string-like representations
         self.text = str(text)         
     else:
         self.text = text
     if not common.isNum(number):
         raise LyricException('Number best be number')
     self.number = number
     self.syllabic = syllabic # can be begin, middle, or end

    def __setitem__(self, key, value):
        '''Dictionary-like setting. Changes are made only to local dictionary.
        Must call write() to make permanent

        >>> from music21 import *
        >>> a = music21.environment.Environment()
        >>> a['debug'] = 1
        >>> a['graphicsPath'] = '/test&Encode'
        >>> a['graphicsPath']
        '/test&Encode'
        >>> a['autoDownload'] = 'adsf'
        Traceback (most recent call last):
        EnvironmentException: adsf is not an acceptable value for preference: autoDownload
        >>> a['showFormat'] = 'adsf'
        Traceback (most recent call last):
        EnvironmentException: adsf is not an acceptable value for preference: showFormat
        >>> a['showFormat'] = 'musicxml'
        '''
        #saxutils.escape # used for escaping strings going to xml
        # with unicode encoding
        # http://www.xml.com/pub/a/2002/11/13/py-xml.html?page=2
        # saxutils.escape(msg).encode('UTF-8')

        if key not in self.ref.keys():
            raise EnvironmentException('no preference: %s' % key)
        if value == '':
            value = None # always replace '' with None

        valid = False
        if key == 'showFormat':
            value = value.lower()
            if value in common.VALID_SHOW_FORMATS:
                valid = True
        elif key == 'writeFormat':
            value = value.lower()
            if value in common.VALID_WRITE_FORMATS:
                valid = True
        elif key == 'debug':
          log.setLevel(logging.INFO)
        elif key == 'autoDownload':
            value = value.lower()
            if value in common.VALID_AUTO_DOWNLOAD:
                valid = True
        else: # temporarily not validating other preferences
            valid = True

        if not valid:
            raise EnvironmentException('%s is not an acceptable value for preference: %s' % (value, key))

        if common.isStr(value):
            value = xml.sax.saxutils.escape(value).encode('UTF-8')
        self.ref[key] = value

    def _filterPitchList(self, pitchTest):
        '''Given a list or one pitch, check if all are pitch objects; convert if necessary.
        '''
        if not common.isListLike(pitchTest):
            if common.isStr(pitchTest):
                pitchTest = pitch.Pitch(pitchTest)
            pitchTest = [pitchTest]
        else:
            # convert a list of string into pitch objects
            temp = []
            for p in pitchTest:
                if common.isStr(p):
                    temp.append(pitch.Pitch(p))
            if len(temp) == len(pitchTest):
                pitchTest = temp

        sortList = [(pitchTest[i].ps, i) for i in range(len(pitchTest))]
        sortList.sort()
        minPitch = pitchTest[sortList[0][1]] # first index
        maxPitch = pitchTest[sortList[-1][1]] # last index

        return pitchTest, minPitch, maxPitch

 def warn(self, msg, header=None):
     '''To print a warning to the user, send a list of strings to this
     method. Similar to printDebug but even if debug is off.
     '''
     if common.isStr(msg):
         msg = [msg] # make into a list
     if header == None:
         if msg[0] != self.modNameParent and self.modNameParent != None:
             msg = [self.modNameParent + ': WARNING:'] + msg
     else:
         msg = [header] + msg
     msg = common.formatStr(*msg)
     sys.stderr.write(msg)

 def printDebug(self, msg, statusLevel=common.DEBUG_USER):
     '''Format one or more data elements into string, and print it 
     to stderr. The first arg can be a list of string; lists are 
     concatenated with common.formatStr(). 
     '''
     if not common.isNum(statusLevel):
         raise EnvironmentException('bad statusLevel argument given: %s' % statusLevel)
     if self.__getitem__('debug') >= statusLevel:
         if common.isStr(msg):
             msg = [msg] # make into a list
         if msg[0] != self.modNameParent and self.modNameParent != None:
             msg = [self.modNameParent + ':'] + msg
 
         msg = common.formatStr(*msg)
         sys.stderr.write(msg)

    def parseData(self, tnData):
        '''Open TinyNotation data from a string or list

        >>> tnData = ["E4 r f# g=lastG trip{b-8 a g} c", "3/4"]
        >>> c = ConverterTinyNotation()
        >>> s = c.parseData(tnData)
        '''
        if common.isStr(tnData):
            tnStr = tnData
            tnTs = None
        else: # assume a 2 element sequence
            tnStr = tnData[0]
            tnTs = tnData[1]
    
        self.stream = tinyNotation.TinyNotationStream(tnStr, tnTs)

    def __setitem__(self, key, value):

        #saxutils.escape # used for escaping strings going to xml
        # with unicode encoding
        # http://www.xml.com/pub/a/2002/11/13/py-xml.html?page=2
        # saxutils.escape(msg).encode('UTF-8')

        # add local corpus path as a key
        if key not in self._ref:
            if key != 'localCorpusPath':
                raise EnvironmentException('no preference: %s' % key)
        if value == '':
            value = None # always replace '' with None

        valid = False
        if key == 'showFormat':
            value = value.lower()
            if value in common.VALID_SHOW_FORMATS:
                valid = True
        elif key == 'writeFormat':
            value = value.lower()
            if value in common.VALID_WRITE_FORMATS:
                valid = True
        elif key == 'autoDownload':
            value = value.lower()
            if value in common.VALID_AUTO_DOWNLOAD:
                valid = True
        elif key == 'localCorpusSettings':
            # needs to be a list of strings for now
            if common.isListLike(value):
                valid = True
        else: # temporarily not validating other preferences
            valid = True

        if not valid:
            raise EnvironmentException('%s is not an acceptable value for preference: %s' % (value, key))

        # need to escape problematic characters for xml storage
        if common.isStr(value):
            value = saxutils.escape(value).encode('UTF-8')
        # set value
        if key == 'localCorpusPath':
            # only add if unique
            if value not in self._ref['localCorpusSettings']:
                # check for malicious values here
                self._ref['localCorpusSettings'].append(value)
        else:
            self._ref[key] = value