Skip to content

Latest commit

 

History

History
294 lines (241 loc) · 14.9 KB

transmissionrpc.rst

File metadata and controls

294 lines (241 loc) · 14.9 KB
Raw

:mod:`transmission_rpc` --- Module reference

.. module:: transmission_rpc

.. moduleauthor:: Erik Svensson <erik.public@gmail.com>

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

Contents

Exceptions

.. autoclass:: TransmissionError

        .. attribute:: original

                The original exception.


.. autoclass:: HTTPHandlerError

        .. attribute:: url

                The requested url.

        .. attribute:: code

                HTTP error code.

        .. attribute:: message

                HTTP error message.

        .. attribute:: headers

                HTTP headers.

        .. attribute:: 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 transmission_rpc
>>> t = transmission_rpc.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 transmission_rpc
>>> c = transmission_rpc.Client()
>>> t = c.get_torrent(0)
>>> t.peer_limit
10
>>> t.peer_limit = 20
>>> t.update()
>>> t.peer_limit
20

Reference

.. autoclass:: Torrent
        :members:

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

.. autoclass:: Session
        :members:

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 transmission_rpc 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

.. autoclass:: Client
        :members: