improve documentation

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
 

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()
 

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__))

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(

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())
 

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
 

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(

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)