# catboxpy
`catboxpy` is a Python wrapper for [Catbox](https://catbox.moe/), which allows you to easily upload files, manage albums, and interact with the Catbox service. This package supports both `synchronous` and `asynchronous usage`.
## Installation
### From PyPI
You can easily install the stable version of `catboxpy` from PyPI using pip:
```bash
pip install catboxpy
```
### From GitHub Repository
Alternatively, if you wish to access the latest (potentially unstable) version directly from the GitHub repository, you can execute the following command:
```bash
pip install git+https://github.com/anshonweb/catboxpy.git
```
## Features
- Upload files to Catbox.
- Create and manage albums (synchronous and asynchronous support).
- Delete files from Catbox.
- Both synchronous and asynchronous methods for flexible usage.
## Installation
To install `catboxpy`, simply use pip:
```bash
pip install catboxpy
```
## Usage
### **Synchronous Usage**
The synchronous interface is simple to use for blocking operations. Here is how to use it:
#### 1. **Uploading a File**
```python
from catboxpy.catbox import CatboxClient
client = CatboxClient(userhash="your_userhash_here")
file_url = client.upload("path/to/your/file.jpg")
print(f"File uploaded to: {file_url}")
```
#### 2. **Uploading a URL**
You can upload files directly from a URL:
```python
url = client.upload('https://example.com/your_image.jpg')
print(f"URL uploaded to: {url}")
```
#### 3. **Creating an Album**
To create an album:
```python
album_url = client.album.create("My Album", "Album description", ["file1.jpg", "file2.jpg"])
print(f"Album created at: {album_url}")
```
#### 4. **Deleting a File**
To delete a file by its URL:
```python
client.delete_file("file_url")
```
---
### **Asynchronous Usage**
The asynchronous interface allows you to perform operations without blocking the execution of other tasks, making it ideal for applications that need to handle multiple requests concurrently.
#### 1. **Uploading a File Asynchronously**
```python
import asyncio
from catboxpy.catbox import AsyncCatboxClient
async def upload_file():
client = AsyncCatboxClient(userhash="your_userhash_here")
file_url = await client.upload("path/to/your/file.jpg")
print(f"File uploaded to: {file_url}")
# Running the async function
asyncio.run(upload_file())
```
#### 2. **Uploading a URL Asynchronously**
```python
import asyncio
from catboxpy.catbox import AsyncCatboxClient
async def upload_url():
client = AsyncCatboxClient(userhash="your_userhash_here")
url = await client.upload('https://example.com/your_image.jpg')
print(f"URL uploaded to: {url}")
# Running the async function
asyncio.run(upload_url())
```
#### 3. **Creating an Album Asynchronously**
```python
import asyncio
from catboxpy.catbox import AsyncCatboxClient
async def create_album():
client = AsyncCatboxClient(userhash="your_userhash_here")
album_url = await client.album.create("My Album", "Album description", ["file1.jpg", "file2.jpg"])
print(f"Album created at: {album_url}")
# Running the async function
asyncio.run(create_album())
```
#### 4. **Deleting a File Asynchronously**
```python
import asyncio
from catboxpy.catbox import AsyncCatboxClient
async def delete_file():
client = AsyncCatboxClient(userhash="your_userhash_here")
await client.delete_file("file_url")
# Running the async function
asyncio.run(delete_file())
```
---
### **Litterbox Usage**
```python
from catboxpy import LitterboxClient
uploader = LitterboxClient()
try:
url = uploader.upload_file("filepath", expire_time="1h")
print(f"Uploaded to: {url}")
except Exception as e:
print(f"Upload failed: {e}")
```
## Authentication
For most operations, such as uploading or managing albums, you need a valid **userhash**. You can obtain the `userhash` by logging in to Catbox and accessing your user settings.
- If you're performing **anonymous uploads**, you can omit the `userhash`. However, operations like creating and managing albums require a valid `userhash`.
---
## Notes
- **Album Limitations**: Catbox albums currently allow a maximum of 500 files. This limit may change in the future.
- **Anonymous Albums**: Anonymous albums cannot be edited or deleted, and they also cannot contain more than 500 files.
---
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## Contact
For issues, bugs, or suggestions, please open an issue on the [GitHub repository](https://github.com/anshonweb/catboxpy/issues).
---
```
Raw data
{
"_id": null,
"home_page": "https://github.com/anshonweb/catboxpy",
"name": "catboxpy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "catbox api python wrapper async litterbox",
"author": "anshonweb",
"author_email": "ansh.a.3112@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/91/92/4e719d1bf2146ab07a3e7238b92a4159b142f0ef7ccb61a1c10cfdbb260d/catboxpy-0.1.1.1.tar.gz",
"platform": null,
"description": "# catboxpy\n\n`catboxpy` is a Python wrapper for [Catbox](https://catbox.moe/), which allows you to easily upload files, manage albums, and interact with the Catbox service. This package supports both `synchronous` and `asynchronous usage`. \n## Installation\n\n### From PyPI\n\nYou can easily install the stable version of `catboxpy` from PyPI using pip:\n\n```bash\npip install catboxpy\n```\n\n### From GitHub Repository\n\nAlternatively, if you wish to access the latest (potentially unstable) version directly from the GitHub repository, you can execute the following command:\n\n```bash\npip install git+https://github.com/anshonweb/catboxpy.git\n```\n\n## Features\n\n- Upload files to Catbox.\n- Create and manage albums (synchronous and asynchronous support).\n- Delete files from Catbox.\n- Both synchronous and asynchronous methods for flexible usage.\n\n## Installation\n\nTo install `catboxpy`, simply use pip:\n\n```bash\npip install catboxpy\n```\n\n## Usage\n\n### **Synchronous Usage**\n\nThe synchronous interface is simple to use for blocking operations. Here is how to use it:\n\n#### 1. **Uploading a File**\n\n```python\nfrom catboxpy.catbox import CatboxClient\n\nclient = CatboxClient(userhash=\"your_userhash_here\")\nfile_url = client.upload(\"path/to/your/file.jpg\")\nprint(f\"File uploaded to: {file_url}\")\n```\n\n#### 2. **Uploading a URL**\n\nYou can upload files directly from a URL:\n\n```python\nurl = client.upload('https://example.com/your_image.jpg')\nprint(f\"URL uploaded to: {url}\")\n```\n\n#### 3. **Creating an Album**\n\nTo create an album:\n\n```python\nalbum_url = client.album.create(\"My Album\", \"Album description\", [\"file1.jpg\", \"file2.jpg\"])\nprint(f\"Album created at: {album_url}\")\n```\n\n#### 4. **Deleting a File**\n\nTo delete a file by its URL:\n\n```python\nclient.delete_file(\"file_url\")\n```\n\n---\n\n### **Asynchronous Usage**\n\nThe asynchronous interface allows you to perform operations without blocking the execution of other tasks, making it ideal for applications that need to handle multiple requests concurrently.\n\n#### 1. **Uploading a File Asynchronously**\n\n```python\nimport asyncio\nfrom catboxpy.catbox import AsyncCatboxClient\n\nasync def upload_file():\n client = AsyncCatboxClient(userhash=\"your_userhash_here\")\n file_url = await client.upload(\"path/to/your/file.jpg\")\n print(f\"File uploaded to: {file_url}\")\n\n# Running the async function\nasyncio.run(upload_file())\n```\n\n#### 2. **Uploading a URL Asynchronously**\n\n```python\nimport asyncio\nfrom catboxpy.catbox import AsyncCatboxClient\n\nasync def upload_url():\n client = AsyncCatboxClient(userhash=\"your_userhash_here\")\n url = await client.upload('https://example.com/your_image.jpg')\n print(f\"URL uploaded to: {url}\")\n\n# Running the async function\nasyncio.run(upload_url())\n```\n\n#### 3. **Creating an Album Asynchronously**\n\n```python\nimport asyncio\nfrom catboxpy.catbox import AsyncCatboxClient\n\nasync def create_album():\n client = AsyncCatboxClient(userhash=\"your_userhash_here\")\n album_url = await client.album.create(\"My Album\", \"Album description\", [\"file1.jpg\", \"file2.jpg\"])\n print(f\"Album created at: {album_url}\")\n\n# Running the async function\nasyncio.run(create_album())\n```\n\n#### 4. **Deleting a File Asynchronously**\n\n```python\nimport asyncio\nfrom catboxpy.catbox import AsyncCatboxClient\n\nasync def delete_file():\n client = AsyncCatboxClient(userhash=\"your_userhash_here\")\n await client.delete_file(\"file_url\")\n\n# Running the async function\nasyncio.run(delete_file())\n```\n\n---\n\n### **Litterbox Usage**\n```python\n\nfrom catboxpy import LitterboxClient\n\nuploader = LitterboxClient()\ntry:\n url = uploader.upload_file(\"filepath\", expire_time=\"1h\")\n print(f\"Uploaded to: {url}\")\nexcept Exception as e:\n print(f\"Upload failed: {e}\")\n\n```\n\n## Authentication\n\nFor most operations, such as uploading or managing albums, you need a valid **userhash**. You can obtain the `userhash` by logging in to Catbox and accessing your user settings.\n\n- If you're performing **anonymous uploads**, you can omit the `userhash`. However, operations like creating and managing albums require a valid `userhash`.\n\n---\n\n## Notes\n\n- **Album Limitations**: Catbox albums currently allow a maximum of 500 files. This limit may change in the future.\n- **Anonymous Albums**: Anonymous albums cannot be edited or deleted, and they also cannot contain more than 500 files.\n\n---\n\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n---\n\n## Contact\n\nFor issues, bugs, or suggestions, please open an issue on the [GitHub repository](https://github.com/anshonweb/catboxpy/issues).\n\n---\n\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python wrapper for the Catbox.moe and Litterbox api with Async features",
"version": "0.1.1.1",
"project_urls": {
"Homepage": "https://github.com/anshonweb/catboxpy"
},
"split_keywords": [
"catbox",
"api",
"python",
"wrapper",
"async",
"litterbox"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "30031c67ac821bbd81bef034f0ba3e69a5340560a147f9dac433b6712817c8d9",
"md5": "762fd3f6b76e132d18f4040ef314db49",
"sha256": "021535e5c64f965ad92e2589b31ed89f31a7c56d24af253e1e4f8c4106acf564"
},
"downloads": -1,
"filename": "catboxpy-0.1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "762fd3f6b76e132d18f4040ef314db49",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7913,
"upload_time": "2025-07-08T22:09:32",
"upload_time_iso_8601": "2025-07-08T22:09:32.290751Z",
"url": "https://files.pythonhosted.org/packages/30/03/1c67ac821bbd81bef034f0ba3e69a5340560a147f9dac433b6712817c8d9/catboxpy-0.1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "91924e719d1bf2146ab07a3e7238b92a4159b142f0ef7ccb61a1c10cfdbb260d",
"md5": "137071f8daa440739436369deb10bd84",
"sha256": "a7cd37e18e88ea86c2d15c384d23c021603b5bde67fa9c2cd4f6e9ab7b812314"
},
"downloads": -1,
"filename": "catboxpy-0.1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "137071f8daa440739436369deb10bd84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6575,
"upload_time": "2025-07-08T22:09:33",
"upload_time_iso_8601": "2025-07-08T22:09:33.640721Z",
"url": "https://files.pythonhosted.org/packages/91/92/4e719d1bf2146ab07a3e7238b92a4159b142f0ef7ccb61a1c10cfdbb260d/catboxpy-0.1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 22:09:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anshonweb",
"github_project": "catboxpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "catboxpy"
}
JSON
