0
# File Upload
1

2
File upload functionality for Telegraph content. This feature allows uploading images and media files to Telegraph servers for use in pages.
3

4
**Warning**: File upload is NOT part of the official Telegraph API and should be used at your own risk.
5

6
## Capabilities
7

8
### Upload File
9

10
Upload files to Telegraph servers for use in page content.
11

12
```python { .api }
13
def upload_file(f) -> list:
14
    """
15
    Upload file to Telegraph servers (unofficial API).
16

17
    Parameters:
18
    - f (str|file|list): File path, file-like object, or list of files.
19
                        Can also be tuple (file, filename) for custom naming.
20

21
    Returns:
22
    list: List of dicts with 'src' key containing the uploaded file URL
23

24
    Raises:
25
    TelegraphException: Upload failed or file type not allowed
26
    RetryAfterError: Rate limiting occurred
27
    """
28
```
29

30
## Supported File Types
31

32
Only the following file types are allowed:
33
- `.jpg`, `.jpeg` - JPEG images
34
- `.png` - PNG images  
35
- `.gif` - GIF images
36
- `.mp4` - MP4 videos
37

38
## Usage Examples
39

40
### Upload Single File
41

42
```python
43
from telegraph import Telegraph
44

45
telegraph = Telegraph()
46

47
# Upload by file path
48
result = telegraph.upload_file('image.jpg')
49
image_url = result[0]['src']
50
print(f"Uploaded to: https://telegra.ph{image_url}")
51

52
# Use in page content
53
telegraph.create_page(
54
    title='Image Post',
55
    html_content=f'<img src="{image_url}" alt="Uploaded image">'
56
)
57
```
58

59
### Upload File-like Object
60

61
```python
62
# Upload file-like object
63
with open('photo.png', 'rb') as f:
64
    result = telegraph.upload_file(f)
65
    image_url = result[0]['src']
66
```
67

68
### Upload Multiple Files
69

70
```python
71
# Upload multiple files
72
files = ['image1.jpg', 'image2.png', 'video.mp4']
73
results = telegraph.upload_file(files)
74

75
for i, result in enumerate(results):
76
    print(f"File {i+1} uploaded to: https://telegra.ph{result['src']}")
77
```
78

79
### Upload with Custom Filename
80

81
```python
82
# Upload with custom filename
83
with open('photo.jpg', 'rb') as f:
84
    result = telegraph.upload_file((f, 'custom_name.jpg'))
85
    image_url = result[0]['src']
86
```
87

88
## Response Format
89

90
Successful uploads return a list of dictionaries with the following structure:
91

92
```python
93
[
94
    {
95
        'src': '/file/abc123def456.jpg'  # Relative URL to uploaded file
96
    }
97
]
98
```
99

100
The full URL is `https://telegra.ph` + `src` value.
101

102
## Error Handling
103

104
File upload operations may raise these exceptions:
105

106
```python
107
from telegraph import Telegraph
108
from telegraph.exceptions import TelegraphException, RetryAfterError
109

110
telegraph = Telegraph()
111

112
try:
113
    result = telegraph.upload_file('large_file.jpg')
114
except RetryAfterError as e:
115
    print(f"Rate limited. Retry after {e.retry_after} seconds")
116
except TelegraphException as e:
117
    print(f"Upload failed: {e}")
118
```
119

120
Common error scenarios:
121
- **File type not allowed**: Attempting to upload unsupported file formats
122
- **File too large**: Files exceeding Telegraph's size limits
123
- **Rate limiting**: Too many uploads in short time period
124
- **Network errors**: Connection issues during upload
125

126
## Integration with Pages
127

128
Use uploaded files in page content:
129

130
```python
131
# Upload image
132
result = telegraph.upload_file('chart.png')
133
image_src = result[0]['src']
134

135
# Create page with uploaded image
136
response = telegraph.create_page(
137
    title='Data Analysis Report',
138
    html_content=f'''
139
    <p>Here are the results of our analysis:</p>
140
    <figure>
141
        <img src="{image_src}" alt="Analysis Chart">
142
        <figcaption>Monthly sales data</figcaption>
143
    </figure>
144
    <p>As shown in the chart above...</p>
145
    '''
146
)
147

148
print(f"Page created: {response['url']}")
149
```
150

151
## Best Practices
152

153
1. **Check file types** before upload to avoid errors
154
2. **Handle rate limiting** with appropriate retry logic
155
3. **Store returned URLs** for use in page content
156
4. **Use descriptive filenames** when uploading with custom names
157
5. **Optimize file sizes** to improve upload performance
158
6. **Consider fallback options** since this is unofficial API
159

160
## Deprecated Function
161

162
The standalone `upload_file` function is deprecated but still available:
163

164
```python { .api }
165
def upload_file(f) -> list:
166
    """
167
    Deprecated standalone upload function.
168
    
169
    Parameters:
170
    - f (str|file|list): File path, file-like object, or list of files
171
    
172
    Returns:
173
    list: List of src URL strings (not dicts like Telegraph.upload_file)
174
    
175
    Deprecated: Use Telegraph.upload_file() instead
176
    """
177
```
178

179
Usage comparison:
180

181
```python
182
# Deprecated - don't use
183
from telegraph import upload_file
184
result = upload_file('image.jpg')  # Returns ['src1', 'src2', ...]
185
print(result)  # ['/file/abc123.jpg']
186

187
# Recommended approach
188
from telegraph import Telegraph
189
telegraph = Telegraph()
190
result = telegraph.upload_file('image.jpg')  # Returns [{'src': 'url'}, ...]
191
print(result)  # [{'src': '/file/abc123.jpg'}]
192
```
193

194
The deprecated function:
195
- Returns only src URL strings, not full response objects
196
- Issues deprecation warnings when used
197
- May be removed in future versions
198
- Provides less error information than the Telegraph class method