Rephrase the search XMLRPC disable error (#12173)

* Rephrase the search XMLRPC disable error

This reflects the current state of the service more accurately and also
serves as a friendlier error message for "pip search" runs.

* Rephrase the sentence as suggested in reviews

* remove xmlrpc search implementation altogether

* update documentation, include references regarding deprecations

Co-authored-by: Ee Durbin <[email protected]>

Author: pradyunsg

docs/api-reference/xml-rpc.rst

@@ -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.
@@ -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/