From 75e2b0a98ddd64a91fc7add4f556cbe840c0421d Mon Sep 17 00:00:00 2001 From: Dustin Ingram Date: Mon, 19 Feb 2018 16:15:27 -0600 Subject: [PATCH 1/5] Explain Simple API and 'legacy' --- docs/api-reference/legacy.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/api-reference/legacy.rst b/docs/api-reference/legacy.rst index 9aa17855520a..76b1a9d1c43c 100644 --- a/docs/api-reference/legacy.rst +++ b/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 @@ -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/ From 7b6f191caee78d46605027a64f51d0ecf72562b9 Mon Sep 17 00:00:00 2001 From: Dustin Ingram Date: Mon, 19 Feb 2018 16:15:57 -0600 Subject: [PATCH 2/5] Document RSS feeds --- docs/api-reference/feeds.rst | 21 +++++++++++++++++++++ docs/api-reference/index.rst | 3 ++- 2 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 docs/api-reference/feeds.rst diff --git a/docs/api-reference/feeds.rst b/docs/api-reference/feeds.rst new file mode 100644 index 000000000000..d325640b243f --- /dev/null +++ b/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. diff --git a/docs/api-reference/index.rst b/docs/api-reference/index.rst index ed8932ed48cc..e0a286f06095 100644 --- a/docs/api-reference/index.rst +++ b/docs/api-reference/index.rst @@ -4,5 +4,6 @@ API Reference .. toctree:: :maxdepth: 1 - xml-rpc + feeds legacy + xml-rpc From b206921eafb4acdede8355c1e524d2fe3133b412 Mon Sep 17 00:00:00 2001 From: Dustin Ingram Date: Mon, 19 Feb 2018 16:16:12 -0600 Subject: [PATCH 3/5] Document JSON API --- docs/api-reference/index.rst | 1 + docs/api-reference/json.rst | 123 +++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+) create mode 100644 docs/api-reference/json.rst diff --git a/docs/api-reference/index.rst b/docs/api-reference/index.rst index e0a286f06095..491b370874b9 100644 --- a/docs/api-reference/index.rst +++ b/docs/api-reference/index.rst @@ -5,5 +5,6 @@ API Reference :maxdepth: 1 feeds + json legacy xml-rpc diff --git a/docs/api-reference/json.rst b/docs/api-reference/json.rst new file mode 100644 index 000000000000..1105827553eb --- /dev/null +++ b/docs/api-reference/json.rst @@ -0,0 +1,123 @@ +JSON API +======== + +PyPI offers two JSON endpoints. + + +.. http:get:: /pypi//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. + + **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": "python-virtualenv@groups.google.com", + "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///json + + Returns metadata about an individual release at a specific version, + otherwise identical to ``/pypi//json``. From 29b690babd1c471bfaa2d5960a5d6cc9ea8c8bad Mon Sep 17 00:00:00 2001 From: Dustin Ingram Date: Mon, 19 Feb 2018 21:43:51 -0600 Subject: [PATCH 4/5] Point to pypi.org where applicable --- docs/api-reference/legacy.rst | 4 ++-- docs/api-reference/xml-rpc.rst | 6 +++--- docs/development/getting-started.rst | 12 ++++++------ docs/development/reviewing-patches.rst | 15 ++++++++------- docs/development/submitting-patches.rst | 2 +- 5 files changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/api-reference/legacy.rst b/docs/api-reference/legacy.rst index 76b1a9d1c43c..bfb16c04c5d1 100644 --- a/docs/api-reference/legacy.rst +++ b/docs/api-reference/legacy.rst @@ -22,7 +22,7 @@ The Simple API implements the HTML-based package index API as specified in `PEP .. code:: http GET /simple/ HTTP/1.1 - Host: pypi.python.org + Host: pypi.org Accept: text/html **Example response**: @@ -89,7 +89,7 @@ The Simple API implements the HTML-based package index API as specified in `PEP .. code:: http GET /simple/warehouse/ HTTP/1.1 - Host: pypi.python.org + Host: pypi.org Accept: text/html **Example response**: diff --git a/docs/api-reference/xml-rpc.rst b/docs/api-reference/xml-rpc.rst index 7e3c689c5248..168e74cd43ed 100644 --- a/docs/api-reference/xml-rpc.rst +++ b/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': , - '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': , - '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 --------------------- diff --git a/docs/development/getting-started.rst b/docs/development/getting-started.rst index 90bc14b513d0..c3cb40377bad 100644 --- a/docs/development/getting-started.rst +++ b/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 `_ +* 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 `_ 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/ diff --git a/docs/development/reviewing-patches.rst b/docs/development/reviewing-patches.rst index 277cc1b1d26f..65cfcdbd2903 100644 --- a/docs/development/reviewing-patches.rst +++ b/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/ diff --git a/docs/development/submitting-patches.rst b/docs/development/submitting-patches.rst index 397bd6aed0df..f505d950219c 100644 --- a/docs/development/submitting-patches.rst +++ b/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 From 4dc1973d6507a665cc8f8ce8daa93c7a2b05f7d6 Mon Sep 17 00:00:00 2001 From: Dustin Ingram Date: Tue, 20 Feb 2018 09:37:52 -0600 Subject: [PATCH 5/5] Address feedback --- docs/api-reference/json.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/api-reference/json.rst b/docs/api-reference/json.rst index 1105827553eb..5bed0dc64f70 100644 --- a/docs/api-reference/json.rst +++ b/docs/api-reference/json.rst @@ -7,8 +7,9 @@ PyPI offers two JSON endpoints. .. http:get:: /pypi//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. + 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**: