diff --git a/docs/references/esmerald.md b/docs/references/esmerald.md index e69de29b..b1e613bb 100644 --- a/docs/references/esmerald.md +++ b/docs/references/esmerald.md @@ -0,0 +1,21 @@ +# **`Esmerald`** class + +This is the reference for the main object `Esmerald` that contains all the parameters, +attributes and functions. + +## How to import + +```python +from esmerald import Esmerald +``` + +::: esmerald.Esmerald + options: + members: + - load_settings_value + + +::: esmerald.ChildEsmerald + options: + members: + - load_settings_value diff --git a/esmerald/applications.py b/esmerald/applications.py index cb9b2dc4..23fe57fa 100644 --- a/esmerald/applications.py +++ b/esmerald/applications.py @@ -20,6 +20,7 @@ from starlette.applications import Starlette from starlette.middleware import Middleware as StarletteMiddleware # noqa from starlette.types import Lifespan, Receive, Scope, Send +from typing_extensions import Annotated, Doc from esmerald.conf import settings as esmerald_settings from esmerald.conf.global_settings import EsmeraldAPISettings @@ -71,7 +72,22 @@ class Esmerald(Starlette): """ - Creates a Esmerald application instance. + `Esmerald` application object. The main entry-point for any application/API + with Esmerald. + + This object is complex and very powerful. Read more in detail about [how to start](https://esmerald.dev/esmerald/) and spin-up an application in minutes. + + !!! Tip + All the parameters available in the object have defaults being loaded by the + [settings system](https://esmerald.dev/application/settings/) if nothing is provided. + + ## Example + + ```python + from esmerald import Esmerald. + + app = Esmerald() + ``` """ __slots__ = ( @@ -123,7 +139,29 @@ class Esmerald(Starlette): def __init__( self: AppType, *, - settings_config: Optional["SettingsType"] = None, + settings_config: Annotated[ + Optional["SettingsType"], + Doc( + """ + Alternative settings parameter. This parameter is an alternative to + `ESMERALD_SETTINGS_MODULE` way of loading your settings into an Esmerald application. + + When the `settings_module` is provided, it will make sure it takes priority over + any other settings provided for the instance. + + Read more about the [settings module](https://esmerald.dev/application/settings/) + and how you can leverage it in your application. + + !!! Tip + The settings module can be very useful if you want to have, for example, a + [ChildEsmerald](https://esmerald.dev/routing/router/?h=childe#child-esmerald-application) that needs completely different settings + from the main app. + + Example: A `ChildEsmerald` that takes care of the authentication into a cloud + provider such as AWS and handles the `boto3` module. + """ + ), + ] = None, debug: Optional[bool] = None, app_name: Optional[str] = None, title: Optional[str] = None, @@ -916,8 +954,25 @@ def add_event_handler(self, event_type: str, func: Callable) -> None: # pragma: class ChildEsmerald(Esmerald): """ - A simple visual representation of an Esmerald application, exactly like Esmerald - but for organisation purposes it might be preferred to use this class. + `ChildEsmerald` application object. The main entry-point for a modular application/API + with Esmerald. + + The `ChildEsmerald` inherits directly from the `Esmerald` object which means all the same + parameters, attributes and functions of Esmerald ara also available in the `ChildEsmerald`. + + This object is complex and very powerful. Read more in detail about [how to use](https://esmerald.dev/routing/router/?h=childe#child-esmerald-application) and spin-up an application in minutes with `ChildEsmerald`. + + !!! Tip + All the parameters available in the object have defaults being loaded by the + [settings system](https://esmerald.dev/application/settings/) if nothing is provided. + + ## Example + + ```python + from esmerald import Esmerald, ChildEsmerald, Include + + app = Esmerald(routes=[Include('/child', app=ChildEsmerald(...))]) + ``` """ ... diff --git a/esmerald/core/urls/base.py b/esmerald/core/urls/base.py index ae9572ca..1fdb5b79 100644 --- a/esmerald/core/urls/base.py +++ b/esmerald/core/urls/base.py @@ -59,12 +59,6 @@ def include( router_patterns = [ Router(path='/', routes=[include('myapp.routes', pattern='myapp_urls')]) ] - - - Args: - namespace (Any): Example: 'mymodule.urls' - pattern (Optional[str], optional): The name of the list to be read from the - module. Defaults to `router_patterns`. """ if not isinstance(arg, str): raise ImproperlyConfigured("The value should be a string with the format .") diff --git a/esmerald/middleware/settings_middleware.py b/esmerald/middleware/settings_middleware.py index 14641319..0549b7bc 100644 --- a/esmerald/middleware/settings_middleware.py +++ b/esmerald/middleware/settings_middleware.py @@ -9,7 +9,6 @@ def __init__(self, app: "ASGIApp"): Args: app: The 'next' ASGI app to call. - settings: An instance of a EsmeraldAPISettings or a subclass. """ super().__init__(app) self.app = app diff --git a/pyproject.toml b/pyproject.toml index 2ea23ef2..362e6156 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -135,6 +135,7 @@ dev = [ ] doc = [ + "griffe-typingdoc>=0.2.2", "mkautodoc>=0.2.0,<0.3.0", "mkdocs>=1.1.2,<2.0.0", "mkdocs-material>=9.4.4,<10.0.0",