`ts3.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¶: A string describing the condition which caused the exception more precise.

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¶: A string describing the condition which caused the exception more precise.

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()

You can either use the low-level class methods, e.g. download_by_resp() or the high-level ones like init_download() to handle the file transfers:

ts3ft = TS3FileTransfer(ts3conn)
        with open("baz.png", "rb") as file:
                ts3ft.init_upload(input_file=file, name="/baz.png", cid=2)
        with open("baz1.png", "wb") as file:
                ts3ft.init_download(output_file=file, name="/baz.png", cid=2)

File transports can be monitored using a reporthook, a function which is periodically called with the current transfer stats:

def reporthook(size, block_size, total_size):
    print("{}% done.".format(size/total_size))

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 query.

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

Seealso:	The TS3 ftinitdownload command

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

Kicks off a file download by using a query response to a ftinitdownload command.

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.

Seealso:	`download()`

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 each time a new data block has been received.

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 query.

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

Seealso:	The TS3 ftinitdownload command

classmethod upload_by_resp(input_file, ftinitupload_resp, reporthook=None, fallbackhost=None)[source]¶

This is almost a shortcut for:

>>> TS3FileTransfer.upload(
...     input_file = file,
...     adr = (resp[0]["ip"], int(resp[0]["port"])),
...     ftkey = resp[0]["ftkey"],
...     seekpos = resp[0]["seekpos"],
...     reporthook = reporthook
...    )

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

Seealso:	`upload()`

classmethod upload(input_file, adr, ftkey, seekpos=0, reporthook=None)[source]¶

Uploads the data in the file input_file to the TS3 server listening at the address adr. ftkey is used to authenticate the file transfer.

When the upload begins, the get pointer of the input_file is set to seekpos.

If the reporthook function (lambda send_size, block_size, total_size) is provided, it is called each time a data block has been successfully transfered.

Raises:	TS3UploadError – If the upload is incomplete or a socket error occured.

ts3.filetransfer¶

`ts3.filetransfer`¶