Improve the template

- Add a fallback in case of Application startup error.
- Unpin `pydantic` version.
- Set the `APP_SHOW_ERROR_DETAILS` env variable in `dev.py`.

Author: RobertoPrevato

CHANGELOG.md

@@ -5,10 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2025-03-17
+
+- Add a fallback in case of Application startup error.
+- Unpin `pydantic` version.
+- Set the `APP_SHOW_ERROR_DETAILS` env variable in `dev.py`.
+
 ## 2023-11-26
+
 - Update the template for BlackSheep v2
 - Remove support for Pydantic v1, add support for `pydantic-settings`,
   and upgrade `Pydantic` pinned version
 
 ## 2023-06-29 :gem:
+
 - New project template

{{cookiecutter.project_name}}/app/diagnostics.py

@@ -0,0 +1,46 @@
+from blacksheep import Application, Router, html
+from blacksheep.server.errors import ServerErrorDetailsHandler
+
+
+def _get_response_without_details(request, info, error_page_template: str):
+    content = error_page_template.format_map(
+        {
+            "info": info,
+            "exctype": "",
+            "excmessage": "",
+            "method": request.method,
+            "path": request.url.value.decode(),
+            "full_url": "",
+        }
+    )
+
+    return html(content, status=503)
+
+
+def get_diagnostic_app(exc: Exception) -> Application:
+    """
+    Returns a fallback application, to help diagnosing start-up errors.
+    """
+    router = Router()
+    error_details_handler = ServerErrorDetailsHandler()
+
+    app = Application(router=router)
+
+    @router.get("/*")
+    async def diagnostic_home(request):
+        if app.show_error_details:
+            response = error_details_handler.produce_response(request, exc)
+            response.status = 503
+            return response
+        return _get_response_without_details(
+            request,
+            (
+                "The application failed to start. Error details are hidden for security "
+                "reasons. To display temporarily error details and investigate the "
+                "issue, configure temporarily the environment to display error details."
+                "APP_SHOW_ERROR_DETAILS=1"
+            ),
+            error_details_handler._error_page_template,
+        )
+
+    return app

{{cookiecutter.project_name}}/app/main.py

@@ -9,8 +9,9 @@
 from app.docs import configure_docs
 {%- endif %}
 from app.errors import configure_error_handlers
+from app.diagnostics import get_diagnostic_app
 from app.services import configure_services
-from app.settings import load_settings, Settings
+from app.settings import Settings
 
 
 def configure_application(
@@ -21,8 +22,6 @@ def configure_application(
         services=services, show_error_details=settings.app.show_error_details
     )
 
-
-
     configure_error_handlers(app)
     configure_authentication(app, settings)
 {%- if cookiecutter.use_openapi %}
@@ -31,4 +30,11 @@ def configure_application(
     return app
 
 
-app = configure_application(*configure_services(load_settings()))
+def get_app():
+    try:
+        return configure_application(*configure_services())
+    except Exception as exc:
+        return get_diagnostic_app(exc)
+
+
+app = get_app()

{{cookiecutter.project_name}}/app/services.py

@@ -7,15 +7,17 @@
     https://github.com/Neoteroi/rodi/wiki
     https://github.com/Neoteroi/rodi/tree/main/examples
 """
+
 from typing import Tuple
 
 from rodi import Container
 
-from app.settings import Settings
+from app.settings import Settings, load_settings
 
 
-def configure_services(settings: Settings) -> Tuple[Container, Settings]:
+def configure_services() -> Tuple[Container, Settings]:
     container = Container()
+    settings = load_settings()
 
     container.add_instance(settings)
 

{{cookiecutter.project_name}}/dev.py

@@ -18,6 +18,7 @@
 
 if __name__ == "__main__":
     os.environ["APP_ENV"] = "dev"
+    os.environ["APP_SHOW_ERROR_DETAILS"] = "1"
     port = int(os.environ.get("APP_PORT", 44777))
 
     console = Console()

{{cookiecutter.project_name}}/requirements.txt

@@ -8,4 +8,4 @@ essentials-configuration[full]
 pydantic-settings
 {%- endif %}
 MarkupSafe==2.1.3
-pydantic==2.5.2
+pydantic