RequestHandler

class beetsplug._utils.requests.RequestHandler

Bases: object

Manages HTTP requests with custom error handling and session management.

Provides a reusable interface for making HTTP requests with automatic conversion of standard HTTP errors to beets-specific exceptions. Supports custom session types and error mappings that can be overridden by subclasses.

Usage:

Subclass and override RequestHandler.create_session, RequestHandler.explicit_http_errors or RequestHandler.status_to_error() to customize behavior.

Use

• RequestHandler.get_json() to get JSON response data

• RequestHandler.get() to get HTTP response object

• RequestHandler.request() to invoke arbitrary HTTP methods

Feel free to define common methods that are used in multiple plugins.

__init__()

Public methods summary

create_session()	Create a new HTTP session instance.
delete(*args, **kwargs)	Perform HTTP DELETE request with automatic error handling.
get(*args, **kwargs)	Perform HTTP GET request with automatic error handling.
get_json(*args, **kwargs)	Fetch and parse JSON data from an HTTP endpoint.
handle_http_error()	Convert standard HTTP errors to beets-specific exceptions.
put(*args, **kwargs)	Perform HTTP PUT request with automatic error handling.
request(*args, **kwargs)	Perform HTTP request using the session with automatic error handling.
status_to_error(code)	Map HTTP status codes to beets-specific exception types.

Methods definition

explicit_http_errors: ClassVar[list[type[BeetsHTTPError]]] = [<class 'beetsplug._utils.requests.HTTPNotFoundError'>]

List of custom exceptions to be raised for specific status codes.

create_session() → TimeoutAndRetrySession

Create a new HTTP session instance.

Can be overridden by subclasses to provide custom session types.

status_to_error(code: int) → type[HTTPError] | None

Map HTTP status codes to beets-specific exception types.

Searches the configured explicit HTTP errors for a matching status code. Returns None if no specific error type is registered for the given code.

handle_http_error() → Iterator[None]

Convert standard HTTP errors to beets-specific exceptions.

Wraps operations that may raise HTTPError, automatically translating recognized status codes into their corresponding beets exception types. Unrecognized errors are re-raised unchanged.

request(*args, **kwargs) → Response

Perform HTTP request using the session with automatic error handling.

Delegates to the underlying session method while converting recognized HTTP errors to beets-specific exceptions through the error handler.

get(*args, **kwargs) → Response

Perform HTTP GET request with automatic error handling.

put(*args, **kwargs) → Response

Perform HTTP PUT request with automatic error handling.

delete(*args, **kwargs) → Response

Perform HTTP DELETE request with automatic error handling.

get_json(*args, **kwargs)

Fetch and parse JSON data from an HTTP endpoint.