Usage

Basic Usage

The aiotus top-level module provides high-level functions that can be used to upload a file and later query the metadata of an uploaded file. These functions retry a number of times in case of communication errors with the server:

import aiotus

creation_url = "http://example.com/files"

metadata = {
    "Filename": "image.jpeg".encode(),
    "Content-Type": "image/jpeg".encode()
}

# Upload a file to a tus server.
with open("image.jpeg", "rb") as f:
    location = await aiotus.upload(creation_url, f, metadata)
    # 'location' is the URL where the file was uploaded to, or 'None'
    # in case of an error.

if location:
    # Read back the metadata from the server.
    metadata = await aiotus.metadata(location)

The retry behaviour can be customized by passing an instance of aiotus.RetryConfiguration.

If these functions do not suit your needs, it is also possible to use the functions from the aiotus.core and aiotus.creation modules directly:

async with aiohttp.ClientSession() as session:
    # Only "create" an upload, but do not upload any actual data.
    location = await aiotus.creation.create(session, creation_url)

Using a Custom aiohttp Session

To customize the way HTTP requests are made, a custom aiohttp.ClientSession can be used:

auth = aiohttp.BasicAuth("username", "password")
additional_headers = {"foo": "bar"}
async with aiohttp.ClientSession(auth=auth, headers=additional_headers) as session:
     await aiotus.metadata(location, client_session=session)

However, if all you want to do is to pass a few additional headers to be used in the HTTP request, they can also be passed in directly:

await aiotus.metadata(location, headers={"foo": "bar"})

Controlling SSL Validation

To customize the way HTTPS checks are done, you can pass in a SSL context or a boolean that is then passed on to the underlying HTTP library:

# Low-level function:
sslcontext = ssl.create_default_context(...)
async with aiohttp.ClientSession() as session:
     location = await aiotus.creation.create(session, creation_url, ssl=sslcontext)

# High-level function:
config = aiotus.RetryConfiguration(ssl=False)
location = await aiotus.upload(creation_url, data, config=config)

More information on the meaning of the argument can be found in the aiohttp documentation.

Logging

All logging is done using the standard logging logging module with a logger called "aiotus".

Command-Line

The aiotus package can be called directly from the command-line to upload files to a tus server and to show the metadata associated with an upload:

$ python3 -m aiotus upload --metadata additional=metadata http://example.com/files image.jpeg
INFO:aiotus:Complete buffer uploaded.
http://example.com/files/abcd...

$ python3 -m aiotus metadata http://example.com/files/abcd...
mime_type: image/jpeg
additional: metadata
filename: image.jpeg

In addition, these commands can serve as additional examples on how to use aiotus. Their implementation can be found in the aiotus.entrypoint module.