Changed in version 3.3:MovedCollections Abstract Base Classes to thecollections.abc module.For backwards compatibility, they continue to be visible in this moduleas well.

8.3.1.ChainMap objects¶

AChainMap class is provided for quickly linking a number of mappingsso they can be treated as a single unit. It is often much faster than creatinga new dictionary and running multipleupdate() calls.

The class can be used to simulate nested scopes and is useful in templating.

classcollections.ChainMap(*maps)¶

AChainMap groups multiple dicts or other mappings together tocreate a single, updateable view. If nomaps are specified, a single emptydictionary is provided so that a new chain always has at least one mapping.

The underlying mappings are stored in a list. That list is public and canaccessed or updated using themaps attribute. There is no other state.

Lookups search the underlying mappings successively until a key is found. Incontrast, writes, updates, and deletions only operate on the first mapping.

AChainMap incorporates the underlying mappings by reference. So, ifone of the underlying mappings gets updated, those changes will be reflectedinChainMap.

All of the usual dictionary methods are supported. In addition, there is amaps attribute, a method for creating new subcontexts, and a property foraccessing all but the first mapping:

maps¶

A user updateable list of mappings. The list is ordered fromfirst-searched to last-searched. It is the only stored state and canbe modified to change which mappings are searched. The list shouldalways contain at least one mapping.

new_child()¶

Returns a newChainMap containing a newdict followed byall of the maps in the current instance. A call tod.new_child() isequivalent to:ChainMap({},*d.maps). This method is used forcreating subcontexts that can be updated without altering values in anyof the parent mappings.

parents¶

Property returning a newChainMap containing all of the maps inthe current instance except the first one. This is useful for skippingthe first map in the search. Use cases are similar to those for thenonlocal keyword used innested scopes. The use cases also parallel those for the built-insuper() function. A reference tod.parents is equivalent to:ChainMap(*d.maps[1:]).

importbuiltinspylookup=ChainMap(locals(),globals(),vars(builtins))

importos,argparsedefaults={'color':'red','user':'guest'}parser=argparse.ArgumentParser()parser.add_argument('-u','--user')parser.add_argument('-c','--color')namespace=parser.parse_args()command_line_args={k:vfork,vinvars(namespace).items()ifv}combined=ChainMap(command_line_args,os.environ,defaults)print(combined['color'])print(combined['user'])

c=ChainMap()# Create root contextd=c.new_child()# Create nested child contexte=c.new_child()# Child of c, independent from de.maps[0]# Current context dictionary -- like Python's locals()e.maps[-1]# Root context -- like Python's globals()e.parents# Enclosing context chain -- like Python's nonlocalsd['x']# Get first key in the chain of contextsd['x']=1# Set value in current contextdeld['x']# Delete from current contextlist(d)# All nested valueskind# Check all nested valueslen(d)# Number of nested valuesd.items()# All nested itemsdict(d)# Flatten into a regular dictionary

classDeepChainMap(ChainMap):'Variant of ChainMap that allows direct updates to inner scopes'def__setitem__(self,key,value):formappinginself.maps:ifkeyinmapping:mapping[key]=valuereturnself.maps[0][key]=valuedef__delitem__(self,key):formappinginself.maps:ifkeyinmapping:delmapping[key]returnraiseKeyError(key)>>>d=DeepChainMap({'zebra':'black'},{'elephant':'blue'},{'lion':'yellow'})>>>d['lion']='orange'# update an existing key two levels down>>>d['snake']='red'# new keys get added to the topmost dict>>>deld['elephant']# remove an existing key one level downDeepChainMap({'zebra':'black','snake':'red'},{},{'lion':'orange'})

8.3.2.Counter objects¶

A counter tool is provided to support convenient and rapid tallies.For example:

>>># Tally occurrences of words in a list>>>cnt=Counter()>>>forwordin['red','blue','red','green','blue','blue']:...cnt[word]+=1>>>cntCounter({'blue': 3, 'red': 2, 'green': 1})>>># Find the ten most common words in Hamlet>>>importre>>>words=re.findall(r'\w+',open('hamlet.txt').read().lower())>>>Counter(words).most_common(10)[('the', 1143), ('and', 966), ('to', 762), ('of', 669), ('i', 631), ('you', 554),  ('a', 546), ('my', 514), ('hamlet', 471), ('in', 451)]

classcollections.Counter([iterable-or-mapping])¶

ACounter is adict subclass for counting hashable objects.It is an unordered collection where elements are stored as dictionary keysand their counts are stored as dictionary values. Counts are allowed to beany integer value including zero or negative counts. TheCounterclass is similar to bags or multisets in other languages.

Elements are counted from aniterable or initialized from anothermapping (or counter):

>>>c=Counter()# a new, empty counter>>>c=Counter('gallahad')# a new counter from an iterable>>>c=Counter({'red':4,'blue':2})# a new counter from a mapping>>>c=Counter(cats=4,dogs=8)# a new counter from keyword args

Counter objects have a dictionary interface except that they return a zerocount for missing items instead of raising aKeyError:

>>>c=Counter(['eggs','ham'])>>>c['bacon']# count of a missing element is zero0

Setting a count to zero does not remove an element from a counter.Usedel to remove it entirely:

>>>c['sausage']=0# counter entry with a zero count>>>delc['sausage']# del actually removes the entry

New in version 3.1.

Counter objects support three methods beyond those available for alldictionaries:

elements()¶

Return an iterator over elements repeating each as many times as itscount. Elements are returned in arbitrary order. If an element’s countis less than one,elements() will ignore it.

>>>c=Counter(a=4,b=2,c=0,d=-2)>>>list(c.elements())['a', 'a', 'a', 'a', 'b', 'b']

most_common([n])¶

Return a list of then most common elements and their counts from themost common to the least. Ifn is not specified,most_common()returnsall elements in the counter. Elements with equal counts areordered arbitrarily:

>>>Counter('abracadabra').most_common(3)[('a', 5), ('r', 2), ('b', 2)]

subtract([iterable-or-mapping])¶

Elements are subtracted from aniterable or from anothermapping(or counter). Likedict.update() but subtracts counts insteadof replacing them. Both inputs and outputs may be zero or negative.

>>>c=Counter(a=4,b=2,c=0,d=-2)>>>d=Counter(a=1,b=2,c=3,d=4)>>>c.subtract(d)>>>cCounter({'a': 3, 'b': 0, 'c': -3, 'd': -6})

New in version 3.2.

The usual dictionary methods are available forCounter objectsexcept for two which work differently for counters.

fromkeys(iterable)¶

This class method is not implemented forCounter objects.

update([iterable-or-mapping])¶

Elements are counted from aniterable or added-in from anothermapping (or counter). Likedict.update() but adds countsinstead of replacing them. Also, theiterable is expected to be asequence of elements, not a sequence of(key,value) pairs.

Common patterns for working withCounter objects:

sum(c.values())# total of all countsc.clear()# reset all countslist(c)# list unique elementsset(c)# convert to a setdict(c)# convert to a regular dictionaryc.items()# convert to a list of (elem, cnt) pairsCounter(dict(list_of_pairs))# convert from a list of (elem, cnt) pairsc.most_common()[:-n-1:-1]# n least common elements+c# remove zero and negative counts

Several mathematical operations are provided for combiningCounterobjects to produce multisets (counters that have counts greater than zero).Addition and subtraction combine counters by adding or subtracting the countsof corresponding elements. Intersection and union return the minimum andmaximum of corresponding counts. Each operation can accept inputs with signedcounts, but the output will exclude results with counts of zero or less.

>>>c=Counter(a=3,b=1)>>>d=Counter(a=1,b=2)>>>c+d# add two counters together:  c[x] + d[x]Counter({'a': 4, 'b': 3})>>>c-d# subtract (keeping only positive counts)Counter({'a': 2})>>>c&d# intersection:  min(c[x], d[x])Counter({'a': 1, 'b': 1})>>>c|d# union:  max(c[x], d[x])Counter({'a': 3, 'b': 2})

Unary addition and substraction are shortcuts for adding an empty counteror subtracting from an empty counter.

>>>c=Counter(a=2,b=-4)>>>+cCounter({'a': 2})>>>-cCounter({'b': 4})

8.3.3.deque objects¶

classcollections.deque([iterable[,maxlen]])¶

Returns a new deque object initialized left-to-right (usingappend()) withdata fromiterable. Ifiterable is not specified, the new deque is empty.

Deques are a generalization of stacks and queues (the name is pronounced “deck”and is short for “double-ended queue”). Deques support thread-safe, memoryefficient appends and pops from either side of the deque with approximately thesame O(1) performance in either direction.

Thoughlist objects support similar operations, they are optimized forfast fixed-length operations and incur O(n) memory movement costs forpop(0) andinsert(0,v) operations which change both the size andposition of the underlying data representation.

Ifmaxlen is not specified or isNone, deques may grow to anarbitrary length. Otherwise, the deque is bounded to the specified maximumlength. Once a bounded length deque is full, when new items are added, acorresponding number of items are discarded from the opposite end. Boundedlength deques provide functionality similar to thetail filter inUnix. They are also useful for tracking transactions and other pools of datawhere only the most recent activity is of interest.

Deque objects support the following methods:

append(x)¶

Addx to the right side of the deque.

appendleft(x)¶

Addx to the left side of the deque.

clear()¶

Remove all elements from the deque leaving it with length 0.

count(x)¶

Count the number of deque elements equal tox.

New in version 3.2.

extend(iterable)¶

Extend the right side of the deque by appending elements from the iterableargument.

extendleft(iterable)¶

Extend the left side of the deque by appending elements fromiterable.Note, the series of left appends results in reversing the order ofelements in the iterable argument.

pop()¶

Remove and return an element from the right side of the deque. If noelements are present, raises anIndexError.

popleft()¶

Remove and return an element from the left side of the deque. If noelements are present, raises anIndexError.

remove(value)¶

Removed the first occurrence ofvalue. If not found, raises aValueError.

reverse()¶

Reverse the elements of the deque in-place and then returnNone.

New in version 3.2.

rotate(n)¶

Rotate the dequen steps to the right. Ifn is negative, rotate tothe left. Rotating one step to the right is equivalent to:d.appendleft(d.pop()).

Deque objects also provide one read-only attribute:

maxlen¶

Maximum size of a deque orNone if unbounded.

New in version 3.1.

In addition to the above, deques support iteration, pickling,len(d),reversed(d),copy.copy(d),copy.deepcopy(d), membership testing withthein operator, and subscript references such asd[-1]. Indexedaccess is O(1) at both ends but slows to O(n) in the middle. For fast randomaccess, use lists instead.

Example:

>>>fromcollectionsimportdeque>>>d=deque('ghi')# make a new deque with three items>>>forelemind:# iterate over the deque's elements...print(elem.upper())GHI>>>d.append('j')# add a new entry to the right side>>>d.appendleft('f')# add a new entry to the left side>>>d# show the representation of the dequedeque(['f', 'g', 'h', 'i', 'j'])>>>d.pop()# return and remove the rightmost item'j'>>>d.popleft()# return and remove the leftmost item'f'>>>list(d)# list the contents of the deque['g', 'h', 'i']>>>d[0]# peek at leftmost item'g'>>>d[-1]# peek at rightmost item'i'>>>list(reversed(d))# list the contents of a deque in reverse['i', 'h', 'g']>>>'h'ind# search the dequeTrue>>>d.extend('jkl')# add multiple elements at once>>>ddeque(['g', 'h', 'i', 'j', 'k', 'l'])>>>d.rotate(1)# right rotation>>>ddeque(['l', 'g', 'h', 'i', 'j', 'k'])>>>d.rotate(-1)# left rotation>>>ddeque(['g', 'h', 'i', 'j', 'k', 'l'])>>>deque(reversed(d))# make a new deque in reverse orderdeque(['l', 'k', 'j', 'i', 'h', 'g'])>>>d.clear()# empty the deque>>>d.pop()# cannot pop from an empty dequeTraceback (most recent call last):File"<pyshell#6>",line1,in-toplevel-d.pop()IndexError:pop from an empty deque>>>d.extendleft('abc')# extendleft() reverses the input order>>>ddeque(['c', 'b', 'a'])

deftail(filename,n=10):'Return the last n lines of a file'withopen(filename)asf:returndeque(f,n)

defmoving_average(iterable,n=3):# moving_average([40, 30, 50, 46, 39, 44]) --> 40.0 42.0 45.0 43.0# http://en.wikipedia.org/wiki/Moving_averageit=iter(iterable)d=deque(itertools.islice(it,n-1))d.appendleft(0)s=sum(d)foreleminit:s+=elem-d.popleft()d.append(elem)yields/n

defdelete_nth(d,n):d.rotate(-n)d.popleft()d.rotate(n)

8.3.4.defaultdict objects¶

classcollections.defaultdict([default_factory[,...]])¶

Returns a new dictionary-like object.defaultdict is a subclass of thebuilt-indict class. It overrides one method and adds one writableinstance variable. The remaining functionality is the same as for thedict class and is not documented here.

The first argument provides the initial value for thedefault_factoryattribute; it defaults toNone. All remaining arguments are treated the sameas if they were passed to thedict constructor, including keywordarguments.

defaultdict objects support the following method in addition to thestandarddict operations:

__missing__(key)¶

If thedefault_factory attribute isNone, this raises aKeyError exception with thekey as argument.

Ifdefault_factory is notNone, it is called without argumentsto provide a default value for the givenkey, this value is inserted inthe dictionary for thekey, and returned.

If callingdefault_factory raises an exception this exception ispropagated unchanged.

This method is called by the__getitem__() method of thedict class when the requested key is not found; whatever itreturns or raises is then returned or raised by__getitem__().

Note that__missing__() isnot called for any operations besides__getitem__(). This means thatget() will, like normaldictionaries, returnNone as a default rather than usingdefault_factory.

defaultdict objects support the following instance variable:

default_factory¶

This attribute is used by the__missing__() method; it isinitialized from the first argument to the constructor, if present, or toNone, if absent.

>>>s=[('yellow',1),('blue',2),('yellow',3),('blue',4),('red',1)]>>>d=defaultdict(list)>>>fork,vins:...d[k].append(v)...>>>list(d.items())[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

>>>d={}>>>fork,vins:...d.setdefault(k,[]).append(v)...>>>list(d.items())[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

>>>s='mississippi'>>>d=defaultdict(int)>>>forkins:...d[k]+=1...>>>list(d.items())[('i', 4), ('p', 2), ('s', 4), ('m', 1)]

>>>defconstant_factory(value):...returnlambda:value>>>d=defaultdict(constant_factory('<missing>'))>>>d.update(name='John',action='ran')>>>'%(name)s %(action)s to %(object)s'%d'John ran to <missing>'

>>>s=[('red',1),('blue',2),('red',3),('blue',4),('red',1),('blue',4)]>>>d=defaultdict(set)>>>fork,vins:...d[k].add(v)...>>>list(d.items())[('blue', {2, 4}), ('red', {1, 3})]

8.3.5.namedtuple() Factory Function for Tuples with Named Fields¶

Named tuples assign meaning to each position in a tuple and allow for more readable,self-documenting code. They can be used wherever regular tuples are used, andthey add the ability to access fields by name instead of position index.

collections.namedtuple(typename,field_names,verbose=False,rename=False)¶

Returns a new tuple subclass namedtypename. The new subclass is used tocreate tuple-like objects that have fields accessible by attribute lookup aswell as being indexable and iterable. Instances of the subclass also have ahelpful docstring (with typename and field_names) and a helpful__repr__()method which lists the tuple contents in aname=value format.

Thefield_names are a single string with each fieldname separated by whitespaceand/or commas, for example'xy' or'x,y'. Alternatively,field_namescan be a sequence of strings such as['x','y'].

Any valid Python identifier may be used for a fieldname except for namesstarting with an underscore. Valid identifiers consist of letters, digits,and underscores but do not start with a digit or underscore and cannot beakeyword such asclass,for,return,global,pass,orraise.

Ifrename is true, invalid fieldnames are automatically replacedwith positional names. For example,['abc','def','ghi','abc'] isconverted to['abc','_1','ghi','_3'], eliminating the keyworddef and the duplicate fieldnameabc.

Ifverbose is true, the class definition is printed after it isbuilt. This option is outdated; instead, it is simpler to print the_source attribute.

Named tuple instances do not have per-instance dictionaries, so they arelightweight and require no more memory than regular tuples.

Changed in version 3.1:Added support forrename.

>>># Basic example>>>Point=namedtuple('Point',['x','y'])>>>p=Point(11,y=22)# instantiate with positional or keyword arguments>>>p[0]+p[1]# indexable like the plain tuple (11, 22)33>>>x,y=p# unpack like a regular tuple>>>x,y(11, 22)>>>p.x+p.y# fields also accessible by name33>>>p# readable __repr__ with a name=value stylePoint(x=11, y=22)

Named tuples are especially useful for assigning field names to result tuples returnedby thecsv orsqlite3 modules:

EmployeeRecord=namedtuple('EmployeeRecord','name, age, title, department, paygrade')importcsvforempinmap(EmployeeRecord._make,csv.reader(open("employees.csv","rb"))):print(emp.name,emp.title)importsqlite3conn=sqlite3.connect('/companydata')cursor=conn.cursor()cursor.execute('SELECT name, age, title, department, paygrade FROM employees')forempinmap(EmployeeRecord._make,cursor.fetchall()):print(emp.name,emp.title)

In addition to the methods inherited from tuples, named tuples supportthree additional methods and two attributes. To prevent conflicts withfield names, the method and attribute names start with an underscore.

classmethodsomenamedtuple._make(iterable)¶

Class method that makes a new instance from an existing sequence or iterable.

>>>t=[11,22]>>>Point._make(t)Point(x=11, y=22)

somenamedtuple._asdict()¶

Return a newOrderedDict which maps field names to their correspondingvalues. Note, this method is no longer needed now that the same effect canbe achieved by using the built-invars() function:

>>>vars(p)OrderedDict([('x', 11), ('y', 22)])

Changed in version 3.1:Returns anOrderedDict instead of a regulardict.

somenamedtuple._replace(kwargs)¶

Return a new instance of the named tuple replacing specified fields with newvalues:

>>>p=Point(x=11,y=22)>>>p._replace(x=33)Point(x=33, y=22)>>>forpartnum,recordininventory.items():...inventory[partnum]=record._replace(price=newprices[partnum],timestamp=time.now())

somenamedtuple._source¶

A string with the pure Python source code used to create the namedtuple class. The source makes the named tuple self-documenting.It can be printed, executed usingexec(), or saved to a fileand imported.

New in version 3.3.

somenamedtuple._fields¶

Tuple of strings listing the field names. Useful for introspectionand for creating new named tuple types from existing named tuples.

>>>p._fields# view the field names('x', 'y')>>>Color=namedtuple('Color','red green blue')>>>Pixel=namedtuple('Pixel',Point._fields+Color._fields)>>>Pixel(11,22,128,255,0)Pixel(x=11, y=22, red=128, green=255, blue=0)

To retrieve a field whose name is stored in a string, use thegetattr()function:

>>>getattr(p,'x')11

To convert a dictionary to a named tuple, use the double-star-operator(as described inUnpacking Argument Lists):

>>>d={'x':11,'y':22}>>>Point(**d)Point(x=11, y=22)

Since a named tuple is a regular Python class, it is easy to add or changefunctionality with a subclass. Here is how to add a calculated field anda fixed-width print format:

>>>classPoint(namedtuple('Point','x y')):    __slots__ = ()    @property    def hypot(self):        return (self.x ** 2 + self.y ** 2) ** 0.5    def __str__(self):        return 'Point: x=%6.3f  y=%6.3f  hypot=%6.3f' % (self.x, self.y, self.hypot)

>>>forpinPoint(3,4),Point(14,5/7):    print(p)Point: x= 3.000  y= 4.000  hypot= 5.000Point: x=14.000  y= 0.714  hypot=14.018

The subclass shown above sets__slots__ to an empty tuple. This helpskeep memory requirements low by preventing the creation of instance dictionaries.

Subclassing is not useful for adding new, stored fields. Instead, simplycreate a new named tuple type from the_fields attribute:

>>>Point3D=namedtuple('Point3D',Point._fields+('z',))

Default values can be implemented by using_replace() tocustomize a prototype instance:

>>>Account=namedtuple('Account','owner balance transaction_count')>>>default_account=Account('<owner name>',0.0,0)>>>johns_account=default_account._replace(owner='John')>>>janes_account=default_account._replace(owner='Jane')

Enumerated constants can be implemented with named tuples, but it is simplerand more efficient to use a simple class declaration:

>>>Status=namedtuple('Status','open pending closed')._make(range(3))>>>Status.open,Status.pending,Status.closed(0, 1, 2)>>>classStatus:    open, pending, closed = range(3)

8.3.6.OrderedDict objects¶

Ordered dictionaries are just like regular dictionaries but they remember theorder that items were inserted. When iterating over an ordered dictionary,the items are returned in the order their keys were first added.

classcollections.OrderedDict([items])¶

Return an instance of a dict subclass, supporting the usualdictmethods. AnOrderedDict is a dict that remembers the order that keyswere first inserted. If a new entry overwrites an existing entry, theoriginal insertion position is left unchanged. Deleting an entry andreinserting it will move it to the end.

New in version 3.1.

popitem(last=True)¶

Thepopitem() method for ordered dictionaries returns and removes a(key, value) pair. The pairs are returned in LIFO order iflast is trueor FIFO order if false.

move_to_end(key,last=True)¶

Move an existingkey to either end of an ordered dictionary. The itemis moved to the right end iflast is true (the default) or to thebeginning iflast is false. RaisesKeyError if thekey doesnot exist:

>>>d=OrderedDict.fromkeys('abcde')>>>d.move_to_end('b')>>>''.join(d.keys())'acdeb'>>>d.move_to_end('b',last=False)>>>''.join(d.keys())'bacde'

New in version 3.2.

In addition to the usual mapping methods, ordered dictionaries also supportreverse iteration usingreversed().

Equality tests betweenOrderedDict objects are order-sensitiveand are implemented aslist(od1.items())==list(od2.items()).Equality tests betweenOrderedDict objects and otherMapping objects are order-insensitive like regulardictionaries. This allowsOrderedDict objects to be substitutedanywhere a regular dictionary is used.

TheOrderedDict constructor andupdate() method both acceptkeyword arguments, but their order is lost because Python’s function callsemantics pass-in keyword arguments using a regular unordered dictionary.

>>># regular unsorted dictionary>>>d={'banana':3,'apple':4,'pear':1,'orange':2}>>># dictionary sorted by key>>>OrderedDict(sorted(d.items(),key=lambdat:t[0]))OrderedDict([('apple', 4), ('banana', 3), ('orange', 2), ('pear', 1)])>>># dictionary sorted by value>>>OrderedDict(sorted(d.items(),key=lambdat:t[1]))OrderedDict([('pear', 1), ('orange', 2), ('banana', 3), ('apple', 4)])>>># dictionary sorted by length of the key string>>>OrderedDict(sorted(d.items(),key=lambdat:len(t[0])))OrderedDict([('pear', 1), ('apple', 4), ('orange', 2), ('banana', 3)])

classLastUpdatedOrderedDict(OrderedDict):'Store items in the order the keys were last added'def__setitem__(self,key,value):ifkeyinself:delself[key]OrderedDict.__setitem__(self,key,value)

classOrderedCounter(Counter,OrderedDict):'Counter that remembers the order elements are first encountered'def__repr__(self):return'%s(%r)'%(self.__class__.__name__,OrderedDict(self))def__reduce__(self):returnself.__class__,(OrderedDict(self),)

8.3.7.UserDict objects¶

The class,UserDict acts as a wrapper around dictionary objects.The need for this class has been partially supplanted by the ability tosubclass directly fromdict; however, this class can be easierto work with because the underlying dictionary is accessible as anattribute.

classcollections.UserDict([initialdata])¶

Class that simulates a dictionary. The instance’s contents are kept in aregular dictionary, which is accessible via thedata attribute ofUserDict instances. Ifinitialdata is provided,data isinitialized with its contents; note that a reference toinitialdata will notbe kept, allowing it be used for other purposes.

In addition to supporting the methods and operations of mappings,UserDict instances provide the following attribute:

data¶

A real dictionary used to store the contents of theUserDictclass.

8.3.8.UserList objects¶

This class acts as a wrapper around list objects. It is a useful base classfor your own list-like classes which can inherit from them and overrideexisting methods or add new ones. In this way, one can add new behaviors tolists.

The need for this class has been partially supplanted by the ability tosubclass directly fromlist; however, this class can be easierto work with because the underlying list is accessible as an attribute.

classcollections.UserList([list])¶

Class that simulates a list. The instance’s contents are kept in a regularlist, which is accessible via thedata attribute ofUserListinstances. The instance’s contents are initially set to a copy oflist,defaulting to the empty list[].list can be any iterable, forexample a real Python list or aUserList object.

In addition to supporting the methods and operations of mutable sequences,UserList instances provide the following attribute:

data¶

A reallist object used to store the contents of theUserList class.

Subclassing requirements: Subclasses ofUserList are expected tooffer a constructor which can be called with either no arguments or oneargument. List operations which return a new sequence attempt to create aninstance of the actual implementation class. To do so, it assumes that theconstructor can be called with a single parameter, which is a sequence objectused as a data source.

If a derived class does not wish to comply with this requirement, all of thespecial methods supported by this class will need to be overridden; pleaseconsult the sources for information about the methods which need to be providedin that case.

8.3.9.UserString objects¶

The class,UserString acts as a wrapper around string objects.The need for this class has been partially supplanted by the ability tosubclass directly fromstr; however, this class can be easierto work with because the underlying string is accessible as anattribute.

classcollections.UserString([sequence])¶

Class that simulates a string or a Unicode string object. The instance’scontent is kept in a regular string object, which is accessible via thedata attribute ofUserString instances. The instance’scontents are initially set to a copy ofsequence. Thesequence canbe an instance ofbytes,str,UserString (or asubclass) or an arbitrary sequence which can be converted into a string usingthe built-instr() function.