fastapi_chameleon 0.1.16__tar.gz

fastapi_chameleon-0.1.16/.gitignore

@@ -0,0 +1,130 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+.idea

fastapi_chameleon-0.1.16/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.

fastapi_chameleon-0.1.16/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.3
+Name: fastapi_chameleon
+Version: 0.1.16
+Summary: Adds integration of the Chameleon template language to FastAPI.
+Project-URL: Homepage, https://github.com/mikeckennedy/fastapi-chameleon
+Author-email: Michael Kennedy <michael@talkpython.fm>
+License: MIT
+Keywords: Chameleon,FastAPI,integration,template
+Classifier: Development Status :: 5 - Production/Stable
+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
+Requires-Dist: chameleon
+Requires-Dist: fastapi
+Description-Content-Type: text/markdown
+
+# fastapi-chameleon
+
+Adds integration of the Chameleon template language to FastAPI. If you are interested in Jinja instead, see the sister project: [github.com/AGeekInside/fastapi-jinja](https://github.com/AGeekInside/fastapi-jinja).
+
+## Installation
+
+Simply `pip install fastapi_chameleon`.
+
+## Usage
+
+This is easy to use. Just create a folder within your web app to hold the templates such as:
+
+```
+├── main.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 fastapi_chameleon
+
+dev_mode = True
+
+BASE_DIR = Path(__file__).resolve().parent
+template_folder = str(BASE_DIR / 'templates')
+fastapi_chameleon.global_init(template_folder, auto_reload=dev_mode)
+```
+
+Then just decorate the FastAPI view methods (works on sync and async methods):
+
+```python
+@router.post('/')
+@fastapi_chameleon.template('home/index.pt')
+async def home_post(request: Request):
+    form = await request.form()
+    vm = PersonViewModel(**form) 
+
+    return vm.dict() # {'first':'Michael', 'last':'Kennedy', ...}
+
+```
+
+The view method should return a `dict` to be passed as variables/values to the template. 
+
+If a `fastapi.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.
+
+## 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 is especially important in FastAPI because FastAPI returns a 404 response + JSON by default.
+This library has support for friendly 404 pages using the `fastapi_chameleon.not_found()` function.
+
+Here's an example:
+
+```python
+@router.get('/catalog/item/{item_id}')
+@fastapi_chameleon.template('catalog/item.pt')
+async def item(item_id: int):
+    item = service.get_item_by_id(item_id)
+    if not item:
+        fastapi_chameleon.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.
+
+If you need to return errors other than `Not Found` (status code `404`), you can use a more
+generic function: `fastapi_chameleon.generic_error(template_file: str, status_code: int)`.
+This function will allow you to return different status codes. It's generic, thus you'll have
+to pass a path to your error template file as well as a status code you want the user to get
+in response. For example:
+
+```python
+@router.get('/catalog/item/{item_id}')
+@fastapi_chameleon.template('catalog/item.pt')
+async def item(item_id: int):
+    item = service.get_item_by_id(item_id)
+    if not item:
+        fastapi_chameleon.generic_error('errors/unauthorized.pt',
+                                        fastapi.status.HTTP_401_UNAUTHORIZED)
+
+    return item.dict()
+```

fastapi_chameleon-0.1.16/README.md

@@ -0,0 +1,97 @@
+# fastapi-chameleon
+
+Adds integration of the Chameleon template language to FastAPI. If you are interested in Jinja instead, see the sister project: [github.com/AGeekInside/fastapi-jinja](https://github.com/AGeekInside/fastapi-jinja).
+
+## Installation
+
+Simply `pip install fastapi_chameleon`.
+
+## Usage
+
+This is easy to use. Just create a folder within your web app to hold the templates such as:
+
+```
+├── main.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 fastapi_chameleon
+
+dev_mode = True
+
+BASE_DIR = Path(__file__).resolve().parent
+template_folder = str(BASE_DIR / 'templates')
+fastapi_chameleon.global_init(template_folder, auto_reload=dev_mode)
+```
+
+Then just decorate the FastAPI view methods (works on sync and async methods):
+
+```python
+@router.post('/')
+@fastapi_chameleon.template('home/index.pt')
+async def home_post(request: Request):
+    form = await request.form()
+    vm = PersonViewModel(**form) 
+
+    return vm.dict() # {'first':'Michael', 'last':'Kennedy', ...}
+
+```
+
+The view method should return a `dict` to be passed as variables/values to the template. 
+
+If a `fastapi.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.
+
+## 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 is especially important in FastAPI because FastAPI returns a 404 response + JSON by default.
+This library has support for friendly 404 pages using the `fastapi_chameleon.not_found()` function.
+
+Here's an example:
+
+```python
+@router.get('/catalog/item/{item_id}')
+@fastapi_chameleon.template('catalog/item.pt')
+async def item(item_id: int):
+    item = service.get_item_by_id(item_id)
+    if not item:
+        fastapi_chameleon.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.
+
+If you need to return errors other than `Not Found` (status code `404`), you can use a more
+generic function: `fastapi_chameleon.generic_error(template_file: str, status_code: int)`.
+This function will allow you to return different status codes. It's generic, thus you'll have
+to pass a path to your error template file as well as a status code you want the user to get
+in response. For example:
+
+```python
+@router.get('/catalog/item/{item_id}')
+@fastapi_chameleon.template('catalog/item.pt')
+async def item(item_id: int):
+    item = service.get_item_by_id(item_id)
+    if not item:
+        fastapi_chameleon.generic_error('errors/unauthorized.pt',
+                                        fastapi.status.HTTP_401_UNAUTHORIZED)
+
+    return item.dict()
+```

fastapi_chameleon-0.1.16/example/example_app.py

@@ -0,0 +1,39 @@
+import asyncio
+from pathlib import Path
+
+import fastapi
+import uvicorn
+
+import fastapi_chameleon
+
+app = fastapi.FastAPI()
+
+
+@app.get("/")
+@fastapi_chameleon.template('index.pt')
+def hello_world():
+    return {'message': "Let's go Chameleon and FastAPI!"}
+
+
+@app.get('/async')
+@fastapi_chameleon.template('async.pt')
+async def async_world():
+    await asyncio.sleep(.01)
+    return {'message': "Let's go async Chameleon and FastAPI!"}
+
+
+def add_chameleon():
+    dev_mode = True
+
+    BASE_DIR = Path(__file__).resolve().parent
+    template_folder = (BASE_DIR / 'templates').as_posix()
+    fastapi_chameleon.global_init(template_folder, auto_reload=dev_mode)
+
+
+def main():
+    add_chameleon()
+    uvicorn.run(app, host='127.0.0.1', port=8000)
+
+
+if __name__ == '__main__':
+    main()

fastapi_chameleon-0.1.16/example/static/site.css

@@ -0,0 +1,8 @@
+body {
+    padding: 20px;
+    background-color: #fafafa;
+}
+
+h1, p {
+    text-align: center;
+}

fastapi_chameleon-0.1.16/example/templates/async.pt

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+    <link rel="stylesheet" href="/static/site.css">
+</head>
+<body>
+<h1>Hello async world</h1>
+<p>Your async message is <strong>${message}</strong></p>
+</body>
+</html>

fastapi_chameleon-0.1.16/example/templates/index.pt

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+    <link rel="stylesheet" href="/static/site.css">
+</head>
+<body>
+<h1>Hello world</h1>
+<p>Your message is <strong>${message}</strong>
+    <a href="/async">See the async example</a> too.</p>
+</body>
+</html>

fastapi_chameleon-0.1.16/fastapi_chameleon/__init__.py

@@ -0,0 +1,11 @@
+"""fastapi-chameleon - Adds integration of the Chameleon template language to FastAPI."""
+
+__version__ = '0.1.16'
+__author__ = 'Michael Kennedy <michael@talkpython.fm>'
+__all__ = ['template', 'global_init', 'not_found', 'response', 'generic_error', ]
+
+from .engine import generic_error
+from .engine import global_init
+from .engine import not_found
+from .engine import response
+from .engine import template

fastapi_chameleon-0.1.16/fastapi_chameleon/engine.py

@@ -0,0 +1,146 @@
+import inspect
+import os
+from functools import wraps
+from typing import Optional, Union, Callable
+
+import fastapi
+from chameleon import PageTemplateLoader, PageTemplate
+
+from fastapi_chameleon.exceptions import (
+    FastAPIChameleonException,
+    FastAPIChameleonGenericException,
+    FastAPIChameleonNotFoundException,
+)
+
+__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 FastAPIChameleonException(msg)
+
+    if not os.path.isdir(template_folder):
+        msg = f"The specified template folder must be a folder, it's not: {template_folder}"
+        raise FastAPIChameleonException(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 FastAPIChameleonException('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, mimetype='text/html', status_code=200, **template_data) -> fastapi.Response:
+    html = render(template_file, **template_data)
+    return fastapi.Response(content=html, media_type=mimetype, status_code=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 FastAPIChameleonException("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):
+            try:
+                response_val = f(*args, **kwargs)
+                return __render_response(template_file, response_val, mimetype)
+            except FastAPIChameleonNotFoundException as nfe:
+                return __render_response(nfe.template_file, {}, 'text/html', 404)
+            except FastAPIChameleonGenericException as nfe:
+                template_data = nfe.template_data if nfe.template_data is not None else {}
+                return __render_response(nfe.template_file, template_data, 'text/html', nfe.status_code)
+
+        @wraps(f)
+        async def async_view_method(*args, **kwargs):
+            try:
+                response_val = await f(*args, **kwargs)
+                return __render_response(template_file, response_val, mimetype)
+            except FastAPIChameleonNotFoundException as nfe:
+                return __render_response(nfe.template_file, {}, 'text/html', 404)
+            except FastAPIChameleonGenericException as nfe:
+                template_data = nfe.template_data if nfe.template_data is not None else {}
+                return __render_response(nfe.template_file, template_data, 'text/html', nfe.status_code)
+
+        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, mimetype, status_code: int = 200) -> fastapi.Response:
+    # source skip: assign-if-exp
+    if isinstance(response_val, fastapi.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 FastAPIChameleonException(msg)
+
+    model = response_val
+
+    html = render(template_file, **model)
+    return fastapi.Response(content=html, media_type=mimetype, status_code=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 FastAPIChameleonNotFoundException(msg, four04template_file)
+    else:
+        raise FastAPIChameleonNotFoundException(msg)
+
+
+def generic_error(template_file: str, status_code: int, template_data: Optional[dict] = None):
+    msg = 'The URL resulted in an error.'
+
+    raise FastAPIChameleonGenericException(template_file, status_code, msg, template_data=template_data)

fastapi_chameleon-0.1.16/fastapi_chameleon/exceptions.py

@@ -0,0 +1,24 @@
+from typing import Optional
+
+
+class FastAPIChameleonException(Exception):
+    pass
+
+
+class FastAPIChameleonNotFoundException(FastAPIChameleonException):
+    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
+
+
+class FastAPIChameleonGenericException(FastAPIChameleonException):
+    def __init__(self, template_file: str, status_code: int,
+                 message: Optional[str] = None, template_data: Optional[dict] = None):
+        super().__init__(message)
+
+        self.template_file: str = template_file
+        self.status_code: int = status_code
+        self.message: Optional[str] = message
+        self.template_data: Optional[dict] = template_data

fastapi_chameleon-0.1.16/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "fastapi_chameleon"
+version = "0.1.16"
+description = "Adds integration of the Chameleon template language to FastAPI."
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Michael Kennedy", email = "michael@talkpython.fm" }
+]
+keywords = ["FastAPI", "Chameleon", "template", "integration"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "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 = [
+    "fastapi",
+    "chameleon"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/mikeckennedy/fastapi-chameleon"
+
+[tool.setuptools]
+packages = ["fastapi_chameleon"]
+
+[build-system]
+requires = ["hatchling>=1.21.0", "hatch-vcs>=0.3.0"]
+build-backend = "hatchling.build"
+
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.github",
+    "/tests",
+    "/example_app",
+    "settings.json",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["fastapi_chameleon"]
+exclude = [
+    "/.github",
+    "/tests",
+    "/example",
+    "/example_client",
+    "settings.json",
+    "ruff.toml",
+]

fastapi_chameleon-0.1.16/requirements-dev.txt

@@ -0,0 +1,8 @@
+-r requirements.txt
+
+pytest
+pytest-clarity
+twine
+hatchling
+hatch-vcs>=0.3.0
+uvicorn

fastapi_chameleon-0.1.16/requirements.txt

@@ -0,0 +1,2 @@
+fastapi
+Chameleon

fastapi_chameleon-0.1.16/ruff.toml

@@ -0,0 +1,42 @@
+# [ruff]
+line-length = 120
+format.quote-style = "single"
+
+# Enable Pyflakes `E` and `F` codes by default.
+select = ["E", "F"]
+ignore = []
+
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    ".env",
+    ".venv",
+    "venv",
+]
+per-file-ignores = {}
+
+# Allow unused variables when underscore-prefixed.
+# dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+# Assume Python 3.13.
+target-version = "py313"
+
+#[tool.ruff.mccabe]
+## Unlike Flake8, default to a complexity level of 10.
+mccabe.max-complexity = 10

fastapi_chameleon-0.1.16/tox.ini

@@ -0,0 +1,6 @@
+[tox]
+envlist = py39,py310,py311,py312,py313
+
+[testenv]
+commands = pytest fastapi-chameleon
+deps = pytest