django-forge-core

English | Français

Runtime foundation for Django Forge projects: small building blocks that generated code imports, also usable on their own in any Django project.

It provides three things:

• settings.py configuration read from the environment, with clear errors;
• common abstract models (timestamps, UUID, soft delete);
• typed business errors meant to be used with pycatch (Result), and their conversion into DRF responses.

Installation

uv add django-forge-core
uv add "django-forge-core[drf]"   # with the Django REST Framework integration

Python 3.12 or later, Django 5.0 or later. Projects created with forge init get it through the Forge CLI.

Configuration from the environment

# settings.py
from forge_core.conf import env, env_bool, env_list, env_int, deep_merge, current_environment

SECRET_KEY = env("SECRET_KEY")                       # ImproperlyConfigured if missing
DEBUG = env_bool("DEBUG", default=False)
ALLOWED_HOSTS = env_list("ALLOWED_HOSTS", default=["localhost"])
DB_PORT = env_int("DB_PORT", default=5432)

A missing variable without a default raises ImproperlyConfigured naming the variable, and an invalid value reports both the name and the raw value.

Layers example:

BASE = {"LOGGING": {"version": 1, "root": {"level": "INFO"}}}
PROD = {"LOGGING": {"root": {"level": "WARNING"}}}

layers = {"dev": BASE, "prod": deep_merge(BASE, PROD)}
globals().update(layers[current_environment()])

Abstract models

from django.db import models
from forge_core.models import SoftDeleteModel, TimeStampedModel, UUIDModel


class Article(UUIDModel, TimeStampedModel, SoftDeleteModel):
    title = models.CharField(max_length=200)

• TimeStampedModel: created_at, updated_at.
• UUIDModel: UUID4 primary key.
• SoftDeleteModel: delete() sets deleted_at. Article.objects only sees active rows, Article.all_objects sees everything. Methods restore() and hard_delete(), and on QuerySets alive(), dead(), hard_delete().

These classes are abstract: no migration of their own, and forge_core does not need to be in INSTALLED_APPS.

Typed errors and pycatch

from pycatch import Err, Ok, Result
from forge_core.errors import NotFound


def get_article(pk: int) -> Result[Article, NotFound]:
    try:
        return Ok(Article.objects.get(pk=pk))
    except Article.DoesNotExist:
        return Err(NotFound(f"Article {pk} not found"))

Provided errors: ValidationFailed (400), Unauthenticated (401), PermissionRefused (403), NotFound (404), Conflict (409). Each carries a stable code and an HTTP status; ForgeError is the base class for your own.

Django REST Framework

from forge_core.drf import respond


class ArticleView(APIView):
    def get(self, request, pk):
        return respond(get_article(pk))

respond turns Ok(value) into a response and Err(ForgeError) into {"code": ..., "detail": ...} with the right status. So that a ForgeError raised inside a view produces the same response:

REST_FRAMEWORK = {"EXCEPTION_HANDLER": "forge_core.drf.exception_handler"}

Development

uv sync
uv run ruff check src tests
uv run pytest --cov=forge_core --cov-report=term-missing

License

MIT