def memoized(func=None, key_factory=equal_args, cache_factory=dict):
  """Memoizes the results of a function call.

  By default, exactly one result is memoized for each unique combination of function arguments.

  Note that memoization is not thread-safe and the default result cache will grow without bound;
  so care must be taken to only apply this decorator to functions with single threaded access and
  an expected reasonably small set of unique call parameters.

  Note that the wrapped function comes equipped with 3 helper function attributes:

  + `put(*args, **kwargs)`: A context manager that takes the same arguments as the memoized
                            function and yields a setter function to set the value in the
                            memoization cache.
  + `forget(*args, **kwargs)`: Takes the same arguments as the memoized function and causes the
                               memoization cache to forget the computed value, if any, for those
                               arguments.
  + `clear()`: Causes the memoization cache to be fully cleared.

  :API: public

  :param func: The function to wrap.  Only generally passed by the python runtime and should be
               omitted when passing a custom `key_factory` or `cache_factory`.
  :param key_factory: A function that can form a cache key from the arguments passed to the
                      wrapped, memoized function; by default uses simple parameter-set equality;
                      ie `equal_args`.
  :param cache_factory: A no-arg callable that produces a mapping object to use for the memoized
                        method's value cache.  By default the `dict` constructor, but could be a
                        a factory for an LRU cache for example.
  :raises: `ValueError` if the wrapper is applied to anything other than a function.
  :returns: A wrapped function that memoizes its results or else a function wrapper that does this.
  """
  if func is None:
    # We're being applied as a decorator factory; ie: the user has supplied args, like so:
    # >>> @memoized(cache_factory=lru_cache)
    # ... def expensive_operation(user):
    # ...   pass
    # So we return a decorator with the user-supplied args curried in for the python decorator
    # machinery to use to wrap the upcoming func.
    #
    # NB: This is just a tricky way to allow for both `@memoized` and `@memoized(...params...)`
    # application forms.  Without this trick, ie: using a decorator class or nested decorator
    # function, the no-params application would have to be `@memoized()`.  It still can, but need
    # not be and a bare `@memoized` will work as well as a `@memoized()`.
    return functools.partial(memoized, key_factory=key_factory, cache_factory=cache_factory)

  if not inspect.isfunction(func):
    raise ValueError('The @memoized decorator must be applied innermost of all decorators.')

  key_func = key_factory or equal_args
  memoized_results = cache_factory() if cache_factory else {}

  @functools.wraps(func)
  def memoize(*args, **kwargs):
    key = key_func(*args, **kwargs)
    if key in memoized_results:
      return memoized_results[key]
    result = func(*args, **kwargs)
    memoized_results[key] = result
    return result

  @contextmanager
  def put(*args, **kwargs):
    key = key_func(*args, **kwargs)
    yield functools.partial(memoized_results.__setitem__, key)
  memoize.put = put

  def forget(*args, **kwargs):
    key = key_func(*args, **kwargs)
    if key in memoized_results:
      del memoized_results[key]
  memoize.forget = forget

  def clear():
    memoized_results.clear()
  memoize.clear = clear

  return memoize