Metadata-Version: 1.2
Name: apipkg
Version: 1.5
Summary: apipkg: namespace control and lazy-import mechanism
Home-page: https://github.com/pytest-dev/apipkg
Author: holger krekel
Maintainer: Ronny Pfannschmidt
Maintainer-email: opensource@ronnypfannschmidt.de
License: MIT License
Description: Welcome to apipkg!
        ------------------------
        
        With apipkg you can control the exported namespace of a Python package and
        greatly reduce the number of imports for your users.
        It is a `small pure Python module`_ that works on CPython 2.7 and 3.4+,
        Jython and PyPy. It cooperates well with Python's ``help()`` system,
        custom importers (PEP302) and common command-line completion tools.
        
        Usage is very simple: you can require 'apipkg' as a dependency or you
        can copy paste the ~200 lines of code into your project.
        
        
        Tutorial example
        -------------------
        
        Here is a simple ``mypkg`` package that specifies one namespace
        and exports two objects imported from different modules::
        
            # mypkg/__init__.py
            import apipkg
            apipkg.initpkg(__name__, {
                'path': {
                    'Class1': "_mypkg.somemodule:Class1",
                    'clsattr': "_mypkg.othermodule:Class2.attr",
                }
            }
        
        The package is initialized with a dictionary as namespace.
        
        You need to create a ``_mypkg`` package with a ``somemodule.py``
        and ``othermodule.py`` containing the respective classes.
        The ``_mypkg`` is not special - it's a completely
        regular Python package.
        
        Namespace dictionaries contain ``name: value`` mappings
        where the value may be another namespace dictionary or
        a string specifying an import location.  On accessing
        an namespace attribute an import will be performed::
        
            >>> import mypkg
            >>> mypkg.path
            <ApiModule 'mypkg.path'>
            >>> mypkg.path.Class1   # '_mypkg.somemodule' gets imported now
            <class _mypkg.somemodule.Class1 at 0xb7d428fc>
            >>> mypkg.path.clsattr  # '_mypkg.othermodule' gets imported now
            4 # the value of _mypkg.othermodule.Class2.attr
        
        The ``mypkg.path`` namespace and its two entries are
        loaded when they are accessed.   This means:
        
        * lazy loading - only what is actually needed is ever loaded
        
        * only the root "mypkg" ever needs to be imported to get
          access to the complete functionality
        
        * the underlying modules are also accessible, for example::
        
            from mypkg.sub import Class1
        
        
        Including apipkg in your package
        --------------------------------------
        
        If you don't want to add an ``apipkg`` dependency to your package you
        can copy the `apipkg.py`_ file somewhere to your own package,
        for example ``_mypkg/apipkg.py`` in the above example.  You
        then import the ``initpkg`` function from that new place and
        are good to go.
        
        .. _`small pure Python module`:
        .. _`apipkg.py`: https://github.com/pytest-dev/apipkg/blob/master/src/apipkg/__init__.py
        
        Feedback?
        -----------------------
        
        If you have questions you are welcome to
        
        * join the #pylib channel on irc.freenode.net
        * create an issue on https://github.com/pytest-dev/apipkg/issues
        
        have fun,
        holger krekel
        
Platform: unix
Platform: linux
Platform: osx
Platform: cygwin
Platform: win32
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*
