Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dreipol/retina
Painless retina image handling
https://github.com/dreipol/retina
Last synced: 7 days ago
JSON representation
Painless retina image handling
- Host: GitHub
- URL: https://github.com/dreipol/retina
- Owner: dreipol
- License: mit
- Created: 2018-11-06T15:44:38.000Z (about 6 years ago)
- Default Branch: develop
- Last Pushed: 2021-06-10T21:03:09.000Z (over 3 years ago)
- Last Synced: 2024-09-25T12:29:24.060Z (about 2 months ago)
- Language: Python
- Homepage:
- Size: 14.6 KB
- Stars: 6
- Watchers: 13
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 👁 Retina
[GitHub](https://github.com/dreipol/retina) | [PyPI](https://pypi.org/project/retina/)
Retina takes an image and a thumbnail alias and generates a dict with resized images. So if your `easy_thumbnails`
alias looks something like this `'portrait': {'size': (150, 200)}` you'll get the resized version of the original image
plus a retina version of it.
```python
image = File(user.profile_image).srcset('portrait')
# image holds now the following dict:
{
'urls': {
'default': [
'path/to/images/profile_image__150x200.jpg',
'path/to/images/profile_image__300x400.jpg',
]
},
'alt': 'John Doe',
}
```
## Installation
First, install the latest release:
$ pip install retina
Register the adapters you want to use somewhere at boot:
```python
from filer.models import Image as FilerImage
from filer.models import File as FilerFile
from retina.adapters.filer import FilerImageAdapter, FilerFileAdapter
from retina import manager
manager.update_adapters({
FilerImage: FilerImageAdapter,
FilerFile: FilerFileAdapter,
})
```
Or if you're using `django` with `django-filer` (which is the use-case Retina was developed for) this is even easier:
```python
from retina import manager
manager.load_default_adapters()
```
## Usage
Initiate the `retina.File` class with a `django-filer` `File` or `Image` model and call the `srcset` method with a `easy_thumbnails` alias as parameter on it. This will always return a dict with a `urls` and `alt` key. Where `urls` is again a dict of different sizes (`default` being the default if nothing else specified) and `alt` is just a string containing the alt text for the image. Retina tries to get the alt text by accessing any of the following properties on the `filer.Image` model: `default_alt_text`, `name`, `original_filename`
### Basic
```python
image = File(user.profile_image).srcset('portrait')
{
'urls': {
'default': [
'path/to/images/profile_image__150x200.jpg',
'path/to/images/profile_image__300x400.jpg',
]
},
'alt': 'John Doe',
}
```
### Density
You can chain an additional density method to get a @3, @4, e.t.c version of the source image.
```python
image = File(user.profile_image).density(3).srcset('portrait')
{
'urls': {
'default': [
'path/to/images/profile_image__150x200.jpg',
'path/to/images/profile_image__300x400.jpg',
'path/to/images/profile_image__450x600.jpg',
]
},
'alt': 'John Doe',
}
```
### Sizes
If you're website needs different image dimensions, say on mobile than on desktop, you can do that as well:
```python
THUMBNAIL_ALIASES = {
'': {
'portrait_sm': {'size': (100, 100)},
'portrait_xl': {'size': (150, 200)},
}
},
image = File(user.profile_image).srcset('portrait', ['sm', 'xl'])
{
'urls': {
'sm': [
'path/to/images/profile_image__100x100.jpg',
'path/to/images/profile_image__200x200.jpg',
],
'xl': [
'path/to/images/profile_image__150x200.jpg',
'path/to/images/profile_image__300x400.jpg',
]
},
'alt': 'John Doe',
}
```
Notice how the alias is now a combination of `portrait` + `_` + `[size]`
### Additional Data
Pass in any arbitary additional data to the returned dict:
```python
image = File(user.profile_image)).additional(foo='bar', bar='baz').srcset('portrait')
{
'urls': {
'default': [
'path/to/images/profile_image__150x200.jpg',
'path/to/images/profile_image__300x400.jpg',
],
},
'foo': 'bar',
'bar': 'baz',
'alt': 'John Doe',
}
```
Notice how the alias is now a combination of `portrait` + `_` + `[size]`
## Adapters
Retina uses the concept of adapters. Each adapter implements a set of methods that define how an image instance (whatever it may be) should be resized. Retina ships with two adapters out of the box: `FilerImageAdapter` and `FilerFileAdapter`. This means, that if you followed the installation steps above you can pass in any `django-filer` `File` or `Image` model and it will output you resized versions of given file (if resizable at all).
You're free two write your own adapters and register them on the manager via the `update_adapters` method. Just pass in a dict where the key is a python `type` (like str, dict or any other object) and the value is your adapter.