From 3d56eb59ca49df4b0c1c64a0a2466a374bdf8b25 Mon Sep 17 00:00:00 2001 From: alex Date: Tue, 7 Jan 2025 16:05:38 +0100 Subject: [PATCH] improve documentation --- docs/migrations/discovery.md | 4 ---- docs_src/commands/discover.py | 6 +++--- docs_src/migrations/fastapi.py | 8 +++++--- docs_src/migrations/migrations.py | 6 ++++-- docs_src/migrations/starlette.py | 8 ++++---- docs_src/tips/connection.py | 5 +++++ docs_src/tips/migrations.py | 7 +++++-- docs_src/tips/sandwich_main.py | 21 ++++++++++++++++++++- 8 files changed, 46 insertions(+), 19 deletions(-) diff --git a/docs/migrations/discovery.md b/docs/migrations/discovery.md index 44524de0..bed9e969 100644 --- a/docs/migrations/discovery.md +++ b/docs/migrations/discovery.md @@ -75,10 +75,6 @@ When no `--app` or no `EDGY_DEFAULT_APP` environment variable is provided, Edgy This is the way that Edgy can `auto discover` your application. -!!! Note - Flask has a similar pattern for the functions called `create_app`. Edgy doesn't use the - `create_app`, instead uses the `get_application` or `get_app` as a pattern as it seems cleaner. - ## Environment variables diff --git a/docs_src/commands/discover.py b/docs_src/commands/discover.py index bd013c88..56c9e571 100644 --- a/docs_src/commands/discover.py +++ b/docs_src/commands/discover.py @@ -6,8 +6,6 @@ from esmerald import Esmerald, Include from my_project.utils import get_db_connection -from edgy import Instance, monkay - def build_path(): """ @@ -23,8 +21,10 @@ def build_path(): def get_application(): """ - This is optional. The function is only used for organisation purposes. + Encapsulate in methods can be useful for capsulating and delaying imports but is optional. """ + from edgy import Instance, monkay + build_path() registry = get_db_connection() diff --git a/docs_src/migrations/fastapi.py b/docs_src/migrations/fastapi.py index 668006d4..38f9eec1 100644 --- a/docs_src/migrations/fastapi.py +++ b/docs_src/migrations/fastapi.py @@ -6,8 +6,6 @@ from fastapi import FastAPI from my_project.utils import get_db_connection -from edgy import Instance, monkay - def build_path(): """ @@ -23,9 +21,13 @@ def build_path(): def get_application(): """ - This is optional. The function is only used for organisation purposes. + Encapsulate in methods can be useful for capsulating and delaying imports but is optional. """ + # first call build_path build_path() + # because edgy tries to load settings eagerly + from edgy import Instance, monkay + registry = get_db_connection() app = registry.asgi(FastAPI(__name__)) diff --git a/docs_src/migrations/migrations.py b/docs_src/migrations/migrations.py index 1e22b8b9..3c035cd8 100644 --- a/docs_src/migrations/migrations.py +++ b/docs_src/migrations/migrations.py @@ -5,7 +5,6 @@ from my_project.utils import get_db_connection -from edgy import Instance, monkay from esmerald import Esmerald, Include @@ -23,9 +22,12 @@ def build_path(): def get_application(): """ - This is optional. The function is only used for organisation purposes. + Encapsulate in methods can be useful for capsulating and delaying imports but is optional. """ + # first call build_path build_path() + # because edgy tries to load settings eagerly + registry = get_db_connection() app = registry.asgi( diff --git a/docs_src/migrations/starlette.py b/docs_src/migrations/starlette.py index 564f1ccc..cf7c57f2 100644 --- a/docs_src/migrations/starlette.py +++ b/docs_src/migrations/starlette.py @@ -6,8 +6,6 @@ from starlette.applications import Starlette from my_project.utils import get_db_connection -from edgy import monkay, Instance - def build_path(): """ @@ -23,10 +21,12 @@ def build_path(): def get_application(): """ - This is optional. The function is only used for organisation purposes. + Encapsulate in methods can be useful for capsulating and delaying imports but is optional. """ + # first call build_path build_path() - registry = get_db_connection() + # because edgy tries to load settings eagerly + from edgy import monkay, Instance app = registry.asgi(Starlette()) diff --git a/docs_src/tips/connection.py b/docs_src/tips/connection.py index d1f72552..64459330 100644 --- a/docs_src/tips/connection.py +++ b/docs_src/tips/connection.py @@ -26,9 +26,14 @@ def disable_edgy_settings_load(): def get_application(): + """ + Encapsulate in methods can be useful for capsulating and delaying imports but is optional. + """ + # first call build_path build_path() # this is optional, for rewiring edgy settings to esmerald settings disable_edgy_settings_load() # disable any settings load + # import edgy now from edgy import Instance, monkay from esmerald.conf import settings diff --git a/docs_src/tips/migrations.py b/docs_src/tips/migrations.py index 0f9cc779..eb6c6b11 100644 --- a/docs_src/tips/migrations.py +++ b/docs_src/tips/migrations.py @@ -7,7 +7,6 @@ import sys from esmerald import Esmerald, Include -from edgy import Instance, monkay from my_project.utils import get_db_connection @@ -25,9 +24,13 @@ def build_path(): def get_application(): """ - This is optional. The function is only used for organisation purposes. + Encapsulate in methods can be useful for capsulating and delaying imports but is optional. """ + # first call build_path build_path() + # because edgy tries to load settings eagerly + from edgy import monkay, Instance + registry = get_db_connection() app = registry.asgi( diff --git a/docs_src/tips/sandwich_main.py b/docs_src/tips/sandwich_main.py index b816fadb..25bf4780 100644 --- a/docs_src/tips/sandwich_main.py +++ b/docs_src/tips/sandwich_main.py @@ -1,16 +1,35 @@ from importlib import import_module -import edgy from esmerald import Esmerald +def build_path(): + """ + Builds the path of the project and project root. + """ + Path(__file__).resolve().parent.parent + SITE_ROOT = os.path.dirname(os.path.realpath(__file__)) + + if SITE_ROOT not in sys.path: + sys.path.append(SITE_ROOT) + sys.path.append(os.path.join(SITE_ROOT, "apps")) + + def setup(): # do preparations ... def get_application(): + """ + Encapsulate in methods can be useful for capsulating and delaying imports but is optional. + """ + build_path() setup() + + # import now edgy when the path is set + import edgy + registry = edgy.Registry(url=...) # extensions shouldn't be applied yet edgy.monkay.set_instance(edgy.Instance(registry=registry), apply_extensions=False)