Esmerald Admin¶
The needed admin for Saffier and Edgy with Esmerald.
Documentation: https://esmerald-admin.tarsild.io 📚
Source Code: https://github.com/tarsil/esmerald-admin
Esmerald admin for Saffier and Edgy¶
Esmerald admin is a flexible user interface for Saffier ORM and Edgy built on the top of the already existing and highly maintained SQLAdmin.
The main goal, as the name of the package says, is to provide a nice, flexible and easy to use user interface that interacts with Saffier and Edgy in a more friendly manner.
Saffier¶
Saffier is a flexible and powerfull ORM built on the top of SQLAlchemy core that allows you to interact with almost every single SQL database out there in an asynchronous mode.
Edgy¶
Edgy is also an extremely, flexible and powerful ORM built on the top of SQLAlchemy core and 100% Pydantic with more flexibility for every single use case, also in asynchronous mode.
Documentation¶
Majority of the documentation for this package can and should be seen in the SQLAdmin official documentation (don't forget to leave a star on that repository) as the core remains exactly the same.
The custom, unique, Esmerald way is placed here within these docs.
Main features include:
- SQLAlchemy sync/async engines
- Esmerald integration
- Saffier support
- Edgy support
- Modern UI using Tabler
Installation¶
For Saffier
$ pip install esmerald-admin[saffier]
For Edgy
$ pip install esmerald-admin[edgy]
For both
$ pip install esmerald-admin[all]
Quickstart¶
Saffier and Edgy are very powerfull ORMs as mentioned before and built on the top of SQLAlchemy core but
also extremely flexible allowing to use the models in a declarative
way, which is the way
SQLAdmin is expecting to use.
This makes both Saffier and Edgy unique since you can use the declarative models for the admin and the core models for anything else.
See the Saffier declarative models and Edgy declarative models for more details.
Let us create a some models first. This example assumes you use the contrib user of Saffier and the contrib user of Edgy from Esmerald.
Warning
Using the user provided by Esmerald is not mandatory and you can use your own design. The documentation uses the one provided by Esmerald as it is easier to explain and use.
import saffier
from esmerald.contrib.auth.saffier.base_user import AbstractUser
from saffier import Database, Registry
database = Database("sqlite:///db.sqlite")
registry = Registry(database=database)
class BaseModel(saffier.Model):
class Meta:
abstract = True
registry = registry
class User(BaseModel, AbstractUser):
"""Inherits from the user base"""
...
# Create the tables
await registry.create_all()
import edgy
from edgy import Database, Registry
from esmerald.contrib.auth.edgy.base_user import AbstractUser
database = Database("sqlite:///db.sqlite")
registry = Registry(database=database)
class BaseModel(edgy.Model):
class Meta:
abstract = True
registry = registry
class User(BaseModel, AbstractUser):
"""Inherits from the user base"""
...
# Create the tables
await registry.create_all()
Now using with Esmerald
Saffier, as mentioned before, has the declarative models ready to be used. These models are only used for the admin.
from accounts.models import User
from esmerald import Esmerald, settings
from esmerald_admin import Admin, ModelView
database, registry = settings.db_access
app = Esmerald()
admin = Admin(app, registry.engine)
# Declarative User
DeclarativeUser = User.declarative()
class UserAdmin(ModelView, model=DeclarativeUser):
column_list = [DeclarativeUser.id, DeclarativeUser.email]
admin.add_view(UserAdmin)
Or if you want some more "organised".
from functools import cached_property
from typing import Optional
from esmerald.conf.enums import EnvironmentType
from esmerald.conf.global_settings import EsmeraldAPISettings
from saffier import Database, Registry
class AppSettings(EsmeraldAPISettings):
app_name: str = "My application in production mode."
title: str = "My app"
environment: Optional[str] = EnvironmentType.PRODUCTION
secret_key: str = "esmerald-insecure-key"
@cached_property
def db_access(self):
database = Database("sqlite:///db.sqlite")
registry = Registry(database=database)
return database, registry
import saffier
from esmerald.conf import settings
from esmerald.contrib.auth.saffier.base_user import AbstractUser
database, models = settings.db_access
class BaseModel(saffier.Model):
class Meta:
abstract = True
registry = models
class User(BaseModel, AbstractUser):
"""Inherits from the user base"""
...
import edgy
from esmerald.conf import settings
from esmerald.contrib.auth.edgy.base_user import AbstractUser
database, models = settings.db_access
class BaseModel(edgy.Model):
class Meta:
abstract = True
registry = models
class User(BaseModel, AbstractUser):
"""Inherits from the user base"""
...
from accounts.models import User as UserModel
from esmerald_admin import Admin, ModelView
# Declarative Models
User = UserModel.declarative()
class UserAdmin(ModelView, model=User):
column_list = [User.id, User.username, User.email, User.first_name, User.last_name]
def get_views(admin: Admin) -> None:
"""Generates the admin views"""
admin.add_model_view(UserAdmin)
import os
import sys
from pathlib import Path
from esmerald import Esmerald, Include, settings
from esmerald_admin import Admin
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 get_admin(app, registry):
"""Starts the saffier admin"""
from .admin import get_views
admin = Admin(app, registry.engine)
# Get the views function from the "admin.py"
get_views(admin)
def get_application():
"""
This is optional. The function is only used for organisation purposes.
"""
build_path()
# Registry that comes from the "settings.py"
# This is Saffier related and centralised in the settings
# file, as per Esmerald design
database, registry = settings.db_access
app = Esmerald(
routes=[Include(namespace="linezap.urls")],
on_startup=[database.connect],
on_shutdown=[database.disconnect],
)
# Admin
get_admin(app, registry)
return app
app = get_application()
Now visiting /admin/
(with slash at the end) on your browser you can see the Esmerald admin interface.
Important¶
As mentioned before, Esmerald admin is built on the top of SQLAdmin. Besides some unique features for Esmerald with Saffier that are documented here, everything else should be checked in the SQLAdmin official documentation as it works exactly the same.
Massive thanks to @aminalaee to get this working so well and without his work, this would not be possible! ⭐️ Star his repo! ⭐️