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: Component

AlertManager fetches and processes libtorrent alerts

cancel_delayed_calls(): Cancel all delayed handlers.

check_delayed_calls()

Returns True if any handler calls are delayed.

Return type:: bool

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.

maybe_handle_alerts()

Return type:: None

on_delayed_call_timeout(result, timeout, **kwargs)

pause()

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

resume()

set_alert_queue_size(queue_size): Sets the maximum size of the libtorrent alert queue

start()

stop()

update()

wait_for_alert_in_thread()

deluge.core.authmanager module

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

Bases: object

authlevel

data()

password

username

class deluge.core.authmanager.AuthManager

Bases: 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: 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: 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: PluginManagerBase, 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: 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: 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(auth_level=5)

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.

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 package

Submodules

deluge.core.alertmanager module

deluge.core.authmanager module

deluge.core.core module

deluge.core.daemon module

deluge.core.daemon_entry module

deluge.core.eventmanager module

deluge.core.filtermanager module

deluge.core.pluginmanager module

deluge.core.preferencesmanager module

deluge.core.rpcserver module

deluge.core.torrent module

deluge.core.torrentmanager module

Module contents