{"id":14633135,"url":"https://github.com/lunaticsm/catbox-uploader","last_synced_at":"2025-09-06T22:31:00.052Z","repository":{"id":255702493,"uuid":"853482945","full_name":"lunaticsm/catbox-uploader","owner":"lunaticsm","description":"Catbox Uploader is a simple Python library to upload files and URLs to Catbox.moe.","archived":false,"fork":false,"pushed_at":"2024-09-17T07:09:55.000Z","size":35,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-08T09:34:46.982Z","etag":null,"topics":["catbox","catbox-moe","catboxmoe","telegraph","telegraph-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lunaticsm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-06T18:42:27.000Z","updated_at":"2025-01-04T09:24:13.000Z","dependencies_parsed_at":"2024-09-06T19:55:12.226Z","dependency_job_id":"8a826749-aa7e-49e4-be84-601b6d228c0a","html_url":"https://github.com/lunaticsm/catbox-uploader","commit_stats":null,"previous_names":["lunaticsm/catbox-uploader"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/lunaticsm/catbox-uploader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunaticsm%2Fcatbox-uploader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunaticsm%2Fcatbox-uploader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunaticsm%2Fcatbox-uploader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunaticsm%2Fcatbox-uploader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lunaticsm","download_url":"https://codeload.github.com/lunaticsm/catbox-uploader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunaticsm%2Fcatbox-uploader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273973379,"owners_count":25200575,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["catbox","catbox-moe","catboxmoe","telegraph","telegraph-api"],"created_at":"2024-09-09T17:01:03.385Z","updated_at":"2025-09-06T22:30:59.808Z","avatar_url":"https://github.com/lunaticsm.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Catbox Uploader\n\nCatbox 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.\n\n## Installation\n\n```bash\npip install catbox-uploader\n```\n\n## Usage\n\n### Using Userhash\n\nCatboxUploader supports using a **userhash** directly. You can pass the `userhash` when initializing the `CatboxUploader` and use it for authenticated uploads and album management.\n\n### Initialize with Userhash\n\n```python\nfrom catbox import CatboxUploader\n\nuploader = CatboxUploader(userhash='your_userhash_here')\n```\n\n### Initialize without Userhash\n\n```python\nfrom catbox import CatboxUploader\n\nuploader = CatboxUploader()\n```\n\n### Upload a File\n\n```python\nlink = uploader.upload_file('path/to/your/file.jpg')\nprint(f'Uploaded file: {link}')\n```\n\n### Upload a File to Litterbox (Temporary Storage)\n\nLitterbox 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.\n\n**Available expiration times**:\n- `1h`: 1 hour\n- `12h`: 12 hours\n- `24h`: 24 hours\n- `72h`: 3 days\n\n```python\nlink = uploader.upload_to_litterbox('path/to/your/file.jpg', time='24h')\nprint(f'Uploaded file (available for 24 hours): {link}')\n```\n\n### Upload Multiple Files as an Album\n\nYou 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.\n\n```python\nfile_paths = ['file1.jpg', 'file2.jpg', 'file3.jpg']\nlinks = uploader.upload_album(file_paths)\nfor link in links:\n    print(f'Uploaded file link: {link}')\n```\n\n### Create and Manage Albums\n\n#### Create an Album\n\nYou can create an album with uploaded files, a title, and a description using the `create_album` method:\n\n```python\nalbum_shortcode = uploader.create_album(file_links, \"My Album\", \"This is a test album\")\nprint(f\"Album created: https://catbox.moe/c/{album_shortcode}\")\n```\n\n#### Edit an Album\n\nYou can edit an album by changing its title, description, or the files it contains:\n\n```python\nuploader.edit_album(album_shortcode, file_links, \"Updated Album Title\", \"Updated description\")\n```\n\n#### Delete an Album\n\nYou can delete an album by its shortcode:\n\n```python\nuploader.delete_album(album_shortcode)\n```\n\n### Error Handling\n\nThe library comes with built-in exception handling to manage common errors such as timeouts, connection issues, or HTTP errors.\n\n### Handling Timeout\n\nIf the upload takes too long and exceeds the specified timeout, a `TimeoutError` will be raised.\n\n```python\nfrom catbox import CatboxUploader, TimeoutError\n\nuploader = CatboxUploader(userhash='your_userhash_here')\ntry:\n    link = uploader.upload_file('path/to/your/file.jpg', timeout=10)\n    print(f'Uploaded file: {link}')\nexcept TimeoutError:\n    print(\"The upload took too long and timed out.\")\n```\n\n### Handling Connection Issues\n\nIf there's a problem connecting to the **Catbox.moe** or **Litterbox** server, a `ConnectionError` will be raised.\n\n```python\nfrom catbox import CatboxUploader, ConnectionError\n\nuploader = CatboxUploader(userhash='your_userhash_here')\ntry:\n    link = uploader.upload_file('path/to/your/file.jpg')\n    print(f'Uploaded file: {link}')\nexcept ConnectionError:\n    print(\"Failed to connect to the server.\")\n```\n\n### Handling HTTP Errors\n\nIn case of HTTP errors (such as 404 or 500), an `HTTPError` will be raised.\n\n```python\nfrom catbox import CatboxUploader, HTTPError\n\nuploader = CatboxUploader(userhash='your_userhash_here')\ntry:\n    link = uploader.upload_file('path/to/your/file.jpg')\n    print(f'Uploaded file: {link}')\nexcept HTTPError as he:\n    print(f\"HTTP error occurred: {he}\")\n```\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flunaticsm%2Fcatbox-uploader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flunaticsm%2Fcatbox-uploader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flunaticsm%2Fcatbox-uploader/lists"}