Edgy Guardian¶
🔥 Per object permissions for Edgy 🔥
Documentation: https://edgy-guardian.dymmond.com 📚
Source Code: https://github.com/dymmond/edgy-guardian
Edgy Guardian is a library that adds object-level permissions to the Edgy framework, inspired by Django Guardian. It enhances Edgy's permission system by allowing fine-grained, per-object access control, making it perfect for applications needing precise authorization.
Why Use Edgy Guardian?¶
Edgy's built-in permission system works at the model level, but many applications need per-object permissions. For example:
- Document management systems where users access only their documents.
- Multi-tenant applications with different access levels for different users or groups.
- Social media platforms with custom visibility settings for posts, comments, and messages.
Edgy Guardian addresses this need by introducing a flexible and efficient object-level permission system.
The following steps explains how to quickly setup Edgy Guardian and it must be followed properly.
This documentation also provides explanations how to use Edgy Guardian features effectively.
Key Concepts¶
Edgy Permissions¶
Edgy provides native permissions that work out of the box. Edgy Guardian offers a different approach for more specific use cases.
Warning
Currently, Edgy Guardian only supports normal primary keys (pk, id), not complex primary keys. This covers most use cases, but future support is planned.
Requirements¶
To use Edgy Guardian, ensure your environment meets these requirements:
- Python 3.10+ (Edgy Guardian uses modern Python features)
- Edgy framework (Ensure Edgy is installed and configured in your project)
Installation¶
Install Edgy Guardian using pip:
pip install edgy-guardian
Introduction¶
ContentType¶
The ContentType model represents all models in an application, allowing dynamic assignment of permissions to specific models. It stores metadata like app label and model name, enabling flexible management of permissions and interactions with different models.
Group¶
A Group allows collective management of permissions for multiple users. Instead of assigning permissions individually, groups enable bulk permission assignments, simplifying access control. Users inherit permissions from the groups they belong to, useful for roles like "Editors", "Moderators", and "Admins".
Permission¶
The Permission model defines specific actions users or groups can perform on a model. Each permission is linked to a ContentType and has a unique codename (e.g., add_user, change_post). Permissions can be assigned directly to users or through groups, providing granular control over actions within an application.
How to Use Edgy Guardian¶
Edgy Guardian introduces the concept of apps. Each installed app must declare an apps.py file, similar to Django.
The Apps¶
Here's an example structure for apps.py in your project:
.
└── guardian
├── apps
│ ├── accounts
│ │ ├── apps.py
│ │ ├── __init__.py
│ │ └── models.py
│ ├── contenttypes
│ │ ├── apps.py
│ │ ├── __init__.py
│ │ └── models.py
│ ├── __init__.py
│ ├── items
│ │ ├── apps.py
│ │ ├── __init__.py
│ │ └── models.py
│ ├── permissions
│ │ ├── apps.py
│ │ ├── __init__.py
│ │ └── models.py
│ └── products
│ ├── apps.py
│ ├── __init__.py
│ └── models.py
├── __init__.py
└── main.py
Each apps.py must implement the AppConfig from Edgy Guardian.
Example
Using contenttypes as an example:
from edgy_guardian.apps import AppConfig
class ContentTypesConfig(AppConfig):
name: str = "contenttypes"
verbose_name: str = "Content Types"
ContentType Model¶
Edgy Guardian provides out-of-the-box ContentType models. Inherit from BaseContentType for migrations:
import edgy
from edgy_guardian.content_types.models import BaseContentType
database = edgy.Database("sqlite:///db.sqlite")
registry = edgy.Registry(database=database)
class ContentType(BaseContentType):
class Meta:
registry = settings.registry
Permissions Model¶
The Permission model is powerful and must inherit from BasePermission. Add a users attribute of type edgy.ManyToManyField:
import edgy
from edgy_guardian.permissions.models import BasePermission
database = edgy.Database("sqlite:///db.sqlite")
registry = edgy.Registry(database=database)
class Permission(BasePermission):
users: list[edgy.Model] = edgy.ManyToManyField(
"User", through_tablename=edgy.NEW_M2M_NAMING, related_name="permissions"
)
class Meta:
registry = registry
Groups Model¶
The Group model is optional but useful for bulk permission assignments. Inherit from BaseGroup and add users and permissions attributes:
import edgy
from edgy_guardian.permissions.models import BaseGroup
database = edgy.Database("sqlite:///db.sqlite")
registry = edgy.Registry(database=database)
class Group(BaseGroup):
users: list[edgy.Model] = edgy.ManyToManyField(
"User", through_tablename=edgy.NEW_M2M_NAMING, related_name="groups"
)
permissions: list[Permission] = edgy.ManyToManyField(
"Permission", through_tablename=edgy.NEW_M2M_NAMING, related_name="groups"
)
class Meta:
registry = settings.registry
User Model¶
Your application user model can be any model. Here's an example:
from datetime import datetime
import edgy
database = edgy.Database("sqlite:///db.sqlite")
registry = edgy.Registry(database=database)
class User(edgy.Model):
first_name: str = edgy.CharField(max_length=150)
last_name: str = edgy.CharField(max_length=150)
username: str = edgy.CharField(max_length=150, unique=True)
email: str = edgy.EmailField(max_length=120, unique=True)
last_login: datetime = edgy.DateTimeField(null=True)
is_active: bool = edgy.BooleanField(default=True)
is_staff: bool = edgy.BooleanField(default=False)
is_superuser: bool = edgy.BooleanField(default=False)
class Meta:
registry = registry
EdgyGuardian Config¶
This configuration ties everything together. Declare the edgy_guardian configuration inside your EdgySettings:
from edgy import EdgySettings as BaseSettings
from edgy_guardian.configs import EdgyGuardianConfig
class EdgyAppSettings(BaseSettings):
preloads: list[str] = [
"accounts.models",
"permissions.models",
"contenttypes.models",
"products.models",
"items.models",
]
edgy_guardian: EdgyGuardianConfig = EdgyGuardianConfig(
models={
"accounts": "accounts.models",
"contenttypes": "contenttypes.models",
"permissions": "permissions.models",
"products": "products.models",
"items": "items.models",
},
apps=[
"accounts.apps.AccountsConfig",
"permissions.apps.PermissionsConfig",
"contenttypes.apps.ContentTypesConfig",
"products.apps.ProductsConfig",
"items.apps.ItemsConfig",
],
content_type_model="ContentType",
user_model="User",
permission_model="Permission",
group_model="Group",
)
handle_content_types¶
This function automatically manages content types on startup:
from edgy_guardian.loader import handle_content_types
Initialize Your Application¶
Here's how to start an application using Edgy and Edgy Guardian:
#!/usr/bin/env python
import os
import sys
from esmerald import Esmerald
from edgy_guardian.loader import handle_content_types
def build_path():
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_application():
build_path()
from edgy import Instance, monkay
from edgy.conf import settings as edgy_settings
from esmerald.conf import settings
edgy_settings.edgy_guardian.register(settings.registry)
monkay.evaluate_settings(ignore_preload_import_errors=False, onetime=False)
app = Esmerald(
on_startup=[settings.registry.__aenter__, handle_content_types],
on_shutdown=[settings.registry.__aexit__],
)
monkay.set_instance(Instance(registry=app.settings.registry, app=app))
return app
app = get_application()
Next Steps¶
Learn how to use the system by using the shortcuts.