| Name | esmerald-admin JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | |
| Summary | The needed admin for Saffier ORM with Esmerald |
| upload_time | 2023-10-17 14:01:06 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
esmerald_admin
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Esmerald Admin
<p align="center">
<a href="https://esmerald-admin.tarsild.io"><img src="https://res.cloudinary.com/dymmond/image/upload/v1673619342/esmerald/img/logo-gr_z1ot8o.png" alt='Esmerald'></a>
</p>
<p align="center">
<em>The needed admin for Saffier and Edgy with Esmerald.</em>
</p>
<p align="center">
<a href="https://github.com/tarsil/esmerald-admin/workflows/Test%20Suite/badge.svg?event=push&branch=main" target="_blank">
<img src="https://github.com/tarsil/esmerald-admin/workflows/Test%20Suite/badge.svg?event=push&branch=main" alt="Test Suite">
</a>
<a href="https://pypi.org/project/esmerald_admin" target="_blank">
<img src="https://img.shields.io/pypi/v/esmerald_admin?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
<a href="https://pypi.org/project/esmerald_admin" target="_blank">
<img src="https://img.shields.io/pypi/pyversions/esmerald_admin.svg?color=%2334D058" alt="Supported Python versions">
</a>
</p>
---
**Documentation**: [https://esmerald-admin.tarsild.io][esmerald_admin] 📚
**Source Code**: [https://github.com/tarsil/esmerald-admin][esmerald_repo]
---
## Esmerald admin for [Saffier][saffier] and [Edgy][edgy]
Esmerald admin is a flexible user interface for [Saffier ORM][saffier] and [Edgy][edgy]
built on the top of the already existing and highly maintained [SQLAdmin][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][saffier] and [Edgy][edgy] in a more friendly manner.
## Saffier
[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][saffier] 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][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][saffier] support
* [Edgy][edgy] support
* Modern UI using Tabler
## Installation
**For Saffier**
```shell
$ pip install esmerald-admin[saffier]
```
**For Edgy**
```shell
$ pip install esmerald-admin[edgy]
```
**For both**
```shell
$ 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][saffier_declarative] and [Edgy declarative models][edgy_declarative] for more details.
Let us create a some models first. This example assumes you use the [contrib user of Saffier](https://esmerald.dev/databases/saffier/models/)
and the [contrib user of Edgy](https://esmerald.dev/databases/edgy/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.
**Saffier**
```python
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()
```
**Edgy**
```python
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][saffier_declarative] ready to be used.
These models are **only used for the admin**.
```python
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".
**Settings**
```python title="myproject/configs/settings.py"
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 # or from edgy 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
```
**Saffier Models**
```python title="myproject/apps/accounts/models.py"
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"""
```
**Edgy Models**
```python title="myproject/apps/accounts/models.py"
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"""
```
**Admin**
```python title="myproject/admin.py"
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 and it is used in
the `main.py` file.
"""
admin.add_model_view(UserAdmin)
```
**Application**
```python title="myproject/app.py"
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)
```
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][esmerald_admin]. Besides some
unique features for Esmerald with Saffier that are documented here, **everything else should be checked**
**in the [SQLAdmin][sqladmin] official documentation** as it works exactly the same.
Massive thanks to [@aminalaee](https://github.com/aminalaee) to get this working so well and without his work, this
would not be possible! ⭐️ Star his repo! ⭐️
[esmerald_admin]: https://esmerald-admin.tarsild.io
[esmerald_repo]: https://github.com/tarsil/esmerald-admin
[saffier]: https://saffier.tarsild.io
[edgy]: https://edgy.tarsild.io
[sqladmin]: https://aminalaee.dev/sqladmin/
[saffier_declarative]: https://saffier.tarsild.io/models/#declarative-models
[edgy_declarative]: https://edgy.tarsild.io/models/#declarative-models
Raw data
{
"_id": null,
"home_page": "",
"name": "esmerald-admin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "esmerald_admin",
"author": "",
"author_email": "Tiago Silva <tiago.arasilva@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/de/c9/de82619e49838d667df70d73e98a187ce872be91aa691138d2e194e9bd9a/esmerald_admin-0.4.0.tar.gz",
"platform": null,
"description": "# Esmerald Admin\n\n<p align=\"center\">\n <a href=\"https://esmerald-admin.tarsild.io\"><img src=\"https://res.cloudinary.com/dymmond/image/upload/v1673619342/esmerald/img/logo-gr_z1ot8o.png\" alt='Esmerald'></a>\n</p>\n\n<p align=\"center\">\n <em>The needed admin for Saffier and Edgy with Esmerald.</em>\n</p>\n\n<p align=\"center\">\n<a href=\"https://github.com/tarsil/esmerald-admin/workflows/Test%20Suite/badge.svg?event=push&branch=main\" target=\"_blank\">\n <img src=\"https://github.com/tarsil/esmerald-admin/workflows/Test%20Suite/badge.svg?event=push&branch=main\" alt=\"Test Suite\">\n</a>\n\n<a href=\"https://pypi.org/project/esmerald_admin\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/esmerald_admin?color=%2334D058&label=pypi%20package\" alt=\"Package version\">\n</a>\n\n<a href=\"https://pypi.org/project/esmerald_admin\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/pyversions/esmerald_admin.svg?color=%2334D058\" alt=\"Supported Python versions\">\n</a>\n</p>\n\n---\n\n**Documentation**: [https://esmerald-admin.tarsild.io][esmerald_admin] \ud83d\udcda\n\n**Source Code**: [https://github.com/tarsil/esmerald-admin][esmerald_repo]\n\n---\n\n## Esmerald admin for [Saffier][saffier] and [Edgy][edgy]\n\nEsmerald admin is a flexible user interface for [Saffier ORM][saffier] and [Edgy][edgy]\nbuilt on the top of the already existing and highly maintained [SQLAdmin][sqladmin].\n\nThe main goal, as the name of the package says, is to provide a nice, flexible and easy to use\nuser interface that interacts with [Saffier][saffier] and [Edgy][edgy] in a more friendly manner.\n\n## Saffier\n\n[Saffier][saffier] is a flexible and powerfull ORM built on the top of SQLAlchemy core that allows\nyou to interact with almost every single SQL database out there in an asynchronous mode.\n\n## Edgy\n\n[Edgy][saffier] is also an extremely, flexible and powerful ORM built on the top of SQLAlchemy core\nand **100% Pydantic** with more flexibility for every single use case, also in asynchronous mode.\n\n### Documentation\n\nMajority of the documentation for this package **can and should** be seen in the [SQLAdmin][sqladmin]\nofficial documentation (don't forget to leave a star on that repository) as the core remains exactly\nthe same.\n\nThe custom, unique, Esmerald way is placed here within these docs.\n\n**Main features include:**\n\n* SQLAlchemy sync/async engines\n* Esmerald integration\n* [Saffier][saffier] support\n* [Edgy][edgy] support\n* Modern UI using Tabler\n\n## Installation\n\n**For Saffier**\n\n```shell\n$ pip install esmerald-admin[saffier]\n```\n\n**For Edgy**\n\n```shell\n$ pip install esmerald-admin[edgy]\n```\n\n**For both**\n\n```shell\n$ pip install esmerald-admin[all]\n```\n\n## Quickstart\n\nSaffier and Edgy are very powerfull ORMs as mentioned before and built on the top of SQLAlchemy core but\nalso extremely flexible allowing to use the models in a `declarative` way, which is the way\nSQLAdmin is expecting to use.\n\nThis makes both Saffier and Edgy unique since you can use the declarative models for the admin and the core\nmodels for anything else.\n\nSee the [Saffier declarative models][saffier_declarative] and [Edgy declarative models][edgy_declarative] for more details.\n\nLet us create a some models first. This example assumes you use the [contrib user of Saffier](https://esmerald.dev/databases/saffier/models/)\nand the [contrib user of Edgy](https://esmerald.dev/databases/edgy/models/)\nfrom Esmerald.\n\n!!! Warning\n Using the user provided by Esmerald is **not mandatory** and you can use your own design.\n The documentation uses the one provided by Esmerald as it is easier to explain and use.\n\n**Saffier**\n\n```python\nimport saffier\nfrom esmerald.contrib.auth.saffier.base_user import AbstractUser\nfrom saffier import Database, Registry\n\ndatabase = Database(\"sqlite:///db.sqlite\")\nregistry = Registry(database=database)\n\n\nclass BaseModel(saffier.Model):\n class Meta:\n abstract = True\n registry = registry\n\n\nclass User(BaseModel, AbstractUser):\n \"\"\"Inherits from the user base\"\"\"\n\n\n# Create the tables\nawait registry.create_all()\n\n```\n\n**Edgy**\n\n```python\nimport edgy\nfrom edgy import Database, Registry\nfrom esmerald.contrib.auth.edgy.base_user import AbstractUser\n\ndatabase = Database(\"sqlite:///db.sqlite\")\nregistry = Registry(database=database)\n\n\nclass BaseModel(edgy.Model):\n class Meta:\n abstract = True\n registry = registry\n\n\nclass User(BaseModel, AbstractUser):\n \"\"\"Inherits from the user base\"\"\"\n...\n\n\n# Create the tables\nawait registry.create_all()\n\n```\n\n**Now using with Esmerald**\n\nSaffier, as mentioned before, has the [declarative models][saffier_declarative] ready to be used.\nThese models are **only used for the admin**.\n\n\n```python\nfrom accounts.models import User\nfrom esmerald import Esmerald, settings\n\nfrom esmerald_admin import Admin, ModelView\n\ndatabase, registry = settings.db_access\n\napp = Esmerald()\nadmin = Admin(app, registry.engine)\n\n# Declarative User\nDeclarativeUser = User.declarative()\n\n\nclass UserAdmin(ModelView, model=DeclarativeUser):\n column_list = [DeclarativeUser.id, DeclarativeUser.email]\n\n\nadmin.add_view(UserAdmin)\n```\n\n\nOr if you want some more \"organised\".\n\n**Settings**\n\n```python title=\"myproject/configs/settings.py\"\nfrom functools import cached_property\nfrom typing import Optional\n\nfrom esmerald.conf.enums import EnvironmentType\nfrom esmerald.conf.global_settings import EsmeraldAPISettings\nfrom saffier import Database, Registry # or from edgy import Database, Registry\n\n\nclass AppSettings(EsmeraldAPISettings):\n app_name: str = \"My application in production mode.\"\n title: str = \"My app\"\n environment: Optional[str] = EnvironmentType.PRODUCTION\n secret_key: str = \"esmerald-insecure-key\"\n\n @cached_property\n def db_access(self):\n database = Database(\"sqlite:///db.sqlite\")\n registry = Registry(database=database)\n return database, registry\n\n```\n\n**Saffier Models**\n\n```python title=\"myproject/apps/accounts/models.py\"\nimport saffier\nfrom esmerald.contrib.auth.saffier.base_user import AbstractUser\nfrom saffier import Database, Registry\n\ndatabase = Database(\"sqlite:///db.sqlite\")\nregistry = Registry(database=database)\n\n\nclass BaseModel(saffier.Model):\n class Meta:\n abstract = True\n registry = registry\n\n\nclass User(BaseModel, AbstractUser):\n \"\"\"Inherits from the user base\"\"\"\n```\n\n**Edgy Models**\n\n```python title=\"myproject/apps/accounts/models.py\"\nimport edgy\nfrom edgy import Database, Registry\nfrom esmerald.contrib.auth.edgy.base_user import AbstractUser\n\ndatabase = Database(\"sqlite:///db.sqlite\")\nregistry = Registry(database=database)\n\n\nclass BaseModel(edgy.Model):\n class Meta:\n abstract = True\n registry = registry\n\n\nclass User(BaseModel, AbstractUser):\n \"\"\"Inherits from the user base\"\"\"\n```\n\n**Admin**\n\n```python title=\"myproject/admin.py\"\nfrom accounts.models import User as UserModel\n\nfrom esmerald_admin import Admin, ModelView\n\n# Declarative Models\nUser = UserModel.declarative()\n\n\nclass UserAdmin(ModelView, model=User):\n column_list = [User.id, User.username, User.email, User.first_name, User.last_name]\n\n\ndef get_views(admin: Admin) -> None:\n \"\"\"Generates the admin views and it is used in\n the `main.py` file.\n \"\"\"\n admin.add_model_view(UserAdmin)\n\n```\n\n**Application**\n\n```python title=\"myproject/app.py\"\nfrom accounts.models import User\nfrom esmerald import Esmerald, settings\n\nfrom esmerald_admin import Admin, ModelView\n\ndatabase, registry = settings.db_access\n\napp = Esmerald()\nadmin = Admin(app, registry.engine)\n\n# Declarative User\nDeclarativeUser = User.declarative()\n\n\nclass UserAdmin(ModelView, model=DeclarativeUser):\n column_list = [DeclarativeUser.id, DeclarativeUser.email]\n\n\nadmin.add_view(UserAdmin)\n```\n\nNow visiting `/admin/` (with slash at the end) on your browser you can see the Esmerald admin interface.\n\n## Important\n\nAs mentioned before, Esmerald admin is built on the top of [SQLAdmin][esmerald_admin]. Besides some\nunique features for Esmerald with Saffier that are documented here, **everything else should be checked**\n**in the [SQLAdmin][sqladmin] official documentation** as it works exactly the same.\n\nMassive thanks to [@aminalaee](https://github.com/aminalaee) to get this working so well and without his work, this\nwould not be possible! \u2b50\ufe0f Star his repo! \u2b50\ufe0f\n\n\n[esmerald_admin]: https://esmerald-admin.tarsild.io\n[esmerald_repo]: https://github.com/tarsil/esmerald-admin\n[saffier]: https://saffier.tarsild.io\n[edgy]: https://edgy.tarsild.io\n[sqladmin]: https://aminalaee.dev/sqladmin/\n[saffier_declarative]: https://saffier.tarsild.io/models/#declarative-models\n[edgy_declarative]: https://edgy.tarsild.io/models/#declarative-models\n",
"bugtrack_url": null,
"license": "",
"summary": "The needed admin for Saffier ORM with Esmerald",
"version": "0.4.0",
"project_urls": {
"Changelog": "https://esmerald-admin.tarsild.io/release-notes/",
"Documentation": "https://esmerald-admin.tarsild.io",
"Funding": "https://github.com/sponsors/tarsil",
"Homepage": "https://github.com/tarsil/esmerald-admin",
"Source": "https://github.com/tarsil/esmerald-admin"
},
"split_keywords": [
"esmerald_admin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3a7aee00aaf46f6ce9057470bd0e88ca5d4d69da171fd879410a9c02778dc3a8",
"md5": "e3a7a9149c0b40b22d7f8284abe3cbfc",
"sha256": "bfb501034582f652e43b54594809f7b63cb7e95b805c28b1eaf10b58081c3a3b"
},
"downloads": -1,
"filename": "esmerald_admin-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3a7a9149c0b40b22d7f8284abe3cbfc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12930,
"upload_time": "2023-10-17T14:01:04",
"upload_time_iso_8601": "2023-10-17T14:01:04.497988Z",
"url": "https://files.pythonhosted.org/packages/3a/7a/ee00aaf46f6ce9057470bd0e88ca5d4d69da171fd879410a9c02778dc3a8/esmerald_admin-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dec9de82619e49838d667df70d73e98a187ce872be91aa691138d2e194e9bd9a",
"md5": "9c35e58b0ed8182f0068de078dc90554",
"sha256": "91100c442111993b571a2964953f9090179bf30fe695f2673e33919e8425655b"
},
"downloads": -1,
"filename": "esmerald_admin-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "9c35e58b0ed8182f0068de078dc90554",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8384,
"upload_time": "2023-10-17T14:01:06",
"upload_time_iso_8601": "2023-10-17T14:01:06.579903Z",
"url": "https://files.pythonhosted.org/packages/de/c9/de82619e49838d667df70d73e98a187ce872be91aa691138d2e194e9bd9a/esmerald_admin-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-17 14:01:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sponsors",
"github_project": "tarsil",
"github_not_found": true,
"lcname": "esmerald-admin"
}
