| Name | django-thumbnails JSON |
| Version |
0.8.0
JSON |
| download |
| home_page | https://github.com/ui/django-thumbnails |
| Summary | A simple Django app to manage image/photo thumbnails. Supports remote/cloud storage systems like Amazon S3. |
| upload_time | 2024-07-24 08:58:58 |
| maintainer | None |
| docs_url | None |
| author | Selwin Ong |
| requires_python | None |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://travis-ci.org/ui/django-thumbnails)
Design:
- Uses Django Storage API
- Uses flexible meta data store. Uses Redis as metadata store.
- Supports creating thumbnails in different formats, for example from
JPG to WEBP to reduce file size
Supported image formats:
- JPG/JPEG
- GIF
- PNG
- WEBP
## Installation
- Add thumbnails to INSTALLED_APPS in settings.py.
- Run python manage.py migrate to create database metadata backend.
## Usage
settings.py:
```python
THUMBNAILS = {
'METADATA': {
'BACKEND': 'thumbnails.backends.metadata.DatabaseBackend',
},
'STORAGE': {
'BACKEND': 'django.core.files.storage.FileSystemStorage',
# You can also use Amazon S3 or any other Django storage backends
},
'SIZES': {
'small': {
'PROCESSORS': [
{'PATH': 'thumbnails.processors.resize', 'width': 10, 'height': 10},
{'PATH': 'thumbnails.processors.crop', 'width': 80, 'height': 80}
],
'POST_PROCESSORS': [
{
'PATH': 'thumbnails.post_processors.optimize',
'png_command': 'optipng -force -o7 "%(filename)s"',
'jpg_command': 'jpegoptim -f --strip-all "%(filename)s"',
},
],
},
'large': {
'PROCESSORS': [
{'PATH': 'thumbnails.processors.resize', 'width': 20, 'height': 20},
{'PATH': 'thumbnails.processors.flip', 'direction': 'horizontal'}
],
},
'watermarked': {
'PROCESSORS': [
{'PATH': 'thumbnails.processors.resize', 'width': 20, 'height': 20},
# Only supports PNG. File must be of the same size with thumbnail (20 x 20 in this case)
{'PATH': 'thumbnails.processors.add_watermark', 'watermark_path': 'watermark.png'}
],
}
}
}
```
If you prefer to use Redis as your metadata storage backend (for performance reasons):
```python
THUMBNAILS = {
'METADATA': {
'PREFIX': 'thumbs',
'BACKEND': 'thumbnails.backends.metadata.RedisBackend',
'db': 2,
'port': 6379,
'host': 'localhost',
},
}
```
## Image Processors
`django-thumbnails` comes with a few builtin image processors:
```python
# To use the following processors, put the arguments of processors in SIZES definition
thumbnails.processors.resize(width, height, method) ## `method` can be `stretch`, `fit` or `fill`
thumbnails.processors.rotate(degrees)
thumbnails.processors.flip(direction)
thumbnails.processors.crop(width, height, center)
thumbnails.processors.add_watermark(watermark_path)
```
Processors are applied sequentially in the same order of definition.
## Storage Backend
New in version 0.5.0 is per field, customizable storage backend. If you want specific fields to use
a different storage backend, you can specify it directly when declaring the field. e.g:
```python
class Food(models.Model):
image = ImageField(storage=FileSystemStorage(), upload_to='food')
```
Storage that is specified on field will be used instead of storage that is specified in the settings.
## Metadata Backend
If you want specific fields to use different metadata backend, you can specify it directly when declaring the field. e.g:
```python
class Food(models.Model):
image = ImageField(metadata_backend=CustomMetadataBackend(), upload_to='food')
```
Metadata backend that is specified on field will be used instead of metadata backend that is specified in the settings.
In python:
```python
from thumbnails.fields import ImageField
class Food(models.Model):
image = ImageField()
food = Food.objects.latest('id')
food.image.thumbnails.all()
food.image.thumbnails.small # Generates "small" sized thumbnail
food.image.thumbnails.large # Generates "large" sized thumbnail
food.image.thumbnails.small.url # Returns "small" sized thumbnail URL
```
And here's how you'd use it in Django's template:
```python
{{ food.image.thumbnails.small.url }} # Returns "small" sized thumbnail URL
```
Use resize_source_to to resize your image while saving it:
```python
from thumbnails.fields import ImageField
class Food(models.Model):
image = ImageField(resize_source_to="medium")
```
Assuming medium is the size that you define in the settings. By passing
medium your saved image will be resized into medium's size
Use pregenerated_sizes to save your thumbnails into storage backend
while saving it:
```python
from thumbnails.fields import ImageField
class Food(models.Model):
image = ImageField(pregenerated_sizes=["small", "large", "medium")
```
When deleting an image, you can opt to retain thumbnails by doing this:
``` python
banner.image.delete(with_thumbnails=False)
```
## Performance
If you need to fetch multiple thumbnails at once, use the provided `fetch_thumbnails` function
for better performance. `fetch_thumbnails` uses Redis pipeline to retrieve
thumbnail metadata in one go, avoiding multiple round trips to Redis.
```python
from thumbnails.field import fetch_thumbnails
food_a = Food.objects.get(id=1)
food_b = Food.objects.get(id=2)
fetch_thumbnails([food_a.image, food_b.image], ['small', 'large'])
```
This way, when we get thumbnails like thumbnail1.size_small or even
thumbnail1.all() we won't query to redis anymore. This feature is
currently only available for Redis metadata Backend.
## Management Commands
If you changed your size definition and want to regenerate the
thumbnails, use:
python manage.py delete_thumbnails --model=app.Model --size=thumbnail_size_to_delete
## Running Tests
To run tests:
`which django-admin.py` test thumbnails --settings=thumbnails.tests.settings --pythonpath=.
## Changelog
### Version 0.8.0 (2024-07-24)
* Automatically create a `Source` image if it doesn't exist. This feature makes migrating regular `ImageField` do django-thumbnails easier. Thanks @JobDoesburg!
* Added compatibility with Python 3.13. Thanks @nZac!
* `ImageField` now supports custom `metadata` backends. Thanks @marsha97!
### Version 0.7.0 (2022-01-03)
* Compatibility with django 4.0. Thanks @yosephbernandus!
* Improved setup.py. Thanks @Le09!
### Version 0.6.0 (2021-05-28)
* Added support for watermarking thumbnails. Thanks @marsha97!
### Version 0.5.0 (2021-05-1)
* You can now pass in `storage` kwarg into `ImageField` so you can specify different storage backends for different fields. Thanks @marsha97!
* Calling `image.delete(with_thumbnails=True)` will delete original image along with all thumbnails. Thanks @marsha97!
### Version 0.4.0 (2021-01-08)
- Support for Django >= 3.0. Thanks @christianciu!
- Added `pregenerated_sizes` to ImageField to allow thumbnails to be
pregenerated on upload. Thanks @marsha97!
- Thumbnails can be generated in different formats (e.g: JPG source
image to WEBP thumbnail). Thanks @yosephbernandus!
### Version 0.3.2
- Fixed another bug in `fetch_thumbnails()` bug. Thanks @marsha97!
### Version 0.3.1
- Fixed `fetch_thumbnails()` bug. Thanks @marsha97!
### Version 0.3.0
- Added `fetch_thumbnails()` command to fetch multiple thumbnail
metadata from Redis. Thanks @marsha97!
### Version 0.2.2
- Fixed `RedisBackend.get_thumbnail()` bug that may cause excessive
trips to Redis. Thanks @marsha97!
### Version 0.2.1
- Add support for Django 1.11, 2.0 and 2.1
### Version 0.2.0
- Improves performance on fields that have a large number of
thumbnails
- Add support for Django 1.8, 1.9 and 1.10
### Version 0.1.3
- Fixes deprecation warning in Django 1.8
### Version 0.1.2
- Fixes deprecation warning in Django 1.8
### Version 0.1.1
- Use
[shortuuid](https://github.com/stochastic-technologies/shortuuid)
instead of uuid4() to be more space efficient
### Version 0.1.0
- First public release
As of February 2015, this library is suitable for production use and has
been used for more than a year in [Stamps](http://stamps.co.id), an
Indonesian based CRM/loyalty system.
Raw data
{
"_id": null,
"home_page": "https://github.com/ui/django-thumbnails",
"name": "django-thumbnails",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Selwin Ong",
"author_email": "selwin.ong@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/09/71/e99376907070858f7bd8d3d939438f5891b6c8073a065aa6b583b113f149/django-thumbnails-0.8.0.tar.gz",
"platform": null,
"description": "[](https://travis-ci.org/ui/django-thumbnails)\n\nDesign:\n\n- Uses Django Storage API\n- Uses flexible meta data store. Uses Redis as metadata store.\n- Supports creating thumbnails in different formats, for example from\n JPG to WEBP to reduce file size\n\nSupported image formats:\n\n- JPG/JPEG\n- GIF\n- PNG\n- WEBP\n\n## Installation\n\n- Add thumbnails to INSTALLED_APPS in settings.py.\n- Run python manage.py migrate to create database metadata backend.\n\n## Usage\n\nsettings.py:\n\n```python\nTHUMBNAILS = {\n 'METADATA': {\n 'BACKEND': 'thumbnails.backends.metadata.DatabaseBackend',\n },\n 'STORAGE': {\n 'BACKEND': 'django.core.files.storage.FileSystemStorage',\n # You can also use Amazon S3 or any other Django storage backends\n },\n 'SIZES': {\n 'small': {\n 'PROCESSORS': [\n {'PATH': 'thumbnails.processors.resize', 'width': 10, 'height': 10},\n {'PATH': 'thumbnails.processors.crop', 'width': 80, 'height': 80}\n ],\n 'POST_PROCESSORS': [\n {\n 'PATH': 'thumbnails.post_processors.optimize',\n 'png_command': 'optipng -force -o7 \"%(filename)s\"',\n 'jpg_command': 'jpegoptim -f --strip-all \"%(filename)s\"',\n },\n ],\n },\n 'large': {\n 'PROCESSORS': [\n {'PATH': 'thumbnails.processors.resize', 'width': 20, 'height': 20},\n {'PATH': 'thumbnails.processors.flip', 'direction': 'horizontal'}\n ],\n },\n 'watermarked': {\n 'PROCESSORS': [\n {'PATH': 'thumbnails.processors.resize', 'width': 20, 'height': 20},\n # Only supports PNG. File must be of the same size with thumbnail (20 x 20 in this case)\n {'PATH': 'thumbnails.processors.add_watermark', 'watermark_path': 'watermark.png'}\n ],\n }\n }\n}\n```\n\nIf you prefer to use Redis as your metadata storage backend (for performance reasons):\n\n```python\nTHUMBNAILS = {\n 'METADATA': {\n 'PREFIX': 'thumbs',\n 'BACKEND': 'thumbnails.backends.metadata.RedisBackend',\n 'db': 2,\n 'port': 6379,\n 'host': 'localhost',\n },\n}\n```\n\n## Image Processors\n\n`django-thumbnails` comes with a few builtin image processors:\n\n```python\n # To use the following processors, put the arguments of processors in SIZES definition\n thumbnails.processors.resize(width, height, method) ## `method` can be `stretch`, `fit` or `fill`\n thumbnails.processors.rotate(degrees)\n thumbnails.processors.flip(direction)\n thumbnails.processors.crop(width, height, center)\n thumbnails.processors.add_watermark(watermark_path)\n```\n\nProcessors are applied sequentially in the same order of definition.\n\n\n## Storage Backend\n\nNew in version 0.5.0 is per field, customizable storage backend. If you want specific fields to use\na different storage backend, you can specify it directly when declaring the field. e.g:\n\n```python\nclass Food(models.Model):\n image = ImageField(storage=FileSystemStorage(), upload_to='food')\n```\n\nStorage that is specified on field will be used instead of storage that is specified in the settings.\n\n\n## Metadata Backend\nIf you want specific fields to use different metadata backend, you can specify it directly when declaring the field. e.g:\n\n```python\nclass Food(models.Model):\n image = ImageField(metadata_backend=CustomMetadataBackend(), upload_to='food')\n```\n\nMetadata backend that is specified on field will be used instead of metadata backend that is specified in the settings. \n\n\nIn python:\n\n```python\nfrom thumbnails.fields import ImageField\n\nclass Food(models.Model):\n image = ImageField()\n\n\nfood = Food.objects.latest('id')\nfood.image.thumbnails.all()\nfood.image.thumbnails.small # Generates \"small\" sized thumbnail\nfood.image.thumbnails.large # Generates \"large\" sized thumbnail\nfood.image.thumbnails.small.url # Returns \"small\" sized thumbnail URL\n```\n\nAnd here's how you'd use it in Django's template:\n\n```python\n{{ food.image.thumbnails.small.url }} # Returns \"small\" sized thumbnail URL\n```\n\nUse resize_source_to to resize your image while saving it:\n\n```python\nfrom thumbnails.fields import ImageField\n\nclass Food(models.Model):\n image = ImageField(resize_source_to=\"medium\")\n```\n\nAssuming medium is the size that you define in the settings. By passing\nmedium your saved image will be resized into medium's size\n\nUse pregenerated_sizes to save your thumbnails into storage backend\nwhile saving it:\n\n```python\nfrom thumbnails.fields import ImageField\n\nclass Food(models.Model):\n image = ImageField(pregenerated_sizes=[\"small\", \"large\", \"medium\")\n```\n\nWhen deleting an image, you can opt to retain thumbnails by doing this:\n``` python\nbanner.image.delete(with_thumbnails=False)\n```\n\n\n## Performance\n\nIf you need to fetch multiple thumbnails at once, use the provided `fetch_thumbnails` function\nfor better performance. `fetch_thumbnails` uses Redis pipeline to retrieve\nthumbnail metadata in one go, avoiding multiple round trips to Redis.\n\n```python\nfrom thumbnails.field import fetch_thumbnails\n\nfood_a = Food.objects.get(id=1)\nfood_b = Food.objects.get(id=2)\n\nfetch_thumbnails([food_a.image, food_b.image], ['small', 'large'])\n```\n\nThis way, when we get thumbnails like thumbnail1.size_small or even\nthumbnail1.all() we won't query to redis anymore. This feature is\ncurrently only available for Redis metadata Backend.\n\n## Management Commands\n\nIf you changed your size definition and want to regenerate the\nthumbnails, use:\n\n python manage.py delete_thumbnails --model=app.Model --size=thumbnail_size_to_delete\n\n## Running Tests\n\nTo run tests:\n\n `which django-admin.py` test thumbnails --settings=thumbnails.tests.settings --pythonpath=.\n\n## Changelog\n\n### Version 0.8.0 (2024-07-24)\n* Automatically create a `Source` image if it doesn't exist. This feature makes migrating regular `ImageField` do django-thumbnails easier. Thanks @JobDoesburg!\n* Added compatibility with Python 3.13. Thanks @nZac!\n* `ImageField` now supports custom `metadata` backends. Thanks @marsha97!\n\n### Version 0.7.0 (2022-01-03)\n\n* Compatibility with django 4.0. Thanks @yosephbernandus!\n* Improved setup.py. Thanks @Le09!\n\n### Version 0.6.0 (2021-05-28)\n\n* Added support for watermarking thumbnails. Thanks @marsha97!\n\n### Version 0.5.0 (2021-05-1)\n\n* You can now pass in `storage` kwarg into `ImageField` so you can specify different storage backends for different fields. Thanks @marsha97!\n* Calling `image.delete(with_thumbnails=True)` will delete original image along with all thumbnails. Thanks @marsha97!\n\n### Version 0.4.0 (2021-01-08)\n\n- Support for Django >= 3.0. Thanks @christianciu!\n- Added `pregenerated_sizes` to ImageField to allow thumbnails to be\n pregenerated on upload. Thanks @marsha97!\n- Thumbnails can be generated in different formats (e.g: JPG source\n image to WEBP thumbnail). Thanks @yosephbernandus!\n\n### Version 0.3.2\n\n- Fixed another bug in `fetch_thumbnails()` bug. Thanks @marsha97!\n\n### Version 0.3.1\n\n- Fixed `fetch_thumbnails()` bug. Thanks @marsha97!\n\n### Version 0.3.0\n\n- Added `fetch_thumbnails()` command to fetch multiple thumbnail\n metadata from Redis. Thanks @marsha97!\n\n### Version 0.2.2\n\n- Fixed `RedisBackend.get_thumbnail()` bug that may cause excessive\n trips to Redis. Thanks @marsha97!\n\n### Version 0.2.1\n\n- Add support for Django 1.11, 2.0 and 2.1\n\n### Version 0.2.0\n\n- Improves performance on fields that have a large number of\n thumbnails\n- Add support for Django 1.8, 1.9 and 1.10\n\n### Version 0.1.3\n\n- Fixes deprecation warning in Django 1.8\n\n### Version 0.1.2\n\n- Fixes deprecation warning in Django 1.8\n\n### Version 0.1.1\n\n- Use\n [shortuuid](https://github.com/stochastic-technologies/shortuuid)\n instead of uuid4() to be more space efficient\n\n### Version 0.1.0\n\n- First public release\n\nAs of February 2015, this library is suitable for production use and has\nbeen used for more than a year in [Stamps](http://stamps.co.id), an\nIndonesian based CRM/loyalty system.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple Django app to manage image/photo thumbnails. Supports remote/cloud storage systems like Amazon S3.",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/ui/django-thumbnails"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "32eab9f0b69ed703eaca4aa2494fa4fc88e282ed74187c4d75bb3cf10d0b29dd",
"md5": "0af92182e7e57d8c20e8073a7df57011",
"sha256": "cf19fab2255fe9c2560fb6ae372e71684afd94c4f24cbc9e9099c6db02dfe2a9"
},
"downloads": -1,
"filename": "django_thumbnails-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0af92182e7e57d8c20e8073a7df57011",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 29983,
"upload_time": "2024-07-24T08:58:52",
"upload_time_iso_8601": "2024-07-24T08:58:52.303121Z",
"url": "https://files.pythonhosted.org/packages/32/ea/b9f0b69ed703eaca4aa2494fa4fc88e282ed74187c4d75bb3cf10d0b29dd/django_thumbnails-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0971e99376907070858f7bd8d3d939438f5891b6c8073a065aa6b583b113f149",
"md5": "1b3dad0f985233cf1d7167a2ee17312a",
"sha256": "209cf995763f28b0d04b07052d10ea187a90019ed0c0ec503522106bfaff465b"
},
"downloads": -1,
"filename": "django-thumbnails-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "1b3dad0f985233cf1d7167a2ee17312a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 21580,
"upload_time": "2024-07-24T08:58:58",
"upload_time_iso_8601": "2024-07-24T08:58:58.781826Z",
"url": "https://files.pythonhosted.org/packages/09/71/e99376907070858f7bd8d3d939438f5891b6c8073a065aa6b583b113f149/django-thumbnails-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-24 08:58:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ui",
"github_project": "django-thumbnails",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-thumbnails"
}
