functools

functools.py - Tools for working with functions and callable objects

Classes

GenericAlias

Represent a PEP 585 generic type

E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,).

RLock

acquire(...)

  acquire(blocking=True) -> bool

  Lock the lock.  `blocking` indicates whether we should wait
  for the lock to be available or not.  If `blocking` is False
  and another thread holds the lock, the method will return False
  immediately.  If `blocking` is True and another thread holds
  the lock, the method will wait for the lock to be released,
  take it and then return True.
  (note: the blocking operation is interruptible.)

  In all other cases, the method will return True immediately.
  Precisely, if the current thread already holds the lock, its
  internal counter is simply incremented. If nobody holds the lock,
  the lock is taken and its internal counter initialized to 1.

release(...)

  release()

  Release the lock, allowing another thread that is blocked waiting for
  the lock to acquire the lock.  The lock must be in the locked state,
  and must be locked by the same thread that unlocks it; otherwise a
  `RuntimeError` is raised.

  Do note that if the lock was acquire()d several times in a row by the
  current thread, release() needs to be called as many times for the lock
  to be available for other threads.

cached_property

partial

partial(func, *args, **keywords) - new function with partial application
    of the given arguments and keywords.

args = <member 'args' of 'functools.partial' objects>
  tuple of arguments to future partial calls

func = <member 'func' of 'functools.partial' objects>
  function object to use in future partial calls

keywords = <member 'keywords' of 'functools.partial' objects>
  dictionary of keyword arguments to future partial calls

partialmethod

Method descriptor with partial application of the given arguments
    and keywords.

    Supports wrapping existing descriptors and handles non-descriptor
    callables as instance methods.

singledispatchmethod

Single-dispatch generic method descriptor.

    Supports wrapping existing descriptors and handles non-descriptor
    callables as instance methods.

register(self, cls, method=None)

  generic_method.register(cls, func) -> func

          Registers a new implementation for the given *cls* on a *generic_method*.

Functions

cache

cache(user_function, /)

  Simple lightweight unbounded cache.  Sometimes called "memoize".

cmp_to_key

cmp_to_key(...)

  Convert a cmp= function into a key= function.

get_cache_token

get_cache_token()

  Returns the current ABC cache token.

  The token is an opaque object (supporting equality testing) identifying the
  current version of the ABC cache for virtual subclasses. The token changes
  with every call to register() on any ABC.

lru_cache

lru_cache(maxsize=128, typed=False)

  Least-recently-used cache decorator.

      If *maxsize* is set to None, the LRU features are disabled and the cache
      can grow without bound.

      If *typed* is True, arguments of different types will be cached separately.
      For example, f(3.0) and f(3) will be treated as distinct calls with
      distinct results.

      Arguments to the cached function must be hashable.

      View the cache statistics named tuple (hits, misses, maxsize, currsize)
      with f.cache_info().  Clear the cache and statistics with f.cache_clear().
      Access the underlying function with f.__wrapped__.

      See:  https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)

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)

recursive_repr

recursive_repr(fillvalue='...')

  Decorator to make a repr function return fillvalue for a recursive call

reduce

reduce(...)

  reduce(function, sequence[, initial]) -> value

  Apply a function of two arguments cumulatively to the items of a sequence,
  from left to right, so as to reduce the sequence to a single value.
  For example, reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) calculates
  ((((1+2)+3)+4)+5).  If initial is present, it is placed before the items
  of the sequence in the calculation, and serves as a default when the
  sequence is empty.

singledispatch

singledispatch(func)

  Single-dispatch generic function decorator.

      Transforms a function into a generic function, which can have different
      behaviours depending upon the type of its first argument. The decorated
      function acts as the default implementation, and additional
      implementations can be registered using the register() attribute of the
      generic function.

total_ordering

total_ordering(cls)

  Class decorator that fills in missing ordering methods

update_wrapper

update_wrapper(wrapper, wrapped, assigned=('__module__', '__name__', '__qualname__', '__doc__', '__annotations__'), updated=('__dict__',))

  Update a wrapper function to look like the wrapped function

         wrapper is the function to be updated
         wrapped is the original function
         assigned is a tuple naming the attributes assigned directly
         from the wrapped function to the wrapper function (defaults to
         functools.WRAPPER_ASSIGNMENTS)
         updated is a tuple naming the attributes of the wrapper that
         are updated with the corresponding attribute from the wrapped
         function (defaults to functools.WRAPPER_UPDATES)

wraps

wraps(wrapped, assigned=('__module__', '__name__', '__qualname__', '__doc__', '__annotations__'), updated=('__dict__',))

  Decorator factory to apply update_wrapper() to a wrapper function

         Returns a decorator that invokes update_wrapper() with the decorated
         function as the wrapper argument and the arguments to wraps() as the
         remaining arguments. Default arguments are as for update_wrapper().
         This is a convenience function to simplify applying partial() to
         update_wrapper().

Other members

WRAPPER_ASSIGNMENTS = ('__module__', '__name__', '__qualname__', '__doc__', '__annotations__')

WRAPPER_UPDATES = ('__dict__',)