Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 1 | :mod:`packaging.pypi.xmlrpc` --- Crawler using the PyPI XML-RPC interface |
| 2 | ========================================================================= |
| 3 | |
| 4 | .. module:: packaging.pypi.xmlrpc |
| 5 | :synopsis: Client using XML-RPC requests to fetch info and distributions. |
| 6 | |
| 7 | |
| 8 | Indexes can be queried using XML-RPC calls, and Packaging provides a simple |
| 9 | way to interface with XML-RPC. |
| 10 | |
| 11 | You should **use** XML-RPC when: |
| 12 | |
| 13 | * Searching the index for projects **on other fields than project |
| 14 | names**. For instance, you can search for projects based on the |
| 15 | author_email field. |
| 16 | * Searching all the versions that have existed for a project. |
| 17 | * you want to retrieve METADATAs information from releases or |
| 18 | distributions. |
| 19 | |
| 20 | |
| 21 | You should **avoid using** XML-RPC method calls when: |
| 22 | |
| 23 | * Retrieving the last version of a project |
| 24 | * Getting the projects with a specific name and version. |
| 25 | * The simple index can match your needs |
| 26 | |
| 27 | |
| 28 | When dealing with indexes, keep in mind that the index queries will always |
| 29 | return you :class:`packaging.pypi.dist.ReleaseInfo` and |
| 30 | :class:`packaging.pypi.dist.ReleasesList` objects. |
| 31 | |
| 32 | Some methods here share common APIs with the one you can find on |
| 33 | :class:`packaging.pypi.simple`, internally, :class:`packaging.pypi.client` |
| 34 | is inherited by :class:`Client` |
| 35 | |
| 36 | |
| 37 | API |
| 38 | --- |
| 39 | |
| 40 | .. class:: Client |
| 41 | |
| 42 | |
| 43 | Usage examples |
| 44 | -------------- |
| 45 | |
| 46 | Use case described here are use case that are not common to the other clients. |
| 47 | If you want to see all the methods, please refer to API or to usage examples |
| 48 | described in :class:`packaging.pypi.client.Client` |
| 49 | |
| 50 | |
| 51 | Finding releases |
| 52 | ^^^^^^^^^^^^^^^^ |
| 53 | |
| 54 | It's a common use case to search for "things" within the index. We can |
| 55 | basically search for projects by their name, which is the most used way for |
| 56 | users (eg. "give me the last version of the FooBar project"). |
| 57 | |
| 58 | This can be accomplished using the following syntax:: |
| 59 | |
| 60 | >>> client = xmlrpc.Client() |
| 61 | >>> client.get_release("Foobar (<= 1.3)) |
| 62 | <FooBar 1.2.1> |
| 63 | >>> client.get_releases("FooBar (<= 1.3)") |
| 64 | [FooBar 1.1, FooBar 1.1.1, FooBar 1.2, FooBar 1.2.1] |
| 65 | |
| 66 | |
| 67 | And we also can find for specific fields:: |
| 68 | |
| 69 | >>> client.search_projects(field=value) |
| 70 | |
| 71 | |
| 72 | You could specify the operator to use, default is "or":: |
| 73 | |
| 74 | >>> client.search_projects(field=value, operator="and") |
| 75 | |
| 76 | |
| 77 | The specific fields you can search are: |
| 78 | |
| 79 | * name |
| 80 | * version |
| 81 | * author |
| 82 | * author_email |
| 83 | * maintainer |
| 84 | * maintainer_email |
| 85 | * home_page |
| 86 | * license |
| 87 | * summary |
| 88 | * description |
| 89 | * keywords |
| 90 | * platform |
| 91 | * download_url |
| 92 | |
| 93 | |
| 94 | Getting metadata information |
| 95 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 96 | |
| 97 | XML-RPC is a prefered way to retrieve metadata information from indexes. |
| 98 | It's really simple to do so:: |
| 99 | |
| 100 | >>> client = xmlrpc.Client() |
| 101 | >>> client.get_metadata("FooBar", "1.1") |
| 102 | <ReleaseInfo FooBar 1.1> |
| 103 | |
| 104 | |
| 105 | Assuming we already have a :class:`packaging.pypi.ReleaseInfo` object defined, |
| 106 | it's possible to pass it to the xmlrpc client to retrieve and complete its |
| 107 | metadata:: |
| 108 | |
| 109 | >>> foobar11 = ReleaseInfo("FooBar", "1.1") |
| 110 | >>> client = xmlrpc.Client() |
| 111 | >>> returned_release = client.get_metadata(release=foobar11) |
| 112 | >>> returned_release |
| 113 | <ReleaseInfo FooBar 1.1> |
| 114 | |
| 115 | |
| 116 | Get all the releases of a project |
| 117 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 118 | |
| 119 | To retrieve all the releases for a project, you can build them using |
| 120 | `get_releases`:: |
| 121 | |
| 122 | >>> client = xmlrpc.Client() |
| 123 | >>> client.get_releases("FooBar") |
| 124 | [<ReleaseInfo FooBar 0.9>, <ReleaseInfo FooBar 1.0>, <ReleaseInfo 1.1>] |
| 125 | |
| 126 | |
| 127 | Get information about distributions |
| 128 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 129 | |
| 130 | Indexes have information about projects, releases **and** distributions. |
| 131 | If you're not familiar with those, please refer to the documentation of |
| 132 | :mod:`packaging.pypi.dist`. |
| 133 | |
| 134 | It's possible to retrieve information about distributions, e.g "what are the |
| 135 | existing distributions for this release ? How to retrieve them ?":: |
| 136 | |
| 137 | >>> client = xmlrpc.Client() |
| 138 | >>> release = client.get_distributions("FooBar", "1.1") |
| 139 | >>> release.dists |
| 140 | {'sdist': <FooBar 1.1 sdist>, 'bdist': <FooBar 1.1 bdist>} |
| 141 | |
| 142 | As you see, this does not return a list of distributions, but a release, |
| 143 | because a release can be used like a list of distributions. |