Metadata-Version: 2.4
Name: django-render-block
Version: 0.11
Summary: Render a particular block from a template to a string.
Home-page: https://github.com/clokep/django-render-block
Author: Patrick Cloke
Author-email: clokep@patrick.cloke.us
License: ISC
Project-URL: Documentation, https://github.com/clokep/django-render-block/blob/main/README.rst
Project-URL: Release notes, https://github.com/clokep/django-render-block/blob/main/CHANGELOG.rst
Project-URL: Source, https://github.com/clokep/django-render-block
Project-URL: Tracker, https://github.com/clokep/django-render-block/issues
Keywords: [django,template,block,templates,render,context]
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Environment :: Web Environment
Classifier: Topic :: Internet
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: ISC License (ISCL)
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: django>=4.2
Provides-Extra: dev
Requires-Dist: Jinja2>=2.8; extra == "dev"
Dynamic: license-file

Django Render Block
###################

.. image:: https://img.shields.io/pypi/v/django-render-block.svg
    :target: https://pypi.org/project/django-render-block/

.. image:: https://github.com/clokep/django-render-block/actions/workflows/main.yml/badge.svg
    :target: https://github.com/clokep/django-render-block/actions/workflows/main.yml

Render the content of a specific block tag from a Django template. Works for
arbitrary template inheritance, even if a block is defined in the child template
but not in the parent. Generally it works like ``render_to_string`` from Django,
but allows you to specify a block to render.

Features
========

*   Render a specific block from a template
*   Fully supports the Django templating engine
*   Partially supports the `Jinja2 <http://jinja.pocoo.org/>`__ engine: it does
    not currently process the ``extends`` tag.

Requirements
============

Django Render Block supports Django 4.2, 5.1, and 5.2 on Python 3.9, 3.10, 3.11,
3.12, and 3.13 (see the `Django documentation <https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django>`_
for which versions of Python are supported by particular Django versions).

Examples
========

In ``test1.html``:

.. code-block:: jinja

    {% block block1 %}block1 from test1{% endblock %}
    {% block block2 %}block2 from test1{% endblock %}

In ``test2.html``:

.. code-block:: jinja

    {% extends 'test1.html' %}
    {% block block1 %}block1 from test2{% endblock %}

And from the Python shell:

.. code-block:: python

    >>> from render_block import render_block_to_string
    >>> print(render_block_to_string('test2.html', 'block1'))
    'block1 from test2'
    >>> print(render_block_to_string('test2.html', 'block2'))
    'block2 from test1'

It can also accept a context as a ``dict`` (just like ``render_to_string``), in
``test3.html``:

.. code-block:: jinja

    {% block block3 %}Render this {{ variable }}!{% endblock %}

And from Python:

.. code-block:: python

    >>> print(render_block_to_string('test3.html', 'block3', {'variable': 'test'}))
    'Render this test!'

API Reference
=============

The API is simple and attempts to mirror the built-in ``render_to_string`` and ``render`` API.

``render_block_to_string(template_name, block_name, context=None, request=None)``

    ``template_name``
        The name of the template to load and render. If it’s a list of template
        names, Django uses ``select_template()`` instead of ``get_template()``
        to find the template.

    ``block_name``
        The name of the block to render from the above template.

    ``context``
        A ``dict`` to be used as the template’s context for rendering. A ``Context``
        object can be provided for Django templates.

        ``context`` is optional. If not provided, an empty context will be used.

    ``request``
        The request object used to render the template.

        ``request`` is optional and works only for Django templates. If both context and request
        are provided, a ``RequestContext`` will be used instead of a ``Context``.

Similarly there is a ``render_block`` function which returns an `HttpResponse` with
the content sent to the result of ``render_block_to_string`` with the same parameters.

``render_block(request, template_name, block_name, context=None, content_type="text/html", status=200)``

    ``request``
        The request object used to render the template.

    ``template_name``
        The name of the template to load and render. If it’s a list of template
        names, Django uses ``select_template()`` instead of ``get_template()``
        to find the template.

    ``block_name``
        The name of the block to render from the above template.

    ``context``
        A ``dict`` to be used as the template’s context for rendering. A ``Context``
        object can be provided for Django templates.

        ``context`` is optional. If not provided, an empty context will be used.

    ``content_type``
        A ``str`` content type for the HTTP response.

    ``status``
        An ``int`` HTTP status code for the HTTP response.

Exceptions
----------

Like ``render_to_string`` this will raise the following exceptions:

    ``TemplateDoesNotExists``
        Raised if the template(s) specified by ``template_name`` cannot be
        loaded.

    ``TemplateSyntaxError``
        Raised if the loaded template contains invalid syntax.

There are also two additional errors that can be raised:

    ``BlockNotFound``
        Raised if the block given by ``block_name`` does not exist in the
        template.

    ``UnsupportedEngine``
        Raised if a template backend besides the Django backend is used.

Contributing
============

If you find a bug or have an idea for an improvement to Django Render Block,
please
`file an issue <https://github.com/clokep/django-render-block/issues/new>`_ or
provide a pull request! Check the
`list of issues <https://github.com/clokep/django-render-block/issues/>`_ for
ideas of what to work on.

Attribution
===========

This is based on a few sources:

* Originally `Django Snippet 769 <https://djangosnippets.org/snippets/769/>`__
* Updated version `Django Snippet 942 <https://djangosnippets.org/snippets/942/>`__
* A version of the snippets was ported as `Django-Block-Render <https://github.com/uniphil/Django-Block-Render/>`_
* Additionally inspired by part of `django-templated-email <https://github.com/BradWhittington/django-templated-email/blob/master/templated_email/utils.py>`_
* Also based on a `StackOverflow answer 2687173 <http://stackoverflow.com/questions/2687173/django-how-can-i-get-a-block-from-a-template>`_

.. :changelog:

Changelog
#########

0.11 (May 12, 2025)
===================

Improvements
------------

* Add a new ``render_block`` function which returns a `HttpResponse` with the content
  set to the result of calling ``render_block_to_string()``. Contributed by
  `@gogognome <https://github.com/gogognome>`_. (`#60 <https://github.com/clokep/django-render-block/pull/60>`_)

Bugfixes
--------

* Fix incorrect type hints. Contributed by `@ma11011s <https://github.com/ma11011s>`_. (`#58 <https://github.com/clokep/django-render-block/pull/58>`_)

Maintenance
-----------

* Include tests in sdist distribution. Contributed by `@Natureshadow <https://github.com/Natureshadow>`_)
  (`#30 <https://github.com/clokep/django-render-block/pull/30>`_)
* Update linters and switch to ruff. (`#64 <https://github.com/clokep/django-render-block/pull/64>`_)
* Support Python 3.13. (`#62 <https://github.com/clokep/django-render-block/pull/62>`_)
* Drop support for Python 3.8. (`#62 <https://github.com/clokep/django-render-block/pull/62>`_,
  `#65 <https://github.com/clokep/django-render-block/pull/65>`_)
* Support Django 5.2. (`#62 <https://github.com/clokep/django-render-block/pull/62>`_)
* Drop support for Django 5.0. (`#62 <https://github.com/clokep/django-render-block/pull/62>`_,
  `#65 <https://github.com/clokep/django-render-block/pull/65>`_)

0.10 (July 15, 2024)
====================

No changes from 0.10b1.


0.10b1 (July 1, 2024)
=====================

Bugfixes
--------

* Fixes exception propagation when rendering templates. Contributed
  by `@yaakovLowenstein <https://github.com/yaakovLowenstein>`_. (`#52 <https://github.com/clokep/django-render-block/pull/52>`_)
* Fix rendering blocks over multiple extended templates. (`#56 <https://github.com/clokep/django-render-block/pull/56>`_)

Maintenance
-----------

* Support Python 3.11 and 3.12. (`#44 <https://github.com/clokep/django-render-block/pull/44>`_,
  `#55 <https://github.com/clokep/django-render-block/pull/55>`_)
* Drop support for Python 3.7. (`#44 <https://github.com/clokep/django-render-block/pull/44>`_)
* Support Django 4.2, 5.0 and 5.1. (`#44 <https://github.com/clokep/django-render-block/pull/44>`_,
  `#55 <https://github.com/clokep/django-render-block/pull/55>`_)
* Drop support for Django < 3.2; Django 4.0; Django 4.1. (`#44 <https://github.com/clokep/django-render-block/pull/44>`_,
  `#55 <https://github.com/clokep/django-render-block/pull/55>`_)
* Add type hints and configure mypy. (`#54 <https://github.com/clokep/django-render-block/pull/54>`_)


0.9.2 (October 18, 2022)
========================

Maintenance
-----------

* Drop support for Python 3.6. (`#36 <https://github.com/clokep/django-render-block/pull/36>`_)
* Improve package metadata. (`#37 <https://github.com/clokep/django-render-block/pull/37>`_)
* Run `black <https://black.readthedocs.io/>`_, `isort <https://pycqa.github.io/isort/>`_,
  and `flake8 <https://flake8.pycqa.org>`_, and `pyupgrade <https://github.com/asottile/pyupgrade>`_.
  (`#38 <https://github.com/clokep/django-render-block/pull/38>`_,
  `#39 <https://github.com/clokep/django-render-block/pull/39>`_)
* Update to include and run tests for Django 4.1. Contributed by
  `Jack Linke <https://github.com/jacklinke>`_.
  (`#41 <https://github.com/clokep/django-render-block/pull/41>`_)


0.9.1 (December 15, 2021)
=========================

Maintenance
-----------

* Support Python 3.10. (`#33 <https://github.com/clokep/django-render-block/pull/33>`_)
* Fixed a packaging issue where the generated wheels were empty. Contributed
  by `@cordery <https://github.com/cordery>`_. (`#35 <https://github.com/clokep/django-render-block/pull/35>`_)


0.9 (December 14, 2021)
=======================

Maintenance
-----------

* Drop support for Django 3.0. (`#31 <https://github.com/clokep/django-render-block/pull/31>`_)
* Support Django 3.2 and 4.0. (`#27 <https://github.com/clokep/django-render-block/pull/27>`_,
  `#31 <https://github.com/clokep/django-render-block/pull/31>`_)
* Switch continuous integration to GitHub Actions. (`#26 <https://github.com/clokep/django-render-block/pull/26>`_,
  `#28 <https://github.com/clokep/django-render-block/pull/28>`_)
* Changed packaging to use setuptools declarative config in ``setup.cfg``.
  (`#32 <https://github.com/clokep/django-render-block/pull/32>`_)


0.8.1 (October 15, 2020)
========================

Bugfixes
--------

* Fixes a regression in v0.8 where a ``Context`` could not be re-used. Contributed
  by `@evanbrumley <https://github.com/evanbrumley>`_. (`#25 <https://github.com/clokep/django-render-block/pull/25>`_)


0.8 (October 6, 2020)
=====================

Bugfixes
--------

* ``render_block_to_string`` now forwards the ``Context`` passed as ``context`` parameter.
  Contributed by `@bblanchon <https://github.com/bblanchon>`_. (`#21 <https://github.com/clokep/django-render-block/pull/21>`_)

Maintenance
-----------

* Drop support for Python 3.5, support Python 3.9. (`#22 <https://github.com/clokep/django-render-block/pull/22>`_)


0.7 (July 13, 2020)
===================

Maintenance
-----------

* Drop support for Django < 2.2. (`#18 <https://github.com/clokep/django-render-block/pull/18>`_)
* Support Django 3.0 and 3.1. (`#18 <https://github.com/clokep/django-render-block/pull/18>`_,
  `#20 <https://github.com/clokep/django-render-block/pull/20>`_)
* Drop support for Python 2.7. (`#19 <https://github.com/clokep/django-render-block/pull/19>`_)
* Support Python 3.8. (`#18 <https://github.com/clokep/django-render-block/pull/18>`_)


0.6 (May 8, 2019)
=================

Improvements
------------

* ``render_block_to_string`` now optionally accepts a ``request`` parameter.
  If given, a ``RequestContext`` instead of a ``Context`` is used when
  rendering with the Django templating engine. Contributed by
  `@vintage <https://github.com/vintage>`_. (`#15 <https://github.com/clokep/django-render-block/pull/15>`_)

Maintenance
-----------

* Support Django 1.11, 2.1, and 2.2. (`#9 <https://github.com/clokep/django-render-block/pull/9>`_,
  `#11 <https://github.com/clokep/django-render-block/pull/11>`_,
  `#17 <https://github.com/clokep/django-render-block/pull/17>`_)
* Support Python 2.7, 3.5, 3.6, and 3.7. (`#9 <https://github.com/clokep/django-render-block/pull/9>`_,
  `#17 <https://github.com/clokep/django-render-block/pull/17>`_)
* Fix rendering of README on PyPI. Contributed by `@mixxorz <https://github.com/mixxorz>`_.
  (`#10 <https://github.com/clokep/django-render-block/pull/10>`_)


0.5 (September 1, 2016)
=======================

Bugfixes
--------

* Fixes a major issue with inheriting templates and rendering a block found in
  the parent template, but overwriting part of it in the child template.
  (`#8 <https://github.com/clokep/django-render-block/pull/8>`_)


0.4 (August 4, 2016)
====================

Improvements
------------

* Initial support for using the `Jinja2 <http://jinja.pocoo.org/>`_ templating
  engine. See README for caveats. (`#3 <https://github.com/clokep/django-render-block/pull/3>`_)

Maintenance
-----------

* Support Django 1.10. (`#5 <https://github.com/clokep/django-render-block/pull/5>`_)
* Support Python 3. (`#6 <https://github.com/clokep/django-render-block/pull/6>`_)


0.3.1 (June 1, 2016)
====================

Maintenance
------------

* Refactoring to make more generic (for potentially supporting multiple
  templating engines).


0.3 (May 27, 2016)
==================

* Largely rewritten.
* Support Django 1.8 and 1.9:

  * Guards against different template backends.
  * Uses internal APIs for each node.
  * Removed ``context_instance`` parameter.
  * Support for calling ``{{ block.super }}``.


0.2.2 (January 10, 2011)
========================

* Updated per
  `comment 3466 on Django Snippet 942 <https://djangosnippets.org/snippets/942/#c3466>`_
  by `eugenyboger <https://djangosnippets.org/users/eugenyboger/>`_
  to fix an issue with nested extends. The specific bug was not reproducible,
  but the additional code shouldn't hurt.


0.2.1 (August 27, 2010)
=======================

* Updated per
  `comment 3237 on Django Snippet 942 <https://djangosnippets.org/snippets/942/#c3237>`_
  by `chadselph <https://djangosnippets.org/users/chadselph/>`_
  to remove a pointless render. The specific bug was not reproducible, but the
  removed code was extraneous.


0.2 (August 4, 2008)
====================

* Updated version from
  `Django Snippet 942 <https://djangosnippets.org/snippets/942/>`_ by
  `zbyte64 <https://djangosnippets.org/users/zbyte64/>`_.
* Improves include:

  1. Simpler/better handling of "extends" block tag
  2. Searches If/Else blocks
  3. Less code
  4. Allow list of templates to be passed which is closer to the behavior of
     ``render_to_response``


0.1 (May 22, 2008)
==================

* Initial version from
  `Django Snippet 769 <https://djangosnippets.org/snippets/769/>`_ by
  `sciyoshi <https://djangosnippets.org/users/sciyoshi/>`_.
* Support Django 0.96.
