116 lines
3.7 KiB
Plaintext
116 lines
3.7 KiB
Plaintext
Metadata-Version: 2.1
|
|
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
|
|
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.*
|
|
|
|
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
|
|
|
|
|