transmissionrpc — Module reference

This documentation will not describe all RPC fields in detail. Please refer to the RPC specification for more information on RPC data.

Exceptions

class transmissionrpc.TransmissionError(message='', original=None)

This exception is raised when there has occurred an error related to communication with Transmission. It is a subclass of Exception.

original

The original exception.

class transmissionrpc.HTTPHandlerError(httpurl=None, httpcode=None, httpmsg=None, httpheaders=None, httpdata=None)

This exception is raised when there has occurred an error related to the HTTP handler. It is a subclass of Exception.

url

The requested url.

code

HTTP error code.

message

HTTP error message.

headers

HTTP headers.

data

HTTP data.

Torrent object

Torrent is a class holding the information received from Transmission regarding a bittorrent transfer.

Attributes

All fetched torrent fields are accessible through this class using attributes. The attributes use underscore instead of hyphen in the names though. This class has a few convenience attributes using the torrent information.

Example:

>>> import transmissionrpc
>>> t = transmissionrpc.Torrent(None, {'id': 1, 'comment': 'My torrent', 'addedDate': 1232281019})
>>> t.comment
'My torrent'
>>> t.date_added
datetime.datetime(2009, 1, 18, 13, 16, 59)
>>>

Transmission returns following fields.

Argument RPC Description
activityDate 1 - Last time of upload or download activity.
addedDate 1 - The date when this torrent was first added.
announceResponse 1 - 7 The announce message from the tracker.
announceURL 1 - 7 Current announce URL.
bandwidthPriority 5 - Bandwidth priority. Low (-1), Normal (0) or High (1).
comment 1 - Torrent comment.
corruptEver 1 - Number of bytes of corrupt data downloaded.
creator 1 - Torrent creator.
dateCreated 1 - Torrent creation date.
desiredAvailable 1 - Number of bytes avalable and left to be downloaded.
doneDate 1 - The date when the torrent finished downloading.
downloadDir 4 - The directory path where the torrent is downloaded to.
downloadLimit 1 - Download limit in Kbps.
downloadLimitMode 1 - 5 Download limit mode. 0 means global, 1 means signle, 2 unlimited.
downloadLimited 5 - Download limit is enabled
downloadedEver 1 - Number of bytes of good data downloaded.
downloaders 4 - 7 Number of downloaders.
error 1 - Kind of error. 0 means OK, 1 means tracker warning, 2 means tracker error, 3 means local error.
errorString 1 - Error message.
eta 1 - Estimated number of seconds left when downloading or seeding. -1 means not available and -2 means unknown.
fileStats 5 - Aray of file statistics containing bytesCompleted, wanted and priority.
files 1 - Array of file object containing key, bytesCompleted, length and name.
hashString 1 - Hashstring unique for the torrent even between sessions.
haveUnchecked 1 - Number of bytes of partial pieces.
haveValid 1 - Number of bytes of checksum verified data.
honorsSessionLimits 5 - True if session upload limits are honored
id 1 - Session unique torrent id.
isFinished 9 - True if the torrent is finished. Downloaded and seeded.
isPrivate 1 - True if the torrent is private.
isStalled 14 - True if the torrent has stalled (been idle for a long time).
lastAnnounceTime 1 - 7 The time of the last announcement.
lastScrapeTime 1 - 7 The time af the last successful scrape.
leechers 1 - 7 Number of leechers.
leftUntilDone 1 - Number of bytes left until the download is done.
magnetLink 7 - The magnet link for this torrent.
manualAnnounceTime 1 - The time until you manually ask for more peers.
maxConnectedPeers 1 - Maximum of connected peers.
metadataPercentComplete 7 - Download progress of metadata. 0.0 to 1.0.
name 1 - Torrent name.
nextAnnounceTime 1 - 7 Next announce time.
nextScrapeTime 1 - 7 Next scrape time.
peer_limit 5 - Maximum number of peers.
peers 2 - Array of peer objects.
peersConnected 1 - Number of peers we are connected to.
peersFrom 1 - Object containing download peers counts for different peer types.
peersGettingFromUs 1 - Number of peers we are sending data to.
peersKnown 1 - 13 Number of peers that the tracker knows.
peersSendingToUs 1 - Number of peers sending to us
percentDone 5 - Download progress of selected files. 0.0 to 1.0.
pieceCount 1 - Number of pieces.
pieceSize 1 - Number of bytes in a piece.
pieces 5 - String with base64 encoded bitfield indicating finished pieces.
priorities 1 - Array of file priorities.
queuePosition 14 - The queue position.
rateDownload 1 - Download rate in bps.
rateUpload 1 - Upload rate in bps.
recheckProgress 1 - Progress of recheck. 0.0 to 1.0.
scrapeResponse 1 - 7 Scrape response message.
scrapeURL 1 - 7 Current scrape URL
seedIdleLimit 10 - Idle limit in minutes.
seedIdleMode 10 - Use global (0), torrent (1), or unlimited (2) limit.
seedRatioLimit 5 - Seed ratio limit.
seedRatioMode 5 - Use global (0), torrent (1), or unlimited (2) limit.
seeders 1 - 7 Number of seeders reported by the tracker.
sizeWhenDone 1 - Size of the torrent download in bytes.
startDate 1 - The date when the torrent was last started.
status 1 - Current status, see source
swarmSpeed 1 - 7 Estimated speed in Kbps in the swarm.
timesCompleted 1 - 7 Number of successful downloads reported by the tracker.
torrentFile 5 - Path to .torrent file.
totalSize 1 - Total size of the torrent in bytes
trackerStats 7 - Array of object containing tracker statistics.
trackers 1 - Array of tracker objects.
uploadLimit 1 - Upload limit in Kbps
uploadLimitMode 1 - 5 Upload limit mode. 0 means global, 1 means signle, 2 unlimited.
uploadLimited 5 - Upload limit enabled.
uploadRatio 1 - Seed ratio.
uploadedEver 1 - Number of bytes uploaded, ever.
wanted 1 - Array of booleans indicated wanted files.
webseeds 1 - Array of webseeds objects
webseedsSendingToUs 1 - Number of webseeds seeding to us.

Mutators

Some attributes can be changed, these are called mutators. These changes will be sent to the server when changed. To reload information from Transmission use update().

Example:

>>> import transmissionrpc
>>> c = transmissionrpc.Client()
>>> t = c.get_torrent(0)
>>> t.peer_limit
10
>>> t.peer_limit = 20
>>> t.update()
>>> t.peer_limit
20

Reference

class transmissionrpc.Torrent(client, fields)

Torrent is a class holding the data received from Transmission regarding a bittorrent transfer.

All fetched torrent fields are accessible through this class using attributes. This class has a few convenience properties using the torrent data.

date_active

Get the attribute “activityDate” as datetime.datetime.

date_added

Get the attribute “addedDate” as datetime.datetime.

date_done

Get the attribute “doneDate” as datetime.datetime.

date_started

Get the attribute “startDate” as datetime.datetime.

download_limit

Download limit in Kbps or None. This is a mutator.

eta

Get the “eta” as datetime.timedelta.

files()

Get list of files for this torrent.

This function returns a dictionary with file information for each file. The file information is has following fields:

{
    <file id>: {
        'name': <file name>,
        'size': <file size in bytes>,
        'completed': <bytes completed>,
        'priority': <priority ('high'|'normal'|'low')>,
        'selected': <selected for download>
    }
    ...
}
format_eta()

Returns the attribute eta formatted as a string.

  • If eta is -1 the result is ‘not available’
  • If eta is -2 the result is ‘unknown’
  • Otherwise eta is formatted as <days> <hours>:<minutes>:<seconds>.
locate_data(location, timeout=None)

Locate torrent data at location.

move_data(location, timeout=None)

Move torrent data to location.

peer_limit

Peer limit. This is a mutator.

priority

Bandwidth priority as string. Can be one of ‘low’, ‘normal’, ‘high’. This is a mutator.

progress

Get the download progress in percent.

queue_position

Queue position

ratio

Get the upload/download ratio.

seed_idle_limit

Torrent seed idle limit in minutes. Also see seed_idle_mode. This is a mutator.

seed_idle_mode

Seed idle mode as string. Can be one of ‘global’, ‘single’ or ‘unlimited’.

  • global, use session seed idle limit.
  • single, use torrent seed idle limit. See seed_idle_limit.
  • unlimited, no seed idle limit.

This is a mutator.

seed_ratio_limit

Torrent seed ratio limit as float. Also see seed_ratio_mode. This is a mutator.

seed_ratio_mode

Seed ratio mode as string. Can be one of ‘global’, ‘single’ or ‘unlimited’.

  • global, use session seed ratio limit.
  • single, use torrent seed ratio limit. See seed_ratio_limit.
  • unlimited, no seed ratio limit.

This is a mutator.

start(bypass_queue=False, timeout=None)

Start the torrent.

status

Returns the torrent status. Is either one of ‘check pending’, ‘checking’, ‘downloading’, ‘seeding’ or ‘stopped’. The first two is related to verification.

stop(timeout=None)

Stop the torrent.

update(timeout=None)

Update the torrent information.

upload_limit

Upload limit in Kbps or None. This is a mutator.

Session object

Session is a class holding the session data for a Transmission session.

Attributes

Access the session field can be done through attributes. The attributes available are the same as the session arguments in the Transmission RPC specification, but with underscore instead of hyphen. download-dir -> download_dir.

Transmission returns following fields.

Argument RPC Replaced by Description
alt_speed_down 5 -   Alternate session download speed limit (in Kib/s).
alt_speed_enabled 5 -   True if alternate global download speed limiter is ebabled.
alt_speed_time_begin 5 -   Time when alternate speeds should be enabled. Minutes after midnight.
alt_speed_time_day 5 -   Days alternate speeds scheduling is enabled.
alt_speed_time_enabled 5 -   True if alternate speeds scheduling is enabled.
alt_speed_time_end 5 -   Time when alternate speeds should be disabled. Minutes after midnight.
alt_speed_up 5 -   Alternate session upload speed limit (in Kib/s)
blocklist_enabled 5 -   True when blocklist is enabled.
blocklist_size 5 -   Number of rules in the blocklist
blocklist_url 11 -   Location of the block list. Updated with blocklist-update.
cache_size_mb 10 -   The maximum size of the disk cache in MB
config_dir 8 -   location of transmissions configuration directory
dht_enabled 6 -   True if DHT enabled.
download_dir 1 -   The download directory.
download_dir_free_space 12 -   Free space in the download directory, in bytes
download_queue_enabled 14 -   True if the download queue is enabled.
download_queue_size 14 -   Number of slots in the download queue.
encryption 1 -   Encryption mode, one of required, preferred or tolerated.
idle_seeding_limit 10 -   Seed inactivity limit in minutes.
idle_seeding_limit_enabled 10 -   True if the seed activity limit is enabled.
incomplete_dir 7 -   The path to the directory for incomplete torrent transfer data.
incomplete_dir_enabled 7 -   True if the incomplete dir is enabled.
lpd_enabled 9 -   True if local peer discovery is enabled.
peer_limit 1 - 5 peer-limit-global Maximum number of peers.
peer_limit_global 5 -   Maximum number of peers.
peer_limit_per_torrent 5 -   Maximum number of peers per transfer.
peer_port 5 -   Peer port.
peer_port_random_on_start 5 -   Enables randomized peer port on start of Transmission.
pex_allowed 1 - 5 pex-enabled True if PEX is allowed.
pex_enabled 5 -   True if PEX is enabled.
port 1 - 5 peer-port Peer port.
port_forwarding_enabled 1 -   True if port forwarding is enabled.
queue_stalled_enabled 14 -   True if stalled tracking of transfers is enabled.
queue_stalled_minutes 14 -   Number of minutes of idle that marks a transfer as stalled.
rename_partial_files 8 -   True if ”.part” is appended to incomplete files
rpc_version 4 -   Transmission RPC API Version.
rpc_version_minimum 4 -   Minimum accepted RPC API Version.
script_torrent_done_enabled 9 -   True if the done script is enabled.
script_torrent_done_filename 9 -   Filename of the script to run when the transfer is done.
seed_queue_enabled 14 -   True if upload queue is enabled.
seed_queue_size 14 -   Number of slots in the upload queue.
seedRatioLimit 5 -   Seed ratio limit. 1.0 means 1:1 download and upload ratio.
seedRatioLimited 5 -   True if seed ration limit is enabled.
speed_limit_down 1 -   Download speed limit (in Kib/s).
speed_limit_down_enabled 1 -   True if the download speed is limited.
speed_limit_up 1 -   Upload speed limit (in Kib/s).
speed_limit_up_enabled 1 -   True if the upload speed is limited.
start_added_torrents 9 -   When true uploaded torrents will start right away.
trash_original_torrent_files 9 -   When true added .torrent files will be deleted.
units 10 -   An object containing units for size and speed.
utp_enabled 13 -   True if Micro Transport Protocol (UTP) is enabled.
version 3 -   Transmission version.

Mutators

Some attributes can be changed, these are called mutators. These changes will be sent to the server when changed. To reload information from Transmission use update().

Reference

class transmissionrpc.Session(client=None, fields=None)

Session is a class holding the session data for a Transmission daemon.

Access the session field can be done through attributes. The attributes available are the same as the session arguments in the Transmission RPC specification, but with underscore instead of hyphen. download-dir -> download_dir.

from_request(data)

Update the session information.

peer_port

Peer port. This is a mutator.

pex_enabled

Enable peer exchange. This is a mutator.

update(timeout=None)

Update the session information.

Client object

This class implements the JSON-RPC protocol to communicate with Transmission.

Torrent ids

Many functions in Client takes torrent id. A torrent id can either be id or hashString. When supplying multiple id’s it is possible to use a list mixed with both id and hashString.

Timeouts

In Python 2.6 it is possible to supply a timeout to a HTTP request. This is accessible through transmissionrpc by either changing the timeout property of a Client object or supply the named argument timeout in most methods of Client. The default timeout is 30 seconds.

Reference

class transmissionrpc.Client(address='localhost', port=9091, user=None, password=None, http_handler=None, timeout=None)

Client is the class handling the Transmission JSON-RPC client protocol.

add(data, timeout=None, **kwargs)

Warning

Deprecated, please use add_torrent.

add_torrent(torrent, timeout=None, **kwargs)

Add torrent to transfers list. Takes a uri to a torrent or base64 encoded torrent data in torrent. Additional arguments are:

Argument RPC Replaced by Description
bandwidthPriority 8 -   Priority for this transfer.
cookies 13 -   One or more HTTP cookie(s).
download_dir 1 -   The directory where the downloaded contents will be saved in.
files_unwanted 1 -   A list of file id’s that shouldn’t be downloaded.
files_wanted 1 -   A list of file id’s that should be downloaded.
paused 1 -   If True, does not start the transfer when added.
peer_limit 1 -   Maximum number of peers allowed.
priority_high 1 -   A list of file id’s that should have high priority.
priority_low 1 -   A list of file id’s that should have low priority.
priority_normal 1 -   A list of file id’s that should have normal priority.

Returns a Torrent object with the fields.

add_uri(uri, **kwargs)

Warning

Deprecated, please use add_torrent.

blocklist_update(timeout=None)

Update block list. Returns the size of the block list.

change(ids, timeout=None, **kwargs)

Warning

Deprecated, please use change_torrent.

change_torrent(ids, timeout=None, **kwargs)

Change torrent parameters for the torrent(s) with the supplied id’s. The parameters are:

Argument RPC Replaced by Description
bandwidthPriority 5 -   Priority for this transfer.
downloadLimit 5 -   Set the speed limit for download in Kib/s.
downloadLimited 5 -   Enable download speed limiter.
files_unwanted 1 -   A list of file id’s that shouldn’t be downloaded.
files_wanted 1 -   A list of file id’s that should be downloaded.
honorsSessionLimits 5 -   Enables or disables the transfer to honour the upload limit set in the session.
location 1 -   Local download location.
peer_limit 1 -   The peer limit for the torrents.
priority_high 1 -   A list of file id’s that should have high priority.
priority_low 1 -   A list of file id’s that should have normal priority.
priority_normal 1 -   A list of file id’s that should have low priority.
queuePosition 14 -   Position of this transfer in its queue.
seedIdleLimit 10 -   Seed inactivity limit in minutes.
seedIdleMode 10 -   Seed inactivity mode. 0 = Use session limit, 1 = Use transfer limit, 2 = Disable limit.
seedRatioLimit 5 -   Seeding ratio.
seedRatioMode 5 -   Which ratio to use. 0 = Use session limit, 1 = Use transfer limit, 2 = Disable limit.
speed_limit_down 1 - 5 downloadLimit Set the speed limit for download in Kib/s.
speed_limit_down_enabled 1 - 5 downloadLimited Enable download speed limiter.
speed_limit_up 1 - 5 uploadLimit Set the speed limit for upload in Kib/s.
speed_limit_up_enabled 1 - 5 uploadLimited Enable upload speed limiter.
trackerAdd 10 -   Array of string with announce URLs to add.
trackerRemove 10 -   Array of ids of trackers to remove.
trackerReplace 10 -   Array of (id, url) tuples where the announce URL should be replaced.
uploadLimit 5 -   Set the speed limit for upload in Kib/s.
uploadLimited 5 -   Enable upload speed limiter.

Note

transmissionrpc will try to automatically fix argument errors.

free_space(path, timeout=None)

Get the ammount of free space (in bytes) at the provided location.

get_files(ids=None, timeout=None)

Get list of files for provided torrent id(s). If ids is empty, information for all torrents are fetched. This function returns a dictionary for each requested torrent id holding the information about the files.

{
        <torrent id>: {
                <file id>: {
                        'name': <file name>,
                        'size': <file size in bytes>,
                        'completed': <bytes completed>,
                        'priority': <priority ('high'|'normal'|'low')>,
                        'selected': <selected for download (True|False)>
                }

                ...
        }

        ...
}
get_session(timeout=None)

Get session parameters. See the Session class for more information.

get_torrent(torrent_id, arguments=None, timeout=None)

Get information for torrent with provided id. arguments contains a list of field names to be returned, when None all fields are requested. See the Torrent class for more information.

Returns a Torrent object with the requested fields.

get_torrents(ids=None, arguments=None, timeout=None)

Get information for torrents with provided ids. For more information see get_torrent.

Returns a list of Torrent object.

info(ids=None, arguments=None, timeout=None)

Warning

Deprecated, please use get_torrent or get_torrents. Please note that the return argument has changed in the new methods. info returns a dictionary indexed by torrent id.

list(timeout=None)

Warning

Deprecated, please use get_torrent or get_torrents. Please note that the return argument has changed in the new methods. list returns a dictionary indexed by torrent id.

locate(ids, location, timeout=None)

Warning

Deprecated, please use locate_torrent_data.

locate_torrent_data(ids, location, timeout=None)

Locate torrent data at the provided location.

move(ids, location, timeout=None)

Warning

Deprecated, please use move_torrent_data.

move_torrent_data(ids, location, timeout=None)

Move torrent data to the new location.

port_test(timeout=None)

Tests to see if your incoming peer port is accessible from the outside world.

queue_bottom(ids, timeout=None)

Move transfer to the bottom of the queue.

queue_down(ids, timeout=None)

Move transfer down in the queue.

queue_top(ids, timeout=None)

Move transfer to the top of the queue.

queue_up(ids, timeout=None)

Move transfer up in the queue.

reannounce(ids, timeout=None)

Warning

Deprecated, please use reannounce_torrent.

reannounce_torrent(ids, timeout=None)

Reannounce torrent(s) with provided id(s)

remove(ids, delete_data=False, timeout=None)

Warning

Deprecated, please use remove_torrent.

remove_torrent(ids, delete_data=False, timeout=None)

remove torrent(s) with provided id(s). Local data is removed if delete_data is True, otherwise not.

rename_torrent_path(torrent_id, location, name, timeout=None)

Rename directory and/or files for torrent. Remember to use get_torrent or get_torrents to update your file information.

rpc_version

Get the Transmission RPC version. Trying to deduct if the server don’t have a version value.

session_stats(timeout=None)

Get session statistics

set_files(items, timeout=None)

Set file properties. Takes a dictionary with similar contents as the result of get_files.

{
        <torrent id>: {
                <file id>: {
                        'priority': <priority ('high'|'normal'|'low')>,
                        'selected': <selected for download (True|False)>
                }

                ...
        }

        ...
}
set_session(timeout=None, **kwargs)

Set session parameters. The parameters are:

Argument RPC Replaced by Description
alt_speed_down 5 -   Alternate session download speed limit (in Kib/s).
alt_speed_enabled 5 -   Enables alternate global download speed limiter.
alt_speed_time_begin 5 -   Time when alternate speeds should be enabled. Minutes after midnight.
alt_speed_time_day 5 -   Enables alternate speeds scheduling these days.
alt_speed_time_enabled 5 -   Enables alternate speeds scheduling.
alt_speed_time_end 5 -   Time when alternate speeds should be disabled. Minutes after midnight.
alt_speed_up 5 -   Alternate session upload speed limit (in Kib/s).
blocklist_enabled 5 -   Enables the block list
blocklist_url 11 -   Location of the block list. Updated with blocklist-update.
cache_size_mb 10 -   The maximum size of the disk cache in MB
dht_enabled 6 -   Enables DHT.
download_dir 1 -   Set the session download directory.
download_queue_enabled 14 -   Enables download queue.
download_queue_size 14 -   Number of slots in the download queue.
encryption 1 -   Set the session encryption mode, one of required, preferred or tolerated.
idle_seeding_limit 10 -   The default seed inactivity limit in minutes.
idle_seeding_limit_enabled 10 -   Enables the default seed inactivity limit
incomplete_dir 7 -   The path to the directory of incomplete transfer data.
incomplete_dir_enabled 7 -   Enables the incomplete transfer data directory. Otherwise data for incomplete transfers are stored in the download target.
lpd_enabled 9 -   Enables local peer discovery for public torrents.
peer_limit 1 - 5 peer-limit-global Maximum number of peers.
peer_limit_global 5 -   Maximum number of peers.
peer_limit_per_torrent 5 -   Maximum number of peers per transfer.
peer_port 5 -   Peer port.
peer_port_random_on_start 5 -   Enables randomized peer port on start of Transmission.
pex_allowed 1 - 5 pex-enabled Allowing PEX in public torrents.
pex_enabled 5 -   Allowing PEX in public torrents.
port 1 - 5 peer-port Peer port.
port_forwarding_enabled 1 -   Enables port forwarding.
queue_stalled_enabled 14 -   Enable tracking of stalled transfers.
queue_stalled_minutes 14 -   Number of minutes of idle that marks a transfer as stalled.
rename_partial_files 8 -   Appends ”.part” to incomplete files
script_torrent_done_enabled 9 -   Whether or not to call the “done” script.
script_torrent_done_filename 9 -   Filename of the script to run when the transfer is done.
seed_queue_enabled 14 -   Enables upload queue.
seed_queue_size 14 -   Number of slots in the upload queue.
seedRatioLimit 5 -   Seed ratio limit. 1.0 means 1:1 download and upload ratio.
seedRatioLimited 5 -   Enables seed ration limit.
speed_limit_down 1 -   Download speed limit (in Kib/s).
speed_limit_down_enabled 1 -   Enables download speed limiting.
speed_limit_up 1 -   Upload speed limit (in Kib/s).
speed_limit_up_enabled 1 -   Enables upload speed limiting.
start_added_torrents 9 -   Added torrents will be started right away.
trash_original_torrent_files 9 -   The .torrent file of added torrents will be deleted.
utp_enabled 13 -   Enables Micro Transport Protocol (UTP).

Note

transmissionrpc will try to automatically fix argument errors.

start(ids, bypass_queue=False, timeout=None)

Warning

Deprecated, please use start_torrent.

start_all(bypass_queue=False, timeout=None)

Start all torrents respecting the queue order

start_torrent(ids, bypass_queue=False, timeout=None)

Start torrent(s) with provided id(s)

stop(ids, timeout=None)

Warning

Deprecated, please use stop_torrent.

stop_torrent(ids, timeout=None)

stop torrent(s) with provided id(s)

timeout

HTTP query timeout.

verify(ids, timeout=None)

Warning

Deprecated, please use verify_torrent.

verify_torrent(ids, timeout=None)

verify torrent(s) with provided id(s)