Tuspy Client for Tus Resumable Upload Protocol

Warnings

• breaking Python 2 support was officially dropped in version 1.0.0. Projects still relying on Python 2 must use tuspy versions prior to 1.0.0.
  Fix: Upgrade to Python 3.5.3+ to use tuspy v1.0.0 and newer versions.
• gotcha When working with `asyncio`, ensure you use `AsyncUploader` provided by `tusclient.asyncclient` and instantiate it via `client.async_uploader()`. The default `Uploader` is for synchronous operations.
  Fix: For async: `from tusclient.asyncclient import AsyncClient, AsyncUploader`; `async_client = AsyncClient(endpoint)`; `async_uploader = async_client.async_uploader(...)`; `await async_uploader.upload()`.
• gotcha Incorrect `chunk_size` can lead to performance issues or errors if the server has strict limits. Larger files benefit from larger `chunk_size` but must not exceed server-defined limits.
  Fix: Experiment with different `chunk_size` values. Default is 2MB (2 * 1024 * 1024 bytes). Consult your tus server documentation for optimal or maximum chunk sizes.
• gotcha Ensure the tus server endpoint (e.g., `http://master.tus.io/files/`) is correct and accessible. A common mistake is providing a file URL instead of the base tus endpoint for uploads.
  Fix: Verify the endpoint URL with your tus server's documentation. It should typically be a base path where new upload requests are initiated, not a specific file's URL.

Install

• pip install tuspy Install tuspy

Imports

• TusClient

  from tusclient import client
  my_client = client.TusClient(...)

• Uploader

  from tusclient.uploader import Uploader

  Uploader is typically instantiated via a TusClient instance or imported from tusclient.uploader. Direct import from top-level tusclient package is incorrect.
• AsyncUploader

  from tusclient.asyncclient import AsyncUploader

  AsyncUploader is part of the asyncclient module. Direct import from top-level tusclient package is incorrect.

Quickstart

This quickstart demonstrates how to initialize a `TusClient` and perform a synchronous file upload using the `Uploader`. It creates a dummy file if one doesn't exist and attempts to upload it to a specified tus server endpoint. Remember to set the `TUS_SERVER_ENDPOINT` environment variable or replace it directly.

import os
from tusclient import client

# Replace with your tus server endpoint
TUS_ENDPOINT = os.environ.get('TUS_SERVER_ENDPOINT', 'http://master.tus.io/files/')
FILE_TO_UPLOAD = 'path/to/your/local/file.txt' # Make sure this file exists

# Create a dummy file for demonstration if it doesn't exist
if not os.path.exists(FILE_TO_UPLOAD):
    with open(FILE_TO_UPLOAD, 'w') as f:
        f.write('This is a test file for tuspy upload.\n' * 100)
    print(f"Created dummy file: {FILE_TO_UPLOAD}")


try:
    # 1. Create a TusClient instance
    my_client = client.TusClient(TUS_ENDPOINT)

    # 2. Create an Uploader instance
    # For synchronous uploads, use my_client.uploader()
    # For asynchronous uploads, use my_client.async_uploader() and await upload()
    uploader = my_client.uploader(FILE_TO_UPLOAD, chunk_size=2 * 1024 * 1024) # 2MB chunks

    # 3. Start the upload
    print(f"Attempting to upload {FILE_TO_UPLOAD} to {TUS_ENDPOINT}...")
    uploader.upload()
    print(f"Upload of {FILE_TO_UPLOAD} complete. Upload URL: {uploader.url}")

except Exception as e:
    print(f"An error occurred during upload: {e}")
    print("Please ensure your TUS_SERVER_ENDPOINT is correct and accessible.")
finally:
    # Clean up dummy file
    if os.path.exists(FILE_TO_UPLOAD):
        os.remove(FILE_TO_UPLOAD)
        print(f"Cleaned up dummy file: {FILE_TO_UPLOAD}")