pkginfo documentation
=====================

Contents:

.. toctree::
   :maxdepth: 2

Distribution Types
------------------

The fundamental abstraction provided by this pacakge is the ``Distribution``
base class.  Implementations exist for specific cases:  source distributions,
binary distributions, installed pakcages, and development checkouts.

.. doctest::

  >>> from pkginfo import Distribution
  >>> from pkginfo import SDist
  >>> assert issubclass(SDist, Distribution)
  >>> from pkginfo import BDist
  >>> assert issubclass(BDist, Distribution)
  >>> from pkginfo import Installed
  >>> assert issubclass(Installed, Distribution)
  >>> from pkginfo import Develop
  >>> assert issubclass(Develop, Distribution)

Introspecting Source Distributions
----------------------------------

``SDist`` objects are created from a filesystem path to the corresponding
archive, which should have been created via the ``sdist`` command from
distutils:

.. doctest::

  >>> mypackage = SDist('docs/examples/mypackage-0.1.tar.gz')

After creation, the ``SDist`` instance will have attributes corrsponding
the the fields defined in the PEP corresponding to the metadata version,
lower-cased and transliterated into valid Python identifiers by mapping
hyphens to underscores.  E.g.:

.. doctest::

  >>> print mypackage.metadata_version
  1.0
  >>> print mypackage.name
  mypackage
  >>> print mypackage.version
  0.1

Fields which are optional under the PEP, and which have no value set
in their ``PKG-INFO``, will map to the value ``None``:

.. doctest::

  >>> print mypackage.keywords
  None

Fields which are marked "multiple use" under the PEP map onto sequences;
their names are pluralized to indicate the sequence.  "Multiple use" fields
with no occurences in the ``PKG-INFO`` file will map onto an empty sequence:

.. doctest::

  >>> print list(mypackage.supported_platforms)
  []

See `Metadata Versions`_ below for an example with a non-empty,
"multiple-use" field.


Introspecting Binary Distributions
----------------------------------

``BDist`` objects are created from the filename, which should have been
generated via ``setup.py bdist_egg``.

.. doctest::

  >>> mypackage = BDist('docs/examples/mypackage-0.1-py2.6.egg')

After that, they have the same metadata as other ``Distribution`` objects,


Introspecting Installed Packages
--------------------------------

``Installed`` objects are created from either a module object or its
dotted name.

.. doctest::

  >>> dotted = Installed('pkginfo')
  >>> import pkginfo
  >>> direct = Installed(pkginfo)

After that, they have the same metadata as other ``Distribution`` objects,
assuming that the package on which they were based has a discoverable
'.egg-info' file / directory.  To be discoverable, the '.egg-info' must
either be located inside the package (e.g., created via ``setup.py develop``
under setuptools), or adjacent to the package (e.g., created via
``setup.py instlall``).


Introspecting Development Checkouts
-----------------------------------

``Develop`` objects are created from a path to a checkout containing
a ``PKG-iNFO`` file, e.g., created by running ``setup.py develop`` under
setuptools.

.. doctest::

  >>> develop = Develop('.')

After that, they have the same metadata as other ``Distribution`` objects.

Metadata Versions
-----------------

The allowed ``PKG-INFO`` fields and their semantics are defined in a series
of PEPs, each of which updates the metadata version field.

- Metadata version 1.0 is specified in PEP 241.
- Metadata version 1.1 is specified in PEP 314.
- Metadata version 1.2 is specified in PEP 345 (still in draft).

A given ``Distribution`` object parses / exposes the attributes which
correspond to the metadata version specified in its ``PKG-INFO``.

You can override the metadata version stored in a given distribution by
passing the specific version (as a string) to its constructor. E.g.,
updating the metadata version here in order to expose the classifiers,
which were not defined under version '1.0':

.. doctest::

  >>> mypackage = SDist('docs/examples/mypackage-0.1.tar.gz',
  ...                   metadata_version='1.1')
  >>> print list(mypackage.classifiers)
  ['Development Status :: 4 - Beta', 'Environment :: Console (Text Based)']
