Exceptions

Every Deluge or network failure raises DelugeWebClientError or one of its subclasses. Catching the base class handles all of them, including any subclass added in a future release:

DelugeWebClientError
├── DelugeWebClientConnectionError   # unreachable host, DNS, TLS, proxy
├── DelugeWebClientTimeoutError      # connect / read timeout
├── DelugeWebClientHTTPError         # non-2xx (.status_code, .reason)
├── DelugeWebClientRPCError          # Deluge reported an error (.method, .error_class, .info_hash)
└── DelugeWebClientDecodeError       # response body was not a JSON object

Transport failures from the underlying niquests library are translated into DelugeWebClientConnectionError and DelugeWebClientTimeoutError; the original exception is kept as __cause__.

ValueError (a malformed URL passed to DelugeWebClient) and OSError (an unreadable torrent file) are deliberately not wrapped, as they signal a bad argument rather than a Deluge failure.

class DelugeWebClientError

Bases: Exception

Represent an error detected while using the Deluge Web API.

This is the base class for every exception raised by this package. Catching it is enough to handle any Deluge or network related failure:

try:
    client.login()
except DelugeWebClientError as exc:
    ...

The only exceptions that are deliberately not wrapped are ValueError (a malformed URL passed to DelugeWebClient) and OSError (an unreadable torrent file).

class DelugeWebClientConnectionError

Bases: DelugeWebClientError

The Deluge Web UI could not be reached.

Raised when the underlying transport fails outright: the host is unreachable, DNS resolution fails, the TLS handshake fails, a proxy rejects the request, or there is no Deluge instance listening at the configured URL. The originating niquests exception is available as __cause__.

class DelugeWebClientTimeoutError

Bases: DelugeWebClientError

The request to the Deluge Web UI timed out.

Covers both connect and read timeouts. The originating niquests exception is available as __cause__.

class DelugeWebClientHTTPError(message, *, status_code=None, reason=None) → None

Bases: DelugeWebClientError

The Deluge Web UI returned a non-2xx HTTP status.

Parameters:
  • message (str) – Human readable description of the failure.

  • status_code (int | None) – HTTP status code returned by the server, if known.

  • reason (str | None) – HTTP reason phrase returned by the server, if known.

class DelugeWebClientRPCError(message, *, method=None, error_class=None, info_hash=None) → None

Bases: DelugeWebClientError

The Deluge Web UI returned a JSON-RPC error.

The HTTP request itself succeeded, but Deluge reported an error in the response body (bad password, unknown method, torrent failed to add, …).

Parameters:
  • message (str) – Human readable description of the failure.

  • method (str | None) – JSON-RPC method that produced the error, if known.

  • error_class (str | None) – Deluge exception class name parsed out of the error, e.g. deluge.error.AddTorrentError.

  • info_hash (str | None) – Info hash parsed out of the error message, if present.

class DelugeWebClientDecodeError

Bases: DelugeWebClientError

The response body was not a JSON-RPC object.

Raised when the body could not be parsed as JSON at all, or parsed into something other than a JSON object. Usually means the URL points at something that is not a Deluge Web UI.