summaryrefslogtreecommitdiffstats
path: root/Doc/library/packaging.pypi.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/library/packaging.pypi.rst')
-rw-r--r--Doc/library/packaging.pypi.rst74
1 files changed, 74 insertions, 0 deletions
diff --git a/Doc/library/packaging.pypi.rst b/Doc/library/packaging.pypi.rst
new file mode 100644
index 0000000..14602ce
--- /dev/null
+++ b/Doc/library/packaging.pypi.rst
@@ -0,0 +1,74 @@
+:mod:`packaging.pypi` --- Interface to projects indexes
+=======================================================
+
+.. module:: packaging.pypi
+ :synopsis: Low-level and high-level APIs to query projects indexes.
+
+
+Packaging queries PyPI to get information about projects or download them. The
+low-level facilities used internally are also part of the public API designed to
+be used by other tools.
+
+The :mod:`packaging.pypi` package provides those facilities, which can be
+used to access information about Python projects registered at indexes, the
+main one being PyPI, located ad http://pypi.python.org/.
+
+There is two ways to retrieve data from these indexes: a screen-scraping
+interface called the "simple API", and XML-RPC. The first one uses HTML pages
+located under http://pypi.python.org/simple/, the second one makes XML-RPC
+requests to http://pypi.python.org/pypi/. All functions and classes also work
+with other indexes such as mirrors, which typically implement only the simple
+interface.
+
+Packaging provides a class that wraps both APIs to provide full query and
+download functionality: :class:`packaging.pypi.client.ClientWrapper`. If you
+want more control, you can use the underlying classes
+:class:`packaging.pypi.simple.Crawler` and :class:`packaging.pypi.xmlrpc.Client`
+to connect to one specific interface.
+
+
+:mod:`packaging.pypi.client` --- High-level query API
+=====================================================
+
+.. module:: packaging.pypi.client
+ :synopsis: Wrapper around :mod;`packaging.pypi.xmlrpc` and
+ :mod:`packaging.pypi.simple` to query indexes.
+
+
+This module provides a high-level API to query indexes and search
+for releases and distributions. The aim of this module is to choose the best
+way to query the API automatically, either using XML-RPC or the simple index,
+with a preference toward the latter.
+
+.. class:: ClientWrapper
+
+ Instances of this class will use the simple interface or XML-RPC requests to
+ query indexes and return :class:`packaging.pypi.dist.ReleaseInfo` and
+ :class:`packaging.pypi.dist.ReleasesList` objects.
+
+ .. method:: find_projects
+
+ .. method:: get_release
+
+ .. method:: get_releases
+
+
+:mod:`packaging.pypi.base` --- Base class for index crawlers
+============================================================
+
+.. module:: packaging.pypi.base
+ :synopsis: Base class used to implement crawlers.
+
+
+.. class:: BaseClient(prefer_final, prefer_source)
+
+ Base class containing common methods for the index crawlers or clients. One
+ method is currently defined:
+
+ .. method:: download_distribution(requirements, temp_path=None, \
+ prefer_source=None, prefer_final=None)
+
+ Download a distribution from the last release according to the
+ requirements. If *temp_path* is provided, download to this path,
+ otherwise, create a temporary directory for the download. If a release is
+ found, the full path to the downloaded file is returned.