https://github.com/lunaticsm/catbox-uploader
Catbox Uploader is a simple Python library to upload files and URLs to Catbox.moe.
https://github.com/lunaticsm/catbox-uploader
catbox catbox-moe catboxmoe telegraph telegraph-api
Last synced: 5 months ago
JSON representation
Catbox Uploader is a simple Python library to upload files and URLs to Catbox.moe.
- Host: GitHub
- URL: https://github.com/lunaticsm/catbox-uploader
- Owner: lunaticsm
- License: mit
- Created: 2024-09-06T18:42:27.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2024-09-08T12:09:31.000Z (8 months ago)
- Last Synced: 2024-09-08T20:13:38.085Z (8 months ago)
- Topics: catbox, catbox-moe, catboxmoe, telegraph, telegraph-api
- Language: Python
- Homepage:
- Size: 28.3 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Catbox Uploader
Catbox Uploader is a simple Python library to upload files and URLs to [Catbox.moe](https://catbox.moe), including its temporary storage feature, **Litterbox**, and album management.
## Installation
```bash
pip install catbox-uploader
```
## Usage
### Using Userhash
CatboxUploader supports using a **userhash** directly. You can pass the `userhash` when initializing the `CatboxUploader` and use it for authenticated uploads and album management.
### Initialize with Userhash
```python
from catbox import CatboxUploader
uploader = CatboxUploader(userhash='your_userhash_here')
```
### Initialize without Userhash
```python
from catbox import CatboxUploader
uploader = CatboxUploader()
```
### Upload a File
```python
link = uploader.upload_file('path/to/your/file.jpg')
print(f'Uploaded file: {link}')
```
### Upload a File to Litterbox (Temporary Storage)
Litterbox allows you to upload files for a temporary period, after which the files will be deleted automatically. Use the `upload_to_litterbox` method to upload files with a specified expiration time.
**Available expiration times**:
- `1h`: 1 hour
- `12h`: 12 hours
- `24h`: 24 hours
- `72h`: 3 days
```python
link = uploader.upload_to_litterbox('path/to/your/file.jpg', time='24h')
print(f'Uploaded file (available for 24 hours): {link}')
```
### Upload Multiple Files as an Album
You can upload multiple files as an album to **Catbox.moe** using the `upload_album` method. This allows you to upload several files at once, and it will return the links for all uploaded files.
```python
file_paths = ['file1.jpg', 'file2.jpg', 'file3.jpg']
links = uploader.upload_album(file_paths)
for link in links:
print(f'Uploaded file link: {link}')
```
### Create and Manage Albums
#### Create an Album
You can create an album with uploaded files, a title, and a description using the `create_album` method:
```python
album_shortcode = uploader.create_album(file_links, "My Album", "This is a test album")
print(f"Album created: https://catbox.moe/c/{album_shortcode}")
```
#### Edit an Album
You can edit an album by changing its title, description, or the files it contains:
```python
uploader.edit_album(album_shortcode, file_links, "Updated Album Title", "Updated description")
```
#### Delete an Album
You can delete an album by its shortcode:
```python
uploader.delete_album(album_shortcode)
```
### Error Handling
The library comes with built-in exception handling to manage common errors such as timeouts, connection issues, or HTTP errors.
### Handling Timeout
If the upload takes too long and exceeds the specified timeout, a `TimeoutError` will be raised.
```python
from catbox import CatboxUploader, TimeoutError
uploader = CatboxUploader(userhash='your_userhash_here')
try:
link = uploader.upload_file('path/to/your/file.jpg', timeout=10)
print(f'Uploaded file: {link}')
except TimeoutError:
print("The upload took too long and timed out.")
```
### Handling Connection Issues
If there's a problem connecting to the **Catbox.moe** or **Litterbox** server, a `ConnectionError` will be raised.
```python
from catbox import CatboxUploader, ConnectionError
uploader = CatboxUploader(userhash='your_userhash_here')
try:
link = uploader.upload_file('path/to/your/file.jpg')
print(f'Uploaded file: {link}')
except ConnectionError:
print("Failed to connect to the server.")
```
### Handling HTTP Errors
In case of HTTP errors (such as 404 or 500), an `HTTPError` will be raised.
```python
from catbox import CatboxUploader, HTTPError
uploader = CatboxUploader(userhash='your_userhash_here')
try:
link = uploader.upload_file('path/to/your/file.jpg')
print(f'Uploaded file: {link}')
except HTTPError as he:
print(f"HTTP error occurred: {he}")
```
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.