['Development']
= deluge.ui.client =
This is the remote api for deluge.

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.

[[PageOutline(1,index,inline)]]
= sclient =
The synchronous api.

''Simple, but blocking the main thread.''
{{{
#!python
#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:
{{{
#!python
{'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.''

{{{
#!python
#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:
{{{
#!python
['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 =
    {{{
#!python
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) ==
    {{{
#!python
>>>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_* ==
{{{
#!python
{
    "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 : 
{{{
#!python
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 ===
{{{
#!python
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