# Configuration There is pleasingly little to configure. One function, three parameters, and no environment variables, settings files, or command-line flags hiding behind them. Everything the engine knows, it learned from a single [global_init()](../reference/global_init.md#fastapi_chameleon.global_init) call at startup. # [global_init()](../reference/global_init.md#fastapi_chameleon.global_init) parameters | Parameter | Type | Default | Effect | |----|----|----|----| | `template_folder` | `str` or `os.PathLike` | required | Root folder for every template path. Must exist and be a directory, otherwise [FastAPIChameleonException](../reference/exceptions.FastAPIChameleonException.md#fastapi_chameleon.exceptions.FastAPIChameleonException) is raised. | | `auto_reload` | `bool` | `False` | When `True`, Chameleon checks template files for changes on each use and recompiles them. When `False`, each template is compiled once per process. | | `cache_init` | `bool` | `True` | When `True`, a call made after the engine is already initialized is ignored. When `False`, the call replaces the loader and folder. | Every row in that table was checked against the source and then by running it. The `auto_reload` flag is handed straight to Chameleon's `PageTemplateLoader`, so its behaviour is Chameleon's behaviour. # Calling [global_init()](../reference/global_init.md#fastapi_chameleon.global_init) more than once This is the one place people get tripped up, because the default is to politely ignore you. | Situation | Result | |----|----| | Second call, `cache_init=True` (default) | Silently ignored. The first folder and `auto_reload` setting stay in effect. | | Second call, `cache_init=False` | New loader and folder take effect for every template rendered from now on. | | `engine.clear()` then [global_init()](../reference/global_init.md#fastapi_chameleon.global_init) | Same as a first call. | The consequence: you cannot flip `auto_reload` by calling [global_init()](../reference/global_init.md#fastapi_chameleon.global_init) a second time with the defaults. The engine will keep whatever it was told first. Pass `cache_init=False`, or call `fastapi_chameleon.engine.clear()` and start over. This design is deliberate. It means a library or a plugin that calls [global_init()](../reference/global_init.md#fastapi_chameleon.global_init) defensively cannot stomp on the app's own configuration. # Development versus production ``` python import os from pathlib import Path import fastapi_chameleon dev_mode = os.environ.get('APP_ENV', 'dev') == 'dev' # your own switch, the package reads no env vars BASE_DIR = Path(__file__).resolve().parent fastapi_chameleon.global_init(BASE_DIR / 'templates', auto_reload=dev_mode) ``` With `auto_reload=False`, Chameleon compiles each template to Python the first time it is used and reuses that compiled version for the life of the process. Rendering a page becomes a function call, which is why Chameleon has a reputation for speed. That is the setting you want under load. With `auto_reload=True`, every use checks the file's modification time first. Cheap, but not free, and pointless on a server where nobody is editing templates. # The decorator `@template(template_file=None, mimetype='text/html')` has two options: | Parameter | Default | Effect | |----|----|----| | `template_file` | `None` | Template path relative to the folder. `None` means infer `{module}/{function}.html`, then `.pt`. | | `mimetype` | `'text/html'` | Content type of the response for a rendered `dict`. Ignored for error pages. | There is no `status_code` parameter on the decorator, and that is on purpose. A rendered dict is always a `200`. For another status use [response()](../reference/response.md#fastapi_chameleon.response), and for error pages use [generic_error()](../reference/generic_error.md#fastapi_chameleon.generic_error), each of which makes the status visible at the call site instead of hiding it in a decorator argument. # Where [global_init()](../reference/global_init.md#fastapi_chameleon.global_init) goes Call it at import time in the module that creates the app, before the view modules are imported. When views live in their own module, the order looks like this: ``` python # main.py import fastapi import fastapi_chameleon app = fastapi.FastAPI() fastapi_chameleon.global_init('templates') from views import home # noqa: E402 imported after init on purpose app.include_router(home.router) ``` The order matters only for views that let the decorator infer the template name. Views with explicit template names resolve them at request time against whatever folder is configured then, so they are indifferent to import order.