`filetransfer`¶

This module contains an API for the TS3 file transfer interface.

exception ts3.filetransfer.TS3FileTransferError[source]¶

Bases: ts3.common.TS3Error

This is the base class for all exceptions in this module.

exception ts3.filetransfer.TS3UploadError(send_size, err=None)[source]¶

Bases: ts3.filetransfer.TS3FileTransferError

Is raised, when an upload fails.

send_size = None¶: The number of sent bytes till the error occured.

err = None¶: If the upload failed due to a thrown exception, this attribute contains it.

exception ts3.filetransfer.TS3DownloadError(read_size, err=None)[source]¶

Bases: ts3.filetransfer.TS3FileTransferError

Is raised, when a download fails.

read_size = None¶: The number of read bytes untill the error occured.

err = None¶: If the download failed due to a thrown exception, this attribute contains the original exception.

class ts3.filetransfer.TS3FileTransfer(ts3conn)[source]¶

Bases: object

A high-level TS3 file transfer handler.

The recommended methods to download or upload a file are:

init_download()
init_upload()

classmethod get_ftid()[source]¶

Returns:	Returns a unique id for a file transfer.
Return type:	int

init_download(output_file, name, cid, cpw='', seekpos=0, query_resp_hook=None, reporthook=None)[source]¶

This is the recommended method to download a file from a TS3 server.

name, cid, cpw and seekpos are the parameters for the TS3 query command ftinitdownload. The parameter clientftid is automatically created and unique for the whole runtime of the programm.

query_resp_hook, if provided, is called, when the response of the ftinitdownload query has been received. Its single parameter is the the response of the querry.

For downloading the file from the server, download() is called. So take a look a this method for further information.

See also

ftinitdownload()
urlretrieve()

classmethod download_by_resp(output_file, ftinitdownload_resp, seekpos=0, reporthook=None, fallbackhost=None)[source]¶

This is almost a shortcut for:

>>> TS3FileTransfer.download(
...     output_file = file,
...     adr = (resp[0]["ip"], int(resp[0]["port"])),
...     ftkey = resp[0]["ftkey"],
...     seekpos = seekpos,
...     total_size = resp[0]["size"],
...     reporthook = reporthook
...     )

Note, that the value of resp[0]["ip"] is a csv list and needs to be parsed.

classmethod download(output_file, adr, ftkey, seekpos=0, total_size=0, reporthook=None)[source]¶

Downloads a file from a TS3 server in the file output_file. The TS3 file transfer interface is specified with the address tuple adr and the download with the file transfer key ftkey.

If seekpos and the total size are provided, the reporthook function (lambda read_size, block_size, total_size: None) is called after receiving a new block.

If you provide seekpos and total_size, this method will check, if the download is complete and raise a TS3DownloadError if not.

Note, that if total_size is 0 or less, each download will be considered as complete.

If no error is raised, the number of read bytes is returned.

Returns:	The number of received bytes.
Return type:	int
Raises:	TS3DownloadError – If the download is incomplete or a socket error occured.

init_upload(input_file, name, cid, cpw='', overwrite=True, resume=False, query_resp_hook=None, reporthook=None)[source]¶

This is the recommended method to upload a file to a TS3 server.

name, cid, cpw, overwrite and resume are the parameters for the TS3 query command ftinitdownload. The parameter clientftid is automatically created and unique for the whole runtime of the programm and the value of size is retrieved by the size of the input_file.

query_resp_hook, if provided, is called, when the response of the ftinitupload query has been received. Its single parameter is the the response of the querry.

For uploading the file to the server upload() is called. So take a look at this method for further information.

filetransfer¶

`filetransfer`¶