Add accept parameters & constants

Author: jwodder

CHANGELOG.md

@@ -31,6 +31,8 @@ v1.0.0 (in development)
 - Renamed `DistributionPackage.from_pep691_details()` to `from_json_data()`
 - `PyPISimple.stream_project_names()` now accepts JSON responses
 - Use pydantic internally to parse JSON responses
+- Added constants for passing to `PyPISimple` and its methods in order to
+  specify the `Accept` header to send
 
 v0.10.0 (2022-06-30)
 --------------------

docs/api.rst

@@ -38,6 +38,19 @@ Constants
 .. autodata:: PYPI_SIMPLE_ENDPOINT
 .. autodata:: SUPPORTED_REPOSITORY_VERSION
 
+:mailheader:`Accept` Header Values
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following constants can be passed as the ``accept`` parameter of
+`PyPISimple` and some of its methods in order to indicate to the server which
+serialization format of the Simple API it should return:
+
+.. autodata:: ACCEPT_ANY
+.. autodata:: ACCEPT_JSON_ONLY
+.. autodata:: ACCEPT_HTML_ONLY
+.. autodata:: ACCEPT_JSON_PREFERRED
+.. autodata:: ACCEPT_HTML_PREFERRED
+
 Exceptions
 ----------
 .. autoexception:: DigestMismatchError()

docs/changelog.rst

@@ -43,6 +43,8 @@ v1.0.0 (in development)
   `~DistributionPackage.from_json_data()`
 - `PyPISimple.stream_project_names()` now accepts JSON responses
 - Use pydantic internally to parse JSON responses
+- Added constants for passing to `PyPISimple` and its methods in order to
+  specify the :mailheader:`Accept` header to send
 
 v0.10.0 (2022-06-30)
 --------------------

src/pypi_simple/__init__.py

@@ -26,6 +26,47 @@
 #: The maximum supported simple repository version (See :pep:`629`)
 SUPPORTED_REPOSITORY_VERSION: str = "1.0"
 
+#: :mailheader:`Accept` header value for accepting either the HTML or JSON
+#: serialization without a preference
+ACCEPT_ANY: str = ", ".join(
+    [
+        "application/vnd.pypi.simple.v1+json",
+        "application/vnd.pypi.simple.v1+html",
+        "text/html;q=0.01",
+    ]
+)
+
+#: :mailheader:`Accept` header value for accepting only the JSON serialization
+ACCEPT_JSON_ONLY = "application/vnd.pypi.simple.v1+json"
+
+#: :mailheader:`Accept` header value for accepting only the HTML serialization
+ACCEPT_HTML_ONLY = ", ".join(
+    [
+        "application/vnd.pypi.simple.v1+html",
+        "text/html;q=0.01",
+    ]
+)
+
+#: :mailheader:`Accept` header value for accepting either the HTML or JSON
+#: serialization with a preference for JSON
+ACCEPT_JSON_PREFERRED = ", ".join(
+    [
+        "application/vnd.pypi.simple.v1+json",
+        "application/vnd.pypi.simple.v1+html;q=0.5",
+        "text/html;q=0.01",
+    ]
+)
+
+#: :mailheader:`Accept` header value for accepting either the HTML or JSON
+#: serialization with a preference for HTML
+ACCEPT_HTML_PREFERRED = ", ".join(
+    [
+        "application/vnd.pypi.simple.v1+html",
+        "text/html;q=0.5",
+        "application/vnd.pypi.simple.v1+json;q=0.1",
+    ]
+)
+
 from .classes import DistributionPackage, IndexPage, ProjectPage
 from .client import NoSuchProjectError, PyPISimple
 from .errors import (

src/pypi_simple/client.py

@@ -8,7 +8,7 @@
 from mailbits import ContentType
 from packaging.utils import canonicalize_name as normalize
 import requests
-from . import PYPI_SIMPLE_ENDPOINT, __url__, __version__
+from . import ACCEPT_ANY, PYPI_SIMPLE_ENDPOINT, __url__, __version__
 from .classes import DistributionPackage, IndexPage, ProjectPage
 from .errors import UnsupportedContentTypeError
 from .html_stream import parse_links_stream_response
@@ -25,14 +25,6 @@
     platform.python_version(),
 )
 
-ACCEPT = ", ".join(
-    [
-        "application/vnd.pypi.simple.v1+json",
-        "application/vnd.pypi.simple.v1+html",
-        "text/html;q=0.01",
-    ]
-)
-
 
 class PyPISimple:
     """
@@ -53,6 +45,10 @@ class PyPISimple:
     automatically close its session on exit, regardless of where the session
     object came from.
 
+    .. versionchanged:: 1.0.0
+
+        ``accept`` parameter added
+
     :param str endpoint: The base URL of the simple API instance to query;
         defaults to the base URL for PyPI's simple API
 
@@ -63,13 +59,19 @@ class PyPISimple:
 
     :param session: Optional `requests.Session` object to use instead of
         creating a fresh one
+
+    :param str accept:
+        The :mailheader:`Accept` header to send in requests in order to specify
+        what serialization format the server should return; defaults to
+        `ACCEPT_ANY`
     """
 
     def __init__(
         self,
         endpoint: str = PYPI_SIMPLE_ENDPOINT,
         auth: Any = None,
         session: Optional[requests.Session] = None,
+        accept: str = ACCEPT_ANY,
     ) -> None:
         self.endpoint: str = endpoint.rstrip("/") + "/"
         self.s: requests.Session
@@ -80,6 +82,7 @@ def __init__(
             self.s.headers["User-Agent"] = USER_AGENT
         if auth is not None:
             self.s.auth = auth
+        self.accept = accept
 
     def __enter__(self) -> PyPISimple:
         return self
@@ -95,6 +98,7 @@ def __exit__(
     def get_index_page(
         self,
         timeout: float | tuple[float, float] | None = None,
+        accept: Optional[str] = None,
     ) -> IndexPage:
         """
         Fetches the index/root page from the simple repository and returns an
@@ -105,8 +109,16 @@ def get_index_page(
             PyPI's project index file is very large and takes several seconds
             to parse.  Use this method sparingly.
 
+        .. versionchanged:: 1.0.0
+
+            ``accept`` parameter added
+
         :param timeout: optional timeout to pass to the ``requests`` call
         :type timeout: float | tuple[float,float] | None
+        :param Optional[str] accept:
+            The :mailheader:`Accept` header to send in order to
+            specify what serialization format the server should return;
+            defaults to the value supplied on client instantiation
         :rtype: IndexPage
         :raises requests.HTTPError: if the repository responds with an HTTP
             error code
@@ -115,14 +127,17 @@ def get_index_page(
         :raises UnsupportedRepoVersionError: if the repository version has a
             greater major component than the supported repository version
         """
-        r = self.s.get(self.endpoint, timeout=timeout, headers={"Accept": ACCEPT})
+        r = self.s.get(
+            self.endpoint, timeout=timeout, headers={"Accept": accept or self.accept}
+        )
         r.raise_for_status()
         return IndexPage.from_response(r)
 
     def stream_project_names(
         self,
         chunk_size: int = 65535,
         timeout: float | tuple[float, float] | None = None,
+        accept: Optional[str] = None,
     ) -> Iterator[str]:
         """
         Returns a generator of names of projects available in the repository.
@@ -145,10 +160,18 @@ def stream_project_names(
             rather than an HTML representation, the response body will be
             loaded & parsed in its entirety before yielding anything.
 
+        .. versionchanged:: 1.0.0
+
+            ``accept`` parameter added
+
         :param int chunk_size: how many bytes to read from the response at a
             time
         :param timeout: optional timeout to pass to the ``requests`` call
         :type timeout: float | tuple[float,float] | None
+        :param Optional[str] accept:
+            The :mailheader:`Accept` header to send in order to
+            specify what serialization format the server should return;
+            defaults to the value supplied on client instantiation
         :rtype: Iterator[str]
         :raises requests.HTTPError: if the repository responds with an HTTP
             error code
@@ -157,7 +180,12 @@ def stream_project_names(
         :raises UnsupportedRepoVersionError: if the repository version has a
             greater major component than the supported repository version
         """
-        with self.s.get(self.endpoint, stream=True, timeout=timeout) as r:
+        with self.s.get(
+            self.endpoint,
+            stream=True,
+            timeout=timeout,
+            headers={"Accept": accept or self.accept},
+        ) as r:
             r.raise_for_status()
             ct = ContentType.parse(r.headers.get("content-type", "text/html"))
             if ct.content_type == "application/vnd.pypi.simple.v1+json":
@@ -176,6 +204,7 @@ def get_project_page(
         self,
         project: str,
         timeout: float | tuple[float, float] | None = None,
+        accept: Optional[str] = None,
     ) -> ProjectPage:
         """
         Fetches the page for the given project from the simple repository and
@@ -185,13 +214,19 @@ def get_project_page(
 
         .. versionchanged:: 1.0.0
 
-            A 404 now causes `NoSuchProjectError` to be raised instead of
-            returning `None`
+            - A 404 now causes `NoSuchProjectError` to be raised instead of
+              returning `None`
+
+            - ``accept`` parameter added
 
         :param str project: The name of the project to fetch information on.
             The name does not need to be normalized.
         :param timeout: optional timeout to pass to the ``requests`` call
         :type timeout: float | tuple[float,float] | None
+        :param Optional[str] accept:
+            The :mailheader:`Accept` header to send in order to
+            specify what serialization format the server should return;
+            defaults to the value supplied on client instantiation
         :rtype: ProjectPage
         :raises NoSuchProjectError: if the repository responds with a 404 error
             code
@@ -203,7 +238,7 @@ def get_project_page(
             greater major component than the supported repository version
         """
         url = self.get_project_url(project)
-        r = self.s.get(url, timeout=timeout, headers={"Accept": ACCEPT})
+        r = self.s.get(url, timeout=timeout, headers={"Accept": accept or None})
         if r.status_code == 404:
             raise NoSuchProjectError(project, url)
         r.raise_for_status()