Reference

aiotus module

Top-level module containing convenience functions.

exception aiotus.ProtocolError[source]

Server response did not follow the tus protocol.

class aiotus.RetryConfiguration(retry_attempts=10, max_retry_period_seconds=60.0, ssl=None)[source]

Class to hold settings for the functions of this module.

max_retry_period_seconds: float = 60.0

Maximum time between retries, in seconds.

Exponential backoff is used in case of communication errors, but the time between retries is caped by this value.

retry_attempts: int = 10

Number of retry attempts to do when the communication fails.

ssl: Union[bool, SSLContext, Fingerprint, None] = None

‘ssl’ argument passed on to the aiohttp calls.

This can be None, False, or an instance of ssl.SSLContext, see the aiohttp documentation for the different meanings.

async aiotus.metadata(endpoint, client_session=None, config=RetryConfiguration(retry_attempts=10, max_retry_period_seconds=60.0, ssl=None), headers=None)[source]

Read back the metadata of an upload.

See aiotus.Metadata for details on how metadata is handled in the tus protocol.

In case of a communication error, this function retries.

Parameters:
Return type:

Optional[Mapping[str, Optional[bytes]]]

Returns:

The metadata associated with the upload.

async aiotus.upload(endpoint, file, metadata=None, client_session=None, config=RetryConfiguration(retry_attempts=10, max_retry_period_seconds=60.0, ssl=None), headers=None, chunksize=4194304)[source]

Upload a file to a tus server.

This function creates an upload on the server and then uploads the data to that location.

In case of a communication error, this function retries the upload.

Parameters:
Return type:

Optional[URL]

Returns:

The location where the file was uploaded to (if the upload succeeded).

async aiotus.upload_multiple(endpoint, files, metadata=None, client_session=None, config=RetryConfiguration(retry_attempts=10, max_retry_period_seconds=60.0, ssl=None), headers=None, chunksize=4194304, parallel_uploads=3)[source]

Upload multiple files using the “concatenation” extension.

Upload multiple files and then use the “concatenation” protocol extension to combine the parts on the server-side.

Parameters:
Return type:

Optional[URL]

Returns:

The location of the final (concatenated) file on the server.

Raises:

RuntimeError – If the server does not support the “concatenation” extension.

aiotus.SSLArgument = Union[bool, ssl.SSLContext, aiohttp.Fingerprint]

Alias for the type of the ‘ssl’ argument passed to aiohttp calls.

aiotus.Metadata = Mapping[str, Optional[bytes]]

Alias for the type used to hold metadata of an upload.

The tus protocol transfers metadata values in binary form (Base64 encoded). If strings should be saved as metadata, they have to be encoded to binary first.

However, while the protocol itself would allow it to store arbitrary binary data as metadata, the handling of metadata may depends on the specific server implementation. For example, tusd decodes the metadata values and drops them if they can not be decoded to strings.

aiotus.core module

Implementation of the core protocol.

The core tus protocol defines how the data upload is handled.

class aiotus.core.ServerConfiguration(protocol_versions, max_size, protocol_extensions)[source]

Class to hold the server’s configuration.

max_size: Optional[int]

The maximum allowed file size (in bytes), if reported by the server.

protocol_extensions: List[str]

The protocol extensions supported by the server.

protocol_versions: List[str]

List of protocol versions supported by the server, sorted by the server’s preference.

async aiotus.core.configuration(session, url, ssl=None, headers=None)[source]

Get the server’s configuration.

Parameters:
Return type:

ServerConfiguration

Returns:

An object describing the server’s configuration.

Raises:

ProtocolError – When the server does not comply to the tus protocol.

async aiotus.core.metadata(session, location, ssl=None, headers=None)[source]

Get the metadata associated with an upload.

See aiotus.Metadata for details on how metadata is handled in the tus protocol.

Parameters:
Return type:

Mapping[str, Optional[bytes]]

Returns:

The metadata of the upload.

Raises:

ProtocolError – When the server does not comply to the tus protocol.

async aiotus.core.offset(session, location, ssl=None, headers=None)[source]

Get the number of uploaded bytes.

Parameters:
Return type:

int

Returns:

The number of bytes that are already on the server.

async aiotus.core.upload_buffer(session, location, buffer, ssl=None, chunksize=4194304, headers=None)[source]

Upload data to the server.

Parameters:
Raises:
Return type:

None

aiotus.creation module

Implementation of the creation extension.

The creation extension defines how to reserve space on the server for uploading data to.

async aiotus.creation.create(session, url, file, metadata, ssl=None, headers=None)[source]

Create an upload.

Parameters:

  • session (ClientSession) – HTTP session to use for connections.

  • url (URL) – The creation endpoint of the server.

  • file (Optional[BinaryIO]) – The file object to upload. Used to determine the length of data to be uploaded. If not given, the corresponding HTTP header is not included in the request.

  • metadata (Mapping[str, Optional[bytes]]) – Additional metadata for the upload.

  • ssl (Union[bool, SSLContext, Fingerprint, None]) – SSL validation mode, passed on to aiohttp.

  • headers (Optional[Mapping[str, str]]) – Optional headers used in the request.

Return type:

URL

Returns:

The URL to upload the data to.

Raises:

ProtocolError – When the server does not comply to the tus protocol.

aiotus.creation.encode_metadata(metadata)[source]

Encode the metadata to the value of the metadata header.

Parameters:

metadata (Mapping[str, Optional[bytes]]) – The metadata to encode.

Return type:

str

Returns:

The value for the “Upload-Metadata” header.