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.

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

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.

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