Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rephrase the search XMLRPC disable error #12173

Merged
merged 7 commits into from
Nov 15, 2022
Merged

Rephrase the search XMLRPC disable error #12173

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
29541c7
Rephrase the search XMLRPC disable error
pradyunsg Sep 2, 2022
bda7549
Rephrase the sentence as suggested in reviews
pradyunsg Oct 18, 2022
4ed051a
Merge branch 'main' into rephrase-xmlrpc
ewdurbin Nov 15, 2022
657b7a0
remove xmlrpc search implementation altogether
ewdurbin Nov 15, 2022
d973b5f
update documentation, include references regarding deprecations
ewdurbin Nov 15, 2022
a2dc6f1
Merge branch 'main' into rephrase-xmlrpc
ewdurbin Nov 15, 2022
14e5673
Merge branch 'main' into rephrase-xmlrpc
ewdurbin Nov 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
325 changes: 188 additions & 137 deletions docs/api-reference/xml-rpc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
PyPI's XML-RPC methods
======================

.. note::
.. warning::
The XML-RPC API will be deprecated in the future. Use of this API is not
recommended, and existing consumers of the API should migrate to the RSS
and/or JSON APIs instead.
Expand Down Expand Up @@ -41,166 +41,217 @@ Example usage (Python 3)::

.. _changes-to-legacy-api:

Changes to Legacy API
Changes to XMLRPC API
---------------------

``package_releases`` As Warehouse does not support the concept of hidden
releases, the `show_hidden` flag now controls whether the latest version or all
versions are returned.
- ``search`` Permanently deprecated and disabled due to excessive traffic
driven by unidentified traffic, presumably automated. `See historical
incident <https://status.python.org/incidents/grk0k7sz6zkp>`_.

``release_data`` The `stable_version` flag is always an empty string. It was
never fully supported anyway.
- ``package_releases`` As Warehouse does not support the concept of hidden
releases, the `show_hidden` flag now controls whether the latest version or
all versions are returned.

``release_downloads`` and ``top_packages`` No longer supported. Use
`Google BigQuery
<https://mail.python.org/pipermail/distutils-sig/2016-May/028986.html>`_
instead (`guidance
<https://packaging.python.org/guides/analyzing-pypi-package-downloads/>`_,
`tips <https://langui.sh/2016/12/09/data-driven-decisions/>`_).
- ``release_data`` The `stable_version` flag is always an empty string. It was
never fully supported anyway.

Package querying
----------------
- ``release_downloads`` and ``top_packages`` No longer supported. Use
:doc:`Google BigQuery <bigquery-datasets>` instead (`guidance
<https://packaging.python.org/guides/analyzing-pypi-package-downloads/>`_,
`tips <https://langui.sh/2016/12/09/data-driven-decisions/>`_).

``list_packages()``
Retrieve a list of the package names registered with the package index.
Returns a list of name strings.

``package_releases(package_name, show_hidden=False)``
Retrieve a list of the releases registered for the given `package_name`,
ordered by version.
.. _changelog-since:

If `show_hidden` is `False` (the default), only the latest version is
returned. Otherwise, all versions are returned.
Mirroring Support
-----------------

``package_roles(package_name)``
Retrieve a list of `[role, user]` for a given `package_name`.
Role is either `Maintainer` or `Owner`.
.. note::
XML-RPC methods for mirroring support are currently the only methods we
consider fully supported, until an improved mechanism for mirroring is
implemented. Users of these methods should **certainly** subscribe to the
pypi-announce_ mailing list to ensure they are aware of changes or
deprecations related to these methods.

``user_packages(user)``
Retrieve a list of `[role, package_name]` for a given `user`.
Role is either `Maintainer` or `Owner`.
``changelog(since, with_ids=False)``
++++++++++++++++++++++++++++++++++++

``release_urls(package_name, release_version)``
Retrieve a list of download URLs for the given `release_version`.
Returns a list of dicts with the following keys:

* filename
* packagetype ('sdist', 'bdist_wheel', etc)
* python_version (required version, or 'source', or 'any')
* size (an ``int``)
* md5_digest
* digests (a dict with two keys, "md5" and "sha256")
* has_sig (a boolean)
* upload_time_iso_8601 (a ``DateTime`` object)
* comment_text
* downloads (always says "-1")
* url
Retrieve a list of `[name, version, timestamp, action]`, or `[name,
version, timestamp, action, id]` if `with_ids=True`, since the given
`since`. All `since` timestamps are UTC values. The argument is a
UTC integer seconds since the epoch (e.g., the ``timestamp`` method
to a ``datetime.datetime`` object).

``release_data(package_name, release_version)``
Retrieve metadata describing a specific `release_version`.
Returns a dict with keys for:

* name
* version
* stable_version (always an empty string or None)
* bugtrack_url
* package_url
* release_url
* docs_url (URL of the packages.python.org docs if they've been supplied)
* home_page
* download_url
* project_url
* author
* author_email
* maintainer
* maintainer_email
* summary
* description (string, sometimes the entirety of a ``README``)
* license
* keywords
* platform
* classifiers (list of classifier strings)
* requires
* requires_dist
* provides
* provides_dist
* obsoletes
* obsoletes_dist
* requires_python
* requires_external
* _pypi_ordering
* _pypi_hidden
* downloads (``{'last_day': 0, 'last_week': 0, 'last_month': 0}``)

If the release does not exist, an empty dictionary is returned.
``changelog_last_serial()``
+++++++++++++++++++++++++++

``search(spec[, operator])``
Search the package database using the indicated search `spec`.

Returns at most 100 results.

The `spec` may include any of the keywords described in the above list
(except 'stable_version' and 'classifiers'), for example:
{'description': 'spam'} will search description fields. Within the spec, a
field's value can be a string or a list of strings (the values within the
list are combined with an OR), for example: {'name': ['foo', 'bar']}. Valid
keys for the spec dict are listed here. Invalid keys are ignored:

* name
* version
* author
* author_email
* maintainer
* maintainer_email
* home_page
* license
* summary
* description
* keywords
* platform
* download_url

Arguments for different fields are combined using either "and" (the default)
or "or". Example: `search({'name': 'foo', 'description': 'bar'}, 'or')`.
The results are returned as a list of dicts `{'name': package name,
'version': package release version, 'summary': package release summary}`
Retrieve the last event's serial id (an ``int``).

``changelog_since_serial(since_serial)``
++++++++++++++++++++++++++++++++++++++++

Retrieve a list of `(name, version, timestamp, action, serial)` since the
event identified by the given ``since_serial``. All timestamps are UTC
values.

``list_packages_with_serial()``
+++++++++++++++++++++++++++++++

Retrieve a dictionary mapping package names to the last serial for each
package.


Package querying
----------------

``package_roles(package_name)``
+++++++++++++++++++++++++++++++

Retrieve a list of `[role, user]` for a given `package_name`.
Role is either `Maintainer` or `Owner`.

``user_packages(user)``
+++++++++++++++++++++++

Retrieve a list of `[role, package_name]` for a given `user`.
Role is either `Maintainer` or `Owner`.

``browse(classifiers)``
Retrieve a list of `[name, version]` of all releases classified with all of
the given classifiers. `classifiers` must be a list of Trove classifier
strings.
+++++++++++++++++++++++

Retrieve a list of `[name, version]` of all releases classified with all of
the given classifiers. `classifiers` must be a list of Trove classifier
strings.

``updated_releases(since)``
Retrieve a list of package releases made since the given timestamp. The
releases will be listed in descending release date.
+++++++++++++++++++++++++++

Retrieve a list of package releases made since the given timestamp. The
releases will be listed in descending release date.

``changed_packages(since)``
Retrieve a list of package names where those packages have been changed
since the given timestamp. The packages will be listed in descending date
of most recent change.
+++++++++++++++++++++++++++

.. _changelog-since:
Retrieve a list of package names where those packages have been changed
since the given timestamp. The packages will be listed in descending date
of most recent change.

Mirroring Support
-----------------

``changelog(since, with_ids=False)``
Retrieve a list of `[name, version, timestamp, action]`, or `[name,
version, timestamp, action, id]` if `with_ids=True`, since the given
`since`. All `since` timestamps are UTC values. The argument is a
UTC integer seconds since the epoch (e.g., the ``timestamp`` method
to a ``datetime.datetime`` object).
``list_packages()``
+++++++++++++++++++

``changelog_last_serial()``
Retrieve the last event's serial id (an ``int``).
.. warning::
Migrate to using the :doc:`Simple API <legacy>`.

``changelog_since_serial(since_serial)``
Retrieve a list of `(name, version, timestamp, action, serial)` since the
event identified by the given ``since_serial``. All timestamps are UTC
values.
Retrieve a list of the package names registered with the package index.
Returns a list of name strings.

``list_packages_with_serial()``
Retrieve a dictionary mapping package names to the last serial for each
package.
``package_releases(package_name, show_hidden=False)``
+++++++++++++++++++++++++++++++++++++++++++++++++++++

.. warning::
Migrate to using the :doc:`json`.

Retrieve a list of the releases registered for the given `package_name`,
ordered by version.

If `show_hidden` is `False` (the default), only the latest version is
returned. Otherwise, all versions are returned.

``release_urls(package_name, release_version)``
+++++++++++++++++++++++++++++++++++++++++++++++

.. warning::
Migrate to using the :doc:`json`.

Retrieve a list of download URLs for the given `release_version`.
Returns a list of dicts with the following keys:

* filename
* packagetype ('sdist', 'bdist_wheel', etc)
* python_version (required version, or 'source', or 'any')
* size (an ``int``)
* md5_digest
* digests (a dict with two keys, "md5" and "sha256")
* has_sig (a boolean)
* upload_time_iso_8601 (a ``DateTime`` object)
* comment_text
* downloads (always says "-1")
* url

``release_data(package_name, release_version)``
+++++++++++++++++++++++++++++++++++++++++++++++

.. warning::
Migrate to using the :doc:`json`.

Retrieve metadata describing a specific `release_version`.
Returns a dict with keys for:

* name
* version
* stable_version (always an empty string or None)
* bugtrack_url
* package_url
* release_url
* docs_url (URL of the packages.python.org docs if they've been supplied)
* home_page
* download_url
* project_url
* author
* author_email
* maintainer
* maintainer_email
* summary
* description (string, sometimes the entirety of a ``README``)
* license
* keywords
* platform
* classifiers (list of classifier strings)
* requires
* requires_dist
* provides
* provides_dist
* obsoletes
* obsoletes_dist
* requires_python
* requires_external
* _pypi_ordering
* _pypi_hidden
* downloads (``{'last_day': 0, 'last_week': 0, 'last_month': 0}``)

If the release does not exist, an empty dictionary is returned.


Deprecated Methods
------------------

.. warning::
The following methods are permanently deprecated and will return a
`RuntimeError`

``package_data(package_name, version)``
+++++++++++++++++++++++++++++++++++++++

Deprecated in favor of ``release_data``, :doc:`json` should be used.

``package_urls(package_name, version)``
+++++++++++++++++++++++++++++++++++++++

Deprecated in favor of ``release_urls``, :doc:`json` should be used.

``top_packages(num=None)``
++++++++++++++++++++++++++

Use :doc:`Google BigQuery <bigquery-datasets>`
instead (`guidance <https://packaging.python.org/guides/analyzing-pypi-package-downloads/>`_,
`tips <https://langui.sh/2016/12/09/data-driven-decisions/>`_).

``search(spec[, operator])``
++++++++++++++++++++++++++++

Permanently deprecated and disabled due to excessive traffic
driven by unidentified traffic, presumably automated. `See historical incident
<https://status.python.org/incidents/grk0k7sz6zkp>`_.

.. _pypi-announce: https://mail.python.org/mailman3/lists/pypi-announce.python.org/
Loading