mousebender.simple – Simple repository API

Utilities to help with Simple repository API responses.

This module helps with the JSON-based Simple repository API by providing TypedDict definitions for API responses. For HTML-based responses, functions are provided to convert the HTML to the equivalent JSON response.

This module implements PEP 503, PEP 592, PEP 629, PEP 658, PEP 691, PEP 700, PEP 714, PEP 740, and PEP 792 of the Simple repository API.

mousebender.simple.ACCEPT_JSON_LATEST = 'application/vnd.pypi.simple.latest+json'

The Accept header value for the latest version of the JSON API.

Use of this value is generally discouraged as major versions of the JSON API are not guaranteed to be backwards compatible, and thus may result in a response that code cannot handle.

Added in version 2022.1.0.

mousebender.simple.ACCEPT_JSON_V1 = 'application/vnd.pypi.simple.v1+json'

The Accept header value for version 1 of the JSON API.

Added in version 2022.1.0.

mousebender.simple.ACCEPT_HTML = 'application/vnd.pypi.simple.v1+html, text/html;q=0.01'

The Accept header value for the HTML API.

Added in version 2022.1.0.

mousebender.simple.ACCEPT_SUPPORTED = 'application/vnd.pypi.simple.v1+json, application/vnd.pypi.simple.v1+html;q=0.02, text/html;q=0.01'

The Accept header for the MIME types that parse_project_index() and parse_project_details() support.

Added in version 2022.1.0.

exception mousebender.simple.UnsupportedAPIVersion(version: str)

The major version of an API response is not supported.

Added in version 2023.0.0.

exception mousebender.simple.APIVersionWarning(version: str)

The minor version of an API response is not supported.

Added in version 2023.0.0.

exception mousebender.simple.UnsupportedMIMEType

An unsupported MIME type was provided in a Content-Type header.

Added in version 2022.1.0.

mousebender.simple.ProjectIndex_1_0

A TypedDict for a project index (PEP 691).

Added in version 2022.0.0.

mousebender.simple.ProjectIndex_1_1

A TypedDict for a project index (PEP 700).

Added in version 2022.1.0.

mousebender.simple.ProjectIndex_1_3

A TypedDict for a project index (PEP 740).

Added in version 2025.0.

mousebender.simple.ProjectIndex

A TypeAlias for any version of the JSON project index response.

Added in version 2022.0.0.

Changed in version 2022.1.0: Added ProjectIndex_1_1.

Changed in version 2025.0: Added ProjectIndex_1_3.

mousebender.simple.ProjectFileDetails_1_0

A TypedDict for the files key of ProjectDetails_1_0.

Added in version 2022.0.0.

mousebender.simple.ProjectFileDetails_1_1

A TypedDict for the files key of ProjectDetails_1_1.

Added in version 2022.1.0.

mousebender.simple.ProjectFileDetails_1_3

A TypedDict for the files key of ProjectDetails_1_3.

Added in version 2025.0.

mousebender.simple.ProjectFileDetails

A TypeAlias for any version of the JSON project file details response.

Added in version 2023.2.

Changed in version 2025.0: Added ProjectFileDetails_1_3.

mousebender.simple.ProjectDetails_1_0

A TypedDict for a project details response (PEP 691).

Added in version 2022.0.0.

mousebender.simple.ProjectDetails_1_1

A TypedDict for a project details response (PEP 700).

Added in version 2022.1.0.

mousebender.simple.ProjectDetails_1_3

A TypedDict for a project details response (PEP 740).

Added in version 2025.0.

mousebender.simple.ProjectDetails

A TypeAlias for any version of the JSON project details response.

Added in version 2022.0.0.

Changed in version 2022.1.0: Added ProjectDetails_1_1.

Changed in version 2025.0: Added ProjectDetails_1_3.

mousebender.simple.from_project_index_html(html: str) → ProjectIndex_1_0

Convert the HTML response of a repository index page to a PEP 691 response.

Added in version 2022.0.0.

mousebender.simple.create_project_url(base_url: str, project_name: str) → str

Construct the URL for a project hosted on a server at base_url.

Added in version 2022.0.0.

mousebender.simple.from_project_details_html(html: str, name: str) → ProjectDetails_1_0

Convert the HTML response for a project details page to a PEP 691 response.

Due to HTML project details pages lacking the name of the project, it must be specified via the name parameter to fill in the JSON data.

Added in version 2022.0.0.

mousebender.simple.parse_project_index(data: str, content_type: str) → ProjectIndex_1_0 | ProjectIndex_1_1 | ProjectIndex_1_3 | ProjectIndex_1_4

Parse an HTTP response for a project index.

The text of the body and Content-Type header are expected to be passed in as data and content_type respectively. This allows for the user to not have to concern themselves with what form the response came back in.

If the specified content_type is not supported, UnsupportedMIMEType is raised.

Added in version 2022.1.0.

mousebender.simple.parse_project_details(data: str, content_type: str, name: str) → ProjectDetails_1_0 | ProjectDetails_1_1 | ProjectDetails_1_3 | ProjectDetails_1_4

Parse an HTTP response for a project’s details.

The text of the body and Content-Type header are expected to be passed in as data and content_type respectively. This allows for the user to not have to concern themselves with what form the response came back in. The name parameter is for the name of the project whose details have been fetched.

If the specified content_type is not supported, UnsupportedMIMEType is raised.

Added in version 2022.1.0.