Pluggables¶
What are pluggables in an Esmerald context? A separate and individual piece of software that can be hooked into any Esmerald application and perform specific actions individually without breaking the ecosystem.
A feature that got a lof of inspirations from the great frameworks out there but simplified for the Esmerald ecosystem.
Take Django as example. There are hundreds, if not thousands, of plugins for Django and usually,
not always, the way of using them is by adding that same pluggin into the INSTALLED_APPS
and
go from there.
Flask on the other hand has a pattern of having those plugin objects with an init_app
function.
Well, what if we could have the best of both? Esmerald as you
are aware is extremely flexible and dynamic in design and therefore having an INSTALLED_APPS
wouldn't make too much sense right?
Also, how could we create this pattern, like Flask, to have an init_app
and allow the application
to do the rest for you? Well, Esmerald now does that via its internal protocols and interfaces.
In Esmerald world, this is called pluggable.
Note
Pluggables only exist on an application level.
Pluggable¶
This object is one of a kind and does a lot of magic for you when creating a pluggble for your application or even for distribution.
A pluggable is an object that receives an Extension class with parameters and hooks them into your Esmerald application and executes the extend method when starting the system.
from typing import Optional
from loguru import logger
from pydantic import BaseModel
from esmerald import Esmerald, Extension, Pluggable
from esmerald.types import DictAny
class PluggableConfig(BaseModel):
name: str
class MyExtension(Extension):
def __init__(
self, app: Optional["Esmerald"] = None, config: PluggableConfig = None, **kwargs: "DictAny"
):
super().__init__(app, **kwargs)
self.app = app
def extend(self, config: PluggableConfig) -> None:
logger.success(f"Successfully passed a config {config.name}")
my_config = PluggableConfig(name="my extension")
pluggable = Pluggable(MyExtension, config=my_config)
app = Esmerald(routes=[], pluggables={"my-extension": pluggable})
It is this simple but is it the only way to add a pluggable into the system? Short answser is no.
More details about this in hooking a pluggable into the application.
Danger
If another object but the Extension is provided to the Pluggable, it will
raise an ImproperlyConfigured
. Pluggables are always expecting an Extension to be provided.
Extension¶
This is the main class that should be extended when creating a pluggable for Esmerald.
This object internally uses the protocols to make sure you follow the patterns needed to hook
a pluggable via pluggables
parameter when instantiating an esmerald application.
When subclassing this object you must implement the extend function. This function is what Esmerald looks for when looking up for pluggables for your application and executes the logic.
Think of the extend
as the init_app
of Flask but enforced as a pattern for Esmerald.
from typing import Optional
from esmerald import Esmerald, Extension
from esmerald.types import DictAny
class MyExtension(Extension):
def __init__(self, app: Optional["Esmerald"] = None, **kwargs: "DictAny"):
super().__init__(app, **kwargs)
self.app = app
self.kwargs = kwargs
def extend(self, **kwargs: "DictAny") -> None:
"""
Function that should always be implemented when extending
the Extension class or a `NotImplementedError` is raised.
"""
# Do something here
extend()¶
The mandatory function that must be implemented when creating an extension to be plugged via Pluggable into Esmerald.
It is the entry-point for your extension.
The extend by default expects kwargs
to be provided but you can pass your own default parameters
as well as there are many ways of creating and [hooking a pluggable]
Hooking pluggables¶
As mentioned before, there are different ways of hooking a pluggable into your Esmerald application.
The automated and default way¶
When using the default and automated way, Esmerald expects the pluggable to be passed into a dict
pluggables
upon instantiation of an Esmerald application with key-pair
value entries and where
the key
is the name for your pluggable and the value
is an instance Pluggable
holding your Extension object.
When added in this way, Esmerald internally hooks your pluggable into the application and starts it by calling the extend with the provided parameters, automatically.
The app
parameter is automatically injected by Esmerald and does not need to be passed as
parameter if needed
from typing import Optional
from loguru import logger
from pydantic import BaseModel
from esmerald import Esmerald, Extension, Pluggable
from esmerald.types import DictAny
class PluggableConfig(BaseModel):
name: str
class MyExtension(Extension):
def __init__(
self, app: Optional["Esmerald"] = None, config: PluggableConfig = None, **kwargs: "DictAny"
):
super().__init__(app, **kwargs)
self.app = app
def extend(self, config: PluggableConfig) -> None:
logger.success(f"Successfully passed a config {config.name}")
my_config = PluggableConfig(name="my extension")
pluggable = Pluggable(MyExtension, config=my_config)
app = Esmerald(routes=[], pluggables={"my-extension": pluggable})
You can access all the pluggables of your application via app.pluggables
at any given time.
The manual and independent way¶
Sometimes you simply don't want to start the pluggable inside an Esmerald instance automatically
and you simply want to start by yourself and on your own, very much in the way Flask does with
the init_app
.
This way you don't need to use the Pluggable object in any way and instead you can simply just use the Extension class or even your own since you are in control of the extension.
from typing import Optional
from loguru import logger
from esmerald import Esmerald, Extension, Gateway, JSONResponse, Request, get
from esmerald.types import DictAny
class MyExtension(Extension):
def __init__(self, app: Optional["Esmerald"] = None, **kwargs: "DictAny"):
super().__init__(app, **kwargs)
self.app = app
self.kwargs = kwargs
def extend(self, **kwargs: "DictAny") -> None:
"""
Function that should always be implemented when extending
the Extension class or a `NotImplementedError` is raised.
"""
# Do something here like print a log or whatever you need
logger.success("Started the extension manually")
# Add the extension to the pluggables of Esmerald
# And make it accessible
self.app.add_pluggable("my-extension", self)
@get("/home")
async def home(request: Request) -> JSONResponse:
"""
Returns a list of pluggables of the system.
"pluggables": ["my-extension"]
"""
pluggables = list(request.app.pluggables)
return JSONResponse({"pluggables": pluggables})
app = Esmerald(routes=[Gateway(handler=home)])
extension = MyExtension(app=app)
extension.extend()
Standalone object¶
But, what if I don't want to use the Extension object for my pluggable? Is this possible?
Short answer, yes, but this comes with limitations:
- You cannot hook the class within a Pluggable and use the automated way.
- You will always need to start it manually.
from typing import Optional
from loguru import logger
from esmerald import Esmerald, Gateway, JSONResponse, Request, get
from esmerald.types import DictAny
class Standalone:
def __init__(self, app: Optional["Esmerald"] = None, **kwargs: "DictAny"):
super().__init__(app, **kwargs)
self.app = app
self.kwargs = kwargs
def extend(self, **kwargs: "DictAny") -> None:
"""
Function that should always be implemented when extending
the Extension class or a `NotImplementedError` is raised.
"""
# Do something here like print a log or whatever you need
logger.success("Started the extension manually")
# Add the extension to the pluggables of Esmerald
# And make it accessible
self.app.add_pluggable("standalone", self)
@get("/home")
async def home(request: Request) -> JSONResponse:
"""
Returns a list of pluggables of the system.
"pluggables": ["standalone"]
"""
pluggables = list(request.app.pluggables)
return JSONResponse({"pluggables": pluggables})
app = Esmerald(routes=[Gateway(handler=home)])
extension = Standalone(app=app)
extension.extend()
Important notes¶
As you can see, pluggables in Esmerald can be a powerful tool that isolates common functionality from the main Esmerald application and can be used to leverage the creation of plugins to be used across your applications and/or to create opensource packages for any need.
ChildEsmerald and pluggables¶
A Pluggable is not the same as a ChildEsmerald.
These are two completely independent pieces of functionality with completely different purposes, be careful when considering one and the other.
Can a ChildEsmerald be added as a pluggable? Of course.
You can do whatever you want with a pluggable, that is the beauty of this system.
Let us see how it would look like if you had a pluggable where the goal was to add a ChildEsmerald into the current applications being plugged.
from typing import Optional
from loguru import logger
from esmerald import ChildEsmerald, Esmerald, Extension, Gateway, JSONResponse, Pluggable, get
from esmerald.types import DictAny
@get("/home")
async def home() -> JSONResponse:
return JSONResponse({"detail": "Welcome"})
class ChildEsmeraldPluggable(Extension):
def __init__(self, app: Optional["Esmerald"] = None, **kwargs: "DictAny"):
super().__init__(app, **kwargs)
self.app = app
self.kwargs = kwargs
def extend(self, **kwargs: "DictAny") -> None:
"""
Add a child Esmerald into the main application.
"""
# Do something here like print a log or whatever you need
logger.info("Adding the ChildEsmerald via pluggable...")
child = ChildEsmerald(routes=[Gateway(handler=home, name="child-esmerald-home")])
self.app.add_child_esmerald(path="/pluggable", child=child)
logger.success("Added the ChildEsmerald via pluggable.")
app = Esmerald(routes=[], pluggables={"child-esmerald": Pluggable(ChildEsmeraldPluggable)})
Crazy dynamic, isn't it? So clean and so simple that you can do whatever you desire with Esmerald.
Pluggables and the application settings¶
Like almost everything in Esmerald, you can also add the Pluggables via settings instead of adding when you instantiate the application.
from typing import Dict, Optional
from loguru import logger
from pydantic import BaseModel
from esmerald import Esmerald, EsmeraldAPISettings, Extension, Pluggable
from esmerald.types import DictAny
class PluggableConfig(BaseModel):
name: str
my_config = PluggableConfig(name="my extension")
class MyExtension(Extension):
def __init__(
self, app: Optional["Esmerald"] = None, config: PluggableConfig = None, **kwargs: "DictAny"
):
super().__init__(app, **kwargs)
self.app = app
def extend(self, config: PluggableConfig) -> None:
logger.success(f"Successfully passed a config {config.name}")
class AppSettings(EsmeraldAPISettings):
@property
def pluggables(self) -> Dict[str, "Pluggable"]:
return {"my-extension": Pluggable(MyExtension, config=my_config)}
app = Esmerald(routes=[])
And simply start the application.
ESMERALD_SETTINGS_MODULE=AppSettings uvicorn src:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for application startup.
INFO: Application startup complete.
$env:ESMERALD_SETTINGS_MODULE="AppSettings"; uvicorn src:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for application startup.
INFO: Application startup complete.
If you prefer, you can also use the settings_module.
from typing import Dict, Optional
from loguru import logger
from pydantic import BaseModel
from esmerald import Esmerald, EsmeraldAPISettings, Extension, Pluggable
from esmerald.types import DictAny
class PluggableConfig(BaseModel):
name: str
my_config = PluggableConfig(name="my extension")
class MyExtension(Extension):
def __init__(
self, app: Optional["Esmerald"] = None, config: PluggableConfig = None, **kwargs: "DictAny"
):
super().__init__(app, **kwargs)
self.app = app
def extend(self, config: PluggableConfig) -> None:
logger.success(f"Successfully passed a config {config.name}")
class AppSettings(EsmeraldAPISettings):
@property
def pluggables(self) -> Dict[str, "Pluggable"]:
return {"my-extension": Pluggable(MyExtension, config=my_config)}
app = Esmerald(routes=[], settings_module=AppSettings)