Implement 'latest' API and release-view endpoints

docs/api-reference/integration-guide.rst

@@ -36,6 +36,27 @@ Here are some tips.
   ``https://pypi.org/pypi/{name}`` (with or without a trailing slash)
   redirects to ``https://pypi.org/project/{name}/``.
 
+* The PyPI page for a specific version of project ``{name}`` can be
+  reached via ``https://pypi.org/project/{name}/{version}/``.
+
+    * E.g., for Django v2.0, browse to
+      ``https://pypi.org/project/Django/2.0``.
+
+    * Special redirects for various flavors of the latest available
+      version of ``{name}`` have been implemented, with version selection
+      semantics identical to the analogous
+      :ref:`JSON endpoints <api_json_latest>`:
+
+        * ``https://pypi.org/project/{name}/latest/``:
+          Latest non-prerelease version if any exists;
+          else, latest pre-release version.
+
+        * ``https://pypi.org/project/{name}/latest-stable/``:
+          Latest non-prerelease version.
+
+        * ``https://pypi.org/project/{name}/latest-unstable/``
+          Latest version regardless of pre-release status.
+
 * Shorter URL: ``https://pypi.org/p/{name}/`` will redirect to
   ``https://pypi.org/project/{name}/``.
 

docs/api-reference/json.rst

@@ -264,3 +264,35 @@ Release
         }
 
     :statuscode 200: no error
+
+
+    .. _api_json_latest:
+
+    There are three special ``<version>`` names that can be passed for any
+    ``<project_name>``, to obtain a `Release`_ JSON response for various flavors
+    of the latest available release for that project:
+
+    * ``/pypi/<project_name>/latest/json``
+
+        Redirects to the latest non-prerelease version of ``<project_name>``,
+        if any exists. If none does exist, redirects instead to the latest
+        pre-release version of ``<project_name>``.
+
+        As of Oct 2020, this behavior is identical to that of the
+        `Project`_ endpoint, and should return an identical JSON response.
+
+    * ``/pypi/<project_name>/latest-stable/json``
+
+        Redirects to the latest non-prerelease version of ``<project_name>``.
+        If no non-prerelease versions exist, returns |http404|_.
+
+    * ``/pypi/<project_name>/latest-unstable/json``
+
+        Redirects to a JSON query for the latest version of ``<project_name>``,
+        regardless of pre-release status.
+
+
+
+.. |http404| replace:: ``404 Not Found``
+
+.. _http404: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5

tests/conftest.py

@@ -14,7 +14,7 @@
 import os.path
 import xmlrpc.client
 
-from collections import defaultdict
+from collections import defaultdict, namedtuple
 from contextlib import contextmanager
 from unittest import mock
 
@@ -36,6 +36,7 @@
 from warehouse.metrics import IMetricsService
 
 from .common.db import Session
+from .common.db.packaging import ProjectFactory, ReleaseFactory
 
 
 def pytest_collection_modifyitems(items):
@@ -337,3 +338,49 @@ def monkeypatch_session():
     m = MonkeyPatch()
     yield m
     m.undo()
+
+
+# Standardized dummy projects for testing version-search
+# behavior under different stable/prerelease circumstances.
+# In particular, created to support the 'latest' endpoints of
+# https://github.com/pypa/warehouse/pull/8615
+
+ProjectData = namedtuple("ProjectData", ["project", "latest_stable", "latest_pre"])
+
+
+@pytest.fixture(scope="function")
+def project_no_pre():
+    project = ProjectFactory.create()
+
+    ReleaseFactory.create(project=project, version="1.0")
+    ReleaseFactory.create(project=project, version="2.0")
+    latest_stable = ReleaseFactory.create(project=project, version="3.0")
+
+    return ProjectData(project=project, latest_stable=latest_stable, latest_pre=None)
+
+
+@pytest.fixture(scope="function")
+def project_with_pre():
+    project = ProjectFactory.create()
+
+    ReleaseFactory.create(project=project, version="1.0")
+    ReleaseFactory.create(project=project, version="2.0")
+
+    latest_stable = ReleaseFactory.create(project=project, version="3.0")
+    latest_pre = ReleaseFactory.create(project=project, version="4.0.dev0")
+
+    return ProjectData(
+        project=project, latest_stable=latest_stable, latest_pre=latest_pre
+    )
+
+
+@pytest.fixture(scope="function")
+def project_only_pre():
+    project = ProjectFactory.create()
+
+    ReleaseFactory.create(project=project, version="1.0.dev0")
+    ReleaseFactory.create(project=project, version="2.0.dev0")
+
+    latest_pre = ReleaseFactory.create(project=project, version="3.0.dev0")
+
+    return ProjectData(project=project, latest_stable=None, latest_pre=latest_pre)

tests/unit/legacy/api/test_json.py

@@ -13,6 +13,7 @@
 from collections import OrderedDict
 
 import pretend
+import pytest
 
 from pyramid.httpexceptions import HTTPMovedPermanently, HTTPNotFound
 
@@ -66,57 +67,41 @@ def test_missing_release(self, db_request):
         assert isinstance(resp, HTTPNotFound)
         _assert_has_cors_headers(resp.headers)
 
-    def test_calls_release_detail(self, monkeypatch, db_request):
-        project = ProjectFactory.create()
-
-        ReleaseFactory.create(project=project, version="1.0")
-        ReleaseFactory.create(project=project, version="2.0")
-
-        release = ReleaseFactory.create(project=project, version="3.0")
-
+    def test_calls_release_detail(self, monkeypatch, db_request, project_no_pre):
         response = pretend.stub()
         json_release = pretend.call_recorder(lambda ctx, request: response)
         monkeypatch.setattr(json, "json_release", json_release)
 
-        resp = json.json_project(project, db_request)
+        resp = json.json_project(project_no_pre.project, db_request)
 
         assert resp is response
-        assert json_release.calls == [pretend.call(release, db_request)]
-
-    def test_with_prereleases(self, monkeypatch, db_request):
-        project = ProjectFactory.create()
-
-        ReleaseFactory.create(project=project, version="1.0")
-        ReleaseFactory.create(project=project, version="2.0")
-        ReleaseFactory.create(project=project, version="4.0.dev0")
-
-        release = ReleaseFactory.create(project=project, version="3.0")
+        assert json_release.calls == [
+            pretend.call(project_no_pre.latest_stable, db_request)
+        ]
 
+    def test_with_prereleases(self, monkeypatch, db_request, project_with_pre):
         response = pretend.stub()
         json_release = pretend.call_recorder(lambda ctx, request: response)
         monkeypatch.setattr(json, "json_release", json_release)
 
-        resp = json.json_project(project, db_request)
+        resp = json.json_project(project_with_pre.project, db_request)
 
         assert resp is response
-        assert json_release.calls == [pretend.call(release, db_request)]
-
-    def test_only_prereleases(self, monkeypatch, db_request):
-        project = ProjectFactory.create()
-
-        ReleaseFactory.create(project=project, version="1.0.dev0")
-        ReleaseFactory.create(project=project, version="2.0.dev0")
-
-        release = ReleaseFactory.create(project=project, version="3.0.dev0")
+        assert json_release.calls == [
+            pretend.call(project_with_pre.latest_stable, db_request)
+        ]
 
+    def test_only_prereleases(self, monkeypatch, db_request, project_only_pre):
         response = pretend.stub()
         json_release = pretend.call_recorder(lambda ctx, request: response)
         monkeypatch.setattr(json, "json_release", json_release)
 
-        resp = json.json_project(project, db_request)
+        resp = json.json_project(project_only_pre.project, db_request)
 
         assert resp is response
-        assert json_release.calls == [pretend.call(release, db_request)]
+        assert json_release.calls == [
+            pretend.call(project_only_pre.latest_pre, db_request)
+        ]
 
     def test_all_releases_yanked(self, monkeypatch, db_request):
         """
@@ -206,6 +191,141 @@ def test_normalizing_redirects(self, db_request):
         assert resp.headers["Location"] == "/project/the-redirect"
 
 
+class TestJSONLatestReleases:
+    @pytest.fixture
+    def check_json_release(self, monkeypatch):
+        response = pretend.stub()
+        json_release = pretend.call_recorder(lambda ctx, request: response)
+        monkeypatch.setattr(json, "json_release", json_release)
+
+        def check_function(db_request, project, release, endpoint):
+            resp = getattr(json, endpoint)(project, db_request)
+
+            assert resp is response
+            assert json_release.calls == [pretend.call(release, db_request)]
+
+        return check_function
+
+    def test_latest_no_pre(self, db_request, project_no_pre, check_json_release):
+        """Confirm 'latest' gives latest-stable for project with no pre-releases."""
+        check_json_release(
+            db_request,
+            project_no_pre.project,
+            project_no_pre.latest_stable,
+            "json_latest",
+        )
+
+    def test_latest_with_pre(self, db_request, project_with_pre, check_json_release):
+        """Confirm 'latest' gives latest-stable with both stable and pre-releases."""
+        check_json_release(
+            db_request,
+            project_with_pre.project,
+            project_with_pre.latest_stable,
+            "json_latest",
+        )
+
+    def test_latest_only_pre(self, db_request, project_only_pre, check_json_release):
+        """Confirm 'latest' gives latest-pre for project with only pre-releases."""
+        check_json_release(
+            db_request,
+            project_only_pre.project,
+            project_only_pre.latest_pre,
+            "json_latest",
+        )
+
+    def test_latest_stable_no_pre(self, db_request, project_no_pre, check_json_release):
+        """Confirm 'latest-stable' gives latest-stable with no pre-releases."""
+        check_json_release(
+            db_request,
+            project_no_pre.project,
+            project_no_pre.latest_stable,
+            "json_latest_stable",
+        )
+
+    def test_latest_stable_with_pre(
+        self, db_request, project_with_pre, check_json_release
+    ):
+        """Confirm 'latest-stable' gives latest-stable with no pre-releases."""
+        check_json_release(
+            db_request,
+            project_with_pre.project,
+            project_with_pre.latest_stable,
+            "json_latest_stable",
+        )
+
+    def test_latest_stable_only_pre(self, db_request, project_only_pre):
+        """Confirm 'latest-stable' fails for project with no pre-releases."""
+        db_request.route_path = pretend.call_recorder(
+            lambda *a, **kw: "/project/the-redirect"
+        )
+
+        resp = json.json_latest_stable(project_only_pre.project, db_request)
+        assert isinstance(resp, HTTPNotFound)
+
+    def test_latest_unstable_no_pre(
+        self, db_request, project_no_pre, check_json_release
+    ):
+        check_json_release(
+            db_request,
+            project_no_pre.project,
+            project_no_pre.latest_stable,
+            "json_latest_unstable",
+        )
+
+    def test_latest_unstable_with_pre(
+        self, db_request, project_with_pre, check_json_release
+    ):
+        check_json_release(
+            db_request,
+            project_with_pre.project,
+            project_with_pre.latest_pre,
+            "json_latest_unstable",
+        )
+
+    def test_latest_unstable_only_pre(
+        self, db_request, project_only_pre, check_json_release
+    ):
+        check_json_release(
+            db_request,
+            project_only_pre.project,
+            project_only_pre.latest_pre,
+            "json_latest_unstable",
+        )
+
+    @pytest.mark.parametrize(
+        "endpoint",
+        ["json_latest", "json_latest_stable", "json_latest_unstable"],
+    )
+    def test_missing_release(self, db_request, endpoint):
+        project = ProjectFactory.create()
+
+        resp = getattr(json, endpoint)(project, db_request)
+        assert isinstance(resp, HTTPNotFound)
+
+
+class TestJSONLatestSlash:
+    @pytest.mark.parametrize(
+        ("endpoint", "route"),
+        [
+            ("json_latest_slash", "legacy.api.json.latest"),
+            ("json_latest_stable_slash", "legacy.api.json.latest_stable"),
+            ("json_latest_unstable_slash", "legacy.api.json.latest_unstable"),
+        ],
+    )
+    def test_normalizing_redirects(self, db_request, endpoint, route):
+        project = ProjectFactory.create()
+
+        db_request.route_path = pretend.call_recorder(
+            lambda *a, **kw: "/project/the-redirect"
+        )
+
+        resp = getattr(json, endpoint)(project, db_request)
+
+        assert isinstance(resp, HTTPMovedPermanently)
+        assert db_request.route_path.calls == [pretend.call(route, name=project.name)]
+        assert resp.headers["Location"] == "/project/the-redirect"
+
+
 class TestJSONRelease:
     def test_normalizing_redirects(self, db_request):
         project = ProjectFactory.create()