Skip to content

Commit

Permalink
Readme update (#280)
Browse files Browse the repository at this point in the history
  • Loading branch information
@rsedykh @evgkirov
rsedykh authored and evgkirov committed Mar 2, 2024
1 parent 3ee178c commit d07e311
Show file tree
Hide file tree
Showing 3 changed files with 223 additions and 65 deletions.
274 changes: 218 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,78 +1,240 @@

<table>
<tr style="border: none;">
<td style="border: none;">
<img src="https://ucarecdn.com/2f4864b7-ed0e-4411-965b-8148623aa680/-/inline/yes/uploadcare-logo-mark.svg" target="" width="64" height="64">
</td>
<th style="vertical-align: center; border: none;">
<h1>PyUploadcare: a Python library for Uploadcare</h1>
</th>
</tr>
</table>

<p>
<a href="https://pypi.org/project/pyuploadcare/">
<img src="https://badge.fury.io/py/pyuploadcare.svg" height="25" />
</a>
<a href="https://github.com/uploadcare/pyuploadcare/actions?query=branch%3Amain+workflow%3ATests++">
<img src="https://github.com/uploadcare/pyuploadcare/actions/workflows/test.yml/badge.svg" height="25" />
</a>
<a href="https://pyuploadcare.readthedocs.io/">
<img src="https://readthedocs.org/projects/pyuploadcare/badge/?version=latest" height="25" />
</a>
<a href="https://stackshare.io/uploadcare">
<img src="https://img.shields.io/badge/tech-stack-0690fa.svg?style=flat" height="25" />
<p align="center">
<a href="https://uploadcare.com/?ref=github-readme">
<picture>
<source media="(prefers-color-scheme: light)" srcset="https://ucarecdn.com/1b4714cd-53be-447b-bbde-e061f1e5a22f/logosafespacetransparent.svg">
<source media="(prefers-color-scheme: dark)" srcset="https://ucarecdn.com/3b610a0a-780c-4750-a8b4-3bf4a8c90389/logotransparentinverted.svg">
<img width=250 alt="Uploadcare logo" src="https://ucarecdn.com/1b4714cd-53be-447b-bbde-e061f1e5a22f/logosafespacetransparent.svg">
</picture>
</a>
</p>
<p align="center">
<a href="https://pyuploadcare.readthedocs.io/en/latest/">Package Docs</a> •
<a href="https://uploadcare.com/docs/">Uploadcare Docs</a> •
<a href="https://uploadcare.com/api-refs/upload-api/">Upload API Reference</a> •
<a href="https://uploadcare.com/api-refs/rest-api/">REST API Reference</a> •
<a href="https://uploadcare.com/api-refs/url-api/">URL API Reference</a> •
<a href="https://uploadcare.com/">Website</a>
</p>

# Python API client for Uploadcare

[![](https://badge.fury.io/py/pyuploadcare.svg)](https://pypi.org/project/pyuploadcare/)
[![](https://github.com/uploadcare/pyuploadcare/actions/workflows/test.yml/badge.svg)](https://github.com/uploadcare/pyuploadcare/actions?query=branch%3Amain+workflow%3ATests++)
[![](https://readthedocs.org/projects/pyuploadcare/badge/?version=latest)](https://pyuploadcare.readthedocs.io/)
[![](https://img.shields.io/badge/tech-stack-0690fa.svg?style=flat)](https://stackshare.io/uploadcare)

Build file handling in minutes. Upload or accept user-generated content, store, transform, optimize, and deliver images, videos, and documents to billions of users.

* [Features](#features)
* [Documentation](#documentation)
* [Requirements and installation](#requirements-and-installation)
* [Usage examples](#usage-examples)
* [Demo app (Docker)](#demo-app)

## Features

This 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.

* [Upload](https://uploadcare.com/docs/uploads/) files from anywhere via API or ready-made File Uploader
* [Manage](https://uploadcare.com/docs/start/file-management/) stored files and perform various actions and conversions with them
* [Optimize](https://uploadcare.com/docs/transformations/image/compression/) and [transform](https://uploadcare.com/docs/transformations/image/) images on the fly
* [Deliver](https://uploadcare.com/docs/delivery/) files fast and secure

## Documentation

Detailed specification of this library is available [on RTD](https://pyuploadcare.readthedocs.io/en/latest/).

Please 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.

## Requirements and installation

* Python 3.8, 3.9, 3.10, 3.11, 3.12

Uploadcare Python & Django integrations handle uploads and further operations
with files by wrapping Upload and REST APIs.
To use pyuploadcare with Python 3.6 or 3.7 please install `pyuploadcare < 5.0`.

Simple file uploads for the web are of most importance for us. Today, everyone
is used to the routine of allowing users to upload their pics or attach resumes.
The routine covers it all: installing image processing libraries, adjusting
permissions, ensuring servers never go down, and enabling CDN.
To use pyuploadcare with Python 2.7 please install `pyuploadcare < 3.0`.

This library consists of the Uploadcare API interface and a couple of Django
goodies.
Django compatibility:

Simple as that, Uploadcare `ImageField` can be added to an
existing Django project in just a couple of [simple steps](https://pyuploadcare.readthedocs.org/en/latest/quickstart.html).
This will enable your users to see the upload progress, pick files
from Google Drive or Instagram, and edit a form while files are
being uploaded asynchronously.
| Py/Dj | 2.2 | 3.0 | 3.1 | 3.2 | 4.0 | 4.1 | 4.2 | 5.0 |
| ----- | --- | --- | --- | --- | --- | --- | --- | --- |
| 3.8 | X | X | X | X | X | X | X | |
| 3.9 | X | X | X | X | X | X | X | |
| 3.10 | | | | X | X | X | X | X |
| 3.11 | | | | | | X | X | X |
| 3.12 | | | | | | | X | X |

You can find an example project [here](https://github.com/uploadcare/pyuploadcare-example).
In order to install `pyuploadcare`, run these command in CLI:

```bash
pip install pyuploadcare
```

To use in Django project install with extra dependencies:

```bash
pip install pyuploadcare[django]
```

## Usage examples

After 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.

In these examples we’re going to use the aforementioned demo keys.

### Basic usage

Let’s start with the basics. Say, you want to upload a file:

```python
from pyuploadcare import Uploadcare

from django import forms
from django.db import models
uploadcare = Uploadcare(public_key="demopublickey", secret_key="demoprivatekey")
with open("sample-file.jpeg", "rb") as file_object:
ucare_file = uploadcare.upload(file_object)
```

from pyuploadcare.dj.models import ImageField
from pyuploadcare.dj.forms import FileWidget, ImageField as ImageFormField
And your file is now uploaded to the Uploadcare CDN. But how do you access it from the web? It’s really simple:

```python
print(ucare_file.cdn_url) # file URL, e.g.: https://ucarecdn.com/640fe4b7-7352-42ca-8d87-0e4387957157/
```

class Candidate(models.Model):
photo = ImageField(blank=True, manual_crop="")
And what about information about the file?

```python
from pprint import pprint

pprint(ucare_file.info)

# {'appdata': None,
# 'content_info': {'image': {'color_mode': <ColorMode.RGB: 'RGB'>,
# 'datetime_original': datetime.datetime(2023, 3, 10, 16, 23, 15),
# 'dpi': (72, 72),
# 'format': 'JPEG',
# 'geo_location': None,
# 'height': 4516,
# 'orientation': 1,
# 'sequence': False,
# 'width': 3011},
# 'mime': {'mime': 'image/jpeg',
# 'subtype': 'jpeg',
# 'type': 'image'},
# 'video': None},
# 'datetime_removed': None,
# 'datetime_stored': datetime.datetime(2024, 2, 16, 14, 44, 29, 637342, tzinfo=TzInfo(UTC)),
# 'datetime_uploaded': datetime.datetime(2024, 2, 16, 14, 44, 29, 395043, tzinfo=TzInfo(UTC)),
# 'is_image': True,
# 'is_ready': True,
# 'metadata': {},
# 'mime_type': 'image/jpeg',
# 'original_file_url': 'https://ucarecdn.com/640fe4b7-7352-42ca-8d87-0e4387957157/samplefile.jpeg',
# 'original_filename': 'sample-file.jpeg',
# 'size': 3518420,
# 'source': None,
# 'url': 'https://api.uploadcare.com/files/640fe4b7-7352-42ca-8d87-0e4387957157/',
# 'uuid': UUID('640fe4b7-7352-42ca-8d87-0e4387957157'),
# 'variations': None}
```

A 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:

```python
from pyuploadcare.transformations.image import ImageTransformation, ScaleCropMode

# optional. provide advanced widget options: https://uploadcare.com/docs/uploads/widget/config/#options
class CandidateForm(forms.Form):
photo = ImageFormField(widget=FileWidget(attrs={
'data-cdn-base': 'https://cdn.super-candidates.com',
'data-image-shrink': '1024x1024',
}))
# These two function calls are equivalent
ucare_file.set_effects("scale_crop/512x512/smart/")
ucare_file.set_effects(ImageTransformation().scale_crop(512, 512, mode=ScaleCropMode.smart))

print(ucare_file.cdn_url) # https://ucarecdn.com/640fe4b7-7352-42ca-8d87-0e4387957157/-/scale_crop/512x512/smart/
```

![](https://ucarecdn.com/f0894ef2-352e-406a-8279-737dd6e1f10c/-/resize/800/manual_crop.png)
There’s a lot more to uncover. For more information please refer to the [documentation](#documentation).

## Documentation
### Django integration

Let's add [File Uploader](https://uploadcare.com/docs/file-uploader/) to an existing Django project.

We 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.

Assume you have a Django project with `gallery` app.

Add `pyuploadcare.dj` into `INSTALLED_APPS`:

```python
INSTALLED_APPS = (
# ...
"pyuploadcare.dj",
"gallery",
)
```

Add API keys to your Django settings file:

```python
UPLOADCARE = {
"pub_key": "demopublickey",
"secret": "demoprivatekey",
}
```

Uploadcare image field adding to your `gallery/models.py` is really simple. Like that:

```python
from django.db import models

from pyuploadcare.dj.models import ImageField


class Photo(models.Model):
title = models.CharField(max_length=255)
photo = ImageField()
```

`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:

![](https://ucarecdn.com/6dbac4f4-7cda-42cd-872b-cecf45b9f515/-/scale_crop/900x600/left/)

Obviously, 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 `<head>` tag of your page:

```htmldjango
{{ form.media }}
<form action="" method="post">
{% csrf_token %}
{{ form.as_p }}
<input type="submit" value="Save"/>
</form>
```
This is a default Django form property which is going to render any scripts needed for the form to work, in our case — Uploadcare scripts.

![](https://ucarecdn.com/f0894ef2-352e-406a-8279-737dd6e1f10c/-/resize/800/josi.png)

After an image is uploaded, you can deliver it while transforming it on the fly:

```htmldjango
{% for photo in photos %}
<h2>{{ photo.title }}</h2>
<img src="{{ photo.photo.cdn_url }}-/resize/400x300/-/effect/flip/-/effect/grayscale/">
{% endfor %}
```

(Refer to Uploadcare [image processing docs](https://uploadcare.com/docs/transformations/image/) for more information).

## Testing

To 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:

```make test_with_github_actions```

This runs the full suite of tests across Python and Django versions.

## Demo app

Detailed documentation is available [on RTD](https://pyuploadcare.readthedocs.io/en/latest/).
We'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.

## Feedback
## Suggestions and questions

Issues and PRs are welcome. You can provide your feedback or drop us a support
request at [hello@uploadcare.com](hello@uploadcare.com).
[Contributing guide](https://github.com/uploadcare/.github/blob/master/CONTRIBUTING.md)
[Security policy](https://github.com/uploadcare/pyuploadcare/security/policy)
[Support](https://github.com/uploadcare/.github/blob/master/SUPPORT.md)
4 changes: 1 addition & 3 deletions docs/django-widget.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -241,9 +241,7 @@ You can pass any widget `options`_ via ``FileWidget``'s attrs argument:
from pyuploadcare.dj.forms import FileWidget, ImageField
# optional. provide advanced widget options:
# https://uploadcare.com/docs/file-uploader/configuration/
# https://uploadcare.com/docs/file-uploader/options/
# Optional: provide advanced widget options https://uploadcare.com/docs/file-uploader/options/
class CandidateForm(forms.Form):
photo = ImageField(widget=FileWidget(attrs={
"source-list": "local,url,camera",
Expand Down
10 changes: 4 additions & 6 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,11 @@ You can find an example project `here`_.
photo = ImageField(blank=True, manual_crop='4:3')
# optional. provide advanced widget options:
# https://uploadcare.com/docs/file-uploader/configuration/
# https://uploadcare.com/docs/file-uploader/options/
# Optional: provide advanced widget options https://uploadcare.com/docs/file-uploader/options/
class CandidateForm(forms.Form):
photo = ImageField(widget=FileWidget(attrs={
'source-list': 'local,url,camera',
'camera-mirror': True,
photo = ImageFormField(widget=FileWidget(attrs={
"source-list": "local,url,camera",
"camera-mirror": True,
}))
.. image:: https://ucarecdn.com/f0894ef2-352e-406a-8279-737dd6e1f10c/-/resize/800/manual_crop.png
Expand Down

0 comments on commit d07e311

Please sign in to comment.