1 files changed, 114 insertions, 0 deletions
diff --git a/Doc/library/packaging.pypi.dist.rst b/Doc/library/packaging.pypi.dist.rst
new file mode 100644
index 0000000000..aaaaab7fb8
--- /dev/null
+++ b/Doc/library/packaging.pypi.dist.rst
@@ -0,0 +1,114 @@
+:mod:`packaging.pypi.dist` --- Classes representing query results
+=================================================================
+
+.. module:: packaging.pypi.dist
+   :synopsis: Classes representing the results of queries to indexes.
+
+
+Information coming from the indexes is held in instances of the classes defined
+in this module.
+
+Keep in mind that each project (eg. FooBar) can have several releases
+(eg. 1.1, 1.2, 1.3), and each of these releases can be provided in multiple
+distributions (eg. a source distribution, a binary one, etc).
+
+
+ReleaseInfo
+-----------
+
+Each release has a project name, version, metadata, and related distributions.
+
+This information is stored in :class:`ReleaseInfo`
+objects.
+
+.. class:: ReleaseInfo
+
+
+DistInfo
+---------
+
+:class:`DistInfo` is a simple class that contains
+information related to distributions; mainly the URLs where distributions
+can be found.
+
+.. class:: DistInfo
+
+
+ReleasesList
+------------
+
+The :mod:`~packaging.pypi.dist` module provides a class which works
+with lists of :class:`ReleaseInfo` classes;
+used to filter and order results.
+
+.. class:: ReleasesList
+
+
+Example usage
+-------------
+
+Build a list of releases and order them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assuming we have a list of releases::
+
+   >>> from packaging.pypi.dist import ReleasesList, ReleaseInfo
+   >>> fb10 = ReleaseInfo("FooBar", "1.0")
+   >>> fb11 = ReleaseInfo("FooBar", "1.1")
+   >>> fb11a = ReleaseInfo("FooBar", "1.1a1")
+   >>> ReleasesList("FooBar", [fb11, fb11a, fb10])
+   >>> releases.sort_releases()
+   >>> releases.get_versions()
+   ['1.1', '1.1a1', '1.0']
+   >>> releases.add_release("1.2a1")
+   >>> releases.get_versions()
+   ['1.1', '1.1a1', '1.0', '1.2a1']
+   >>> releases.sort_releases()
+   ['1.2a1', '1.1', '1.1a1', '1.0']
+   >>> releases.sort_releases(prefer_final=True)
+   >>> releases.get_versions()
+   ['1.1', '1.0', '1.2a1', '1.1a1']
+
+
+Add distribution related information to releases
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It's easy to add distribution information to releases::
+
+   >>> from packaging.pypi.dist import ReleasesList, ReleaseInfo
+   >>> r = ReleaseInfo("FooBar", "1.0")
+   >>> r.add_distribution("sdist", url="http://example.org/foobar-1.0.tar.gz")
+   >>> r.dists
+   {'sdist': FooBar 1.0 sdist}
+   >>> r['sdist'].url
+   {'url': 'http://example.org/foobar-1.0.tar.gz', 'hashname': None, 'hashval':
+   None, 'is_external': True}
+
+
+Getting attributes from the dist objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To abstract querying information returned from the indexes, attributes and
+release information can be retrieved directly from dist objects.
+
+For instance, if you have a release instance that does not contain the metadata
+attribute, it can be fetched by using the "fetch_metadata" method::
+
+   >>> r = Release("FooBar", "1.1")
+   >>> print r.metadata
+   None # metadata field is actually set to "None"
+   >>> r.fetch_metadata()
+   <Metadata for FooBar 1.1>
+
+.. XXX add proper roles to these constructs
+
+
+It's possible to retrieve a project's releases (`fetch_releases`),
+metadata (`fetch_metadata`) and distributions (`fetch_distributions`) using
+a similar work flow.
+
+.. XXX what is possible?
+
+Internally, this is possible because while retrieving information about
+projects, releases or distributions, a reference to the client used is
+stored which can be accessed using the objects `_index` attribute.