Document APIs

docs/api-reference/feeds.rst

@@ -0,0 +1,21 @@
+Feeds
+=====
+
+PyPI offers two RSS feeds, the `Newest Packages Feed`_ and the `Latest Updates
+Feed`_.
+
+
+Newest Packages Feed
+--------------------
+
+Available at https://pypi.org/rss/packages.xml, this feed provides the latest
+newly created projects on PyPI, including the package name, description and a
+link to the project page.
+
+
+Latest Updates Feed
+-------------------
+
+Available at https://pypi.org/rss/updates.xml, this feed provides the latest
+newly created releases for individual projects on PyPI, including the project
+name and description, release version, and a link to the release page.

docs/api-reference/index.rst

@@ -4,5 +4,7 @@ API Reference
 .. toctree::
     :maxdepth: 1
 
-    xml-rpc
+    feeds
+    json
     legacy
+    xml-rpc

docs/api-reference/json.rst

@@ -0,0 +1,124 @@
+JSON API
+========
+
+PyPI offers two JSON endpoints.
+
+
+.. http:get:: /pypi/<project_name>/json
+
+    Returns metadata (info) about an individual project at the latest version,
+    a list of all releases for that project, and project URLs. Releases include
+    the release name, URL, and MD5 and SHA256 hash digests, and are keyed by
+    the release version string.
+
+    **Example Request**:
+
+    .. code:: http
+
+        GET /pypi/pip/json HTTP/1.1
+        Host: pypi.org
+        Accept: application/json
+
+    **Example response**:
+
+    .. code:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json; charset="UTF-8"
+
+        {
+            "info": {
+                "author": "The pip developers",
+                "author_email": "[email protected]",
+                "bugtrack_url": "",
+                "classifiers": [
+                    "Development Status :: 5 - Production/Stable",
+                    "Intended Audience :: Developers",
+                    "License :: OSI Approved :: MIT License",
+                    "Programming Language :: Python :: 2",
+                    "Programming Language :: Python :: 2.6",
+                    "Programming Language :: Python :: 2.7",
+                    "Programming Language :: Python :: 3",
+                    "Programming Language :: Python :: 3.3",
+                    "Programming Language :: Python :: 3.4",
+                    "Programming Language :: Python :: 3.5",
+                    "Programming Language :: Python :: Implementation :: PyPy",
+                    "Topic :: Software Development :: Build Tools"
+                ],
+                "description": "...",
+                "docs_url": null,
+                "download_url": "",
+                "downloads": {
+                    "last_day": 0,
+                    "last_month": 0,
+                    "last_week": 0
+                },
+                "home_page": "https://pip.pypa.io/",
+                "keywords": "easy_install distutils setuptools egg virtualenv",
+                "license": "MIT",
+                "maintainer": "",
+                "maintainer_email": "",
+                "name": "pip",
+                "platform": "",
+                "project_url": "https://pypi.org/project/pip/",
+                "release_url": "https://pypi.org/project/pip/9.0.1/",
+                "requires_dist": [
+                    "mock; extra == 'testing'",
+                    "pretend; extra == 'testing'",
+                    "pytest; extra == 'testing'",
+                    "scripttest (>=1.3); extra == 'testing'",
+                    "virtualenv (>=1.10); extra == 'testing'"
+                ],
+                "requires_python": ">=2.6,!=3.0.*,!=3.1.*,!=3.2.*",
+                "summary": "The PyPA recommended tool for installing Python packages.",
+                "version": "9.0.1"
+            },
+            "releases": {
+                ...,
+                "9.0.1": [
+                    {
+                        "comment_text": "",
+                        "digests": {
+                            "md5": "297dbd16ef53bcef0447d245815f5144",
+                            "sha256": "690b762c0a8460c303c089d5d0be034fb15a5ea2b75bdf565f40421f542fefb0"
+                        },
+                        "downloads": -1,
+                        "filename": "pip-9.0.1-py2.py3-none-any.whl",
+                        "has_sig": true,
+                        "md5_digest": "297dbd16ef53bcef0447d245815f5144",
+                        "packagetype": "bdist_wheel",
+                        "python_version": "py2.py3",
+                        "size": 1254803,
+                        "upload_time": "2016-11-06T18:51:46",
+                        "url": "https://files.pythonhosted.org/packages/b6/ac/7015eb97dc749283ffdec1c3a88ddb8ae03b8fad0f0e611408f196358da3/pip-9.0.1-py2.py3-none-any.whl"
+                    },
+                    {
+                        "comment_text": "",
+                        "digests": {
+                            "md5": "35f01da33009719497f01a4ba69d63c9",
+                            "sha256": "09f243e1a7b461f654c26a725fa373211bb7ff17a9300058b205c61658ca940d"
+                        },
+                        "downloads": -1,
+                        "filename": "pip-9.0.1.tar.gz",
+                        "has_sig": true,
+                        "md5_digest": "35f01da33009719497f01a4ba69d63c9",
+                        "packagetype": "sdist",
+                        "python_version": "source",
+                        "size": 1197370,
+                        "upload_time": "2016-11-06T18:51:51",
+                        "url": "https://files.pythonhosted.org/packages/11/b6/abcb525026a4be042b486df43905d6893fb04f05aac21c32c638e939e447/pip-9.0.1.tar.gz"
+                    }
+                ]
+            },
+            "urls": {
+                ...
+            }
+        }
+
+    :statuscode 200: no error
+
+
+.. http:get:: /pypi/<project_name>/<version>/json
+
+    Returns metadata about an individual release at a specific version,
+    otherwise identical to ``/pypi/<project_name>/json``.

docs/api-reference/legacy.rst

@@ -1,10 +1,16 @@
 Legacy API
 ==========
 
+The "Legacy API" provides feature parity with `pypi-legacy`_, hence the term
+"legacy".
+
 
 Simple Project API
 ------------------
 
+The Simple API implements the HTML-based package index API as specified in `PEP
+503`_.
+
 .. http:get:: /simple/
 
     All of the projects that have been registered. All responses *MUST* have
@@ -16,7 +22,7 @@ Simple Project API
     .. code:: http
 
         GET /simple/ HTTP/1.1
-        Host: pypi.python.org
+        Host: pypi.org
         Accept: text/html
 
     **Example response**:
@@ -83,7 +89,7 @@ Simple Project API
     .. code:: http
 
         GET /simple/warehouse/ HTTP/1.1
-        Host: pypi.python.org
+        Host: pypi.org
         Accept: text/html
 
     **Example response**:
@@ -112,3 +118,7 @@ Simple Project API
     :resheader X-PyPI-Last-Serial: The most recent serial id number for the
                                    project.
     :statuscode 200: no error
+
+
+.. _`pypi-legacy`: https://pypi.python.org/
+.. _`PEP 503`: https://www.python.org/dev/peps/pep-0503/

docs/api-reference/xml-rpc.rst

@@ -6,7 +6,7 @@ Example usage::
 
   >>> import xmlrpclib
   >>> import pprint
-  >>> client = xmlrpclib.ServerProxy('https://pypi.python.org/pypi')
+  >>> client = xmlrpclib.ServerProxy('https://pypi.org/pypi')
   >>> client.package_releases('roundup')
   ['1.4.10']
   >>> pprint.pprint(client.release_urls('roundup', '1.4.10'))
@@ -19,7 +19,7 @@ Example usage::
     'python_version': 'source',
     'size': 876455,
     'upload_time': <DateTime '20060427T06:22:35' at 912fecc>,
-    'url': 'https://pypi.python.org/packages/source/r/roundup/roundup-1.1.2.tar.gz'},
+    'url': 'https://pypi.org/packages/source/r/roundup/roundup-1.1.2.tar.gz'},
    {'comment_text': '',
     'downloads': 2067,
     'filename': 'roundup-1.1.2.win32.exe',
@@ -29,7 +29,7 @@ Example usage::
     'python_version': 'any',
     'size': 614270,
     'upload_time': <DateTime '20060427T06:26:04' at 912fdec>,
-    'url': 'https://pypi.python.org/packages/any/r/roundup/roundup-1.1.2.win32.exe'}]
+    'url': 'https://pypi.org/packages/any/r/roundup/roundup-1.1.2.win32.exe'}]
 
 Changes to Legacy API
 ---------------------

docs/development/getting-started.rst

@@ -138,7 +138,7 @@ Next, you will:
 * create a new Postgres database,
 * install example data to the Postgres database,
 * run migrations, and
-* load some example data from `Test PyPI <https://testpypi.python.org/>`_
+* load some example data from `Test PyPI`_
 
 In a second terminal, separate from the ``make serve`` command above, run:
 
@@ -205,9 +205,8 @@ The repository is exposed inside of the web container at
 ``/opt/warehouse/src/`` and Warehouse will automatically reload when it detects
 any changes made to the code.
 
-The example data located in ``dev/example.sql.xz`` is taken from
-`Test PyPI <https://testpypi.python.org/>`_ and has been sanitized to remove
-anything private.
+The example data located in ``dev/example.sql.xz`` is taken from `Test PyPI`_
+and has been sanitized to remove anything private.
 
 
 Running your developer environment after initial setup
@@ -390,10 +389,11 @@ command will give the following error message:
   Makefile:53: recipe for target '.state/env/pyvenv.cfg' failed
   make: *** [.state/env/pyvenv.cfg] Error 127
 
-.. _`pip`: https://pypi.python.org/pypi/pip
-.. _`sphinx`: https://pypi.python.org/pypi/Sphinx
+.. _`pip`: https://pypi.org/project/pip
+.. _`sphinx`: https://pypi.org/project/Sphinx
 .. _`reStructured Text`: http://sphinx-doc.org/rest.html
 .. _`open issues that are labelled "good first issue"`: https://github.com/pypa/warehouse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
 .. _`GitHub`: https://github.com/pypa/warehouse
 .. _`on Freenode`: https://webchat.freenode.net/?channels=%23pypa-dev,pypa
 .. _`pypa-dev mailing list`: https://groups.google.com/forum/#!forum/pypa-dev
+.. _`Test PyPI`: https://test.pypi.org/

docs/development/reviewing-patches.rst

@@ -2,7 +2,10 @@ Reviewing and merging patches
 =============================
 
 Everyone is encouraged to review open pull requests. We only ask that you try
-and think carefully, ask questions and are `excellent to one another`_. When engaging in code review, please remember that you are bound by the `Code of Conduct`_. Code review is our opportunity to share knowledge, design ideas and make friends.
+and think carefully, ask questions and are `excellent to one another`_. When
+engaging in code review, please remember that you are bound by the `Code of
+Conduct`_. Code review is our opportunity to share knowledge, design ideas and
+make friends.
 
 When reviewing a patch try to keep each of these concepts in mind:
 
@@ -106,10 +109,10 @@ Testing with twine
 ------------------
 If you are testing Warehouse locally, you may want to use `twine`_ to try
 uploading a test package. First, checkout the branch you would like to test.
-Then, start up the development environment (as described in :ref:`getting-started`).
-Once you have the Warehouse site working on ``localhost:80``, you can upload a
-package to the version of Warehouse running in your development environment
-with Twine using the following command:
+Then, start up the development environment (as described in
+:ref:`getting-started`).  Once you have the Warehouse site working on
+``localhost:80``, you can upload a package to the version of Warehouse running
+in your development environment with Twine using the following command:
 
 .. code-block:: console
 
@@ -148,5 +151,3 @@ Merge requirements
 .. _`Code of Conduct`: https://www.pypa.io/en/latest/code-of-conduct/
 
 .. _`twine`: https://github.com/pypa/twine
-
-.. _`TestPyPI`: https://testpypi.python.org/

docs/development/submitting-patches.rst

@@ -169,4 +169,4 @@ feature branch at least once while you are working on it.
 .. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists
 .. _`Studies have shown`: https://smartbear.com/smartbear/media/pdfs/wp-cc-11-best-practices-of-peer-code-review.pdf
 .. _`doc8`: https://github.com/stackforge/doc8
-.. _`coverage.py`: https://pypi.python.org/pypi/coverage
+.. _`coverage.py`: https://pypi.org/project/coverage