Development

This page is for Deluge <= 1.1. For later versions e.g. 1.3 see: Development/1.3/UIClient

deluge.ui.client

This is the remote api for Deluge <= 1.1.

It is used by all deluge user-interfaces and scripts.

It's also exposed to plugins as deluge.plugins.coreclient.client , so a client-script could easily be rewritten to a plugin. I recommend plugin writers to write some tests with uiclient first before porting the logic to a plugin.

index

  1. deluge.ui.client
  2. sclient
  3. aclient
  4. Client Methods
  5. Deluge 1.0 to 1.1
  6. Remote api
  7. Notes
  8. Real world examples

sclient

The synchronous api.

Simple, but blocking the main thread.

#get list of torrents
from deluge.ui.client import sclient
sclient.set_core_uri()
torrent_ids = sclient.get_session_state()
for id in torrent_ids:
    print sclient.get_torrent_status(id, ['name','paused','ratio','progress'])

result:

{'paused': False, 'progress': 100.0, 'ratio': 0.0, 'name': 'autocat_1.0.1.jar'}
{'paused': False, 'progress': 100.0, 'ratio': 0.0, 'name': 'autospeed_0.9.0.jar'}
{'paused': False, 'progress': 100.0, 'ratio': 0.0, 'name': 'aesmsclient_0.2.1.jar'}

aclient

The asynchronous api.

Used by rich user interfaces like gtk, or for performance critical batch-calls in webui.

#get list of torrents
from deluge.ui.client import aclient

class TestClient:
    def __init__(self):
        self.torrent_ids = []
        self.torrent_status = []

    def cb_session_state(self, torrent_ids):
        self.torrent_ids = torrent_ids

    def cb_torrent_status(self, status):
        self.torrent_status.append(status)

    def run(self):
        aclient.get_session_state(self.cb_session_state)
        aclient.force_call(block=True)
        print self.torrent_ids

        for id in self.torrent_ids:
            aclient.get_torrent_status(self.cb_torrent_status, id , [])
        aclient.force_call(block=True)
        for status in self.torrent_status:
            print status

aclient.set_core_uri()
t = TestClient()
t.run()

result:

['a8d15bd5c740e29f6a0a5bd91547ad5356d01305', 'ca5820f21b316d169c63a953faa3abb1a8abb9f0', 'f2b609578473f6a29d3123ba0897213b3c1bbcda']
{'paused': False, 'progress': 100.0, 'ratio': 0.0, 'name': 'autocat_1.0.1.jar'}
{'paused': False, 'progress': 100.0, 'ratio': 0.0, 'name': 'autospeed_0.9.0.jar'}
{'paused': False, 'progress': 100.0, 'ratio': 0.0, 'name': 'aesmsclient_0.2.1.jar'}

Client Methods

Non-Core methods on sclient and aclient

Generated from docstrings , do not edit

connect_on_new_core(callback):

Connect a callback whenever a new core is connected to.

connect_on_no_core(callback):

Connect a callback whenever the core is disconnected from.

connected():

Returns True if connected to a host, and False if not.

force_call(block):

Forces the multicall batch to go now and not wait for the timer. This call also blocks until all callbacks have been dealt with.

get_core_uri():

Get the core URI

is_localhost():

Returns True if core is a localhost

set_core_uri(uri):

Sets the core uri

shutdown():

Shutdown the core daemon

Deluge 1.0 to 1.1

  • set_torrent_options obsoletes : set_torrent_max_connections, set_torrent_max_download_speed, set_torrent_max_upload_speed , set_torrent_auto_managed, set_torrent_max_connections, set_torrent_max_upload_slots, set_torrent_file_priorities,set_torrent_auto_managed, etc..
  • get_stats obsoletes : get_download_rate, get_upload_rate , get_dht_nodes

Remote api

Core methods exposed by aclient , sclient and plugins.coreclient.client

for sclient, coreclient : ignore [callback]

for acleint : [callback] is the 1st parameter and refers to a callback method.

Generated from docstrings , do not edit

add_torrent_file(torrent_files, torrent_options):

Adds torrent files to the core
Expects a list of torrent files
A list of torrent_option dictionaries in the same order of torrent_files

add_torrent_file_binary(filename, fdump, options):

Core-wrapper.
Adds 1 torrent file to the core.
Expects fdump as a bytestring (== result of f.read()).

add_torrent_url(url, save_path, options):

block_ip_range(range):

Block an ip range

deregister_client():

De-registers a client with the signal manager.

disable_plugin(plugin):

enable_plugin(plugin):

force_reannounce(torrent_ids):

force_recheck(torrent_ids):

Forces a data recheck on torrent_ids

get_available_plugins([callback]):

Returns a list of plugins available in the core

get_config([callback]):

Get all the preferences as a dictionary

get_config_value([callback], key):

Get the config value for key

get_dht_nodes([callback]):

Returns the number of dht nodes

get_download_rate([callback]):

Returns the payload download rate

get_enabled_plugins([callback]):

Returns a list of enabled plugins in the core

get_filter_tree([callback]):

returns {field: [(value,count)] }
for use in sidebar(s)

get_health([callback]):

Returns True if we have established incoming connections

get_listen_port([callback]):

Returns the active listen port

get_num_connections([callback]):

Returns the current number of connections

get_session_state([callback]):

Returns a list of torrent_ids in the session.

get_stats([callback]):

returns: {
'download_rate':float(),
'upload_rate':float(),
'num_connections':int(),
'dht_nodes',int(),
'max_num_connections':int(),
'max_download':float(),
'max_upload':float()
}

get_status_keys([callback]):

returns all possible keys for the keys argument in get_torrent(s)_status.

get_torrent_status([callback], torrent_id, keys):

get_torrents_status([callback], filter_dict, keys):

returns all torrents , optionally filtered by filter_dict.

get_upload_rate([callback]):

Returns the payload upload rate

move_storage(torrent_ids, dest):

pause_all_torrents():

Pause all torrents in the session

pause_torrent(torrent_ids):

ping([callback]):

A method to see if the core is running

queue_bottom([callback], torrent_ids):

queue_down([callback], torrent_ids):

queue_top([callback], torrent_ids):

## Queueing functions ##

queue_up([callback], torrent_ids):

register_client(port):

Registers a client with the signal manager so that signals are
sent to it.

remove_torrent(torrent_ids, remove_torrent, remove_data):

reset_ip_filter([callback]):

Clears the ip filter

resume_all_torrents():

Resume all torrents in the session

resume_torrent(torrent_ids):

save_state([callback]):

Save the current session state to file.

set_config(config):

Set the config with values from dictionary

set_torrent_auto_managed(torrent_id, value):

Sets the auto managed flag for queueing purposes

set_torrent_file_priorities(torrent_id, priorities):

Sets a torrents file priorities

set_torrent_max_connections(torrent_id, value):

Sets a torrents max number of connections

set_torrent_max_download_speed(torrent_id, value):

Sets a torrents max download speed

set_torrent_max_upload_slots(torrent_id, value):

Sets a torrents max number of upload slots

set_torrent_max_upload_speed(torrent_id, value):

Sets a torrents max upload speed

set_torrent_move_on_completed(torrent_id, value):

Sets the torrent to be moved when completed

set_torrent_move_on_completed_path(torrent_id, value):

Sets the path for the torrent to be moved when completed

set_torrent_options([callback], torrent_ids, options):

Sets the torrent options for torrent_ids

set_torrent_prioritize_first_last(torrent_id, value):

Sets a higher priority to the first and last pieces

set_torrent_remove_at_ratio(torrent_id, value):

Sets the torrent to be removed at 'stop_ratio'

set_torrent_stop_at_ratio(torrent_id, value):

Sets the torrent to stop at 'stop_ratio'

set_torrent_stop_ratio(torrent_id, value):

Sets the ratio when to stop a torrent if 'stop_at_ratio' is set

set_torrent_trackers(torrent_id, trackers):

Sets a torrents tracker list.  trackers will be [{"url", "tier"}]

shutdown([callback]):

Shutdown the core daemon

Notes

How to disable logging

see : http://www.python.org/doc/2.5.2/lib/module-logging.html

Examples:

import logging
logging.disable(logging.WARNING) #wil surpress all log-levels less severe than WARNING ; will display errors, but no info and warning.
logging.disable(logging.CRITICAL) #wil surpress all log-levels including ERROR and critical.

The available keys for get_torrent_status(id, keys)

>>>sorted(sclient.get_status_keys())
['active_time', 'compact', 'distributed_copies', 'download_payload_rate', 'eta', 'file_priorities',
'file_progress', 'files', 'hash', 'is_auto_managed', 'is_seed', 'label', 'max_connections',
'max_download_speed', 'max_upload_slots', 'max_upload_speed', 'message', 'move_on_completed',
'move_on_completed_path', 'name', 'next_announce', 'num_files', 'num_peers', 'num_pieces',
'num_seeds', 'paused', 'peers', 'piece_length', 'prioritize_first_last', 'private', 'progress',
'queue', 'ratio', 'remove_at_ratio', 'save_path', 'seed_rank', 'seeding_time', 'state',
'stop_at_ratio', 'stop_ratio', 'total_done', 'total_payload_download', 'total_payload_upload',
'total_peers', 'total_seeds', 'total_size', 'total_uploaded', 'total_wanted', 'tracker',
'tracker_host', 'tracker_status', 'trackers', 'upload_payload_rate']

Options parameter used in set_torrent_options and add_torrent_*

{
    "max_download_speed": float(),
    "max_upload_speed": float(),
    "max_connections": int(),
    "max_upload_slots": int(),
    "prioritize_first_last_pieces": bool(),
    "auto_managed": bool(),
    "file_priorities": list(), #list of integers.
    "download_location": string()
}

These are also status-keys: get_torrent_options :

sclient.get_torrent_status(torrent_id,["max_download_speed","max_upload_speed","max_connections","max_upload_slots"
    ,"prioritize_first_last_pieces","auto_managed","file_priorities","download_location"] )

Config-values used in get_config,set_config

add_paused:bool()
allow_remote:bool()
auto_managed:bool()
autoadd_enable:bool()
autoadd_location:str()
compact_allocation:bool()
config_location:str()
copy_torrent_file:bool()
daemon_port:int()
dht:bool()
dont_count_slow_torrents:bool()
download_location:str()
enabled_plugins:list()
enc_in_policy:int()
enc_level:int()
enc_out_policy:int()
enc_prefer_rc4:bool()
ignore_limits_on_local_network:bool()
info_sent:float()
listen_ports:list()
lsd:bool()
max_active_downloading:int()
max_active_limit:int()
max_active_seeding:int()
max_connections_global:int()
max_connections_per_second:int()
max_connections_per_torrent:int()
max_download_speed:float()
max_download_speed_per_torrent:int()
max_half_open_connections:int()
max_upload_slots_global:int()
max_upload_slots_per_torrent:int()
max_upload_speed:float()
max_upload_speed_per_torrent:float()
move_completed:bool()
move_completed_path:str()
natpmp:bool()
new_release_check:bool()
outgoing_ports:list()
peer_tos:str()
plugins_location:str()
prioritize_first_last_pieces:bool()
proxy_password:str()
proxy_port:int()
proxy_server:str()
proxy_type:int()
proxy_username:str()
queue_new_to_top:bool()
random_outgoing_ports:bool()
random_port:bool()
remove_seed_at_ratio:bool()
seed_time_limit:float()
seed_time_ratio_limit:float()
send_info:bool()
share_ratio_limit:float()
state_location:str()
stop_seed_at_ratio:bool()
stop_seed_ratio:float()
torrentfiles_location:str()
upnp:bool()
utpex:bool()

Real world examples

A scheduler using cron and ui.client

http://dev.deluge-torrent.org/ticket/382#comment:4

Setting a random port

http://forum.deluge-torrent.org/viewtopic.php?f=9&t=8765

Setting file priority

http://forum.deluge-torrent.org/viewtopic.php?f=8&t=8955&p=41775#p41775

Random stuff from IRC

Development/UiClient/Scripts

Test scripts in svn

Many test scripts use sclient or aclient:

http://dev.deluge-torrent.org/browser/trunk/deluge/tests

Last modified 11 years ago Last modified on 06/18/2013 12:51:55 PM