django-nublado-core 0.3.0

A Django app for common configuration, utilities, and base models.

django-nublado-core

Common abstract models, utilities, and a simple dictionary-based app settings system for Django projects.

Overview

I found myself copying and pasting the same "core" app containing common abstract models, utilities, and app settings configuration in my Django projects, so I decided to publish it as a reusable package.

The goal is to provide simple, reliable core building blocks without introducing unnecessary complexity. The package evolves incrementally as needs arise in my projects, and is shared for others who may find it useful.

What’s included

• Abstract base models for common Django patterns (timestamps, UUIDs, published status, language).
• A small utility for typed, dictionary-based application settings using dataclasses.

Installation

Install the package from PyPI.

pip install django-nublado-core

Add the app to your Django project.

INSTALLED_APPS = [
    ...
    "django_nublado_core",
]

The package provides only abstract models and utilities, and does not create database tables or migrations on its own.

Abstract models

These core abstract models provide common fields and related functionality used across multiple models. All models are abstract and do not create database tables or migrations on their own.

ValidatedSaveModel

An abstract model that provides an explicit helper to validate a subclassed object before saving it, without overriding the model's save method and inadvertently messing something up.

This is especially useful in cases where you want to ensure model validation is applied outside of Django forms.

Minimal example

from django.db import models

from django_nublado_core.models import ValidatedSaveModel


class Article(ValidatedSaveModel):
    title = models.CharField(max_length=200)


# Sample usage
article = Article(title="hello there")
# full_clean and save
article.validate_and_save()

Notes

• Calls full_clean() before saving.
• Does not override Django’s save() method.
• Validation occurs only when validate_and_save() is called explicitly.
• Useful for explicit validation outside of forms when saving.

TimestampModel

An abstract model that adds automatic timestamp fields for object creation and updates.

Minimal example

from django.db import models

from django_nublado_core.models import TimestampModel


class Article(TimestampModel):
    title = models.CharField(max_length=200)


# Sample usage
article = Article(title="hello there")
article.save()
article.date_created
article.date_updated # date_updated is refreshed on each save

Notes

• Uses timezone-aware datetimes.

Fields:

• date_created
• date_updated

UUIDModel

An abstract model that generates a UUID for a subclassed model's id (primary key) field.

Minimal example

from django.db import models

from django_nublado_core.models import UUIDModel


class User(UUIDModel):
    username = models.CharField(max_length=200)

# Sample usage
user = User(username="Paco")
user.save()
# Primary key is a generated UUID.
user.pk # UUID('eeb4a289-034c-4e4c-9c54-98100cca1ee7')

Notes

• The generated UUID field is set as the primary key.

LanguageModel

An abstract model that provides a language choices field populated by the project's language settings.

Minimal example

LanguageModel contains an inner LanguageChoices enum derived from settings.LANGUAGES.

from django.db import models

from django_nublado_core.models import LanguageModel


class Article(LanguageModel):
    title = models.CharField(max_length=200)


# Sample usage
article = Article(title="hello there")
article.save()
article.language # "en"

article.LanguageChoices.EN.value # "en"

Notes

• The default language value is taken from settings.LANGUAGE_CODE.
• Language values are validated via full_clean(), but are not enforced at the database level by default. This is intentional. Database-level constraints can be added in concrete subclasses if needed.

PublishedModel

An abstract model for "publishable" models (e.g., blog posts, news articles) to distinguish published and draft objects.

Minimal example

PublishedModel contains an inner PublishedStatus enum with available published_status options.

from django.db import models

from django_nublado_core.models import PublishedModel


class Article(PublishedModel):
    title = models.CharField(max_length=200)


# Sample usage
article = Article(title="hello there")
article.save()
article.published_status # "DRAFT"

# Article is validated and saved with published_status = "PUBLISHED", and date_published = timezone.now()
article.publish()
article.is_published # True
article.date_published # Datetime article was published.

# Article is validated and saved with published_status = "DRAFT", and date_published = None
article.unpublish()
article.is_published # False
article.date_published # None

# The PublishedStatus enum can be accessed from an object instance or the class itself.
article.PublishedStatus.PUBLISHED.value
Article.PublishedStatus.PUBLISHED.value

Notes

• The publish() and unpublish() methods update the object's published_status and date_published attributes, then call full_clean() and save().
• is_published is a convenience property derived from published_status.

Application settings

This package provides a small utility for loading typed, dictionary-based application settings using Django settings and Python dataclasses.

To configure settings for an app, define three things in a module (conf.py or app_settings.py for example):

• The name of the settings dictionary
• A dictionary of default values
• A dataclass defining the exposed settings

Defining app settings

from dataclasses import dataclass

from django_nublado_core.conf.base import AppSettings

# The app's settings dict name (defined in Django settings.py)
SETTINGS_DICT_NAME = "YOUR_APP_SETTINGS"

# Default values for all exposed settings
SETTINGS_DEFAULTS = {
    "SETTING_A": "setting A",
}


@dataclass(frozen=True)
class AppData:
    SETTING_A: str


app_settings = AppSettings(
    settings_dict_name=SETTINGS_DICT_NAME,
    defaults=SETTINGS_DEFAULTS,
    cls=AppData,
)

Overriding settings

In your project's settings.py, define a dictionary matching the configured settings name.

YOUR_APP_SETTINGS = {
    "SETTING_A": "custom value",
}

Only keys explicitly declared on the dataclass are loaded. Unknown keys are ignored and logged as warnings.

Usage

The resulting app_settings object provides typed, read-only access to your application settings.

from .config import app_settings

value = app_settings.SETTING_A

Notes

• All settings must have defaults defined.
• Settings are loaded and cached at runtime.
• Unknown user-defined keys are ignored and logged.
• The resulting settings object is immutable.