flaskit-cli 0.2.1__py3-none-any.whl

flaskit/templates/project/app.py.j2

@@ -0,0 +1,551 @@
+"""Flask application factory generated by flaskit."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import logging
+import sys
+import time
+import uuid
+from base64 import b64encode
+from copy import deepcopy
+from datetime import datetime
+from logging.handlers import RotatingFileHandler, TimedRotatingFileHandler
+from pathlib import Path
+
+import click
+import config
+from flask import Flask, g, jsonify, render_template, request
+from flask_smorest import Api
+
+try:
+    import bjoern
+except ImportError:  # pragma: no cover - optional production dependency
+    bjoern = None
+
+try:
+    from opentelemetry import trace
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+        OTLPSpanExporter as OTLPSpanExporterGrpc,
+    )
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+        OTLPSpanExporter as OTLPSpanExporterHttp,
+    )
+    from opentelemetry.instrumentation.flask import FlaskInstrumentor
+    from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+    from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, ConsoleLogExporter
+    from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+except ImportError:  # pragma: no cover - optional
+    trace = None
+    OTLPSpanExporterGrpc = None
+    OTLPSpanExporterHttp = None
+    FlaskInstrumentor = None
+    LoggerProvider = None
+    LoggingHandler = None
+    BatchLogRecordProcessor = None
+    ConsoleLogExporter = None
+    SERVICE_NAME = None
+    Resource = None
+    TracerProvider = None
+    BatchSpanProcessor = None
+    TraceContextTextMapPropagator = None
+
+ROOT = Path(__file__).resolve().parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+request_logger = logging.getLogger(config.LOG_REQUEST_NAME)
+response_logger = logging.getLogger(config.LOG_RESPONSE_NAME)
+
+
+def _openapi_server_url():
+    """Return BASE_PATH for OpenAPI servers, or None when unset/root."""
+    base = (config.BASE_PATH or "").strip()
+    if not base or base == "/":
+        return None
+    return base
+
+
+class _FlushStreamHandler(logging.StreamHandler):
+    """Stream handler that flushes after every record."""
+
+    def emit(self, record):
+        super().emit(record)
+        self.flush()
+
+
+def _make_file_handler(path, formatter):
+    path = Path(path)
+    if not path.is_absolute():
+        path = ROOT / path
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    if config.LOG_ROTATION == "time":
+        handler = TimedRotatingFileHandler(
+            path,
+            when=config.LOG_WHEN,
+            interval=config.LOG_INTERVAL,
+            backupCount=config.LOG_BACKUP_COUNT,
+            encoding="utf-8",
+        )
+    elif config.LOG_ROTATION == "none":
+        handler = logging.FileHandler(path, encoding="utf-8")
+    else:
+        handler = RotatingFileHandler(
+            path,
+            maxBytes=config.LOG_MAX_BYTES,
+            backupCount=config.LOG_BACKUP_COUNT,
+            encoding="utf-8",
+        )
+    handler.setFormatter(formatter)
+    return handler
+
+
+def _configure_logger(logger, log_file):
+    """Attach stream/file handlers to one named logger."""
+    level = getattr(logging, config.LOG_LEVEL, logging.INFO)
+    formatter = logging.Formatter(config.LOG_FORMAT, datefmt=config.LOG_DATE_FORMAT)
+
+    logger.handlers.clear()
+    logger.disabled = False
+    logger.setLevel(level)
+    logger.propagate = config.LOG_PROPAGATE
+
+    if "stream" in config.LOG_OUTPUT or not config.LOG_OUTPUT:
+        stream = sys.stderr if config.LOG_STREAM != "stdout" else sys.stdout
+        handler = _FlushStreamHandler(stream)
+        handler.setFormatter(formatter)
+        handler.setLevel(level)
+        logger.addHandler(handler)
+
+    if "file" in config.LOG_OUTPUT:
+        logger.addHandler(_make_file_handler(log_file, formatter))
+
+
+def setup_logging(app):
+    """Configure app, request, and response loggers (+ optional OTel log bridge)."""
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(line_buffering=True)
+        except Exception:
+            pass
+
+    _configure_logger(app.logger, config.LOG_APP_FILE)
+    app.logger.name = config.LOG_APP_NAME
+    _configure_logger(request_logger, config.LOG_REQUEST_FILE)
+    _configure_logger(response_logger, config.LOG_RESPONSE_FILE)
+
+    if not config.OTEL_LOGS_ENABLED or LoggerProvider is None:
+        return
+
+    resource = Resource.create({SERVICE_NAME: config.OTEL_SERVICE_NAME})
+    provider = LoggerProvider(resource=resource)
+    if "stream" in config.LOG_OUTPUT or not config.LOG_OUTPUT:
+        provider.add_log_record_processor(BatchLogRecordProcessor(ConsoleLogExporter()))
+    # File mirroring stays on stdlib handlers above; OTel console exporter
+    # complements OTLP when a collector is configured in setup_otel.
+    otel_handler = LoggingHandler(level=getattr(logging, config.LOG_LEVEL, logging.INFO), logger_provider=provider)
+    for logger in (app.logger, request_logger, response_logger):
+        logger.addHandler(otel_handler)
+
+
+def _tz_offset_seconds():
+    now = datetime.now(config.TZ)
+    return int(now.utcoffset().total_seconds()) if now.utcoffset() else 0
+
+
+def _trace_fields():
+    fields = {"trace_id": None, "span_id": None, "timezone": config.TIMEZONE}
+    if trace is None:
+        return fields
+    span = trace.get_current_span()
+    ctx = span.get_span_context()
+    if ctx.is_valid:
+        fields["trace_id"] = format(ctx.trace_id, "032x")
+        fields["span_id"] = format(ctx.span_id, "016x")
+    return fields
+
+
+def _safe_headers(headers):
+    return {
+        key: ("***" if key.lower() in config.LOG_REDACT_HEADERS else value)
+        for key, value in headers.items()
+    }
+
+
+def _encode_body(data, logger):
+    """Include body only when logger level is below INFO (DEBUG)."""
+    if not logger.isEnabledFor(logging.DEBUG):
+        return ""
+    if not data:
+        return ""
+    return b64encode(data).decode("ascii")
+
+
+def _base_log_fields():
+    return {
+        "timestamp": time.time(),
+        "tz_offset": _tz_offset_seconds(),
+        "timezone": config.TIMEZONE,
+        "api_version": config.API_VERSION,
+        "api_title": config.API_TITLE.lower(),
+        "request_id": getattr(g, "request_id", None),
+        "log_id": str(uuid.uuid4()),
+        **_trace_fields(),
+    }
+
+
+def setup_request_logging(app):
+    """Log each request and response as JSON (stdlib + OTel context fields)."""
+
+    @app.before_request
+    def before_request():
+        g.start = time.time()
+        g.request_id = str(uuid.uuid4())
+
+        payload = {
+            **_base_log_fields(),
+            "log_level": "debug" if request_logger.isEnabledFor(logging.DEBUG) else "info",
+            "method": request.method,
+            "path": request.path,
+            "url": request.url,
+            "client_ip": request.headers.get("X-Forwarded-For", request.remote_addr),
+            "query_string": request.query_string.decode("utf-8", errors="replace"),
+            "headers": _safe_headers(request.headers),
+            "body": _encode_body(request.get_data(cache=True), request_logger),
+            "body_size": len(request.get_data(cache=True) or b""),
+            "module": config.LOG_REQUEST_NAME,
+        }
+        request_logger.info(json.dumps(payload, ensure_ascii=False))
+
+    @app.after_request
+    def after_request(response):
+        response.direct_passthrough = False
+
+        if (
+            trace is not None
+            and TraceContextTextMapPropagator is not None
+        ):
+            span = trace.get_current_span()
+            if span.get_span_context().is_valid:
+                carrier = {}
+                TraceContextTextMapPropagator().inject(carrier)
+                if carrier.get("traceparent"):
+                    response.headers["traceparent"] = carrier["traceparent"]
+
+        body = response.get_data()
+        payload = {
+            **_base_log_fields(),
+            "log_level": "debug" if response_logger.isEnabledFor(logging.DEBUG) else "info",
+            "status": response.status_code,
+            "duration": time.time() - getattr(g, "start", time.time()),
+            "headers": _safe_headers(response.headers),
+            "body": _encode_body(body, response_logger),
+            "body_size": len(body or b""),
+            "module": config.LOG_RESPONSE_NAME,
+            "method": request.method,
+            "path": request.path,
+        }
+        response_logger.info(json.dumps(payload, ensure_ascii=False))
+        return response
+
+
+def setup_static_caching(app):
+    """Apply Cache-Control under {BASE_PATH}/assets/statics."""
+    statics_prefix = config.app_path("assets", "statics")
+    max_age = max(0, int(config.STATIC_CACHE_MAX_AGE))
+
+    @app.after_request
+    def cache_statics(response):
+        path = request.path
+        if path == statics_prefix or path.startswith(statics_prefix + "/"):
+            if response.status_code in {200, 304}:
+                if max_age > 0:
+                    response.cache_control.public = True
+                    response.cache_control.max_age = max_age
+                    response.headers["Cache-Control"] = f"public, max-age={max_age}"
+                else:
+                    response.headers["Cache-Control"] = "no-cache"
+        return response
+
+
+def setup_otel(app):
+    if not config.OTEL_ENABLED:
+        return
+    if trace is None or TracerProvider is None or FlaskInstrumentor is None:
+        app.logger.warning("OpenTelemetry not installed; skipping")
+        return
+
+    provider = TracerProvider(
+        resource=Resource.create({SERVICE_NAME: config.OTEL_SERVICE_NAME})
+    )
+    try:
+        if config.OTEL_EXPORTER_OTLP_PROTOCOL in {"http", "http/protobuf"}:
+            exporter = OTLPSpanExporterHttp(endpoint=config.OTEL_EXPORTER_OTLP_ENDPOINT)
+        else:
+            exporter = OTLPSpanExporterGrpc(endpoint=config.OTEL_EXPORTER_OTLP_ENDPOINT)
+        provider.add_span_processor(BatchSpanProcessor(exporter))
+    except Exception:
+        app.logger.exception("OTLP exporter failed")
+
+    trace.set_tracer_provider(provider)
+    FlaskInstrumentor().instrument_app(app)
+
+
+def apply_security(api):
+    name = config.AUTH_SECURITY_NAME
+    if config.AUTH_SCHEME == "bearer":
+        scheme = {
+            "type": "http",
+            "scheme": "bearer",
+            "bearerFormat": config.AUTH_BEARER_FORMAT,
+        }
+    else:
+        scheme = {"type": "apiKey", "in": "header", "name": config.AUTH_HEADER}
+    api.spec.components.security_scheme(name, scheme)
+    api.spec.options.setdefault("security", [{name: []}])
+
+
+def discover_modules():
+    resources_dir = ROOT / "resources"
+    found = []
+    if not resources_dir.is_dir():
+        return found
+
+    for folder in sorted(resources_dir.iterdir()):
+        if not folder.is_dir() or folder.name.startswith((".", "_")):
+            continue
+        if not (folder / "blueprint.py").exists() or not (folder / "resource.py").exists():
+            continue
+        try:
+            bp_mod = importlib.import_module(f"resources.{folder.name}.blueprint")
+            res_mod = importlib.import_module(f"resources.{folder.name}.resource")
+            flask_bp = getattr(bp_mod, "flask_bp", None) or getattr(bp_mod, "bp", None)
+            smorest_blp = getattr(res_mod, "smorest_blp", None) or getattr(res_mod, "blp", None)
+            if flask_bp and smorest_blp:
+                url_prefix = getattr(bp_mod, "URL_PREFIX", None) or f"/{folder.name}"
+                found.append((folder.name, flask_bp, smorest_blp, url_prefix))
+        except Exception:
+            logging.getLogger(config.LOG_APP_NAME).exception(
+                "Failed to load module %s", folder.name
+            )
+    return found
+
+
+def filter_spec(spec, tag):
+    result = deepcopy(spec)
+    paths = {}
+    for path, methods in (spec.get("paths") or {}).items():
+        kept = {
+            method: op
+            for method, op in methods.items()
+            if isinstance(op, dict) and tag in (op.get("tags") or [])
+        }
+        if kept:
+            paths[path] = kept
+    result["paths"] = paths
+    result["tags"] = [t for t in (spec.get("tags") or []) if t.get("name") == tag]
+    return result
+
+
+def setup_docs(app, api, modules):
+    prefix = config.docs_url_prefix().rstrip("/") or "/docs"
+    assets = config.assets_url_path().rstrip("/")
+    urls = [{"name": "All modules", "url": f"{prefix}/openapi.json"}]
+    for name in modules:
+        urls.append({"name": name, "url": f"{prefix}/modules/{name}/openapi.json"})
+
+    @app.get(f"{prefix}/modules/<module_name>/openapi.json")
+    def module_openapi(module_name):
+        if module_name not in modules:
+            return jsonify({"message": "Unknown module"}), 404
+        return jsonify(filter_spec(api.spec.to_dict(), module_name))
+
+    @app.get(prefix)
+    @app.get(f"{prefix}/")
+    def swagger_ui():
+        return render_template(
+            "swagger_ui.html",
+            title=config.API_TITLE,
+            css_url=f"{assets}/swagger-ui/swagger-ui.css",
+            bundle_url=f"{assets}/swagger-ui/swagger-ui-bundle.js",
+            preset_url=f"{assets}/swagger-ui/swagger-ui-standalone-preset.js",
+            urls=urls,
+            show_servers=_openapi_server_url() is not None,
+        )
+
+
+def init_app(app):
+    """Wire discovered modules, OpenAPI tags, and docs onto an existing app.
+
+    Called at the end of ``create_app``. Safe to call more than once (no-op if
+    already initialized).
+    """
+    if app.extensions.get("flaskit_ready"):
+        return
+
+    api = app.extensions["flaskit_api"]
+    modules = []
+
+    for name, flask_bp, smorest_blp, blueprint_path in discover_modules():
+        prefix = config.route_prefix(blueprint_path)
+        app.register_blueprint(flask_bp, url_prefix=prefix)
+        smorest_blp.register_views_in_doc(
+            api, app, api.spec, name=f"{flask_bp.name}.{smorest_blp.name}", parameters=None
+        )
+        api.spec.tag({"name": name, "description": smorest_blp.description or name})
+        modules.append(name)
+        app.logger.info("Registered %s at %s", name, prefix)
+
+    setup_docs(app, api, modules)
+
+    @app.cli.command("list-modules")
+    def list_modules():
+        for name in modules:
+            click.echo(name)
+
+    app.extensions["flaskit_ready"] = True
+
+
+def create_app():
+    """Application factory: Flask + logging + Smorest + module discovery.
+
+    Customize here (database, cache, auth extensions). See docs/extending.md.
+    """
+    app = Flask(
+        __name__,
+        static_folder="assets",
+        static_url_path=config.assets_url_path(),
+        template_folder="templates",
+    )
+    docs_prefix = config.docs_url_prefix()
+    app.config.update(
+        SECRET_KEY=config.SECRET_KEY,
+        API_TITLE=config.API_TITLE,
+        API_VERSION=config.API_VERSION,
+        OPENAPI_VERSION=config.OPENAPI_VERSION,
+        OPENAPI_URL_PREFIX=docs_prefix,
+        OPENAPI_JSON_PATH="openapi.json",
+        OPENAPI_SWAGGER_UI_PATH=None,
+        OPENAPI_SWAGGER_UI_URL=None,
+        API_SPEC_OPTIONS={
+            "info": {"description": config.API_DESCRIPTION},
+            **(
+                {"servers": [{"url": server}]}
+                if (server := _openapi_server_url()) is not None
+                else {}
+            ),
+        },
+    )
+
+    setup_logging(app)
+    setup_request_logging(app)
+    setup_static_caching(app)
+    setup_otel(app)
+
+    (ROOT / "assets" / "statics").mkdir(parents=True, exist_ok=True)
+
+    # Example extension hook (database, redis, ...):
+    # from mydb import init_db
+    # init_db(app)
+
+    api = Api(app)
+    apply_security(api)
+    app.extensions["flaskit_api"] = api
+
+    init_app(app)
+    return app
+
+
+def _run_bjoern():
+    """Production WSGI server (bjoern / libev — installed only in Docker)."""
+    if bjoern is None:
+        raise SystemExit(
+            "bjoern is required for ENV=production and is installed only in Docker. "
+            "Build/run the Dockerfile, or use ENV=development locally (Flask)."
+        )
+
+    app = create_app()
+    app.logger.info(
+        "Starting bjoern on %s:%s (reuse_port=%s)",
+        config.HOST,
+        config.PORT,
+        config.BJOERN_REUSE_PORT,
+    )
+    bjoern.run(
+        app,
+        config.HOST,
+        config.PORT,
+        reuse_port=config.BJOERN_REUSE_PORT,
+    )
+
+
+def _parse_cli_args(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="app.py",
+        description=(
+            "Run the API. development -> Flask; production -> bjoern. "
+            "Most settings come from environment variables (see config.py / .env.example)."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "examples:\n"
+            "  python app.py\n"
+            "  python app.py -h\n"
+            "  python app.py --host 0.0.0.0 -p 8082\n"
+            "  python app.py -e production --host 0.0.0.0 -p 80\n"
+            "  set HOST=0.0.0.0&& set PORT=8082&& python app.py"
+        ),
+    )
+    parser.add_argument(
+        "-e",
+        "--env",
+        choices=("development", "production"),
+        default=None,
+        help="Override ENV for this process (default: value of ENV / FLASK_ENV).",
+    )
+    parser.add_argument(
+        "--host",
+        default=None,
+        help=f"Bind host (default: {config.HOST}).",
+    )
+    parser.add_argument(
+        "-p",
+        "--port",
+        type=int,
+        default=None,
+        help=f"Bind port (default: {config.PORT}).",
+    )
+    parser.add_argument(
+        "--debug",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Enable/disable Flask debug (development only).",
+    )
+    return parser.parse_args(argv)
+
+
+if __name__ == "__main__":
+    args = _parse_cli_args()
+    if args.env is not None:
+        config.ENV = args.env
+    if args.host is not None:
+        config.HOST = args.host
+    if args.port is not None:
+        config.PORT = args.port
+    if args.debug is not None:
+        config.DEBUG = args.debug
+
+    if config.ENV in {"production", "prod"}:
+        _run_bjoern()
+    else:
+        create_app().run(
+            host=config.HOST,
+            port=config.PORT,
+            debug=config.DEBUG,
+        )