# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "chameleon_flask",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Chameleon, Flask, integration, template",
"author": null,
"author_email": "Michael Kennedy <michael@talkpython.fm>",
"download_url": "https://files.pythonhosted.org/packages/a9/73/dc5ba88d1cd0eba587f69fdaf3e70b155a1e0a784d4b96cc267082dfa1cd/chameleon_flask-0.5.1.tar.gz",
"platform": null,
"description": "# chameleon-flask\n\nAdds integration of the Chameleon template language to Flask and Quart. \n\n## Installation\n\nSimply `pip install chameleon_flask`.\n\n## Usage\n\nThis is easy to use. Just create a folder within your web app to hold the templates such as:\n\n```\n\u251c\u2500\u2500 app.py\n\u251c\u2500\u2500 views.py\n\u2502\n\u251c\u2500\u2500 templates\n\u2502 \u251c\u2500\u2500 home\n\u2502 \u2502 \u2514\u2500\u2500 index.pt\n\u2502 \u2514\u2500\u2500 shared\n\u2502 \u2514\u2500\u2500 layout.pt\n\n```\n\nIn the app startup, tell the library about the folder you wish to use:\n\n```python\nimport os\nfrom pathlib import Path\nimport chameleon_flask\n\ndev_mode = True\n\nBASE_DIR = Path(__file__).resolve().parent\ntemplate_folder = str(BASE_DIR / 'templates')\nchameleon_flask.global_init(template_folder, auto_reload=dev_mode)\n```\n\nThen just decorate the Flask or Quart view methods (works on sync and async methods):\n\n```python\n@app.get('/async')\n@chameleon_flask.template('async.pt')\nasync def async_world():\n await asyncio.sleep(.01)\n return {'message': \"Let's go async Chameleon!\"}\n```\n\nThe view method should return a `dict` to be passed as variables/values to the template.\n\nIf a `flask.Response` is returned, the template is skipped and the response along with status_code and\nother values is directly passed through. This is common for redirects and error responses not meant\nfor this page template. Otherwise the dictionary is used to render `async.pt` in this example.\n\n## Friendly 404s and errors\n\nA 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/).\nThis library has support for friendly 404 pages using the `chameleon_flask.not_found()` function.\n\nHere's an example:\n\n```python\n@app.get('/catalog/item/{item_id}')\n@chameleon_flask.template('catalog/item.pt')\nasync def item(item_id: int):\n item = service.get_item_by_id(item_id)\n if not item:\n chameleon_flask.not_found()\n \n return item.dict()\n```\n\nThis will render a 404 response with using the template file `templates/errors/404.pt`.\nYou can specify another template to use for the response, but it's not required.\n\n## An example\n\nSee the `example/example_app.py` file for a working example to play with.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Adds integration of the Chameleon template language to Flask and Quart.",
"version": "0.5.1",
"project_urls": {
"Homepage": "https://github.com/mikeckennedy/chameleon-flask"
},
"split_keywords": [
"chameleon",
" flask",
" integration",
" template"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cdcecf1cc95d124ce192007980886eb82200d79a4d596797c9a8b78884d904b0",
"md5": "c39a5f70f0995aa1a2f15362387fc88e",
"sha256": "e3bf544c8ed9c23aa52c609b8f365a23ead370883a9915979525c8953cf76dcf"
},
"downloads": -1,
"filename": "chameleon_flask-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c39a5f70f0995aa1a2f15362387fc88e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 5298,
"upload_time": "2025-01-12T17:28:33",
"upload_time_iso_8601": "2025-01-12T17:28:33.407894Z",
"url": "https://files.pythonhosted.org/packages/cd/ce/cf1cc95d124ce192007980886eb82200d79a4d596797c9a8b78884d904b0/chameleon_flask-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a973dc5ba88d1cd0eba587f69fdaf3e70b155a1e0a784d4b96cc267082dfa1cd",
"md5": "0d80ca3ff4bf0290b71b0486225f1ff1",
"sha256": "ba6fcee2b1f1649d390e3cb2421bf87224c391425bb4b23d2a46051210565f5d"
},
"downloads": -1,
"filename": "chameleon_flask-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "0d80ca3ff4bf0290b71b0486225f1ff1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 5638,
"upload_time": "2025-01-12T17:28:37",
"upload_time_iso_8601": "2025-01-12T17:28:37.097972Z",
"url": "https://files.pythonhosted.org/packages/a9/73/dc5ba88d1cd0eba587f69fdaf3e70b155a1e0a784d4b96cc267082dfa1cd/chameleon_flask-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-12 17:28:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mikeckennedy",
"github_project": "chameleon-flask",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "flask",
"specs": []
},
{
"name": "Chameleon",
"specs": []
}
],
"tox": true,
"lcname": "chameleon_flask"
}
JSON
