tusclient package

Submodules

tusclient.client module

class tusclient.client.TusClient(url, headers=None)

Bases: object

Object representation of Tus client.

Attributes:
  • url (str):
    represents the tus server’s create extension url. On instantiation this argument must be passed to the constructor.
  • headers (dict):
    This can be used to set the server specific headers. These headers would be sent along with every request made by the cleint to the server. This may be used to set authentication headers. These headers should not include headers required by tus protocol. If not set this defaults to an empty dictionary.
Constructor Args:
 
  • url (str)
  • headers (Optiional[dict])
set_headers(headers)

Set tus client headers.

Update and/or set new headers that would be sent along with every request made to the server.

Args:
  • headers (dict):
    key, value pairs of the headers to be set. This argument is required.
uploader(*args, **kwargs)

Return uploader instance pointing at current client instance.

Return uplaoder instance with which you can control the upload of a specific file. The current instance of the tus client is passed to the uploader on creation.

Args:see tusclient.uploader.Uploader for required and optional arguments.

tusclient.exceptions module

Global Tusclient exception and warning classes.

exception tusclient.exceptions.TusCommunicationError(message, status_code=None, response_content=None)

Bases: Exception

Should be raised when communications with tus-server behaves unexpectedly.

Attributes:
  • message (str):
    Main message of the exception
  • status_code (int):
    Status code of response indicating an error
  • response_content (str):
    Content of response indicating an error
Constructor Args:
 
  • message (Optional[str])
  • status_code (Optional[int])
  • response_content (Optional[str])
exception tusclient.exceptions.TusUploadFailed(message, status_code=None, response_content=None)

Bases: tusclient.exceptions.TusCommunicationError

Should be raised when an attempted upload fails

tusclient.request module

class tusclient.request.TusRequest(uploader)

Bases: object

Http Request Abstraction.

Sets up tus custom http request on instantiation.

requires argument ‘uploader’ an instance of tusclient.uploader.Uploader on instantiation.

Attributes:
  • handle (<http.client.HTTPConnection>)
  • response_headers (dict)
  • file (file):
    The file that is being uploaded.
close()

close request handle and end request session

perform()

Perform actual request.

response_content

Return response data

tusclient.uploader module

class tusclient.uploader.Uploader(file_path=None, file_stream=None, url=None, client=None, chunk_size=None, metadata=None, retries=0, retry_delay=30, store_url=False, url_storage=None, fingerprinter=None, log_func=None)

Bases: object

Object to control upload related functions.

Attributes:
  • file_path (str):
    This is the path(absolute/relative) to the file that is intended for upload to the tus server. On instantiation this attribute is required.
  • file_stream (file):
    As an alternative to the file_path, an instance of the file to be uploaded can be passed to the constructor as file_stream. Do note that either the file_stream or the file_path must be passed on instantiation.
  • url (str):
    If the upload url for the file is known, it can be passed to the constructor. This may happen when you resume an upload.
  • client (<tusclient.client.TusClient>):
    An instance of tusclient.client.TusClient. This would tell the uploader instance what client it is operating with. Although this argument is optional, it is only optional if the ‘url’ argument is specified.
  • chunk_size (int):
    This tells the uploader what chunk size(in bytes) should be uploaded when the method upload_chunk is called. This defaults to the maximum possible integer if not specified.
  • metadata (dict):
    A dictionary containing the upload-metadata. This would be encoded internally by the method encode_metadata to conform with the tus protocol.
  • offset (int):
    The offset value of the upload indicates the current position of the file upload.
  • stop_at (int):
    At what offset value the upload should stop.
  • request (<tusclient.request.TusRequest>):
    A http Request instance of the last chunk uploaded.
  • retries (int):
    The number of attempts the uploader should make in the case of a failed upload. If not specified, it defaults to 0.
  • retry_delay (int):
    How long (in seconds) the uploader should wait before retrying a failed upload attempt. If not specified, it defaults to 30.
  • store_url (bool):
    Determines whether or not url should be stored, and uploads should be resumed.
  • url_storage (<tusclient.storage.interface.Storage>):
    An implementation of <tusclient.storage.interface.Storage> which is an API for URL storage. This value must be set if store_url is set to true. A ready to use implementation exists atbe used out of the box. But you can implement your own custom storage API and pass an instace of it as value.
  • fingerprinter (<tusclient.fingerprint.interface.Fingerprint>):
    An implementation of <tusclient.fingerprint.interface.Fingerprint> which is an API to generate a unique fingerprint for the uploaded file. This is used for url storage when resumability is enabled. if store_url is set to true, the default fingerprint module (<tusclient.fingerprint.fingerprint.Fingerprint>) would be used. But you can set your own custom fingerprint module by passing it to the constructor.
  • log_func (<function>):
    A logging function to be passed diagnostic messages during file uploads
Constructor Args:
 
  • file_path (str)
  • file_stream (Optional[file])
  • url (Optional[str])
  • client (Optional [<tusclient.client.TusClient>])
  • chunk_size (Optional[int])
  • metadata (Optional[dict])
  • retries (Optional[int])
  • retry_delay (Optional[int])
  • store_url (Optional[bool])
  • url_storage (Optinal [<tusclient.storage.interface.Storage>])
  • fingerprinter (Optional [<tusclient.fingerprint.interface.Fingerprint>])
  • log_func (Optional [<function>])
DEFAULT_CHUNK_SIZE = 9223372036854775807
DEFAULT_HEADERS = {'Tus-Resumable': '1.0.0'}
create_url()

Return upload url.

Makes request to tus server to create a new upload url for the required file upload.

encode_metadata()

Return list of encoded metadata as defined by the Tus protocol.

file_size

Return size of the file.

get_file_stream()

Return a file stream instance of the upload.

get_offset()

Return offset from tus server.

This is different from the instance attribute ‘offset’ because this makes an http request to the tus server to retrieve the offset.

get_url()

Return the tus upload url.

If resumability is enabled, this would try to get the url from storage if available, otherwise it would request a new upload url from the tus server.

headers

Return headers of the uploader instance. This would include the headers of the client instance.

headers_as_list

Does the same as ‘headers’ except it is returned as a list.

request_length

Return length of next chunk upload.

upload(stop_at=None)

Perform file upload.

Performs continous upload of chunks of the file. The size uploaded at each cycle is the value of the attribute ‘chunk_size’.

Args:
  • stop_at (Optional[int]):
    Determines at what offset value the upload should stop. If not specified this defaults to the file size.
upload_chunk()

Upload chunk of file.

verify_upload()

Confirm that the last upload was sucessful. Raises TusUploadFailed exception if the upload was not sucessful.