deluge.core package

Submodules

deluge.core.alertmanager module

The AlertManager handles all the libtorrent alerts.

This should typically only be used by the Core. Plugins should utilize the :mod:EventManager for similar functionality.

class deluge.core.alertmanager.AlertManager

Bases: deluge.component.Component

AlertManager fetches and processes libtorrent alerts

static create_alert_copy(alert)

Create a Python copy of libtorrent alert

Avoid segfault if an alert is handled after next pop_alert call

deregister_handler(handler)

De-registers the handler function from all alert types.

Parameters

handler (Callable[[Any], None]) – The handler function to deregister.

handle_alerts()

Pops all libtorrent alerts in the session queue and handles them appropriately.

register_handler(alert_type, handler)

Registers a function that will be called when ‘alert_type’ is pop’d in handle_alerts. The handler function should look like: handler(alert) Where ‘alert’ is the actual alert object from libtorrent.

Parameters

• alert_type (str) – String representation of the libtorrent alert name. Can be supplied with or without _alert suffix.

• handler (Callable[[Any], None]) – Callback function when the alert is raised.

Return type

None

set_alert_queue_size(queue_size)

Sets the maximum size of the libtorrent alert queue

stop()

update()

deluge.core.authmanager module

class deluge.core.authmanager.Account(username, password, authlevel)

Bases: object

authlevel

data()

password

username

class deluge.core.authmanager.AuthManager

Bases: deluge.component.Component

authorize(username, password)

Authorizes users based on username and password.

Parameters

• username (str) – Username

• password (str) – Password

Returns

int – The auth level for this user.

Raises

• AuthenticationRequired – If additional details are required to authenticate.

• BadLoginError – If the username does not exist or password does not match.

create_account(username, password, authlevel)

get_known_accounts()

Returns a list of known deluge usernames.

has_account(username)

remove_account(username)

shutdown()

start()

stop()

update()

update_account(username, password, authlevel)

write_auth_file()

deluge.core.core module

deluge.core.daemon module

deluge.core.daemon_entry module

deluge.core.daemon_entry.add_daemon_options(parser)

deluge.core.daemon_entry.start_daemon(skip_start=False)

Entry point for daemon script

Parameters

skip_start (bool) – If starting daemon should be skipped.

Returns

deluge.core.daemon.Daemon – A new daemon object

deluge.core.eventmanager module

class deluge.core.eventmanager.EventManager

Bases: deluge.component.Component

deregister_event_handler(event, handler)

Deregisters an event handler function.

Parameters

• event – str, the event name

• handler – function, currently registered to handle :param:event

emit(event)

Emits the event to interested clients.

Parameters

event – DelugeEvent

register_event_handler(event, handler)

Registers a function to be called when a :param:event is emitted.

Parameters

• event – str, the event name

• handler – function, to be called when :param:event is emitted

deluge.core.filtermanager module

class deluge.core.filtermanager.FilterManager(core)

Bases: deluge.component.Component

deregister_filter(filter_id)

deregister_tree_field(field)

filter_state_active(torrent_ids)

filter_torrent_ids(filter_dict)

returns a list of torrent_id’s matching filter_dict. core filter method

get_filter_tree(show_zero_hits=True, hide_cat=None)

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

register_filter(filter_id, filter_func, filter_value=None)

register_tree_field(field, init_func=<function FilterManager.<lambda>>)

deluge.core.filtermanager.filter_by_name(torrent_ids, search_string)

deluge.core.filtermanager.filter_keywords(torrent_ids, values)

deluge.core.filtermanager.filter_one_keyword(torrent_ids, keyword)

search torrent on keyword. searches title,state,tracker-status,tracker,files

deluge.core.filtermanager.tracker_error_filter(torrent_ids, values)

deluge.core.pluginmanager module

PluginManager for Core

class deluge.core.pluginmanager.PluginManager(core)

Bases: deluge.pluginmanagerbase.PluginManagerBase, deluge.component.Component

PluginManager handles the loading of plugins and provides plugins with functions to access parts of the core.

deregister_status_field(field)

Deregisters a status field

disable_plugin(name)

Disable a plugin.

Parameters

plugin_name (str) – The plugin name.

Returns

Deferred –

A deferred with callback value True or False indicating

whether the plugin is disabled or not.

enable_plugin(name)

Enable a plugin.

Parameters

plugin_name (str) – The plugin name.

Returns

Deferred –

A deferred with callback value True or False indicating

whether the plugin is enabled or not.

get_status(torrent_id, fields)

Return the value of status fields for the selected torrent_id.

register_status_field(field, function)

Register a new status field. This can be used in the same way the client requests other status information from core.

shutdown()

start()

stop()

update_plugins()

deluge.core.preferencesmanager module

deluge.core.rpcserver module

RPCServer Module

class deluge.core.rpcserver.DelugeRPCProtocol

Bases: deluge.transfer.DelugeTransferProtocol

connectionLost(reason=<twisted.python.failure.Failure twisted.internet.error.ConnectionDone: Connection was closed cleanly.>)

This method is called when the client is disconnected.

Parameters

reason (str) – the reason the client disconnected.

connectionMade()

This method is called when a new client connects.

dispatch(request_id, method, args, kwargs)

This method is run when a RPC Request is made. It will run the local method and will send either a RPC Response or RPC Error back to the client.

Parameters

• request_id (int) – the request_id from the client (sent in the RPC Request)

• method (str) – the local method to call. It must be registered with the RPCServer.

• args (list) – the arguments to pass to method

• kwargs (dict) – the keyword-arguments to pass to method

message_received(request)

This method is called whenever a message is received from a client. The only message that a client sends to the server is a RPC Request message. If the RPC Request message is valid, then the method is called in dispatch().

Parameters

request – the request from the client.

sendData(data)

Sends the data to the client.

Parameters

data (object) – the object that is to be sent to the client. This should be one of the RPC message types.

valid_session()

class deluge.core.rpcserver.RPCServer(port=58846, interface='', allow_remote=False, listen=True)

Bases: deluge.component.Component

This class is used to handle rpc requests from the client. Objects are registered with this class and their methods are exported using the export decorator.

Parameters

• port (int) – the port the RPCServer will listen on

• interface (str) – the interface to listen on, this may override the allow_remote setting

• allow_remote (bool) – set True if the server should allow remote connections

• listen (bool) – if False, will not start listening.. This is only useful in Classic Mode

deregister_object(obj)

Deregisters an objects exported rpc methods.

Parameters

obj – the object that was previously registered

emit_event(event)

Emits the event to interested clients.

Parameters

event (deluge.event.DelugeEvent) – the event to emit

emit_event_for_session_id(session_id, event)

Emits the event to specified session_id.

Parameters

• session_id (int) – the event to emit

• event (deluge.event.DelugeEvent) – the event to emit

get_method_list()

Returns a list of the exported methods.

Returns

the exported methods

Return type

list

get_object_method(name)

Returns a registered method.

Parameters

name (str) – the name of the method, usually in the form of ‘object.method’

Returns

method

Raises

KeyError – if name is not registered

get_rpc_auth_level(rpc)

Returns the auth level requirement for an exported rpc.

Returns

the auth level

Return type

int

get_session_auth_level()

Returns the auth level of the user calling the current RPC.

Returns

the auth level

Return type

int

get_session_id()

Returns the session id of the current RPC.

Returns

the session id, this will be -1 if no connections have been made

Return type

int

get_session_user()

Returns the username calling the current RPC.

Returns

the username of the user calling the current RPC

Return type

string

is_session_valid(session_id)

Checks if the session is still valid, eg, if the client is still connected.

Parameters

session_id (int) – the session id

Returns

True if the session is valid

Return type

bool

register_object(obj, name=None)

Registers an object to export it’s rpc methods. These methods should be exported with the export decorator prior to registering the object.

Parameters

• obj (object) – the object that we want to export

• name (str) – the name to use, if None, it will be the class name of the object

stop()

deluge.core.rpcserver.export(func: deluge.core.rpcserver.TCallable) → deluge.core.rpcserver.TCallable

deluge.core.rpcserver.export(auth_level: int) → Callable[[deluge.core.rpcserver.TCallable], deluge.core.rpcserver.TCallable]

Decorator function to register an object’s method as an RPC. The object will need to be registered with an RPCServer to be effective.

Parameters

• func (function) – the function to export

• auth_level (int) – the auth level required to call this method

deluge.core.rpcserver.format_request(call)

Format the RPCRequest message for debug printing

Parameters

call (a RPCRequest) – the request

Returns

a formatted string for printing

Return type

str

deluge.core.torrent module

Internal Torrent class

deluge.core.torrent.LT_TORRENT_STATE_MAP

Maps the torrent state from libtorrent to Deluge state.

Type

dict

class deluge.core.torrent.Torrent(handle, options, state=None, filename=None, magnet=None)

Bases: object

Torrent holds information about torrents added to the libtorrent session.

Parameters

• handle – The libtorrent torrent handle.

• options (dict) – The torrent options.

• state (TorrentState) – The torrent state.

• filename (str) – The filename of the torrent file.

• magnet (str) – The magnet URI.

torrent_id

The torrent_id for this torrent

Type

str

handle

Holds the libtorrent torrent handle

magnet

The magnet URI used to add this torrent (if available).

Type

str

status

Holds status info so that we don”t need to keep getting it from libtorrent.

torrent_info

store the torrent info.

has_metadata

True if the metadata for the torrent is available, False otherwise.

Type

bool

status_funcs

The function mappings to get torrent status

Type

dict

prev_status

Previous status dicts returned for this torrent. We use this to return dicts that only contain changes from the previous. {session_id: status_dict, …}

Type

dict

waiting_on_folder_rename

A list of Deferreds for file indexes we’re waiting for file_rename alerts on. This is so we can send one folder_renamed signal instead of multiple file_renamed signals. [{index: Deferred, …}, …]

Type

list of dict

options

The torrent options.

Type

dict

filename

The filename of the torrent file in case it is required.

Type

str

is_finished

Keep track if torrent is finished to prevent some weird things on state load.

Type

bool

statusmsg

Status message holds error/extra info about the torrent.

Type

str

state

The torrent’s state

Type

str

trackers

The torrent’s trackers

Type

list of dict

tracker_status

Status message of currently connected tracker

Type

str

tracker_host

Hostname of the currently connected tracker

Type

str

forcing_recheck

Keep track if we’re forcing a recheck of the torrent

Type

bool

forcing_recheck_paused

Keep track if we’re forcing a recheck of the torrent so that we can re-pause it after its done if necessary

Type

bool

forced_error

Keep track if we have forced this torrent to be in Error state.

Type

TorrentError

cleanup_prev_status()

Checks the validity of the keys in the prev_status dict.

If the key is no longer valid, the dict will be deleted.

clear_forced_error_state(update_state=True)

connect_peer(peer_ip, peer_port)

Manually add a peer to the torrent

Parameters

• peer_ip (str) – Peer IP Address

• peer_port (int) – Peer Port

Returns

bool – True is successful, otherwise False

delete_torrentfile(delete_copies=False)

Deletes the .torrent file in the state directory in config

force_error_state(message, restart_to_resume=True)

Forces the torrent into an error state.

For setting an error state not covered by libtorrent.

Parameters

• message (str) – The error status message.

• restart_to_resume (bool, optional) – Prevent resuming clearing the error, only restarting session can resume.

force_reannounce()

Force a tracker reannounce

force_recheck()

Forces a recheck of the torrent’s pieces

get_eta()

Get the ETA for this torrent.

Returns

int – The ETA in seconds.

get_file_priorities()

Return the file priorities

get_file_progress()

Calculates the file progress as a percentage.

Returns

list of floats – The file progress (0.0 -> 1.0), empty list if n/a.

get_files()

Get the files this torrent contains.

Returns

list of dict – The files.

get_lt_status()

Get the torrent status fresh, not from cache.

This should be used when a guaranteed fresh status is needed rather than torrent.handle.status() because it will update the cache as well.

Return type

torrent_status

get_magnet_uri()

Returns a magnet URI for this torrent

get_name()

The name of the torrent (distinct from the filenames).

Note

Can be manually set in options through name key. If the key is reset to empty string “” it will return the original torrent name.

Returns

str – the name of the torrent.

get_options()

Get the torrent options.

Returns

dict – the torrent options.

get_orig_files()

Get the original filenames of files in this torrent.

Returns

list of dict – The files with original filenames.

get_peers()

Get the peers for this torrent.

A list of peers and various information about them.

Returns

list of dict – The peers.

The format for the peer dict:

{
    "client": str,
    "country": str,
    "down_speed": int,
    "ip": str,
    "progress": float,
    "seed": bool,
    "up_speed": int
}

get_progress()

The progress of this torrent’s current task.

Returns

float – The progress percentage (0 to 100).

get_queue_position()

Get the torrents queue position

Returns

int – queue position

get_ratio()

Get the ratio of upload/download for this torrent.

Returns

float – The ratio or -1.0 (for infinity).

get_status(keys, diff=False, update=False, all_keys=False)

Returns the status of the torrent based on the keys provided

Parameters

• keys (list of str) – the keys to get the status on

• diff (bool) – Will return a diff of the changes since the last call to get_status based on the session_id

• update (bool) – If True the status will be updated from libtorrent if False, the cached values will be returned

• all_keys (bool) – If True return all keys while ignoring the keys param if False, return only the requested keys

Returns

dict – a dictionary of the status keys and their values

get_time_since_transfer()

The time since either upload/download from peers

get_tracker_host()

Get the hostname of the currently connected tracker.

If no tracker is connected, it uses the 1st tracker.

Returns

str – The tracker host

merge_trackers(torrent_info)

Merges new trackers in torrent_info into torrent

move_storage(dest)

Move a torrent’s storage location

Parameters

dest (str) – The destination folder for the torrent data

Returns

bool – True if successful, otherwise False

on_metadata_received()

Process the metadata received alert for this torrent

pause()

Pause this torrent.

Returns

bool – True is successful, otherwise False.

remove_empty_folders(folder)

Recursively removes folders but only if they are empty.

This cleans up after libtorrent folder renames.

Parameters

folder (str) – The folder to recursively check

rename_files(filenames)

Renames files in the torrent.

Parameters

filenames (list) – A list of (index, filename) pairs.

rename_folder(folder, new_folder)

Renames a folder within a torrent.

This basically does a file rename on all of the folders children.

Parameters

• folder (str) – The original folder name

• new_folder (str) – The new folder name

Returns

twisted.internet.defer.Deferred – A deferred which fires when the rename is complete

resume()

Resumes this torrent.

save_resume_data(flush_disk_cache=False)

Signals libtorrent to build resume data for this torrent.

Parameters

flush_disk_cache (bool) – Avoids potential issue with file timestamps and is only needed when stopping the session.

Returns

None – The response with resume data is returned in a libtorrent save_resume_data_alert.

scrape_tracker()

Scrape the tracker

A scrape request queries the tracker for statistics such as total number of incomplete peers, complete peers, number of downloads etc.

set_auto_managed(auto_managed)

Set auto managed mode, i.e. will be started or queued automatically.

Parameters

auto_managed (bool) – Enable auto managed.

set_download_location(download_location)

The location for downloading torrent data.

set_file_priorities(file_priorities)

Sets the file priotities.

Parameters

file_priorities (list of int) – List of file priorities.

set_max_connections(max_connections)

Sets maximum number of connections this torrent will open.

Parameters

max_connections (int) – Maximum number of connections

Note

The minimum value for handle.max_connections is 2 (or -1 for unlimited connections). This is enforced by libtorrent and values 0 or 1 raise an assert with lt debug builds.

set_max_download_speed(m_down_speed)

Sets maximum download speed for this torrent.

Parameters

m_down_speed (float) – Maximum download speed in KiB/s.

set_max_upload_slots(max_slots)

Sets maximum number of upload slots for this torrent.

Parameters

max_slots (int) – Maximum upload slots

set_max_upload_speed(m_up_speed)

Sets maximum upload speed for this torrent.

Parameters

m_up_speed (float) – Maximum upload speed in KiB/s.

set_move_completed(move_completed)

Set whether to move the torrent when downloading has finished.

Parameters

move_completed (bool) – Move the torrent.

set_move_completed_path(move_completed_path)

Set the path to move torrent to when downloading has finished.

Parameters

move_completed_path (str) – The move path.

set_options(options)

Set the torrent options.

Parameters

options (dict) – Torrent options, see TorrentOptions class for valid keys.

set_owner(account)

Sets the owner of this torrent.

Parameters

account (str) – The new owner account name.

Notes

Only a user with admin level auth can change this value.

set_prioritize_first_last(prioritize)

Deprecated: Use set_prioritize_first_last_pieces.

set_prioritize_first_last_pieces(prioritize)

Prioritize the first and last pieces in the torrent.

Parameters

prioritize (bool) – Prioritize the first and last pieces.

set_remove_at_ratio(remove_at_ratio)

Remove the torrent when it has reached the stop_ratio.

Parameters

remove_at_ratio (bool) – Remove the torrent.

set_save_path(download_location)

Deprecated: Use set_download_location.

set_sequential_download(sequential)

Sets whether to download the pieces of the torrent in order.

Parameters

sequential (bool) – Enable sequential downloading.

set_status_message(message=None)

Sets the torrent status message.

Calling method without a message will reset the message to ‘OK’.

Parameters

message (str, optional) – The status message.

set_stop_at_ratio(stop_at_ratio)

Stop the torrent when it has reached stop_ratio.

Parameters

stop_at_ratio (bool) – Stop the torrent.

set_stop_ratio(stop_ratio)

The seeding ratio to stop (or remove) the torrent at.

Parameters

stop_ratio (float) – The seeding ratio.

set_super_seeding(super_seeding)

Set super seeding/initial seeding.

Parameters

super_seeding (bool) – Enable super seeding.

set_tracker_status(status)

Sets the tracker status.

Parameters

status (str) – The tracker status.

Emits:

TorrentTrackerStatusEvent upon tracker status change.

set_trackers(trackers=None)

Sets the trackers for this torrent.

Parameters

trackers (list of dicts) – A list of trackers.

property status: deluge._libtorrent.lt.torrent_status

Cached copy of the libtorrent status for this torrent.

If it has not been updated within the last five seconds, it will be automatically refreshed.

Return type

torrent_status

update_state()

Updates the state, based on libtorrent’s torrent state

write_torrentfile(filedump=None)

Writes the torrent file to the state dir and optional ‘copy of’ dir.

Parameters

filedump (str, optional) – bencoded filedump of a torrent file.

class deluge.core.torrent.TorrentError(error_message, was_paused=False, restart_to_resume=False)

Bases: object

class deluge.core.torrent.TorrentOptions

Bases: dict

TorrentOptions create a dict of the torrent options.

add_paused

Add the torrrent in a paused state.

Type

bool

auto_managed

Set torrent to auto managed mode, i.e. will be started or queued automatically.

Type

bool

download_location

The path for the torrent data to be stored while downloading.

Type

str

file_priorities

The priority for files in torrent, range is [0..7] however only [0, 1, 4, 7] are normally used and correspond to [Skip, Low, Normal, High]

Type

list of int

mapped_files

A mapping of the renamed filenames in ‘index:filename’ pairs.

Type

dict

max_connections

Sets maximum number of connections this torrent will open. This must be at least 2. The default is unlimited (-1).

Type

int

max_download_speed

Will limit the download bandwidth used by this torrent to the limit you set.The default is unlimited (-1) but will not exceed global limit.

Type

float

max_upload_slots

Sets the maximum number of peers that are unchoked at the same time on this torrent. This defaults to infinite (-1).

Type

int

max_upload_speed

Will limit the upload bandwidth used by this torrent to the limit you set. The default is unlimited (-1) but will not exceed global limit.

Type

float

move_completed

Move the torrent when downloading has finished.

Type

bool

move_completed_path

The path to move torrent to when downloading has finished.

Type

str

name

The display name of the torrent.

Type

str

owner

The user this torrent belongs to.

Type

str

pre_allocate_storage

When adding the torrent should all files be pre-allocated.

Type

bool

prioritize_first_last_pieces

Prioritize the first and last pieces in the torrent.

Type

bool

remove_at_ratio

Remove the torrent when it has reached the stop_ratio.

Type

bool

seed_mode

Assume that all files are present for this torrent (Only used when adding a torent).

Type

bool

sequential_download

Download the pieces of the torrent in order.

Type

bool

shared

Enable the torrent to be seen by other Deluge users.

Type

bool

stop_at_ratio

Stop the torrent when it has reached stop_ratio.

Type

bool

stop_ratio

The seeding ratio to stop (or remove) the torrent at.

Type

float

super_seeding

Enable super seeding/initial seeding.

Type

bool

deluge.core.torrent.convert_lt_files(files)

Indexes and decodes files from libtorrent get_files().

Parameters

files (file_storage) – The libtorrent torrent files.

Returns

list of dict – The files.

The format for the file dict:

{
    "index": int,
    "path": str,
    "size": int,
    "offset": int
}

deluge.core.torrent.sanitize_filepath(filepath, folder=False)

Returns a sanitized filepath to pass to libtorrent rename_file().

The filepath will have backslashes substituted along with whitespace padding and duplicate slashes stripped.

Parameters

folder (bool) – A trailing slash is appended to the returned filepath.

deluge.core.torrentmanager module

Module contents