Configuration

axion is configured through a single Python module. Defaults live in axion/config/settings.py; a project may override any of them by creating a config/settings.py module in the process working directory (the opinionated project layout produced by axion startproject).

How overrides work

When axion is imported, it loads ./config/settings.py if present and applies every name that matches a declared default. Unknown or private names are ignored. The merge is applied at import time — settings are read once per process.

# config/settings.py
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

HOST = "127.0.0.1"
PORT = 8000
DEBUG = True

TEMPLATE_DIRS = [BASE_DIR / "views"]
STATIC_DIRS = [BASE_DIR / "static"]
DATABASE_URL = "sqlite:///db.sqlite3"

Full settings reference

Application

Setting Default Description
APP_NAME "Axion" Application display name
APP_VERSION "0.1.0a1" Application version
BASE_DIR package root Root directory of the axion package
DEBUG True Development mode; disable in production
SHOW_TRACEBACKS True Render detailed exception pages

Server

Setting Default Description
HOST "127.0.0.1" Bind address
PORT 8000 Bind port
BACKLOG 128 Socket listen backlog
MAX_WORKERS 64 Worker thread pool size
CONNECTION_TIMEOUT 5.0 Idle timeout (seconds) for keep-alive connections
KEEP_ALIVE True Whether persistent connections are enabled
MAX_REQUEST_SIZE 10 * 1024 * 1024 Maximum request size in bytes
AUTO_RELOAD True Development auto-reload hint

Security

Setting Default Description
ALLOWED_HOSTS ["*"] Allowed host header values
SECRET_KEY "change-me" Signing secret (set in production!)
CORS_ALLOWED_ORIGINS ["*"] Origins allowed for CORS
CORS_ALLOW_CREDENTIALS True Send CORS credentials header
CSRF_COOKIE_NAME "csrftoken" CSRF cookie name
CSRF_HEADER_NAME "X-CSRFToken" CSRF header name

Templates & static files

Setting Default Description
TEMPLATE_DIRS [BASE_DIR / "templates"] Jinja2 template search directories
STATIC_DIRS [BASE_DIR / "static"] Static file directories
STATIC_URL "/static/" URL prefix for static assets
MEDIA_DIR BASE_DIR / "media" Media uploads directory
MEDIA_URL "/media/" URL prefix for media
PUBLIC_DIR BASE_DIR / "public" Public files directory

Logging

Setting Default Description
LOG_LEVEL "DEBUG" Logging level
ENABLE_REQUEST_LOGGING True Log each request after handling

Database

Setting Default Description
DATABASE_URL "sqlite:///db.sqlite3" Connection URL for use_database()
AUTO_CREATE_TABLES True Create missing tables on first use
DATABASE_ECHO False Echo SQL to the logger

Extensions

Setting Default Description
MIDDLEWARE [] Extra middleware by dotted path
INSTALLED_APPS [] Installed application modules
EXCEPTION_HANDLERS {} Custom exception handler paths
ROUTE_PREFIXES {} Route prefix mapping

Defaults

Setting Default Description
DEFAULT_CHARSET "utf-8" Response encoding

Which settings are actually wired up?

Settings that are actively used include HOST/PORT, BACKLOG, MAX_WORKERS, CONNECTION_TIMEOUT, KEEP_ALIVE, MAX_REQUEST_SIZE, DEBUG, SHOW_TRACEBACKS, ALLOWED_HOSTS, TEMPLATE_DIRS, STATIC_DIRS/ STATIC_URL, MEDIA_DIR/MEDIA_URL, PUBLIC_DIR, CSRF_*, CORS_ALLOWED_ORIGINS, ENABLE_REQUEST_LOGGING, LOG_LEVEL, DEFAULT_CHARSET, DATABASE_URL, AUTO_CREATE_TABLES, DATABASE_ECHO, and MIDDLEWARE. The rest (SECRET_KEY, AUTO_RELOAD, INSTALLED_APPS, EXCEPTION_HANDLERS, ROUTE_PREFIXES) are future extension points.

Next steps