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.