|package version|
|license|
|pypi status|
|coverage|
|python versions supported|
|django versions supported|
|code style black|
|pypi downloads|
|github stars|
==================
Django Lazy srcset
==================
Lazy srcset and responsive image generation for Django. Minimum effort required. No database required.
Django Lazy srcset will create the markup and generate the images you need to provide responsive images via the `srcset and sizes attributes for the img tag <https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#resolution_switching_different_sizes>`_. All you need to do is install it, configure your breakpoints and use the ``{% srcset %}`` template tag.
All of the hard work (image generation and cacheing) is done by django-imagekit, by default this means images are generated just in time - lazily. Please see the `django-imagekit docs <https://django-imagekit.readthedocs.io>`_ for more info and configuration options.
Width and height attributes are generated to help avoid layout shifts. Make sure you set these in CSS so they are only used by the browser for aspect ratio.
SVG images are supported, they will not be converted or resized but width and height attributes are still added as well as the ``role="img"`` attribute.
You will also need Django and Pillow.
Installation & Usage
--------------------
Install with pip:
.. code-block:: bash
$ pip install django-lazy-srcset
Add ``"imagekit"`` and ``"lazy_srcset"`` to ``INSTALLED_APPS``:
.. code-block:: python
INSTALLED_APPS = [
# ...
"imagekit",
"lazy_srcset",
# ...
]
Configure your breakpoints and stuff (most/all of this is optional):
.. code-block:: python
# When disabled src, width and height attributes are returned so images still work but no srcset or image
# generation will happen. By default, lazy-srcset is disabled when debug is True.
LAZY_SRCSET_ENABLED = not django_settings.DEBUG
# The default threshold to use when not specified in the config.
LAZY_SRCSET_THRESHOLD = 69
# The default generator to use when not specified in the config.
LAZY_SRCSET_GENERATOR_ID = "lazy_srcset:srcset_image"
LAZY_SRCSET = {
"default": {
# breakpoints is the only setting you must define
"breakpoints": [1920, 1580, 1280, 1024, 640],
# If max_width is not provided the source image width is used.
# It's a good idea to set this.
"max_width": 2560,
# If quality is not provided PIL will choose a default
"quality": 91,
# If format is not provided the source image format is used
"format": "WEBP",
# The difference in width (px) required to generate a new image
# This prevents images being created which are too similar in size
"threshold": LAZY_SRCSET_THRESHOLD,
# If generator_id is not provided LAZY_SRCSET_GENERATOR_ID is used
"generator_id": LAZY_SRCSET_GENERATOR_ID,
}
}
Use the ``{% srcset %}`` template tag:
.. code-block:: django
{% load lazy_srcset %}
{# image is an ImageField. With no args or kwargs provided all sizes are assumed to be 100vw #}
<img {% srcset image %} alt="Lovely and lazy" />
{# You can provide a path to a static file instead of an ImageField. #}
<img {% srcset 'path/to/my/image.png' %} />
{# You can provide relative (vw) image widths e.g. for a 4 - 3 - 2 - 1 col degradation #}
{# These are used to calculate the width of the generated images for each breakpoint #}
<img {% srcset image 25 33 50 %} />
{# Kwargs can be used to define breakpoints and some settings #}
<img {% srcset image 1920=25 1580=33 1024=50 640=100 max_width=1920 %} />
{# Fixed width images can be defined with px units. These are always made regardless of threshold #}
<img {% srcset image '500px' '400px' '300px' %} />
Whilst not required it is advisable to take a nap at this stage.
For further documentation and examples of all the options please see the huge and obvious docstring in the source code for `lazy_srcset/templatetags/lazy_srcset.py <https://github.com/Quantra/django-lazy-srcset/blob/master/lazy_srcset/templatetags/lazy_srcset.py>`_.
How it Works
------------
If the source image is wider than the ``max_width`` it is resized to ``max_width``. Otherwise it is converted as is. This image is then used in the srcset and src attributes.
For each breakpoint we calculate the target width of the image required and iterate from biggest to smallest. Images are then generated if the required width is:
* Smaller than the source width (no upscaling!).
* Smaller than the previously generated image by more than ``threshold`` px unless the size was defined with px units.
Once imagekit has generated an image it won't create it again and it will store this fact in the cache to further speed up subsequent renders.
Advanced
--------
Due to the awesomeness of django-imagekit it's possible to configure django-lazy-srcset to use any image generator you have registered on a per config basis. Take a look at `lazy_srcset/conf.py <https://github.com/Quantra/django-lazy-srcset/blob/master/lazy_srcset/conf.py>`_ to see how to change the ``generator_id`` setting. For an example image generator look at `lazy_srcset/imagegenerators.py <https://github.com/Quantra/django-lazy-srcset/blob/master/lazy_srcset/imagegenerators.py>`_. This is completely optional but I thought I'd mention it as there are potential artistic uses here; for example you could use a generator to add filters to some images.
Currently imagekit ``SourceGroup`` has not been implemented therefore the imagekit ``generateimages`` management command will not generate images for django-lazy-srcset. If you want to pre-generate images you can ``render_to_string()`` your templates in an appropriate save method or signal. If you are using `django-content-blocks <https://github.com/Quantra/django-content-blocks>`_ this happens on publish anyway.
Clean up of old, unused files created by django-lazy-srcset is down to you, if you require it at all.
Development Status & Roadmap
----------------------------
Django lazy srcset is in beta. There are currently no plans for further development.
Dependencies & Thank You
------------------------
* https://github.com/matthewwithanm/django-imagekit/
Other Packages to Consider
--------------------------
* https://github.com/codingjoe/django-pictures
.. shields.io badges
.. |package version| image:: https://img.shields.io/pypi/v/django-lazy-srcset
:alt: PyPI Package Version
:target: https://pypi.python.org/pypi/django-lazy-srcset/
.. |python versions supported| image:: https://img.shields.io/pypi/pyversions/django-lazy-srcset
:alt: Python Versions Supported
:target: https://pypi.python.org/pypi/django-lazy-srcset/
.. |django versions supported| image:: https://img.shields.io/pypi/frameworkversions/django/django-lazy-srcset
:alt: Django Versions Supported
:target: https://pypi.python.org/pypi/django-lazy-srcset/
.. |coverage| image:: https://img.shields.io/badge/dynamic/xml?color=success&label=coverage&query=round%28%2F%2Fcoverage%2F%40line-rate%20%2A%20100%29&suffix=%25&url=https%3A%2F%2Fraw.githubusercontent.com%2FQuantra%2Fdjango-lazy-srcset%2Fmaster%2Fcoverage.xml
:alt: Test Coverage
:target: https://github.com/Quantra/django-lazy-srcset/blob/master/coverage.xml
.. |code style black| image:: https://img.shields.io/badge/code%20style-black-black
:alt: Code Style Black
:target: https://github.com/psf/black
.. |license| image:: https://img.shields.io/github/license/Quantra/django-lazy-srcset
:alt: MIT License
:target: https://github.com/Quantra/django-lazy-srcset/blob/master/LICENSE
.. |github stars| image:: https://img.shields.io/github/stars/Quantra/django-lazy-srcset?style=social
:alt: GitHub Repo Stars
:target: https://github.com/Quantra/django-lazy-srcset/stargazers
.. |pypi downloads| image:: https://img.shields.io/pypi/dm/django-lazy-srcset
:alt: PyPI Downloads
:target: https://pypi.python.org/pypi/django-lazy-srcset/
.. |pypi status| image:: https://img.shields.io/pypi/status/django-lazy-srcset
:alt: PyPI Status
:target: https://pypi.python.org/pypi/django-lazy-srcset/
Raw data
{
"_id": null,
"home_page": "https://github.com/Quantra/django-lazy-srcset",
"name": "django-lazy-srcset",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "django,django-lazy-srcset,django lazy srcset,django srcset,django responsive images,django responsive",
"author": "Vince Coleman",
"author_email": "vince@shystudios.co.uk",
"download_url": "https://files.pythonhosted.org/packages/b1/80/713e4b6c40bbfa0933e84300bc03d17803cd6bab02971d904865a5876073/django-lazy-srcset-1.0.3.tar.gz",
"platform": null,
"description": "|package version|\n|license|\n|pypi status|\n|coverage|\n\n|python versions supported|\n|django versions supported|\n\n|code style black|\n|pypi downloads|\n|github stars|\n\n==================\nDjango Lazy srcset\n==================\n\nLazy srcset and responsive image generation for Django. Minimum effort required. No database required.\n\nDjango Lazy srcset will create the markup and generate the images you need to provide responsive images via the `srcset and sizes attributes for the img tag <https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#resolution_switching_different_sizes>`_. All you need to do is install it, configure your breakpoints and use the ``{% srcset %}`` template tag.\n\nAll of the hard work (image generation and cacheing) is done by django-imagekit, by default this means images are generated just in time - lazily. Please see the `django-imagekit docs <https://django-imagekit.readthedocs.io>`_ for more info and configuration options.\n\nWidth and height attributes are generated to help avoid layout shifts. Make sure you set these in CSS so they are only used by the browser for aspect ratio.\n\nSVG images are supported, they will not be converted or resized but width and height attributes are still added as well as the ``role=\"img\"`` attribute.\n\nYou will also need Django and Pillow.\n\nInstallation & Usage\n--------------------\n\nInstall with pip:\n\n.. code-block:: bash\n\n $ pip install django-lazy-srcset\n\nAdd ``\"imagekit\"`` and ``\"lazy_srcset\"`` to ``INSTALLED_APPS``:\n\n.. code-block:: python\n\n INSTALLED_APPS = [\n # ...\n \"imagekit\",\n \"lazy_srcset\",\n # ...\n ]\n\nConfigure your breakpoints and stuff (most/all of this is optional):\n\n.. code-block:: python\n\n # When disabled src, width and height attributes are returned so images still work but no srcset or image\n # generation will happen. By default, lazy-srcset is disabled when debug is True.\n LAZY_SRCSET_ENABLED = not django_settings.DEBUG\n\n # The default threshold to use when not specified in the config.\n LAZY_SRCSET_THRESHOLD = 69\n\n # The default generator to use when not specified in the config.\n LAZY_SRCSET_GENERATOR_ID = \"lazy_srcset:srcset_image\"\n\n LAZY_SRCSET = {\n \"default\": {\n # breakpoints is the only setting you must define\n \"breakpoints\": [1920, 1580, 1280, 1024, 640],\n # If max_width is not provided the source image width is used.\n # It's a good idea to set this.\n \"max_width\": 2560,\n # If quality is not provided PIL will choose a default\n \"quality\": 91,\n # If format is not provided the source image format is used\n \"format\": \"WEBP\",\n # The difference in width (px) required to generate a new image\n # This prevents images being created which are too similar in size\n \"threshold\": LAZY_SRCSET_THRESHOLD,\n # If generator_id is not provided LAZY_SRCSET_GENERATOR_ID is used\n \"generator_id\": LAZY_SRCSET_GENERATOR_ID,\n }\n }\n\nUse the ``{% srcset %}`` template tag:\n\n.. code-block:: django\n\n {% load lazy_srcset %}\n\n {# image is an ImageField. With no args or kwargs provided all sizes are assumed to be 100vw #}\n <img {% srcset image %} alt=\"Lovely and lazy\" />\n\n {# You can provide a path to a static file instead of an ImageField. #}\n <img {% srcset 'path/to/my/image.png' %} />\n\n {# You can provide relative (vw) image widths e.g. for a 4 - 3 - 2 - 1 col degradation #}\n {# These are used to calculate the width of the generated images for each breakpoint #}\n <img {% srcset image 25 33 50 %} />\n\n {# Kwargs can be used to define breakpoints and some settings #}\n <img {% srcset image 1920=25 1580=33 1024=50 640=100 max_width=1920 %} />\n\n {# Fixed width images can be defined with px units. These are always made regardless of threshold #}\n <img {% srcset image '500px' '400px' '300px' %} />\n\nWhilst not required it is advisable to take a nap at this stage.\n\nFor further documentation and examples of all the options please see the huge and obvious docstring in the source code for `lazy_srcset/templatetags/lazy_srcset.py <https://github.com/Quantra/django-lazy-srcset/blob/master/lazy_srcset/templatetags/lazy_srcset.py>`_.\n\nHow it Works\n------------\n\nIf the source image is wider than the ``max_width`` it is resized to ``max_width``. Otherwise it is converted as is. This image is then used in the srcset and src attributes.\n\nFor each breakpoint we calculate the target width of the image required and iterate from biggest to smallest. Images are then generated if the required width is:\n\n* Smaller than the source width (no upscaling!).\n* Smaller than the previously generated image by more than ``threshold`` px unless the size was defined with px units.\n\nOnce imagekit has generated an image it won't create it again and it will store this fact in the cache to further speed up subsequent renders.\n\nAdvanced\n--------\n\nDue to the awesomeness of django-imagekit it's possible to configure django-lazy-srcset to use any image generator you have registered on a per config basis. Take a look at `lazy_srcset/conf.py <https://github.com/Quantra/django-lazy-srcset/blob/master/lazy_srcset/conf.py>`_ to see how to change the ``generator_id`` setting. For an example image generator look at `lazy_srcset/imagegenerators.py <https://github.com/Quantra/django-lazy-srcset/blob/master/lazy_srcset/imagegenerators.py>`_. This is completely optional but I thought I'd mention it as there are potential artistic uses here; for example you could use a generator to add filters to some images.\n\nCurrently imagekit ``SourceGroup`` has not been implemented therefore the imagekit ``generateimages`` management command will not generate images for django-lazy-srcset. If you want to pre-generate images you can ``render_to_string()`` your templates in an appropriate save method or signal. If you are using `django-content-blocks <https://github.com/Quantra/django-content-blocks>`_ this happens on publish anyway.\n\nClean up of old, unused files created by django-lazy-srcset is down to you, if you require it at all.\n\nDevelopment Status & Roadmap\n----------------------------\n\nDjango lazy srcset is in beta. There are currently no plans for further development.\n\nDependencies & Thank You\n------------------------\n\n* https://github.com/matthewwithanm/django-imagekit/\n\nOther Packages to Consider\n--------------------------\n\n* https://github.com/codingjoe/django-pictures\n\n.. shields.io badges\n\n.. |package version| image:: https://img.shields.io/pypi/v/django-lazy-srcset\n :alt: PyPI Package Version\n :target: https://pypi.python.org/pypi/django-lazy-srcset/\n\n.. |python versions supported| image:: https://img.shields.io/pypi/pyversions/django-lazy-srcset\n :alt: Python Versions Supported\n :target: https://pypi.python.org/pypi/django-lazy-srcset/\n\n.. |django versions supported| image:: https://img.shields.io/pypi/frameworkversions/django/django-lazy-srcset\n :alt: Django Versions Supported\n :target: https://pypi.python.org/pypi/django-lazy-srcset/\n\n.. |coverage| image:: https://img.shields.io/badge/dynamic/xml?color=success&label=coverage&query=round%28%2F%2Fcoverage%2F%40line-rate%20%2A%20100%29&suffix=%25&url=https%3A%2F%2Fraw.githubusercontent.com%2FQuantra%2Fdjango-lazy-srcset%2Fmaster%2Fcoverage.xml\n :alt: Test Coverage\n :target: https://github.com/Quantra/django-lazy-srcset/blob/master/coverage.xml\n\n.. |code style black| image:: https://img.shields.io/badge/code%20style-black-black\n :alt: Code Style Black\n :target: https://github.com/psf/black\n\n.. |license| image:: https://img.shields.io/github/license/Quantra/django-lazy-srcset\n :alt: MIT License\n :target: https://github.com/Quantra/django-lazy-srcset/blob/master/LICENSE\n\n.. |github stars| image:: https://img.shields.io/github/stars/Quantra/django-lazy-srcset?style=social\n :alt: GitHub Repo Stars\n :target: https://github.com/Quantra/django-lazy-srcset/stargazers\n\n.. |pypi downloads| image:: https://img.shields.io/pypi/dm/django-lazy-srcset\n :alt: PyPI Downloads\n :target: https://pypi.python.org/pypi/django-lazy-srcset/\n\n.. |pypi status| image:: https://img.shields.io/pypi/status/django-lazy-srcset\n :alt: PyPI Status\n :target: https://pypi.python.org/pypi/django-lazy-srcset/\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lazy srcset and responsive image generation for Django. Minimum effort required. No database required.",
"version": "1.0.3",
"project_urls": {
"Homepage": "https://github.com/Quantra/django-lazy-srcset",
"Source": "https://github.com/Quantra/django-lazy-srcset"
},
"split_keywords": [
"django",
"django-lazy-srcset",
"django lazy srcset",
"django srcset",
"django responsive images",
"django responsive"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f80f5bdf1927dfa9101a73759d839cb5689c9cc5798e4e354b8ef58482452534",
"md5": "9066154a1548b7256d9ab6a8dab589e6",
"sha256": "b8d34bb98cd9f57cc42345ad5121cf5ec4d9247779792aa0537d08f481bc055d"
},
"downloads": -1,
"filename": "django_lazy_srcset-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9066154a1548b7256d9ab6a8dab589e6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13764,
"upload_time": "2023-12-12T12:33:44",
"upload_time_iso_8601": "2023-12-12T12:33:44.201016Z",
"url": "https://files.pythonhosted.org/packages/f8/0f/5bdf1927dfa9101a73759d839cb5689c9cc5798e4e354b8ef58482452534/django_lazy_srcset-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b180713e4b6c40bbfa0933e84300bc03d17803cd6bab02971d904865a5876073",
"md5": "eba8425f6dd6c8865432f20f8687c839",
"sha256": "75b593ef170ae980043f311ff1bb4fe9f0cfbb7838ebe4e6f8a38f1690da4758"
},
"downloads": -1,
"filename": "django-lazy-srcset-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "eba8425f6dd6c8865432f20f8687c839",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 12316,
"upload_time": "2023-12-12T12:33:46",
"upload_time_iso_8601": "2023-12-12T12:33:46.110471Z",
"url": "https://files.pythonhosted.org/packages/b1/80/713e4b6c40bbfa0933e84300bc03d17803cd6bab02971d904865a5876073/django-lazy-srcset-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-12 12:33:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Quantra",
"github_project": "django-lazy-srcset",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"requirements": [],
"tox": true,
"lcname": "django-lazy-srcset"
}
JSON
