0
# TusPy
1

2
A Python client implementation for the tus resumable upload protocol, enabling robust file uploads with pause and resume capabilities. TusPy provides both synchronous and asynchronous operations, configurable chunk sizes, authentication support, and built-in retry mechanisms for handling network interruptions.
3

4
## Package Information
5

6
- **Package Name**: tuspy
7
- **Language**: Python
8
- **Installation**: `pip install tuspy`
9
- **Dependencies**: requests, aiohttp, tinydb
10

11
## Core Imports
12

13
```python
14
from tusclient import client
15
from tusclient.uploader import Uploader, AsyncUploader
16
```
17

18
For storage and fingerprinting:
19

20
```python
21
from tusclient.storage.interface import Storage
22
from tusclient.storage.filestorage import FileStorage
23
from tusclient.fingerprint.interface import Fingerprint
24
from tusclient.fingerprint.fingerprint import Fingerprint as DefaultFingerprint
25
```
26

27
For exceptions:
28

29
```python
30
from tusclient.exceptions import TusCommunicationError, TusUploadFailed
31
```
32

33
For advanced request handling:
34

35
```python
36
from tusclient.request import TusRequest, AsyncTusRequest, BaseTusRequest, catch_requests_error
37
```
38

39
## Basic Usage
40

41
```python
42
from tusclient import client
43

44
# Create client with server URL and optional headers
45
my_client = client.TusClient(
46
    'http://tusd.tusdemo.net/files/',
47
    headers={'Authorization': 'Bearer token'}
48
)
49

50
# Upload from file path
51
uploader = my_client.uploader('/path/to/file.ext', chunk_size=1024*1024)
52
uploader.upload()
53

54
# Upload from file stream
55
with open('/path/to/file.ext', 'rb') as fs:
56
    uploader = my_client.uploader(file_stream=fs, chunk_size=1024*1024)
57
    uploader.upload()
58

59
# Async upload
60
async_uploader = my_client.async_uploader('/path/to/file.ext', chunk_size=1024*1024)
61
await async_uploader.upload()
62
```
63

64
## Architecture
65

66
TusPy implements the tus resumable upload protocol with a layered architecture:
67

68
- **Client Layer**: TusClient manages server communication and provides uploader factories
69
- **Uploader Layer**: BaseUploader, Uploader, and AsyncUploader handle file upload logic
70
- **Storage Layer**: Optional URL storage for resumability across sessions using pluggable backends
71
- **Fingerprint Layer**: File identification for resume capability using MD5-based fingerprinting
72
- **Request Layer**: HTTP request abstraction supporting both requests and aiohttp libraries
73
- **Exception Layer**: Custom exceptions for protocol-specific error handling
74

75
This design enables reliable file uploads over unstable connections with comprehensive error handling and retry mechanisms.
76

77
## Capabilities
78

79
### Client Management
80

81
Core client functionality for connecting to tus servers, managing authentication headers, and creating uploader instances.
82

83
```python { .api }
84
class TusClient:
85
    def __init__(self, url: str, headers: Optional[Dict[str, str]] = None, 
86
                 client_cert: Optional[Union[str, Tuple[str, str]]] = None): ...
87
    def set_headers(self, headers: Dict[str, str]): ...
88
    def uploader(self, *args, **kwargs) -> Uploader: ...
89
    def async_uploader(self, *args, **kwargs) -> AsyncUploader: ...
90
```
91

92
[Client Management](./client-management.md)
93

94
### File Upload Operations
95

96
Synchronous and asynchronous file upload capabilities with chunked transfer, progress tracking, and error recovery.
97

98
```python { .api }
99
class Uploader(BaseUploader):
100
    def upload(self, stop_at: Optional[int] = None): ...
101
    def upload_chunk(): ...
102
    def create_url(): ...
103

104
class AsyncUploader(BaseUploader):
105
    async def upload(self, stop_at: Optional[int] = None): ...
106
    async def upload_chunk(): ...
107
    async def create_url(): ...
108
```
109

110
[File Upload Operations](./upload-operations.md)
111

112
### Storage and Resumability
113

114
URL storage interfaces and implementations for resuming uploads across sessions.
115

116
```python { .api }
117
class Storage(abc.ABC):
118
    def get_item(self, key: str): ...
119
    def set_item(self, key: str, value: str): ...
120
    def remove_item(self, key: str): ...
121

122
class FileStorage(Storage):
123
    def __init__(self, fp: str): ...
124
    def close(): ...
125
```
126

127
[Storage and Resumability](./storage-resumability.md)
128

129
### Request Handling
130

131
HTTP request abstraction layer for tus protocol operations with both synchronous and asynchronous implementations.
132

133
```python { .api }
134
class BaseTusRequest:
135
    def __init__(self, uploader): ...
136
    def add_checksum(self, chunk: bytes): ...
137

138
class TusRequest(BaseTusRequest):
139
    def perform(): ...
140

141
class AsyncTusRequest(BaseTusRequest):
142
    async def perform(): ...
143

144
def catch_requests_error(func): ...
145
```
146

147
[Request Handling](./request-handling.md)
148

149
### Exception Handling
150

151
Custom exceptions for tus protocol communication errors and upload failures.
152

153
```python { .api }
154
class TusCommunicationError(Exception):
155
    def __init__(self, message: str, status_code: Optional[int] = None, 
156
                 response_content: Optional[str] = None): ...
157

158
class TusUploadFailed(TusCommunicationError): ...
159
```
160

161
[Exception Handling](./exception-handling.md)
162

163
## Common Types
164

165
```python { .api }
166
from typing import Dict, Optional, Tuple, Union, IO, Callable, List
167
import hashlib
168
import sys
169

170
# Type aliases used throughout the API
171
Headers = Dict[str, str]
172
ClientCert = Union[str, Tuple[str, str]]
173
FileInput = Union[str, IO]
174

175
# Constants used throughout the library
176
DEFAULT_HEADERS = {"Tus-Resumable": "1.0.0"}
177
DEFAULT_CHUNK_SIZE = sys.maxsize
178
CHECKSUM_ALGORITHM_PAIR = ("sha1", hashlib.sha1)
179
FINGERPRINT_BLOCK_SIZE = 65536
180
```