deluge-web-client

Deluge Web API Client

Python HTTP client implementation for Deluge

User Guide and API Reference available on Read the Docs.

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

# instantiate a client
client = DelugeWebClient(url="https://site.net/deluge", password="example_password")

# 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, id=1)

# 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

# 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="0407326f9d74629d299b525bd5f9b5dd583xxxx", error=None, id=1)

Notes

Calling client.disconnect() will log the user out of the WebUI in both the client and any connected web browser. Be cautious if you're also logged in to the WebUI via your browser as this will terminate your session there as well.

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.