4.2. Representation of informations coming from indexes

Informations coming from indexes are represented by the classes present in the distutils2.index.dist module.

4.2.1. API

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).

4.2.1.1. ReleaseInfo

Each release have a project name, a project version and contain project metadata. In addition, releases contain the distributions too.

These informations are stored in distutils2.index.dist.ReleaseInfo objects.

4.2.1.2. DistInfo

distutils2.index.dist.DistInfo is a simple class that contains informations related to distributions. It’s mainly about the URLs where those distributions can be found.

4.2.1.3. ReleasesList

The dist module also provides another class, to work with lists of distutils2.index.dist.ReleaseInfo classes. It allow to filter and order results.

4.2.2. Exemple usages

4.2.2.1. Build a list of releases, and order them

Assuming we have a list of releases:

>>> from distutils2.index.dist import ReleaseList, 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']

4.2.2.2. Add distribution related informations to releases

It’s easy to add distribution informatons to releases:

>>> from distutils2.index.dist import ReleaseList, 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}

4.2.2.3. Getting attributes from the dist objects

To abstract a maximum the way of querying informations to the indexes, attributes and releases informations can be retrieved directly from the objects returned by the indexes.

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>

Like this, it’s possible to retrieve project’s releases (fetch_releases), releases metadata (fetch_metadata and releases distributions (fetch_distributions informations).

Internally, this is possible because while retrieving for the first time informations about projects, releases or distributions, a reference to the client used is stored in the objects (can be accessed using the object _index attribute.