115 lines
3.3 KiB
ReStructuredText
115 lines
3.3 KiB
ReStructuredText
|
: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.
|