jinja_partials 0.2.0__tar.gz

jinja_partials-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,130 @@
+# 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/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/jinja_partials.egg-info/PKG-INFO

@@ -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/jinja_partials.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+setup.py
+jinja_partials/__init__.py
+jinja_partials.egg-info/PKG-INFO
+jinja_partials.egg-info/SOURCES.txt
+jinja_partials.egg-info/dependency_links.txt
+jinja_partials.egg-info/requires.txt
+jinja_partials.egg-info/top_level.txt
+tests/test_rendering.py

jinja_partials-0.2.0/jinja_partials.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jinja_partials-0.2.0/jinja_partials.egg-info/requires.txt

@@ -0,0 +1 @@
+jinja2

jinja_partials-0.2.0/jinja_partials.egg-info/top_level.txt

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

jinja_partials-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jinja_partials-0.2.0/setup.py

@@ -0,0 +1,58 @@
+import io
+import os
+import re
+
+from setuptools import find_packages
+from setuptools import setup
+
+
+def read(filename):
+    filename = os.path.join(os.path.dirname(__file__), filename)
+    text_type = type(u"")
+    with io.open(filename, mode="r", encoding='utf-8') as fd:
+        return re.sub(text_type(r':[a-z]+:`~?(.*?)`'), text_type(r'``\1``'), fd.read())
+
+
+with open('./requirements.txt', 'r', encoding='utf-8') as fin:
+    requires_list = [line.strip() for line in fin if line and line.strip()]
+
+
+def read_version():
+    filename = os.path.join(os.path.dirname(__file__), 'jinja_partials', '__init__.py')
+    with open(filename, mode="r", encoding='utf-8') as fin2:
+        for line in fin2:
+            if line and line.strip() and line.startswith('__version__'):
+                return line.split('=')[1].strip().strip("'").strip('"')
+
+    return "0.0.0.0"
+
+
+setup(
+    name="jinja_partials",
+    version=read_version(),
+    url="https://github.com/mikeckennedy/jinja_partials",
+    license='MIT',
+
+    author="Michael Kennedy",
+    author_email="michael@talkpython.fm",
+
+    description="Simple reuse of partial HTML page templates in the Jinja template language for Python web frameworks.",
+    long_description=read("README.md"),
+    long_description_content_type="text/markdown",
+
+    packages=find_packages(exclude=('tests', 'example', 'readme_resources', 'build', 'dist',)),
+
+    install_requires=requires_list,
+
+    classifiers=[
+        'Development Status :: 2 - Pre-Alpha',
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.6',
+        'Programming Language :: Python :: 3.7',
+        'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+    ],
+)

jinja_partials-0.2.0/tests/test_rendering.py

@@ -0,0 +1,100 @@
+import sys
+from types import SimpleNamespace
+from typing import Callable
+
+# noinspection PyPackageRequirements
+import pytest as pytest
+from jinja2 import TemplateNotFound
+from markupsafe import Markup
+
+import jinja_partials
+
+
+def test_render_empty(registered_extension):
+    html: Markup = jinja_partials.render_partial('render/bare.html')
+    assert '<h1>This is bare HTML fragment</h1>' in html
+
+
+def test_render_with_data(registered_extension):
+    name = 'Sarah'
+    age = 32
+    html: Markup = jinja_partials.render_partial('render/with_data.html', name=name, age=age)
+    assert f'<span>Your name is {name} and age is {age}</span>' in html
+
+
+def test_render_with_layout(registered_extension):
+    value_text = "The message is clear"
+    html: Markup = jinja_partials.render_partial('render/with_layout.html', message=value_text)
+    assert '<title>Jinja Partials Test Template</title>' in html
+    assert value_text in html
+
+
+def test_render_recursive(registered_extension):
+    value_text = "The message is clear"
+    inner_text = "The message is recursive"
+
+    html: Markup = jinja_partials.render_partial('render/recursive.html',
+                                                 message=value_text,
+                                                 inner=inner_text)
+    assert value_text in html
+    assert inner_text in html
+
+
+def test_missing_template(registered_extension):
+    with pytest.raises(TemplateNotFound):
+        jinja_partials.render_partial('no-way.pt', message=7)
+
+
+def test_not_registered():
+    with pytest.raises(Exception):
+        jinja_partials.render_partial('doesnt-matter.pt', message=7)
+
+
+def test_starlette_render_recursive(starlette_render_partial: Callable[..., Markup]):
+    value_text = "The message is clear"
+    inner_text = "The message is recursive"
+
+    html = starlette_render_partial(
+        'render/recursive.html',
+        message=value_text,
+        inner=inner_text,
+    )
+    assert value_text in html
+    assert inner_text in html
+
+
+def test_register_environment(environment_render_partial: Callable[..., Markup]):
+    value_text = "The message is clear"
+    inner_text = "The message is recursive"
+
+    html = environment_render_partial(
+        'render/recursive.html',
+        message=value_text,
+        inner=inner_text,
+    )
+    assert value_text in html
+    assert inner_text in html
+
+
+def test_register_extensions_raises_if_flask_is_not_installed():
+    sys.modules['flask'] = None
+    del sys.modules['jinja_partials']
+    import jinja_partials
+    with pytest.raises(
+            jinja_partials.PartialsException,
+            match='Install Flask to use `register_extensions`',
+    ):
+        jinja_partials.register_extensions(SimpleNamespace())
+    del sys.modules['flask']
+
+
+def test_register_extensions_raises_if_starlette_is_not_installed():
+    sys.modules['starlette'] = None
+    del sys.modules['jinja_partials']
+    import jinja_partials
+    with pytest.raises(
+            jinja_partials.PartialsException,
+            match='Install Starlette to use `register_starlette_extensions`',
+    ):
+        jinja_partials.register_starlette_extensions(SimpleNamespace())
+    del sys.modules['starlette']