jinja_partials 0.2.0__py3-none-any.whl

jinja_partials/__init__.py

@@ -0,0 +1,84 @@
+"""
+jinja_partials - Simple reuse of partial HTML page templates in the Jinja template language for Python web frameworks.
+"""
+
+__version__ = '0.2.0'
+__author__ = 'Michael Kennedy <michael@talkpython.fm>'
+__all__ = [
+    'register_extensions',
+    'register_starlette_extensions',
+    'register_environment',
+    'render_partial',
+    'generate_render_partial',
+    'PartialsException',
+]
+
+from functools import partial
+from typing import TYPE_CHECKING, Any, Callable, Optional, Union
+
+from jinja2 import Environment
+from markupsafe import Markup as Markup
+
+try:
+    import flask
+except ImportError:
+    flask = None
+
+try:
+    import starlette
+except ImportError:
+    starlette = None
+
+if TYPE_CHECKING:
+    from flask import Flask
+    from starlette.templating import Jinja2Templates
+
+
+class PartialsException(Exception):
+    pass
+
+
+def render_partial(
+        template_name: str,
+        renderer: Optional[Callable[..., Any]] = None,
+        markup: bool = True,
+        **data: Any,
+) -> Union[Markup, str]:
+    if renderer is None:
+        if flask is None:
+            raise PartialsException('No renderer specified')
+        else:
+            renderer = flask.render_template
+
+    if markup:
+        return Markup(renderer(template_name, **data))
+
+    return renderer(template_name, **data)
+
+
+def generate_render_partial(renderer: Callable[..., Any], markup: bool = True) -> Callable[..., Markup]:
+    return partial(render_partial, renderer=renderer, markup=markup)
+
+
+def register_extensions(app: 'Flask'):
+    if flask is None:
+        raise PartialsException('Install Flask to use `register_extensions`')
+
+    app.jinja_env.globals.update(render_partial=generate_render_partial(flask.render_template))
+
+
+def register_starlette_extensions(templates: 'Jinja2Templates'):
+    if starlette is None:
+        raise PartialsException('Install Starlette to use `register_starlette_extensions`')
+
+    def renderer(template_name: str, **data: Any) -> str:
+        return templates.get_template(template_name).render(**data)
+
+    templates.env.globals.update(render_partial=generate_render_partial(renderer))
+
+
+def register_environment(env: Environment, markup: bool = False):
+    def renderer(template_name: str, **data: Any) -> str:
+        return env.get_template(template_name).render(**data)
+
+    env.globals.update(render_partial=generate_render_partial(renderer, markup=markup))

jinja_partials-0.2.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Michael Kennedy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jinja_partials-0.2.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.1
+Name: jinja_partials
+Version: 0.2.0
+Summary: Simple reuse of partial HTML page templates in the Jinja template language for Python web frameworks.
+Home-page: https://github.com/mikeckennedy/jinja_partials
+Author: Michael Kennedy
+Author-email: michael@talkpython.fm
+License: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2
+
+# Jinja Partials
+
+Simple reuse of partial HTML page templates in the Jinja template language for Python web frameworks.
+(There is also a [Pyramid/Chameleon version here](https://github.com/mikeckennedy/chameleon_partials).)
+
+## Overview
+
+When building real-world web apps with Flask + Jinja2, it's easy to end up with repeated HTML fragments.
+Just like organizing code for reuse, it would be ideal to reuse smaller sections of HTML template code.
+That's what this library is all about.
+
+## Example
+
+This project comes with a sample flask application (see the `example` folder). This app displays videos
+that can be played on YouTube. The image, subtitle of author and view count are reused throughout the
+app. Here's a visual:
+
+![](https://raw.githubusercontent.com/mikeckennedy/jinja_partials/main/readme_resources/reused-html-visual.png)
+
+Check out the [**demo / example application**](https://github.com/mikeckennedy/jinja_partials/tree/main/example) 
+to see it in action. 
+
+## Installation
+
+It's just `pip install jinja-partials` and you're all set with this pure Python package.
+
+## Usage
+
+Using the library is incredible easy. The first step is to register the partial method with Jinja and Flask.
+Do this once at app startup:
+
+```python
+import flask
+import jinja_partials
+
+app = flask.Flask(__name__)
+
+jinja_partials.register_extensions(app)
+# ...
+```
+
+You can also use this library in your FastAPI (or Starlette) project!
+```python
+from fastapi.templating import Jinja2Templates
+# or `from starlette.templating import Jinja2Templates`
+
+import jinja_partials
+
+templates = Jinja2Templates("tests/test_templates")
+
+jinja_partials.register_starlette_extensions(templates)
+# ...
+```
+
+Or directly using a jijna environment!
+```python
+import jinja_partials
+from jinja2 import Environment, FileSystemLoader
+
+environment = Environment(loader=FileSystemLoader("tests/test_templates"))
+jinja_partials.register_environment(environment)
+# ...
+```
+
+Next, you define your main HTML (Jinja2) templates as usual. Then 
+define your partial templates. I recommend locating and naming them accordingly:
+
+```
+├── templates
+│   ├── home
+│   │   ├── index.html
+│   │   └── listing.html
+│   └── shared
+│       ├── _layout.html
+│       └── partials
+│           ├── video_image.html
+│           └── video_square.html
+```
+
+Notice the `partials` subfolder in the `templates/shared` folder.
+
+The templates are just HTML fragments. Here is a stand-alone one for the YouTube thumbnail from
+the example app:
+
+```html
+<img src="https://img.youtube.com/vi/{{ video.id }}/maxresdefault.jpg"
+     class="img img-responsive {{ ' '.join(classes) }}"
+     alt="{{ video.title }}"
+     title="{{ video.title }}">
+```
+
+Notice that an object called `video` and list of classes are passed in as the model.
+
+Templates can also be nested. Here is the whole single video fragment with the image as well as other info
+linking out to YouTube:
+
+```html
+<div>
+    <a href="https://www.youtube.com/watch?v={{ video.id }}" target="_blank">
+        {{ render_partial('shared/partials/video_image.html', video=video) }}
+    </a>
+    <a href="https://www.youtube.com/watch?v={{ video.id }}" target="_blank"
+       class="author">{{ video.author }}</a>
+    <div class="views">{{ "{:,}".format(video.views) }} views</div>
+</div>
+```
+
+Now you see the `render_partial()` method. It takes the subpath into the templates folder and
+any model data passed in as keyword arguments.
+
+We can finally generate the list of video blocks as follows:
+
+```html
+{% for v in videos %}
+
+    <div class="col-md-3 video">
+        {{ render_partial('shared/partials/video_square.html', video=v) }}
+    </div>
+
+{% endfor %}
+```
+
+This time, we reframe each item in the list from the outer template (called `v`) as the `video` model
+in the inner HTML section.
+
+
+## Why not just use `include` or `macro` from Jinja?
+
+The short answer is they are nearly the same, but both fall short in different ways. 
+For a more detailed response, see the discussion on [**issue #1**](https://github.com/mikeckennedy/jinja_partials/issues/1)

jinja_partials-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+jinja_partials/__init__.py,sha256=ol5s2emjaxa3aDBU3fBpkYU10Ah12nabdxixKfh--4E,2385
+jinja_partials-0.2.0.dist-info/LICENSE,sha256=B_XBSvJtJYaSzXE0o9ptgql9kUId_iA0d1_XlrYfcaM,1072
+jinja_partials-0.2.0.dist-info/METADATA,sha256=EUv5PoKaCxZhorM-cvkH5HgSTp5TazTfK205_6WbJCE,4973
+jinja_partials-0.2.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+jinja_partials-0.2.0.dist-info/top_level.txt,sha256=8ZW7w6eR_CzS9ZjcYGhRpjTn4Py9WwLeje0KuM5N7Ew,15
+jinja_partials-0.2.0.dist-info/RECORD,,

jinja_partials-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.42.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jinja_partials-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+jinja_partials