.. pynsive documentation master file, created by
   sphinx-quickstart on Sat Aug 10 01:16:27 2013.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Pynsive
=======

Pronounced, "Pensive"
~~~~~~~~~~~~~~~~~~~~~

This is a simple plugin library that uses the **sys.meta\_path** list
along with custom finder and loader definitions to hook into the Python
import process. This means that when directores or other plugin search targets
are added in Pynsive, future import statements will now search the newly added
path for plugin modules and classes.

For more information on the import process hooks, please see:

-  `Python 3 Import Process <http://docs.python.org/3/reference/import.html>`_
-  `PEP-302 <http://www.python.org/dev/peps/pep-0302/>`_


Latest Release Notes
~~~~~~~~~~~~~~~~~~~~

This version has the following changes from release version <=0.1.4

-  **discover\_classes** was renamed to **rlist\_classes**
-  **discover\_modules** was renamed to **list\_modules**


Creating a Plugin Context
^^^^^^^^^^^^^^^^^^^^^^^^^

The plugin context is a nice way of managing what directories you've
plugged into the **sys.meta\_path** variable. Managers may be destroyed
when no longer needed. Destroying a manager removes all directories that
the manager plugged into from the **sys.meta\_path** variable.

::

    import pynsive

    plugin_manager = pynsive.PluginManager()
    plugin_manager.plug_into('/some/path')

    try:
        import myplugins.module.plugin_a as plugin
        print('Imported plugin module: {1}', plugin)
    finally:
        plugin_manager.destroy()


Dynamically Listing Submodules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Note:** The list functions in Pynsive **will not** descend into the
submodules that may exist under the specified module. In order to recursively
search use the rlist functions.

::

    import pynsive
    import test_module

    plugin_manager = pynsive.PluginManager()
    plugin_manager.plug_into('/some/path')

    try:
        found_modules = pynsive.list_modules('ext.plugins')
        print('Discovered {1} modules.', len(found_modules))
    finally:
        plugin_manager.destroy()


Dynamically Finding Classes in a Module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Note:** The list functions in Pynsive **will not** descend into the
submodules that may exist under the specified module. In order to recursively
search use the rlist functions.

::

    import pynsive
    import test_module

    plugin_manager = pynsive.PluginManager()
    plugin_manager.plug_into('/some/path')

    try:
        def subclasses_only(type_to_test):
            same = type_to_test is not test_module.MyClass
            is_subclass = issubclass(type_to_test, test_module.MyClass)
            return not same and is_subclass

        classes = pynsive.list_classes('ext.plugins', subclasses_only)
        print('Discovered {1} classes.', len(classes))
    finally:
        plugin_manager.destroy()


Dynamically Finding Classes in a Module and its Submodules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Note:** The rlist functions in Pynsive **will** descend into the submodules
that may exist under the specified module. In order to perform a non-recursive
listing use the list functions.

::

    import pynsive
    import test_module

    plugin_manager = pynsive.PluginManager()
    plugin_manager.plug_into('/some/path')

    try:
        def subclasses_only(type_to_test):
            same = type_to_test is not test_module.MyClass
            is_subclass = issubclass(type_to_test, test_module.MyClass)
            return not same and is_subclass

        classes = pynsive.rlist_classes('ext.plugins', subclasses_only)
        print('Discovered {1} classes.', len(classes))
    finally:
        plugin_manager.destroy()


API Documentation
^^^^^^^^^^^^^^^^^

.. toctree::
   :maxdepth: 4

   pynsive


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`


Other Documentation
~~~~~~~~~~~~~~~~~~~

-  `Getting started with Pynsive <http://www.giantflyingsaucer.com/blog/?p=4634>`_
-  `Pynsive at Readthedocs <https://pynsive.readthedocs.org>`_


That Legal Thing...
~~~~~~~~~~~~~~~~~~~

This software library is released to you under the
`Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0.html>`_
. See `LICENSE <https://github.com/zinic/pynsive/blob/master/LICENSE>`_ for
more information.

