Deluge Web API Client¶
Python HTTP client implementation for Deluge
Features¶
Provides access to the majority of Web API methods as well as key core functionalities through RPC. For more details, see the official Web API Documentation and RPC API Documentation.
Allows you to use direct http connections, allowing access via reverse proxy or any direct url.
Installation¶
Install via pip from PyPI:
python -m pip install deluge-web-client
# or
poetry add deluge-web-client
# or
uv add deluge-web-client
Getting Started¶
Before getting started, ensure that you have a running instance of Deluge with the WebUI enabled. You will also need to have a user set up for authentication. For guidance on setting up the WebUI, visit the Deluge setup guide. Another good tutorial is Trash-Guides basic setup.
Basic Usage¶
from deluge_web_client import DelugeWebClient, TorrentOptions
# instantiate a client
client = DelugeWebClient(
url="https://site.net/deluge",
password="example_password",
daemon_port=58846, # optional
)
# login
# once logged in the `client` will maintain the logged in state as long as you don't call
# client.disconnect()
client.login()
# uploading a torrent
# 1) define your torrent options (what ever you don't set here will utilize Deluge defaults)
torrent_options = TorrentOptions(
add_paused=True,
auto_managed=True,
)
# 2) upload the torrent and capture the returned output
upload = client.upload_torrent(
torrent_path="filepath.torrent",
torrent_options=torrent_options,
)
# this will return a `Response` object
print(upload)
# Response(result=True, error=None, message="Torrent added successfully")
# retrieve and show all torrents
all_torrents = client.get_torrents_status()
# pause torrent (pass torrent hash)
pause_torrent = client.pause_torrent("0407326f9d74629d299b525bd5f9b5dd583xxxx")
# remove torrent
remove_torrent = client.remove_torrent("0407326f9d74629d299b525bd5f9b5dd583xxxx")
Context Manager¶
from deluge_web_client import DelugeWebClient, TorrentOptions
# using a context manager automatically logs you in
with DelugeWebClient(url="https://site.net/deluge", password="example_password") as client:
torrent_options = TorrentOptions(
add_paused=True,
auto_managed=True,
)
upload = client.upload_torrent(
torrent_path="filepath.torrent",
torrent_options=torrent_options,
)
print(upload)
# Response(result="<torrent-id>", error=None, message="Torrent added successfully")
Error Handling¶
Every Deluge or network failure raises DelugeWebClientError
or one of its subclasses, so catching the base class is always enough:
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
from deluge_web_client import (
DelugeWebClient,
DelugeWebClientConnectionError,
DelugeWebClientError,
DelugeWebClientRPCError,
)
client = DelugeWebClient(url="https://site.net/deluge", password="example_password")
try:
client.login()
except DelugeWebClientConnectionError:
print("no Deluge Web UI at that URL")
except DelugeWebClientRPCError as error:
print(f"Deluge rejected the call: {error.method}")
except DelugeWebClientError as error:
# catches everything above, including anything added in the future
print(f"something went wrong: {error}")
The underlying niquests exception is preserved as __cause__ on connection
and timeout errors if you need the transport level detail.
Two exceptions are deliberately not wrapped, because they signal a bad argument rather than a Deluge failure:
ValueError– theurlpassed toDelugeWebClientis not an absolute HTTP/HTTPS URL, or contains a fragment.OSError/FileNotFoundError– a torrent file passed toupload_torrentcannot be read.
Notes¶
Calling client.disconnect() disconnects the Web UI session from its currently
connected Deluge daemon. Call client.close_session() when you only need to
release this client’s HTTP resources.
Access RPC Directly¶
This package uses HTTP to connect to the Deluge client, relying on the Web API / JSON to handle these calls. It’s fully capable of making all core calls to the Deluge backend. However, if you are looking for a package focused solely on RPC, consider deluge-client, which served as inspiration for this project alongside qbittorrent-api.