unittest.util

Various utility functions.

Classes

Counter

Dict subclass for counting hashable items.  Sometimes called a bag
    or multiset.  Elements are stored as dictionary keys and their counts
    are stored as dictionary values.

    >>> c = Counter('abcdeabcdabcaba')  # count elements from a string

    >>> c.most_common(3)                # three most common elements
    [('a', 5), ('b', 4), ('c', 3)]
    >>> sorted(c)                       # list all unique elements
    ['a', 'b', 'c', 'd', 'e']
    >>> ''.join(sorted(c.elements()))   # list elements with repetitions
    'aaaaabbbbcccdde'
    >>> sum(c.values())                 # total of all counts
    15

    >>> c['a']                          # count of letter 'a'
    5
    >>> for elem in 'shazam':           # update counts from an iterable
    ...     c[elem] += 1                # by adding 1 to each element's count
    >>> c['a']                          # now there are seven 'a'
    7
    >>> del c['b']                      # remove all 'b'
    >>> c['b']                          # now there are zero 'b'
    0

    >>> d = Counter('simsalabim')       # make another counter
    >>> c.update(d)                     # add in the second counter
    >>> c['a']                          # now there are nine 'a'
    9

    >>> c.clear()                       # empty the counter
    >>> c
    Counter()

    Note:  If a count is set to zero or reduced to zero, it will remain
    in the counter until the entry is deleted or the counter is cleared:

    >>> c = Counter('aaabbc')
    >>> c['b'] -= 2                     # reduce the count of 'b' by two
    >>> c.most_common()                 # 'b' is still in, but its count is zero
    [('a', 3), ('c', 1), ('b', 0)]

clear(...)

  D.clear() -> None.  Remove all items from D.

copy(self)

  Return a shallow copy.

elements(self)

  Iterator over elements repeating each as many times as its count.

          >>> c = Counter('ABCABC')
          >>> sorted(c.elements())
          ['A', 'A', 'B', 'B', 'C', 'C']

          # Knuth's example for prime factors of 1836:  2**2 * 3**3 * 17**1
          >>> prime_factors = Counter({2: 2, 3: 3, 17: 1})
          >>> product = 1
          >>> for factor in prime_factors.elements():     # loop over factors
          ...     product *= factor                       # and multiply them
          >>> product
          1836

          Note, if an element's count has been set to zero or is a negative
          number, elements() will ignore it.

fromkeys(iterable, v=None)

get(self, key, default=None, /)

  Return the value for key if key is in the dictionary, else default.

items(...)

  D.items() -> a set-like object providing a view on D's items

keys(...)

  D.keys() -> a set-like object providing a view on D's keys

most_common(self, n=None)

  List the n most common elements and their counts from the most
          common to the least.  If n is None, then list all element counts.

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

pop(...)

  D.pop(k[,d]) -> v, remove specified key and return the corresponding value.

  If key is not found, default is returned if given, otherwise KeyError is raised

popitem(self, /)

  Remove and return a (key, value) pair as a 2-tuple.

  Pairs are returned in LIFO (last-in, first-out) order.
  Raises KeyError if the dict is empty.

setdefault(self, key, default=None, /)

  Insert key with a value of default if key is not in the dictionary.

  Return the value for key if key is in the dictionary, else default.

subtract(self, iterable=None, /, **kwds)

  Like dict.update() but subtracts counts instead of replacing them.
          Counts can be reduced below zero.  Both the inputs and outputs are
          allowed to contain zero and negative counts.

          Source can be an iterable, a dictionary, or another Counter instance.

          >>> c = Counter('which')
          >>> c.subtract('witch')             # subtract elements from another iterable
          >>> c.subtract(Counter('watch'))    # subtract elements from another counter
          >>> c['h']                          # 2 in which, minus 1 in witch, minus 1 in watch
          0
          >>> c['w']                          # 1 in which, minus 1 in witch, minus 1 in watch
          -1

update(self, iterable=None, /, **kwds)

  Like dict.update() but add counts instead of replacing them.

          Source can be an iterable, a dictionary, or another Counter instance.

          >>> c = Counter('which')
          >>> c.update('witch')           # add elements from another iterable
          >>> d = Counter('watch')
          >>> c.update(d)                 # add elements from another counter
          >>> c['h']                      # four 'h' in which, witch, and watch
          4

values(...)

  D.values() -> an object providing a view on D's values

Functions

commonprefix

commonprefix(m)

  Given a list of pathnames, returns the longest common leading component

namedtuple

namedtuple(typename, field_names, *, rename=False, defaults=None, module=None)

  Returns a new subclass of tuple with named fields.

      >>> Point = namedtuple('Point', ['x', 'y'])
      >>> Point.__doc__                   # docstring for the new class
      'Point(x, y)'
      >>> p = Point(11, y=22)             # instantiate with positional args or keywords
      >>> p[0] + p[1]                     # indexable like a plain tuple
      33
      >>> x, y = p                        # unpack like a regular tuple
      >>> x, y
      (11, 22)
      >>> p.x + p.y                       # fields also accessible by name
      33
      >>> d = p._asdict()                 # convert to a dictionary
      >>> d['x']
      11
      >>> Point(**d)                      # convert from a dictionary
      Point(x=11, y=22)
      >>> p._replace(x=100)               # _replace() is like str.replace() but targets named fields
      Point(x=100, y=22)

safe_repr

safe_repr(obj, short=False)

sorted_list_difference

sorted_list_difference(expected, actual)

  Finds elements in only one or the other of two, sorted input lists.

      Returns a two-element tuple of lists.    The first list contains those
      elements in the "expected" list but not in the "actual" list, and the
      second contains those elements in the "actual" list but not in the
      "expected" list.    Duplicate elements in either input list are ignored.

strclass

strclass(cls)

three_way_cmp

three_way_cmp(x, y)

  Return -1 if x < y, 0 if x == y and 1 if x > y

unorderable_list_difference

unorderable_list_difference(expected, actual)

  Same behavior as sorted_list_difference but
      for lists of unorderable items (like dicts).

      As it does a linear search per item (remove) it
      has O(n*n) performance.