Skip to main content

The needed admin for Saffier ORM with Esmerald

Project description

Esmerald Admin

Esmerald

The needed admin for Saffier ORM with Esmerald.

Test Suite Package version Supported Python versions


Documentation: https://esmerald-admin.tarsild.io 📚

Source Code: https://github.com/tarsil/esmerald-admin


Esmerald admin for Saffier ORM

Esmerald admin is a flexible user interface for Saffier ORM 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 ORM 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.

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
  • Modern UI using Tabler

Installation

$ pip install esmerald-admin

Quickstart

Saffier is a very powerfull ORM 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 Saffier unique since you can use the declarative models for the admin and the core models for anything else.

See the declarative models for more details on this.

Let us create a some Saffier models first. This example assumes you use the [contrib user][https://esmerald.dev/databases/saffier/models/] 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()

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 esmerald import Esmerald
from esmerald_admin import Admin, ModelView

app = Esmerald()
admin = Admin(app, 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".

Settings

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

Models

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"""
    ...

Admin

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)

Application

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! ⭐️

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

esmerald_admin-0.1.0.tar.gz (8.1 kB view details)

Uploaded Source

Built Distribution

esmerald_admin-0.1.0-py3-none-any.whl (10.0 kB view details)

Uploaded Python 3

File details

Details for the file esmerald_admin-0.1.0.tar.gz.

File metadata

  • Download URL: esmerald_admin-0.1.0.tar.gz
  • Upload date:
  • Size: 8.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.8.17

File hashes

Hashes for esmerald_admin-0.1.0.tar.gz
Algorithm Hash digest
SHA256 59c1977815c33bc84357e38d1d3bc752e8d2b5e02fafc65e596aac5e386bc549
MD5 5a97b90ae2ad7136fda57b1cb4a58707
BLAKE2b-256 6984c099a96714f9606217e0f09f49784e6adde4fc9c8c789e179a4f4ace861b

See more details on using hashes here.

File details

Details for the file esmerald_admin-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: esmerald_admin-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 10.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.8.17

File hashes

Hashes for esmerald_admin-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 dfa5c4d79081e547cf911e292b0a1a25014fdd1abbded227c3e2bad81df50f89
MD5 68c43f1f1c61412e8ddc94f72327f4f3
BLAKE2b-256 f77be1cd04120891494e12f4cb6691f19cb18d528e8ed6dae7e5b5d60692308a

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page