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: Optional[Union[ssl.SSLContext, bool, aiohttp.client_reqrep.Fingerprint]] = 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
  • endpoint (Union[str, URL]) – The location of the upload.

  • client_session (Optional[ClientSession]) – An aiohttp ClientSession to use.

  • config (RetryConfiguration) – Settings to customize the retry behaviour.

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

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
  • endpoint (Union[str, URL]) – The creation endpoint of the server.

  • file (BinaryIO) – The file to upload.

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

  • client_session (Optional[ClientSession]) – An aiohttp ClientSession to use.

  • config (RetryConfiguration) – Settings to customize the retry behaviour.

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

  • chunksize (int) – The size of individual chunks to upload at a time.

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 and then use the “concatenation” protocol extension to combine the parts on the server-side.

Parameters
  • endpoint (Union[str, URL]) – The creation endpoint of the server.

  • files (Iterable[BinaryIO]) – The files to upload.

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

  • client_session (Optional[ClientSession]) – An aiohttp ClientSession to use.

  • config (RetryConfiguration) – Settings to customize the retry behaviour.

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

  • chunksize (int) – The size of individual chunks to upload at a time.

  • parallel_uploads (int) – The number of parallel uploads to do concurrently.

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 tus protocol.

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
  • session (ClientSession) – HTTP session to use for connections.

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

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

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

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
  • session (ClientSession) – HTTP session to use for connections.

  • location (URL) – The upload endpoint to query.

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

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

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
  • session (ClientSession) – HTTP session to use for connections.

  • location (URL) – The upload endpoint to query.

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

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

Return type

int

Returns

The number of bytes that are already on the server.

Raises

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

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

Upload data to the server.

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

  • location (URL) – The endpoint to upload to.

  • buffer (BinaryIO) – The data to upload.

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

  • chunksize (int) – The size of individual chunks to upload at a time.

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

Raises
Return type

None

aiotus.creation module

Implementation of the creation extension to the tus protocol.

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[SSLContext, bool, 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.