Skip to main content
`Ctrl`+`K`

# 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.