🌱 - clod: CLass mODule! Give your module the power of an object - 🌱
=========================================================================

_Give your module the power of an object, with ``clod`` (and save a
little typing too)._

Ever wanted to call a module directly, or index it?
Or just sick of seeing ``from foo import foo`` in your examples?

``clod`` is a tiny library that solves both these issues in one line of code,
by extending a module with the methods and members of a Python object.

This is extremely handy for modules that primarily do one thing.

EXAMPLE: Make a module callable

.. code-block:: python

    # In your_module.py
    import clod

    A_CONSTANT = 23

    @clod
    def a_function(*args, **kwargs):
        print('a function!')
        return args, kwargs


    # Test at the command line
    >>> import your_module

    >>> your_module(2, 3, a=5)
    a function!
    (2, 3), {'a': 5}

    >>> assert your_module.A_CONSTANT == 23

EXAMPLE: Make a module look like an object

.. code-block:: python

    # In your_module.py
    import clod

    A_CONSTANT = 23

    clod(list(), __name__)

    # Test at the command line
    >>> import your_module

    >>> assert your_module == []

    >>> assert your_module.A_CONSTANT == 23

    >>> your_module.extend(range(3))

    >>> print(your_module)
    [0, 1, 2]

API
---

``clod.clod(extension=None, name=None, properties=None, omit=None)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(`clod.py, 96-177 <https://github.com/rec/clod/blob/master/clod.py#L96-L177>`_)

Extend the system module at ``name`` with any Python object.

The original module is replaced in ``sys.modules`` by a proxy class
which delegates attributes, first to the extension, and then to the
original module.

``clod`` can also be used as a decorator, both with and without
parameters.

ARGUMENTS
  extension
    The object whose methods and properties extend the namespace.
    This includes magic methods like __call__ and __getitem__.

  name
    The name of this symbol in ``sys.modules``.  If this is ``None``
    then ``clod`` will use ``extension.__module__``.

    If the ``name`` argument is given, it should almost certainly be
    ``__name__``.

  properties
    There is little need to use this argument.

    Properties in this list are copied directly from the module into the
    custom class - they do not get overridden by the extension.

    If ``properties`` is None, it defaults to ``clod.MODULE_PROPERTIES``
    which seems to work well a lot of the time

  omit
    There is little need to use this argument.

    A list of methods _not_ to delegate from the proxy to the extension.

(automatically generated by `doks <https://github.com/rec/doks/>`_ on 2020-07-18T15:46:33.018839)
