Merge pull request #42 from jwodder/pep792

Support PEP 792

Author: jwodder

CHANGELOG.md

@@ -3,6 +3,10 @@ v1.7.0 (in development)
 - Support Python 3.13
 - **Bugfix**: Fix parsing of PEP 708 `alternate-locations` fields in JSON
   project pages (Previous versions looked for the field in the wrong location)
+- Support PEP 792
+    - `status` and `status_reason` attributes added to `ProjectPage` and `RepositoryPage`
+    - `ProjectStatus` enum added
+    - `SUPPORTED_REPOSITORY_VERSION` increased to `"1.4"`
 
 v1.6.1 (2024-10-23)
 -------------------

README.rst

@@ -27,13 +27,13 @@
 
 ``pypi-simple`` is a client library for the Python Simple Repository API as
 specified in :pep:`503` and updated by :pep:`592`, :pep:`629`, :pep:`658`,
-:pep:`691`, :pep:`700`, :pep:`708`, :pep:`714`, and :pep:`740`.  With it, you
-can query `the Python Package Index (PyPI) <https://pypi.org>`_ and other `pip
-<https://pip.pypa.io>`_-compatible repositories for a list of their available
-projects and lists of each project's available package files.  The library also
-allows you to download package files and query them for their project version,
-package type, file digests, ``requires_python`` string, PGP signature URL, and
-metadata URL.
+:pep:`691`, :pep:`700`, :pep:`708`, :pep:`714`, :pep:`740`, and :pep:`792`.
+With it, you can query `the Python Package Index (PyPI) <https://pypi.org>`_
+and other `pip <https://pip.pypa.io>`_-compatible repositories for a list of
+their available projects and lists of each project's available package files.
+The library also allows you to download package files and query them for their
+project version, package type, file digests, ``requires_python`` string, PGP
+signature URL, and metadata URL.
 
 See `the documentation <https://pypi-simple.readthedocs.io>`_ for more
 information.

docs/api.rst

@@ -12,6 +12,7 @@ Core Classes
 .. autoclass:: IndexPage()
 .. autoclass:: ProjectPage()
 .. autoclass:: DistributionPackage()
+.. autoclass:: ProjectStatus()
 
 Progress Trackers
 -----------------

docs/changelog.rst

@@ -6,9 +6,16 @@ Changelog
 v1.7.0 (in development)
 -----------------------
 - Support Python 3.13
+
 - **Bugfix**: Fix parsing of :pep:`708` ``alternate-locations`` fields in JSON
   project pages (Previous versions looked for the field in the wrong location)
 
+- Support :pep:`792`
+
+  - ``status`` and ``status_reason`` attributes added to `ProjectPage` and `RepositoryPage`
+  - `ProjectStatus` enum added
+  - `SUPPORTED_REPOSITORY_VERSION` increased to `"1.4"`
+
 
 v1.6.1 (2024-10-23)
 -------------------

docs/index.rst

@@ -19,13 +19,13 @@ pypi-simple — PyPI Simple Repository API client library
 
 ``pypi-simple`` is a client library for the Python Simple Repository API as
 specified in :pep:`503` and updated by :pep:`592`, :pep:`629`, :pep:`658`,
-:pep:`691`, :pep:`700`, :pep:`708`, :pep:`714`, and :pep:`740`.  With it, you
-can query `the Python Package Index (PyPI) <https://pypi.org>`_ and other `pip
-<https://pip.pypa.io>`_-compatible repositories for a list of their available
-projects and lists of each project's available package files.  The library also
-allows you to download package files and query them for their project version,
-package type, file digests, ``requires_python`` string, PGP signature URL, and
-metadata URL.
+:pep:`691`, :pep:`700`, :pep:`708`, :pep:`714`, :pep:`740`, and :pep:`792`.
+With it, you can query `the Python Package Index (PyPI) <https://pypi.org>`_
+and other `pip <https://pip.pypa.io>`_-compatible repositories for a list of
+their available projects and lists of each project's available package files.
+The library also allows you to download package files and query them for their
+project version, package type, file digests, ``requires_python`` string, PGP
+signature URL, and metadata URL.
 
 Installation
 ============

src/pypi_simple/__init__.py

@@ -24,7 +24,7 @@
 PYPI_SIMPLE_ENDPOINT: str = "https://pypi.org/simple/"
 
 #: The maximum supported simple repository version (See :pep:`629`)
-SUPPORTED_REPOSITORY_VERSION: str = "1.3"
+SUPPORTED_REPOSITORY_VERSION: str = "1.4"
 
 #: :mailheader:`Accept` header value for accepting either the HTML or JSON
 #: serialization without a preference
@@ -69,6 +69,7 @@
 
 from .classes import DistributionPackage, IndexPage, ProjectPage
 from .client import PyPISimple
+from .enums import ProjectStatus
 from .errors import (
     DigestMismatchError,
     NoDigestsError,
@@ -97,6 +98,7 @@
     "PYPI_SIMPLE_ENDPOINT",
     "ProgressTracker",
     "ProjectPage",
+    "ProjectStatus",
     "PyPISimple",
     "RepositoryPage",
     "SUPPORTED_REPOSITORY_VERSION",

src/pypi_simple/classes.py

@@ -6,6 +6,7 @@
 from urllib.parse import urlparse, urlunparse
 from mailbits import ContentType
 import requests
+from .enums import ProjectStatus
 from .errors import UnparsableFilenameError, UnsupportedContentTypeError
 from .filenames import parse_filename
 from .html import Link, RepositoryPage
@@ -277,6 +278,16 @@ class ProjectPage:
     #: __ https://peps.python.org/pep-0708/#alternate-locations-metadata
     alternate_locations: list[str] = field(default_factory=list)
 
+    #: .. versionadded:: 1.7.0
+    #:
+    #: Project status marker, or `None` if not specified.  See :pep:`792`.
+    status: ProjectStatus | None = None
+
+    #: .. versionadded:: 1.7.0
+    #:
+    #: Freeform text contextualizing `status`, or `None` if not specified
+    status_reason: str | None = None
+
     @classmethod
     def from_html(
         cls,
@@ -317,6 +328,8 @@ def from_html(
             versions=None,
             tracks=page.tracks,
             alternate_locations=page.alternate_locations,
+            status=page.status,
+            status_reason=page.status_reason,
         )
 
     @classmethod
@@ -352,6 +365,8 @@ def from_json_data(cls, data: Any, base_url: Optional[str] = None) -> ProjectPag
             versions=project.versions,
             tracks=project.meta.tracks,
             alternate_locations=project.alternate_locations,
+            status=project.project_status.status,
+            status_reason=project.project_status.reason,
         )
 
     @classmethod

src/pypi_simple/enums.py

@@ -0,0 +1,25 @@
+from enum import Enum
+
+
+class ProjectStatus(str, Enum):
+    """
+    .. versionadded:: 1.7.0
+
+    Enum of project status markers as defined by :pep:`792`
+    """
+
+    #: The project is active.  This is the default status for a project.
+    ACTIVE = "active"
+
+    #: The project does not expect to be updated in the future.
+    ARCHIVED = "archived"
+
+    #: The project is considered generally unsafe for use, e.g. due to malware.
+    QUARANTINED = "quarantined"
+
+    #: The project is considered obsolete, and may have been superseded by
+    #: another project.
+    DEPRECATED = "deprecated"
+
+    def __str__(self) -> str:
+        return self.value

src/pypi_simple/html.py

@@ -4,6 +4,7 @@
 from typing import Optional
 from urllib.parse import urljoin
 from bs4 import BeautifulSoup, Tag
+from .enums import ProjectStatus
 from .util import basejoin, check_repo_version
 
 
@@ -52,6 +53,28 @@ def alternate_locations(self) -> list[str]:
         """
         return self.pypi_meta.get("alternate-locations", [])
 
+    @property
+    def status(self) -> ProjectStatus | None:
+        """
+        .. versionadded:: 1.7.0
+
+        Project status marker, or `None` if not specified.  See :pep:`792`.
+        """
+        if st := self.pypi_meta.get("project-status"):
+            return ProjectStatus(st[0])
+        else:
+            return None
+
+    @property
+    def status_reason(self) -> str | None:
+        """
+        .. versionadded:: 1.7.0
+
+        Freeform text contextualizing `status`, or `None` if not specified.
+        See :pep:`792` for more information.
+        """
+        return self.pypi_meta.get("project-status-reason", [None])[0]
+
     @classmethod
     def from_html(
         cls,

src/pypi_simple/pep691.py

@@ -2,6 +2,7 @@
 from datetime import datetime
 from typing import Any, Dict, List, Optional, Union
 from pydantic import BaseModel, Field, StrictBool, field_validator
+from .enums import ProjectStatus
 
 
 def shishkebab(s: str) -> str:
@@ -25,6 +26,11 @@ class ProjectMeta(Meta):
     tracks: List[str] = Field(default_factory=list)
 
 
+class StatusData(BaseModel):
+    status: Optional[ProjectStatus] = None
+    reason: Optional[str] = None
+
+
 class File(BaseModel, alias_generator=shishkebab, populate_by_name=True):
     filename: str
     url: str
@@ -73,6 +79,7 @@ class Project(BaseModel, alias_generator=shishkebab, populate_by_name=True):
     files: List[File]
     meta: ProjectMeta
     alternate_locations: List[str] = Field(default_factory=list)
+    project_status: StatusData = Field(default_factory=StatusData)
     versions: Optional[List[str]] = None