chameleon_flask 0.0.1__tar.gz

chameleon_flask-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 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.

chameleon_flask-0.0.1/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.1
+Name: chameleon_flask
+Version: 0.0.1
+Summary: Adds integration of the Chameleon template language to Flask and Quart.
+Author-email: Michael Kennedy <michael@talkpython.fm>
+License: MIT
+Project-URL: Homepage, https://github.com/mikeckennedy/chameleon-flask
+Keywords: Flask,Chameleon,template,integration
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask[async]
+Requires-Dist: Chameleon
+
+# chameleon-flask
+
+Adds integration of the Chameleon template language to Flask and Quart. 
+
+## Installation
+
+Simply `pip install chameleon_flask`.
+
+## Usage
+
+This is easy to use. Just create a folder within your web app to hold the templates such as:
+
+```
+├── app.py
+├── views.py
+│
+├── templates
+│   ├── home
+│   │   └── index.pt
+│   └── shared
+│       └── layout.pt
+
+```
+
+In the app startup, tell the library about the folder you wish to use:
+
+```python
+import os
+from pathlib import Path
+import chameleon_flask
+
+dev_mode = True
+
+BASE_DIR = Path(__file__).resolve().parent
+template_folder = str(BASE_DIR / 'templates')
+chameleon_flask.global_init(template_folder, auto_reload=dev_mode)
+```
+
+Then just decorate the Flask or Quart view methods (works on sync and async methods):
+
+```python
+@app.get('/async')
+@chameleon_flask.template('async.pt')
+async def async_world():
+    await asyncio.sleep(.01)
+    return {'message': "Let's go async Chameleon!"}
+```
+
+The view method should return a `dict` to be passed as variables/values to the template.
+
+If a `flask.Response` is returned, the template is skipped and the response along with status_code and
+other values is directly passed through. This is common for redirects and error responses not meant
+for this page template. Otherwise the dictionary is used to render `async.pt` in this example.
+
+## Friendly 404s and errors
+
+A common technique for user-friendly sites is to use a [custom HTML page for 404 responses](http://www.instantshift.com/2019/10/16/user-friendly-404-pages/).
+This library has support for friendly 404 pages using the `chameleon_flask.not_found()` function.
+
+Here's an example:
+
+```python
+@app.get('/catalog/item/{item_id}')
+@chameleon_flask.template('catalog/item.pt')
+async def item(item_id: int):
+    item = service.get_item_by_id(item_id)
+    if not item:
+        chameleon_flask.not_found()
+    
+    return item.dict()
+```
+
+This will render a 404 response with using the template file `templates/errors/404.pt`.
+You can specify another template to use for the response, but it's not required.
+
+## An example
+
+See the `example/example_app.py` file for a working example to play with.
+

chameleon_flask-0.0.1/README.md

@@ -0,0 +1,79 @@
+# chameleon-flask
+
+Adds integration of the Chameleon template language to Flask and Quart. 
+
+## Installation
+
+Simply `pip install chameleon_flask`.
+
+## Usage
+
+This is easy to use. Just create a folder within your web app to hold the templates such as:
+
+```
+├── app.py
+├── views.py
+│
+├── templates
+│   ├── home
+│   │   └── index.pt
+│   └── shared
+│       └── layout.pt
+
+```
+
+In the app startup, tell the library about the folder you wish to use:
+
+```python
+import os
+from pathlib import Path
+import chameleon_flask
+
+dev_mode = True
+
+BASE_DIR = Path(__file__).resolve().parent
+template_folder = str(BASE_DIR / 'templates')
+chameleon_flask.global_init(template_folder, auto_reload=dev_mode)
+```
+
+Then just decorate the Flask or Quart view methods (works on sync and async methods):
+
+```python
+@app.get('/async')
+@chameleon_flask.template('async.pt')
+async def async_world():
+    await asyncio.sleep(.01)
+    return {'message': "Let's go async Chameleon!"}
+```
+
+The view method should return a `dict` to be passed as variables/values to the template.
+
+If a `flask.Response` is returned, the template is skipped and the response along with status_code and
+other values is directly passed through. This is common for redirects and error responses not meant
+for this page template. Otherwise the dictionary is used to render `async.pt` in this example.
+
+## Friendly 404s and errors
+
+A common technique for user-friendly sites is to use a [custom HTML page for 404 responses](http://www.instantshift.com/2019/10/16/user-friendly-404-pages/).
+This library has support for friendly 404 pages using the `chameleon_flask.not_found()` function.
+
+Here's an example:
+
+```python
+@app.get('/catalog/item/{item_id}')
+@chameleon_flask.template('catalog/item.pt')
+async def item(item_id: int):
+    item = service.get_item_by_id(item_id)
+    if not item:
+        chameleon_flask.not_found()
+    
+    return item.dict()
+```
+
+This will render a 404 response with using the template file `templates/errors/404.pt`.
+You can specify another template to use for the response, but it's not required.
+
+## An example
+
+See the `example/example_app.py` file for a working example to play with.
+

chameleon_flask-0.0.1/chameleon_flask/__init__.py

@@ -0,0 +1,10 @@
+"""chameleon-flask - Adds integration of the Chameleon template language to Flask and Quart."""
+
+__version__ = '0.0.1'
+__author__ = 'Michael Kennedy <michael@talkpython.fm>'
+__all__ = ['template', 'global_init', 'not_found', 'response', ]
+
+from .engine import global_init
+from .engine import not_found
+from .engine import response
+from .engine import template

chameleon_flask-0.0.1/chameleon_flask/engine.py

@@ -0,0 +1,130 @@
+import inspect
+import os
+from functools import wraps
+from typing import Optional, Union, Callable
+
+import flask
+from chameleon import PageTemplateLoader, PageTemplate
+
+from chameleon_flask.exceptions import FlaskChameleonException, FlaskChameleonNotFoundException
+
+__templates: Optional[PageTemplateLoader] = None
+template_path: Optional[str] = None
+
+
+def global_init(template_folder: str, auto_reload=False, cache_init=True):
+    global __templates, template_path
+
+    if __templates and cache_init:
+        return
+
+    if not template_folder:
+        msg = 'The template_folder must be specified.'
+        raise FlaskChameleonException(msg)
+
+    if not os.path.isdir(template_folder):
+        msg = f"The specified template folder must be a folder, it's not: {template_folder}"
+        raise FlaskChameleonException(msg)
+
+    template_path = template_folder
+    __templates = PageTemplateLoader(template_folder, auto_reload=auto_reload)
+
+
+def clear():
+    global __templates, template_path
+    __templates = None
+    template_path = None
+
+
+def render(template_file: str, **template_data: dict) -> str:
+    if not __templates:
+        raise FlaskChameleonException('You must call global_init() before rendering templates.')
+
+    page: PageTemplate = __templates[template_file]
+    return page.render(encoding='utf-8', **template_data)
+
+
+def response(template_file: str, content_type='text/html', status_code=200, **template_data) -> flask.Response:
+    html = render(template_file, **template_data)
+    return flask.Response(response=html, content_type=content_type, status=status_code)
+
+
+def template(template_file: Optional[Union[Callable, str]] = None, mimetype: str = 'text/html'):
+    """
+    Decorate a FastAPI view method to render an HTML response.
+
+    :param str template_file: Optional, the Chameleon template file (path relative to template folder, *.pt).
+    :param str mimetype: The mimetype response (defaults to text/html).
+    :return: Decorator to be consumed by FastAPI
+    """
+
+    wrapped_function = None
+    if callable(template_file):
+        wrapped_function = template_file
+        template_file = None
+
+    def response_inner(f):
+        nonlocal template_file
+        global template_path
+
+        if not template_path:
+            template_path = 'templates'
+            # raise FlaskChameleonException("Cannot continue: fastapi_chameleon.global_init() has not been called.")
+
+        if not template_file:
+            # Use the default naming scheme: template_folder/module_name/function_name.pt
+            module = f.__module__
+            if '.' in module:
+                module = module.split('.')[-1]
+            view = f.__name__
+            template_file = f'{module}/{view}.html'
+
+            if not os.path.exists(os.path.join(template_path, template_file)):
+                template_file = f'{module}/{view}.pt'
+
+        @wraps(f)
+        def sync_view_method(*args, **kwargs) -> flask.Response:
+            try:
+                response_val = f(*args, **kwargs)
+                return __render_response(template_file, response_val, mimetype)
+            except FlaskChameleonNotFoundException as nfe:
+                return __render_response(nfe.template_file, {}, 'text/html', 404)
+
+        @wraps(f)
+        async def async_view_method(*args, **kwargs) -> flask.Response:
+            try:
+                response_val = await f(*args, **kwargs)
+                return __render_response(template_file, response_val, mimetype)
+            except FlaskChameleonNotFoundException as nfe:
+                return __render_response(nfe.template_file, {}, 'text/html', 404)
+
+        if inspect.iscoroutinefunction(f):
+            return async_view_method
+        else:
+            return sync_view_method
+
+    return response_inner(wrapped_function) if wrapped_function else response_inner
+
+
+def __render_response(template_file, response_val, content_type, status_code: int = 200) -> flask.Response:
+    # source skip: assign-if-exp
+    if isinstance(response_val, flask.Response):
+        return response_val
+
+    if template_file and not isinstance(response_val, dict):
+        msg = f'Invalid return type {type(response_val)}, we expected a dict or fastapi.Response as the return value.'
+        raise FlaskChameleonException(msg)
+
+    model = response_val
+
+    html = render(template_file, **model)
+    return flask.Response(response=html, content_type=content_type, status=status_code)
+
+
+def not_found(four04template_file: str = 'errors/404.pt'):
+    msg = 'The URL resulted in a 404 response.'
+
+    if four04template_file and four04template_file.strip():
+        raise FlaskChameleonNotFoundException(msg, four04template_file)
+    else:
+        raise FlaskChameleonNotFoundException(msg)

chameleon_flask-0.0.1/chameleon_flask/exceptions.py

@@ -0,0 +1,13 @@
+from typing import Optional
+
+
+class FlaskChameleonException(Exception):
+    pass
+
+
+class FlaskChameleonNotFoundException(FlaskChameleonException):
+    def __init__(self, message: Optional[str] = None, four04template_file: str = 'errors/404.pt'):
+        super().__init__(message)
+
+        self.template_file: str = four04template_file
+        self.message: Optional[str] = message

chameleon_flask-0.0.1/chameleon_flask.egg-info/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.1
+Name: chameleon_flask
+Version: 0.0.1
+Summary: Adds integration of the Chameleon template language to Flask and Quart.
+Author-email: Michael Kennedy <michael@talkpython.fm>
+License: MIT
+Project-URL: Homepage, https://github.com/mikeckennedy/chameleon-flask
+Keywords: Flask,Chameleon,template,integration
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask[async]
+Requires-Dist: Chameleon
+
+# chameleon-flask
+
+Adds integration of the Chameleon template language to Flask and Quart. 
+
+## Installation
+
+Simply `pip install chameleon_flask`.
+
+## Usage
+
+This is easy to use. Just create a folder within your web app to hold the templates such as:
+
+```
+├── app.py
+├── views.py
+│
+├── templates
+│   ├── home
+│   │   └── index.pt
+│   └── shared
+│       └── layout.pt
+
+```
+
+In the app startup, tell the library about the folder you wish to use:
+
+```python
+import os
+from pathlib import Path
+import chameleon_flask
+
+dev_mode = True
+
+BASE_DIR = Path(__file__).resolve().parent
+template_folder = str(BASE_DIR / 'templates')
+chameleon_flask.global_init(template_folder, auto_reload=dev_mode)
+```
+
+Then just decorate the Flask or Quart view methods (works on sync and async methods):
+
+```python
+@app.get('/async')
+@chameleon_flask.template('async.pt')
+async def async_world():
+    await asyncio.sleep(.01)
+    return {'message': "Let's go async Chameleon!"}
+```
+
+The view method should return a `dict` to be passed as variables/values to the template.
+
+If a `flask.Response` is returned, the template is skipped and the response along with status_code and
+other values is directly passed through. This is common for redirects and error responses not meant
+for this page template. Otherwise the dictionary is used to render `async.pt` in this example.
+
+## Friendly 404s and errors
+
+A common technique for user-friendly sites is to use a [custom HTML page for 404 responses](http://www.instantshift.com/2019/10/16/user-friendly-404-pages/).
+This library has support for friendly 404 pages using the `chameleon_flask.not_found()` function.
+
+Here's an example:
+
+```python
+@app.get('/catalog/item/{item_id}')
+@chameleon_flask.template('catalog/item.pt')
+async def item(item_id: int):
+    item = service.get_item_by_id(item_id)
+    if not item:
+        chameleon_flask.not_found()
+    
+    return item.dict()
+```
+
+This will render a 404 response with using the template file `templates/errors/404.pt`.
+You can specify another template to use for the response, but it's not required.
+
+## An example
+
+See the `example/example_app.py` file for a working example to play with.
+

chameleon_flask-0.0.1/chameleon_flask.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+chameleon_flask/__init__.py
+chameleon_flask/engine.py
+chameleon_flask/exceptions.py
+chameleon_flask.egg-info/PKG-INFO
+chameleon_flask.egg-info/SOURCES.txt
+chameleon_flask.egg-info/dependency_links.txt
+chameleon_flask.egg-info/requires.txt
+chameleon_flask.egg-info/top_level.txt
+tests/test_init.py
+tests/test_not_found.py
+tests/test_render.py

chameleon_flask-0.0.1/chameleon_flask.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chameleon_flask-0.0.1/chameleon_flask.egg-info/requires.txt

@@ -0,0 +1,2 @@
+flask[async]
+Chameleon

chameleon_flask-0.0.1/chameleon_flask.egg-info/top_level.txt

@@ -0,0 +1 @@
+chameleon_flask

chameleon_flask-0.0.1/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chameleon_flask"
+version = "0.0.1"
+description = "Adds integration of the Chameleon template language to Flask and Quart."
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Michael Kennedy", email = "michael@talkpython.fm" }
+]
+keywords = ["Flask", "Chameleon", "template", "integration"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13"
+]
+dependencies = [
+    "flask[async]",
+    "Chameleon"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/mikeckennedy/chameleon-flask"
+
+[tool.setuptools]
+packages = ["chameleon_flask"]

chameleon_flask-0.0.1/setup.cfg

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

chameleon_flask-0.0.1/tests/test_init.py

@@ -0,0 +1,29 @@
+import pytest
+
+import chameleon_flask as fc
+from chameleon_flask.exceptions import FlaskChameleonException
+
+
+def test_cannot_decorate_with_missing_init():
+    fc.engine.clear()
+
+    with pytest.raises(FlaskChameleonException):
+
+        @fc.template('home/index.pt')
+        def view_method(a, b, c):
+            return {'a': a, 'b': b, 'c': c}
+
+        view_method(1, 2, 3)
+
+
+def test_can_call_init_with_good_path(test_templates_path):
+    fc.global_init(str(test_templates_path), cache_init=False)
+
+    # Clear paths to no effect future tests
+    fc.engine.clear()
+
+
+def test_cannot_call_init_with_bad_path(test_templates_path):
+    bad_path = test_templates_path / 'missing'
+    with pytest.raises(Exception):
+        fc.global_init(str(bad_path), cache_init=False)

chameleon_flask-0.0.1/tests/test_not_found.py

@@ -0,0 +1,56 @@
+import asyncio
+
+import flask
+
+import chameleon_flask
+import chameleon_flask as fc
+
+
+# setup_global_template - needed as pytest mix-in.
+# noinspection PyUnusedLocal
+def test_friendly_404_sync_method(setup_global_template):
+    @fc.template('home/index.pt')
+    def view_method(a, b, c):
+        chameleon_flask.not_found()
+        return {'a': a, 'b': b, 'c': c}
+
+    resp = view_method(1, 2, 3)
+    html = response_to_html(resp)
+    assert isinstance(resp, flask.Response)
+    assert resp.status_code == 404
+    assert '<h1>This is a pretty 404 page.</h1>' in html
+
+
+# setup_global_template - needed as pytest mix-in.
+# noinspection PyUnusedLocal
+def test_friendly_404_custom_template_sync_method(setup_global_template):
+    @fc.template('home/index.pt')
+    def view_method(a, b, c):
+        chameleon_flask.not_found(four04template_file='errors/other_error_page.pt')
+        return {'a': a, 'b': b, 'c': c}
+
+    resp = view_method(1, 2, 3)
+    html = response_to_html(resp)
+    assert isinstance(resp, flask.Response)
+    assert resp.status_code == 404
+    assert '<h1>Another pretty 404 page.</h1>' in html
+
+
+# setup_global_template - needed as pytest mix-in.
+# noinspection PyUnusedLocal
+def test_friendly_404_async_method(setup_global_template):
+    @fc.template('home/index.pt')
+    async def view_method(a, b, c) -> flask.Response:
+        chameleon_flask.not_found()
+        return {'a': a, 'b': b, 'c': c}
+
+    resp = asyncio.run(view_method(1, 2, 3))
+    html = response_to_html(resp)
+    assert isinstance(resp, flask.Response)
+    assert resp.status_code == 404
+    assert '<h1>This is a pretty 404 page.</h1>' in html
+
+
+def response_to_html(response: flask.Response) -> str:
+    # noinspection PyUnresolvedReferences
+    return response.response[0].decode('utf-8')

chameleon_flask-0.0.1/tests/test_render.py

@@ -0,0 +1,110 @@
+import asyncio
+
+import flask
+# noinspection PyPackageRequirements
+import pytest
+
+import chameleon_flask as fc
+
+
+# setup_global_template - needed as pytest mix-in.
+# noinspection PyUnusedLocal
+def test_cannot_decorate_missing_template(setup_global_template):
+    with pytest.raises(ValueError):
+
+        @fc.template('home/missing.pt')
+        def view_method():
+            return {}
+
+        view_method()
+
+
+# setup_global_template - needed as pytest mix-in.
+# noinspection PyUnusedLocal
+def test_requires_template_for_default_name(setup_global_template):
+    with pytest.raises(ValueError):
+
+        @fc.template(None)
+        def view_method():
+            return {}
+
+        view_method()
+
+
+# setup_global_template - needed as pytest mix-in.
+# noinspection PyUnusedLocal
+def test_default_template_name_pt(setup_global_template):
+    @fc.template()
+    def index(a, b, c):
+        return {'a': a, 'b': b, 'c': c, 'world': 'WORLD'}
+
+    resp = index(1, 2, 3)
+    assert isinstance(resp, flask.Response)
+    assert resp.status_code == 200
+    html = response_to_html(resp)
+    assert '<h1>Hello default WORLD!</h1>' in html
+
+
+# setup_global_template - needed as pytest mix-in.
+# noinspection PyUnusedLocal
+def test_default_template_name_no_parentheses(setup_global_template):
+    @fc.template
+    def index(a, b, c):
+        return {'a': a, 'b': b, 'c': c, 'world': 'WORLD'}
+
+    resp = index(1, 2, 3)
+    assert isinstance(resp, flask.Response)
+    assert resp.status_code == 200
+    html = response_to_html(resp)
+    assert '<h1>Hello default WORLD!</h1>' in html
+
+
+def test_default_template_name_html(setup_global_template):
+    @fc.template()
+    def details(a, b, c):
+        return {'a': a, 'b': b, 'c': c, 'world': 'WORLD'}
+
+    resp = details(1, 2, 3)
+    assert isinstance(resp, flask.Response)
+    assert resp.status_code == 200
+    html = response_to_html(resp)
+    assert '<h1>Hello default WORLD!</h1>' in html
+
+
+# setup_global_template - needed as pytest mix-in.
+# noinspection PyUnusedLocal
+def test_can_decorate_dict_sync_method(setup_global_template):
+    @fc.template('home/index.pt')
+    def view_method(a, b, c):
+        return {'a': a, 'b': b, 'c': c}
+
+    resp = view_method(1, 2, 3)
+    assert isinstance(resp, flask.Response)
+    assert resp.status_code == 200
+
+
+def test_can_decorate_dict_async_method(setup_global_template):
+    @fc.template('home/index.pt')
+    async def view_method(a, b, c):
+        return {'a': a, 'b': b, 'c': c}
+
+    resp = asyncio.run(view_method(1, 2, 3))
+    assert isinstance(resp, flask.Response)
+    assert resp.status_code == 200
+
+
+def test_direct_response_pass_through():
+    @fc.template('home/index.pt')
+    def view_method(a, b, c):
+        return flask.Response(response='abc', status=418)
+
+    resp = view_method(1, 2, 3)
+    html = response_to_html(resp)
+    assert isinstance(resp, flask.Response)
+    assert resp.status_code == 418
+    assert html == 'abc'
+
+
+def response_to_html(response: flask.Response) -> str:
+    # noinspection PyUnresolvedReferences
+    return response.response[0].decode('utf-8')