{"id":13419438,"url":"https://github.com/uploadcare/pyuploadcare","last_synced_at":"2025-04-08T02:36:13.875Z","repository":{"id":650063,"uuid":"2203143","full_name":"uploadcare/pyuploadcare","owner":"uploadcare","description":"Build file handling in minutes. Upload or accept user-generated content, store, transform, optimize, and deliver images, videos, and documents to billions of users.","archived":false,"fork":false,"pushed_at":"2025-03-12T12:11:50.000Z","size":3396,"stargazers_count":129,"open_issues_count":7,"forks_count":33,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-03-21T23:35:13.786Z","etag":null,"topics":["cdn","file-system","file-upload","image-manipulation","image-processing","python","upload","uploader"],"latest_commit_sha":null,"homepage":"https://uploadcare.com/","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/uploadcare.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security_issues.rst","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-08-13T21:16:31.000Z","updated_at":"2025-03-06T22:27:38.000Z","dependencies_parsed_at":"2023-07-05T15:02:27.942Z","dependency_job_id":"d02df469-c64f-4ca0-8c4b-da078dd46137","html_url":"https://github.com/uploadcare/pyuploadcare","commit_stats":{"total_commits":753,"total_committers":27,"mean_commits":27.88888888888889,"dds":0.7529880478087649,"last_synced_commit":"51f47f6c3ca6bea45e7e0b33735c16af3ae5717e"},"previous_names":[],"tags_count":68,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fpyuploadcare","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fpyuploadcare/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fpyuploadcare/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fpyuploadcare/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uploadcare","download_url":"https://codeload.github.com/uploadcare/pyuploadcare/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247765460,"owners_count":20992314,"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","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":["cdn","file-system","file-upload","image-manipulation","image-processing","python","upload","uploader"],"created_at":"2024-07-30T22:01:16.020Z","updated_at":"2025-04-08T02:36:13.853Z","avatar_url":"https://github.com/uploadcare.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://uploadcare.com/?ref=github-readme\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://ucarecdn.com/1b4714cd-53be-447b-bbde-e061f1e5a22f/logosafespacetransparent.svg\"\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://ucarecdn.com/3b610a0a-780c-4750-a8b4-3bf4a8c90389/logotransparentinverted.svg\"\u003e\n      \u003cimg width=250 alt=\"Uploadcare logo\" src=\"https://ucarecdn.com/1b4714cd-53be-447b-bbde-e061f1e5a22f/logosafespacetransparent.svg\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pyuploadcare.readthedocs.io/en/latest/\"\u003ePackage Docs\u003c/a\u003e • \n  \u003ca href=\"https://uploadcare.com/docs/\"\u003eUploadcare Docs\u003c/a\u003e • \n  \u003ca href=\"https://uploadcare.com/api-refs/upload-api/\"\u003eUpload API Reference\u003c/a\u003e • \n  \u003ca href=\"https://uploadcare.com/api-refs/rest-api/\"\u003eREST API Reference\u003c/a\u003e • \n  \u003ca href=\"https://uploadcare.com/api-refs/url-api/\"\u003eURL API Reference\u003c/a\u003e • \n  \u003ca href=\"https://uploadcare.com/\"\u003eWebsite\u003c/a\u003e\n\u003c/p\u003e\n\n# Python API client for Uploadcare\n\n[![](https://badge.fury.io/py/pyuploadcare.svg)](https://pypi.org/project/pyuploadcare/)\n[![](https://github.com/uploadcare/pyuploadcare/actions/workflows/test.yml/badge.svg)](https://github.com/uploadcare/pyuploadcare/actions?query=branch%3Amain+workflow%3ATests++)\n[![](https://readthedocs.org/projects/pyuploadcare/badge/?version=latest)](https://pyuploadcare.readthedocs.io/)\n[![](https://img.shields.io/badge/tech-stack-0690fa.svg?style=flat)](https://stackshare.io/uploadcare)\n\nBuild file handling in minutes. Upload or accept user-generated content, store, transform, optimize, and deliver images, videos, and documents to billions of users.\n\n* [Description](#description)\n* [Documentation](#documentation)\n* [Installation](#installation)\n* [Requirements](#requirements)\n* [Usage](#usage)\n* [Testing](#testing)\n* [Demo app (Docker)](#demo-app)\n\n## Description\n\nThis library consists of the APIs interface and a couple of Django goodies, 100% covering [Upload](https://uploadcare.com/api-refs/upload-api/), [REST](https://uploadcare.com/api-refs/rest-api/) and [URL](https://uploadcare.com/api-refs/url-api/) Uploadcare APIs.\n\n* [Upload](https://uploadcare.com/docs/uploads/) files from anywhere via API or ready-made File Uploader\n* [Manage](https://uploadcare.com/docs/start/file-management/) stored files and perform various actions and conversions with them\n* [Optimize](https://uploadcare.com/docs/transformations/image/compression/) and [transform](https://uploadcare.com/docs/transformations/image/) images on the fly\n* [Deliver](https://uploadcare.com/docs/delivery/) files fast and secure\n\n## Documentation\n\nDetailed specification of this library is available [on RTD](https://pyuploadcare.readthedocs.io/en/latest/).\n\nPlease note that this package uses Uploadcare [API keys](https://app.uploadcare.com/projects/-/api-keys) and is intended to be used in server-side code only.\n\n## Installation\n\nIn order to install `pyuploadcare`, run these command in CLI:\n\n```bash\npip install pyuploadcare\n```\n\nTo use in Django project install with extra dependencies:\n\n```bash\npip install pyuploadcare[django]\n```\n\n## Requirements\n\n* Python 3.8, 3.9, 3.10, 3.11, 3.12\n\nTo use pyuploadcare with Python 3.6 or 3.7 please install `pyuploadcare \u003c 5.0`.\n\nTo use pyuploadcare with Python 2.7 please install `pyuploadcare \u003c 3.0`.\n\nDjango compatibility:\n\n| Py/Dj | 2.2 | 3.0 | 3.1 | 3.2 | 4.0 | 4.1 | 4.2 | 5.0 |\n| ----- | --- | --- | --- | --- | --- | --- | --- | --- |\n| 3.8   | X   | X   | X   | X   | X   | X   | X   |     |\n| 3.9   | X   | X   | X   | X   | X   | X   | X   |     |\n| 3.10  |     |     |     | X   | X   | X   | X   | X   |\n| 3.11  |     |     |     |     |     | X   | X   | X   |\n| 3.12  |     |     |     |     |     |     | X   | X   |\n\n## Usage\n\nAfter package [installation](#requirements-and-installation), you’ll need API keys: public and secret. Get them in [Uploadcare dashboard](https://app.uploadcare.com/projects/-/api-keys). If you don’t have an account yet, you can use demo keys, as in example. However, the files on demo account are regularly removed, so create an account as soon as Uploadcare catches your fancy.\n\nIn these examples we’re going to use the aforementioned demo keys.\n\n### Basic usage\n\nLet’s start with the basics. Say, you want to upload a file:\n\n```python\nfrom pyuploadcare import Uploadcare\n\nuploadcare = Uploadcare(public_key=\"demopublickey\", secret_key=\"demoprivatekey\")\nwith open(\"sample-file.jpeg\", \"rb\") as file_object:\n    ucare_file = uploadcare.upload(file_object)\n```\n\nAnd your file is now uploaded to the Uploadcare CDN. But how do you access it from the web? It’s really simple:\n\n```python\nprint(ucare_file.cdn_url)  # file URL, e.g.: https://ucarecdn.com/640fe4b7-7352-42ca-8d87-0e4387957157/\n```\n\nAnd what about information about the file?\n\n```python\nfrom pprint import pprint\n\npprint(ucare_file.info)\n\n# {'appdata': None,\n#  'content_info': {'image': {'color_mode': \u003cColorMode.RGB: 'RGB'\u003e,\n#                             'datetime_original': datetime.datetime(2023, 3, 10, 16, 23, 15),\n#                             'dpi': (72, 72),\n#                             'format': 'JPEG',\n#                             'geo_location': None,\n#                             'height': 4516,\n#                             'orientation': 1,\n#                             'sequence': False,\n#                             'width': 3011},\n#                   'mime': {'mime': 'image/jpeg',\n#                            'subtype': 'jpeg',\n#                            'type': 'image'},\n#                   'video': None},\n#  'datetime_removed': None,\n#  'datetime_stored': datetime.datetime(2024, 2, 16, 14, 44, 29, 637342, tzinfo=TzInfo(UTC)),\n#  'datetime_uploaded': datetime.datetime(2024, 2, 16, 14, 44, 29, 395043, tzinfo=TzInfo(UTC)),\n#  'is_image': True,\n#  'is_ready': True,\n#  'metadata': {},\n#  'mime_type': 'image/jpeg',\n#  'original_file_url': 'https://ucarecdn.com/640fe4b7-7352-42ca-8d87-0e4387957157/samplefile.jpeg',\n#  'original_filename': 'sample-file.jpeg',\n#  'size': 3518420,\n#  'source': None,\n#  'url': 'https://api.uploadcare.com/files/640fe4b7-7352-42ca-8d87-0e4387957157/',\n#  'uuid': UUID('640fe4b7-7352-42ca-8d87-0e4387957157'),\n#  'variations': None}\n```\n\nA whole slew of different file operations are available. Do you want to crop your image, but don't want important information (faces, objects) to be cropped? You can do that with content-aware (“smart”) crop:\n\n```python\nfrom pyuploadcare.transformations.image import ImageTransformation, ScaleCropMode\n\n# These two function calls are equivalent\nucare_file.set_effects(\"scale_crop/512x512/smart/\")\nucare_file.set_effects(ImageTransformation().scale_crop(512, 512, mode=ScaleCropMode.smart))\n\nprint(ucare_file.cdn_url)  # https://ucarecdn.com/640fe4b7-7352-42ca-8d87-0e4387957157/-/scale_crop/512x512/smart/\n```\n\nThere’s a lot more to uncover. For more information please refer to the [documentation](#documentation).\n\n### Django integration\n\nLet's add [File Uploader](https://uploadcare.com/docs/file-uploader/) to an existing Django project.\n\nWe will allow users to upload their images through a nice and modern UI within the standard Django admin or outside of it, and then display these images on the website and modify them using advanced Uploadcare CDN features.\n\nAssume you have a Django project with `gallery` app.\n\nAdd `pyuploadcare.dj` into `INSTALLED_APPS`:\n\n```python\nINSTALLED_APPS = (\n    # ...\n    \"pyuploadcare.dj\",\n    \"gallery\",\n)\n```\n\nAdd API keys to your Django settings file:\n\n```python\nUPLOADCARE = {\n    \"pub_key\": \"demopublickey\",\n    \"secret\": \"demoprivatekey\",\n}\n```\n\nUploadcare image field adding to your `gallery/models.py` is really simple. Like that:\n\n```python\nfrom django.db import models\n\nfrom pyuploadcare.dj.models import ImageField\n\n\nclass Photo(models.Model):\n    title = models.CharField(max_length=255)\n    photo = ImageField()\n```\n\n`ImageField` doesn’t require any arguments, file paths or whatever. **It just works**. That’s the point of it all. It looks nice in the admin interface as well:\n\n![](https://ucarecdn.com/6dbac4f4-7cda-42cd-872b-cecf45b9f515/-/scale_crop/900x600/left/)\n\nObviously, you would want to use Uploadcare field outside an admin. It’s going to work just as well, but, however, you have to remember to add `{{ form.media }}` in the `\u003chead\u003e` tag of your page:\n\n```htmldjango\n{{ form.media }}\n\n\u003cform action=\"\" method=\"post\"\u003e\n    {% csrf_token %}\n    {{ form.as_p }}\n    \u003cinput type=\"submit\" value=\"Save\"/\u003e\n\u003c/form\u003e\n```\nThis is a default Django form property which is going to render any scripts needed for the form to work, in our case — Uploadcare scripts.\n\n![](https://ucarecdn.com/f0894ef2-352e-406a-8279-737dd6e1f10c/-/resize/800/josi.png)\n\nAfter an image is uploaded, you can deliver it while transforming it on the fly:\n\n```htmldjango\n{% for photo in photos %}\n    \u003ch2\u003e{{ photo.title }}\u003c/h2\u003e\n    \u003cimg src=\"{{ photo.photo.cdn_url }}-/resize/400x300/-/effect/flip/-/effect/grayscale/\"\u003e\n{% endfor %}\n```\n\n(Refer to Uploadcare [image processing docs](https://uploadcare.com/docs/transformations/image/) for more information).\n\n## Testing\n\nTo run tests using [Github Actions](https://github.com/uploadcare/pyuploadcare/actions) workflows, but locally, install the [act](https://github.com/nektos/act) utility, and then run it:\n\n```make test_with_github_actions```\n\nThis runs the full suite of tests across Python and Django versions.\n\n## Demo app\n\nWe've developed a demo app that showcases most of the features. You can install [pyuploadcare-example](https://github.com/uploadcare/pyuploadcare-example) using Docker or without it. You can use it as a reference or even base your project on it.\n\n## Suggestions and questions\n\n[Contributing guide](https://github.com/uploadcare/.github/blob/master/CONTRIBUTING.md)  \n[Security policy](https://github.com/uploadcare/pyuploadcare/security/policy)  \n[Support](https://github.com/uploadcare/.github/blob/master/SUPPORT.md)  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuploadcare%2Fpyuploadcare","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuploadcare%2Fpyuploadcare","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuploadcare%2Fpyuploadcare/lists"}