update docs, fix highlights

docs/migrations/migrations.md

@@ -119,7 +119,7 @@ Assuming you have a `utils.py` where you place your information about the databa
 
 Something like this:
 
-```python title="my_project/utils.py" hl_lines="6-9"
+```python title="my_project/utils.py" hl_lines="4-9"
 {!> ../docs_src/migrations/lru.py !}
 ```
 
@@ -130,7 +130,7 @@ Now that we have our details about the database and registry, it is time to use
 
 #### Using Esmerald
 
-```python title="my_project/main.py" hl_lines="9 12 32 38"
+```python title="my_project/main.py" hl_lines="6 36-40 42"
 {!> ../docs_src/migrations/migrations.py !}
 ```
 
@@ -139,15 +139,15 @@ Now that we have our details about the database and registry, it is time to use
 As mentioned before, Edgy is framework agnostic so you can also use it in your FastAPI
 application.
 
-```python title="my_project/main.py" hl_lines="6 9 29 33"
+```python title="my_project/main.py" hl_lines="6 36 38"
 {!> ../docs_src/migrations/fastapi.py !}
 ```
 
 #### Using Starlette
 
 The same goes for Starlette.
 
-```python title="my_project/main.py" hl_lines="6 9 29 33"
+```python title="my_project/main.py" hl_lines="6 35 37"
 {!> ../docs_src/migrations/starlette.py !}
 ```
 

docs/release-notes.md

@@ -13,7 +13,6 @@ hide:
 
 - Try harder to avoid circular imports when providing settings with edgy references.
 
-
 ## 0.24.1
 
 ### Fixed

docs/tips-and-tricks.md

@@ -21,7 +21,7 @@ it comes with a simple and easy way of accesing the settings anywhere in the cod
 
 Something simple like this:
 
-```python hl_lines="18-25"
+```python hl_lines="20-28"
 {!> ../docs_src/tips/settings.py !}
 ```
 
@@ -55,7 +55,7 @@ codebase and making sure you **do not generate** extra objects and this is exact
 Use the example above, let us now create a new file called `utils.py` where we will be applying
 the `lru_cache` technique for our `db_connection`.
 
-```python title="utils.py" hl_lines="6"
+```python title="utils.py"
 {!> ../docs_src/tips/lru.py !}
 ```
 
@@ -143,15 +143,15 @@ This structure is generated by using the
 As mentioned before we will have a settings file with database connection properties assembled.
 We have also `edgy_settings` defined (any name is possible). It will be used for the central configuration management
 
-```python title="my_project/configs/settings.py" hl_lines="19-20"
+```python title="my_project/configs/settings.py" hl_lines="20-28 30-35"
 {!> ../docs_src/tips/settings.py !}
 ```
 
 ### The utils
 
 Now we create the `utils.py` where we appy the [LRU](#the-lru-cache) technique.
 
-```python title="myproject/utils.py" hl_lines="6"
+```python title="myproject/utils.py"
 {!> ../docs_src/tips/lru.py !}
 ```
 
@@ -179,7 +179,7 @@ Now it is time to tell the application that your models and migrations are manag
 More information on [migrations](./migrations/migrations.md) where explains how to use it.
 
 
-```python title="myproject/main.py" hl_lines="10 31 33-37 39"
+```python title="myproject/main.py" hl_lines="10 32 38-42 44"
 {!> ../docs_src/tips/migrations.py !}
 ```
 
@@ -192,7 +192,7 @@ application. We use an approach for the central management of configuration via
 provide a settings forwarder.
 You can also remove the settings forward and manage edgy settings via environment variable too.
 
-```python title="myproject/main.py" hl_lines="12 24 34-39 52"
+```python title="myproject/main.py" hl_lines="32-38 40 48-52 54"
 {!> ../docs_src/tips/connection.py !}
 ```
 

docs_src/commands/discover.py

@@ -21,7 +21,7 @@ def build_path():
 
 def get_application():
     """
-    Encapsulate in methods can be useful for capsulating and delaying imports but is optional.
+    Encapsulating in methods can be useful for controlling the import order but is optional.
     """
     from edgy import Instance, monkay
 

docs_src/migrations/fastapi.py

@@ -21,7 +21,7 @@ def build_path():
 
 def get_application():
     """
-    Encapsulate in methods can be useful for capsulating and delaying imports but is optional.
+    Encapsulating in methods can be useful for controlling the import order but is optional.
     """
     # first call build_path
     build_path()
@@ -30,6 +30,9 @@ def get_application():
 
     registry = get_db_connection()
 
+    # ensure the settings are loaded
+    monkay.evaluate_settings_once(ignore_import_errors=False)
+
     app = registry.asgi(FastAPI(__name__))
 
     monkay.set_instance(Instance(registry=registry, app=app))

docs_src/migrations/lru.py

@@ -1,10 +1,9 @@
 from functools import lru_cache
 
-from edgy import Database, Registry
-
 
 @lru_cache()
 def get_db_connection():
-    # use echo=True for getting the connection infos printed
-    database = Database("postgresql+asyncpg://user:pass@localhost:5432/my_database", echo=True)
-    return Registry(database=database)
+    from edgy import Registry
+
+    # use echo=True for getting the connection infos printed, extra kwargs are passed to main database
+    return Registry("postgresql+asyncpg://user:pass@localhost:5432/my_database", echo=True)

docs_src/migrations/migrations.py

@@ -3,9 +3,8 @@
 import sys
 from pathlib import Path
 
-from my_project.utils import get_db_connection
-
 from esmerald import Esmerald, Include
+from my_project.utils import get_db_connection
 
 
 def build_path():
@@ -22,14 +21,18 @@ def build_path():
 
 def get_application():
     """
-    Encapsulate in methods can be useful for capsulating and delaying imports but is optional.
+    Encapsulating in methods can be useful for controlling the import order 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()
 
+    # ensure the settings are loaded
+    monkay.evaluate_settings_once(ignore_import_errors=False)
+
     app = registry.asgi(
         Esmerald(
             routes=[Include(namespace="my_project.urls")],

docs_src/migrations/starlette.py

@@ -21,16 +21,20 @@ def build_path():
 
 def get_application():
     """
-    Encapsulate in methods can be useful for capsulating and delaying imports but is optional.
+    Encapsulating in methods can be useful for controlling the import order 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()
+    # ensure the settings are loaded
+    monkay.evaluate_settings_once(ignore_import_errors=False)
+
     app = registry.asgi(Starlette())
 
-    monkay.set_instance(Instance(app=app, registry=registry))
+    monkay.set_instance(Instance(registry=registry, app=app))
     return app
 
 

docs_src/tips/connection.py

@@ -27,7 +27,7 @@ def disable_edgy_settings_load():
 
 def get_application():
     """
-    Encapsulate in methods can be useful for capsulating and delaying imports but is optional.
+    Encapsulating in methods can be useful for controlling the import order but is optional.
     """
     # first call build_path
     build_path()
@@ -38,7 +38,7 @@ def get_application():
     from esmerald.conf import settings
 
     monkay.settings = lambda: settings.edgy_settings  # rewire
-    monkay.evaluate_settings_once(ignore_import_errors=False)
+    monkay.evaluate_settings_once(ignore_import_errors=False)  # import manually
 
     # now the project is in the search path and we can import
     from my_project.utils import get_db_connection

docs_src/tips/lru.py

@@ -1,23 +1,9 @@
-import sys
-import os
 from functools import lru_cache
 
 
-# we need this also here because we access settings and must be sure the import path is importable
-def build_path():
-    """
-    Builds the path of the project and project root.
-    """
-    SITE_ROOT = os.path.dirname(os.path.realpath(__file__))
-
-    if SITE_ROOT not in sys.path:
-        sys.path.append(SITE_ROOT)
-        # in case of apps
-        sys.path.append(os.path.join(SITE_ROOT, "apps"))
-
-
 @lru_cache()
 def get_db_connection():
+    # Encapsulate to delay the import
     from esmerald.conf import settings
 
     return settings.db_connection

docs_src/tips/migrations.py

@@ -24,14 +24,16 @@ def build_path():
 
 def get_application():
     """
-    Encapsulate in methods can be useful for capsulating and delaying imports but is optional.
+    Encapsulating in methods can be useful for controlling the import order 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()
+    # ensure the settings are loaded
+    monkay.evaluate_settings_once(ignore_import_errors=False)
 
     app = registry.asgi(
         Esmerald(

docs_src/tips/sandwich_main.py

@@ -15,26 +15,20 @@ def build_path():
         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.
+    Encapsulating in methods can be useful for controlling the import order 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)
-    # post loads
-    import_module("myproject.models")
+    # load extensions and preloads
+    # not evaluate_settings_once because maybe some preloads weren't resolved
+    monkay.evaluate_settings(on_conflict="keep")
     app = Esmerald()
     # now apply the extensions
     edgy.monkay.set_instance(edgy.Instance(registry=registry, app=app))