Metadata-Version: 2.1
Name: xmod
Version: 1.3.1
Summary: Create and recursively fill a temporary directory
Home-page: https://github.com/rec/xmod
Author: Tom Ritchford
Author-email: tom@swirly.com
License: MIT
Keywords: testing,modules
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
License-File: LICENSE

🌱 - xmod: Extend a module with any Python object - 🌱
=========================================================================

Callable modules!  Indexable modules!?

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

Give your module the awesome power of an object, or maybe just save a
little typing, with ``xmod``.

``xmod`` is a tiny library that extends a module to do things that normally
only a class could do - handy for modules that "just do one thing".


EXAMPLE: Make a module callable as a function

.. code-block:: python

    # In your_module.py
    import xmod

    @xmod
    def a_function():
        return 'HERE!!'


    # Test at the command line
    >>> import your_module
    >>> your_module()
    HERE!!


EXAMPLE: Make a module look like an object

.. code-block:: python

    # In your_module.py
    import xmod

    xmod(list(), __name__)

    # Test at the command line
    >>> import your_module
    >>> assert your_module == []
    >>> your_module.extend(range(3))
    >>> print(your_module)
    [0, 1, 2]

API
---

``xmod()``
~~~~~~~~~~

.. code-block:: python

  xmod(
       extension=None,
       name=None,
       full=None,
       props=None,
       omit=None,
       mutable=False,
  )

(`xmod.py, 72-180 <https://github.com/rec/xmod/blob/master/xmod.py#L72-L180>`_)

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 to the original module, and then adds
attributes from the extension.

In the most common use case, the extension is a callable and only the
``__call__`` method is delegated, so ``xmod`` 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 ``xmod`` will use ``extension.__module__``.

    This only needs to be be set if ``extension`` is _not_ a function or
    class defined in the module that's being extended.

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

  full
    If ``False``, just add extension as a callable.

    If ``True``, extend the module with all members of ``extension``.

    If ``None``, the default, add the extension if it's a callable, otherwise
    extend the module with all members of ``extension``.

  mutable:
    If ``True``, the attributes on the proxy are mutable and write through to
    the underlying module.  If ``False``, the default, attributes on the proxy
    cannot be changed.

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

    If ``omit`` is None, it defaults to ``xmod.OMIT``, which seems to
    work well.

(automatically generated by `doks <https://github.com/rec/doks/>`_ on 2020-11-16T17:28:35.769504)


