django-headless 1.0.0__tar.gz

django_headless-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leon van der Grient
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_headless-1.0.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: django-headless
+Version: 1.0.0
+Summary: Automagically create a REST API for your Django models
+License-Expression: MIT
+License-File: LICENSE
+Keywords: django,rest,api,headless,cms
+Author: Leon van der Grient
+Author-email: leon@dwarsbit.nl
+Requires-Python: >=3.12
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: Django (>=5.2,<7.0)
+Requires-Dist: djangorestframework (>=3.18,<4.0)
+Requires-Dist: drf-flex-fields (>=1.0,<2.0)
+Requires-Dist: rich (>=14)
+Project-URL: Changelog, https://github.com/dwarsbit/django-headless/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://djangoheadless.org/docs/intro
+Project-URL: Homepage, https://djangoheadless.org
+Project-URL: Issues, https://github.com/dwarsbit/django-headless/issues
+Project-URL: Source, https://github.com/dwarsbit/django-headless
+Description-Content-Type: text/markdown
+
+# Django Headless
+
+[![PyPI version](https://badge.fury.io/py/django-headless.svg)](https://badge.fury.io/py/django-headless)
+[![Python versions](https://img.shields.io/pypi/pyversions/django-headless.svg)](https://pypi.org/project/django-headless/)
+[![Django versions](https://img.shields.io/badge/django-5.2%2B-blue.svg)](https://www.djangoproject.com/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Django Headless generates a REST API for your Django models, so Django can serve as the backend of a headless CMS. Decorate a model with `@expose()` and it gets list, detail, create, update and delete routes, with no serializers, viewsets or URL patterns to write.
+
+Read the documentation at [djangoheadless.org](https://djangoheadless.org).
+
+## Features
+
+- **Routes per model**: one decorator generates the routes of a model.
+- **Singletons**: site settings and other one-off objects as a single route.
+- **Filtering**: every lookup a field supports, from the query string.
+- **Lookup routes**: fetch an object by a unique field such as a slug, at `/api/blog.article/by_slug/<value>`.
+- **Pagination**: a stable, paginated list envelope with ready-to-fetch links.
+- **Protected by default**: generated routes only answer staff users until you open them up.
+
+## Quick start
+
+1. Install the package:
+
+   ```bash
+   pip install django-headless
+   ```
+
+2. Add `rest_framework`, `headless` and `headless.rest` to `INSTALLED_APPS`:
+
+   ```python
+   # mysite/settings.py
+   INSTALLED_APPS = [
+       # ...
+       "rest_framework",
+       "headless",
+       "headless.rest",
+   ]
+   ```
+
+3. Include the API in your URL configuration:
+
+   ```python
+   # mysite/urls.py
+   from django.urls import include, path
+
+   urlpatterns = [
+       # ...
+       path("api/", include("headless.rest.urls")),
+   ]
+   ```
+
+4. Expose a model:
+
+   ```python
+   # blog/models.py
+   from django.db import models
+   from headless import expose
+
+
+   @expose()
+   class Article(models.Model):
+       title = models.CharField(max_length=200)
+       body = models.TextField()
+       published = models.BooleanField(default=False)
+       created_at = models.DateTimeField(auto_now_add=True)
+
+       def __str__(self):
+           return self.title
+   ```
+
+Run `python manage.py runserver`; the article list is at `/api/blog.article`.
+
+Generated routes answer `403 Forbidden` to everyone but staff users, so an exposed model is never public by accident. To configure authentication or open the routes up, see [Permissions](https://djangoheadless.org/docs/permissions).
+
+## Documentation
+
+- [Installation](https://djangoheadless.org/docs/installation): requirements and setup
+- [Exposing models](https://djangoheadless.org/docs/models): the `@expose()` options
+- [Singletons](https://djangoheadless.org/docs/singletons): single-instance resources such as site settings
+- [Filtering](https://djangoheadless.org/docs/filtering): lookups, exclusions and type casting
+- [Pagination](https://djangoheadless.org/docs/pagination): the list envelope
+- [Authentication](https://djangoheadless.org/docs/authentication): secret key and DRF authentication
+- [Serializers](https://djangoheadless.org/docs/serializers): expanding relations and model properties
+- [Permissions](https://djangoheadless.org/docs/permissions): defaults and overrides for generated routes
+- [Settings reference](https://djangoheadless.org/docs/settings): every `HEADLESS` setting
+- [System checks](https://djangoheadless.org/docs/checks): the checks for risky or broken settings
+
+## Contributing
+
+To contribute a change:
+
+1. Fork the repository.
+2. Create a branch: `git checkout -b fix-boolean-casting`.
+3. Make the change and add tests for it.
+4. Run the test suite: `poetry run python scripts/test_wrapper.py test`.
+5. Commit and push the branch.
+6. Open a pull request.
+
+Set up a development environment with Poetry:
+
+```bash
+git clone https://github.com/dwarsbit/django-headless.git
+cd django-headless
+poetry install
+poetry run python scripts/test_wrapper.py test
+```
+
+Writing for the README or the documentation follows [STYLE.md](STYLE.md).
+
+## Support
+
+- Bug reports: [GitHub Issues](https://github.com/dwarsbit/django-headless/issues)
+- Questions: [GitHub Discussions](https://github.com/dwarsbit/django-headless/discussions)
+- Email: leon@dwarsbit.nl
+
+## License
+
+Django Headless is licensed under the MIT License; see [LICENSE](LICENSE).
+
+## Links
+
+- [Documentation](https://djangoheadless.org)
+- [PyPI](https://pypi.org/project/django-headless/)
+- [GitHub](https://github.com/dwarsbit/django-headless)
+- [Changelog](CHANGELOG.md)
+

django_headless-1.0.0/README.md

@@ -0,0 +1,126 @@
+# Django Headless
+
+[![PyPI version](https://badge.fury.io/py/django-headless.svg)](https://badge.fury.io/py/django-headless)
+[![Python versions](https://img.shields.io/pypi/pyversions/django-headless.svg)](https://pypi.org/project/django-headless/)
+[![Django versions](https://img.shields.io/badge/django-5.2%2B-blue.svg)](https://www.djangoproject.com/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Django Headless generates a REST API for your Django models, so Django can serve as the backend of a headless CMS. Decorate a model with `@expose()` and it gets list, detail, create, update and delete routes, with no serializers, viewsets or URL patterns to write.
+
+Read the documentation at [djangoheadless.org](https://djangoheadless.org).
+
+## Features
+
+- **Routes per model**: one decorator generates the routes of a model.
+- **Singletons**: site settings and other one-off objects as a single route.
+- **Filtering**: every lookup a field supports, from the query string.
+- **Lookup routes**: fetch an object by a unique field such as a slug, at `/api/blog.article/by_slug/<value>`.
+- **Pagination**: a stable, paginated list envelope with ready-to-fetch links.
+- **Protected by default**: generated routes only answer staff users until you open them up.
+
+## Quick start
+
+1. Install the package:
+
+   ```bash
+   pip install django-headless
+   ```
+
+2. Add `rest_framework`, `headless` and `headless.rest` to `INSTALLED_APPS`:
+
+   ```python
+   # mysite/settings.py
+   INSTALLED_APPS = [
+       # ...
+       "rest_framework",
+       "headless",
+       "headless.rest",
+   ]
+   ```
+
+3. Include the API in your URL configuration:
+
+   ```python
+   # mysite/urls.py
+   from django.urls import include, path
+
+   urlpatterns = [
+       # ...
+       path("api/", include("headless.rest.urls")),
+   ]
+   ```
+
+4. Expose a model:
+
+   ```python
+   # blog/models.py
+   from django.db import models
+   from headless import expose
+
+
+   @expose()
+   class Article(models.Model):
+       title = models.CharField(max_length=200)
+       body = models.TextField()
+       published = models.BooleanField(default=False)
+       created_at = models.DateTimeField(auto_now_add=True)
+
+       def __str__(self):
+           return self.title
+   ```
+
+Run `python manage.py runserver`; the article list is at `/api/blog.article`.
+
+Generated routes answer `403 Forbidden` to everyone but staff users, so an exposed model is never public by accident. To configure authentication or open the routes up, see [Permissions](https://djangoheadless.org/docs/permissions).
+
+## Documentation
+
+- [Installation](https://djangoheadless.org/docs/installation): requirements and setup
+- [Exposing models](https://djangoheadless.org/docs/models): the `@expose()` options
+- [Singletons](https://djangoheadless.org/docs/singletons): single-instance resources such as site settings
+- [Filtering](https://djangoheadless.org/docs/filtering): lookups, exclusions and type casting
+- [Pagination](https://djangoheadless.org/docs/pagination): the list envelope
+- [Authentication](https://djangoheadless.org/docs/authentication): secret key and DRF authentication
+- [Serializers](https://djangoheadless.org/docs/serializers): expanding relations and model properties
+- [Permissions](https://djangoheadless.org/docs/permissions): defaults and overrides for generated routes
+- [Settings reference](https://djangoheadless.org/docs/settings): every `HEADLESS` setting
+- [System checks](https://djangoheadless.org/docs/checks): the checks for risky or broken settings
+
+## Contributing
+
+To contribute a change:
+
+1. Fork the repository.
+2. Create a branch: `git checkout -b fix-boolean-casting`.
+3. Make the change and add tests for it.
+4. Run the test suite: `poetry run python scripts/test_wrapper.py test`.
+5. Commit and push the branch.
+6. Open a pull request.
+
+Set up a development environment with Poetry:
+
+```bash
+git clone https://github.com/dwarsbit/django-headless.git
+cd django-headless
+poetry install
+poetry run python scripts/test_wrapper.py test
+```
+
+Writing for the README or the documentation follows [STYLE.md](STYLE.md).
+
+## Support
+
+- Bug reports: [GitHub Issues](https://github.com/dwarsbit/django-headless/issues)
+- Questions: [GitHub Discussions](https://github.com/dwarsbit/django-headless/discussions)
+- Email: leon@dwarsbit.nl
+
+## License
+
+Django Headless is licensed under the MIT License; see [LICENSE](LICENSE).
+
+## Links
+
+- [Documentation](https://djangoheadless.org)
+- [PyPI](https://pypi.org/project/django-headless/)
+- [GitHub](https://github.com/dwarsbit/django-headless)
+- [Changelog](CHANGELOG.md)

django_headless-1.0.0/headless/__init__.py

@@ -0,0 +1,83 @@
+__title__ = "Django Headless"
+__version__ = "1.0.0"
+__author__ = "Leon van der Grient"
+__license__ = "MIT"
+
+from typing import Type
+
+from django.db import models
+
+from .registry import headless_registry
+
+# Version synonym
+VERSION = __version__
+
+
+def expose(singleton=False, search_fields=None, fields=None, exclude=None, read_only=False, lookup_fields=None):
+    """
+    Decorator to register a Django model to the headless registry.
+
+    Args:
+        singleton: If True, the model will be treated as a singleton (single instance).
+        search_fields: List of field names to enable search functionality on.
+        fields: Restrict the exposed serializer to these field names.
+        exclude: Exclude these field names from the exposed serializer.
+        read_only: If True, the model is exposed read-only (no create, update or delete).
+        lookup_fields: Names of unique fields to expose a retrieve route for, at by_<field>/<value>.
+
+    Usage:
+        @expose()
+        class MyModel(models.Model):
+            pass
+    """
+
+    def decorator(model_class: Type[models.Model]):
+        expose_model(
+            model_class,
+            singleton=singleton,
+            search_fields=search_fields,
+            fields=fields,
+            exclude=exclude,
+            read_only=read_only,
+            lookup_fields=lookup_fields,
+        )
+
+        return model_class
+
+    return decorator
+
+
+def expose_model(
+    model_class: Type[models.Model],
+    singleton=False,
+    search_fields=None,
+    fields=None,
+    exclude=None,
+    read_only=False,
+    lookup_fields=None,
+):
+    """
+    Register a Django model to the headless registry.
+
+    Args:
+        model_class: The Django model class to expose via the REST API.
+        singleton: If True, the model will be treated as a singleton (single instance).
+        search_fields: List of field names to enable search functionality on.
+        fields: Restrict the exposed serializer to these field names.
+        exclude: Exclude these field names from the exposed serializer.
+        read_only: If True, the model is exposed read-only (no create, update or delete).
+        lookup_fields: Names of unique fields to expose a retrieve route for, at by_<field>/<value>.
+
+    Usage:
+        expose_model(MyModel, singleton=False, search_fields=['name', 'description'])
+    """
+
+    headless_registry.register(
+        model_class,
+        singleton=singleton,
+        search_fields=search_fields,
+        fields=fields,
+        exclude=exclude,
+        read_only=read_only,
+        lookup_fields=lookup_fields,
+    )

django_headless-1.0.0/headless/apps.py

@@ -0,0 +1,49 @@
+from django.apps import AppConfig
+
+from . import VERSION
+from .utils import (
+    log,
+    is_boot_log_enabled,
+    get_latest_version,
+    is_newer_version,
+    normalize_version,
+)
+
+
+class DjangoHeadlessConfig(AppConfig):
+    name = "headless"
+    label = "headless"
+
+    def ready(self):
+        # Register the system checks of the registry and settings. The headless
+        # app manages the registry; apps such as headless.rest serve the models.
+        from . import checks  # noqa: F401
+
+        if is_boot_log_enabled():
+            self.log_boot()
+
+    def log_boot(self):
+        """
+        Log the version and the exposed models. Exposure apps such as
+        headless.rest log their own part of the boot log after this.
+        """
+        from headless.settings import headless_settings
+        from .registry import headless_registry
+
+        log("")
+        log("[bold magenta]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold magenta]")
+        log("[bold cyan]Django Headless[/bold cyan]")
+
+        # Check for a newer version, unless the check is turned off
+        latest_version = get_latest_version() if headless_settings.VERSION_CHECK else None
+        if latest_version and is_newer_version(latest_version, VERSION):
+            log(f"[yellow]⚠️  New version available[/yellow]")
+            log(f"Current: [bold]{normalize_version(VERSION)}[/bold] → Latest: {normalize_version(latest_version)}")
+        else:
+            log(f"[bold]Version {normalize_version(VERSION)}[/bold]")
+
+        log("[bold magenta]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold magenta]")
+        log(f":gift:  Found [bold green]{len(headless_registry)}[/bold green] exposed models:")
+        for model_config in headless_registry.get_models():
+            model = model_config["model"]
+            log(f"  [cyan]•[/cyan] {model._meta.verbose_name} ([dim]{model._meta.label_lower}[/dim])")

django_headless-1.0.0/headless/checks.py

@@ -0,0 +1,146 @@
+"""
+Django system checks for the registry and settings of Django Headless,
+whatever app serves the exposed models. The checks of the REST routes
+live in headless.rest.checks.
+
+They run with runserver, migrate and manage.py check. Silence a single
+check with SILENCED_SYSTEM_CHECKS, e.g. ["headless.W005"].
+"""
+
+from difflib import get_close_matches
+
+from django.apps import apps
+from django.core import checks
+
+from .registry import headless_registry
+from .settings import DEFAULTS, SETTINGS_NAMESPACE, headless_settings
+
+# Apps that serve the exposed models
+EXPOSURE_APPS = ["headless.rest"]
+
+# Parts of a field name (split on "_") that mark it as a credential
+SENSITIVE_NAME_PARTS = {"password", "passwd", "pwd", "secret", "token", "otp", "salt", "apikey"}
+
+# Consecutive parts of a field name that mark it as a credential
+SENSITIVE_NAME_PAIRS = {("api", "key"), ("private", "key"), ("access", "key")}
+
+
+def is_sensitive_field_name(name: str) -> bool:
+    """
+    Check whether a field name looks like a credential, such as password_hash,
+    access_token or api_key. Only whole parts of the name count, so names
+    like sort_key or tokenizer do not match.
+    """
+    parts = name.lower().split("_")
+    return any(part in SENSITIVE_NAME_PARTS for part in parts) or any(
+        pair in SENSITIVE_NAME_PAIRS for pair in zip(parts, parts[1:])
+    )
+
+
+def _implicitly_serialized_fields(config):
+    """
+    Return the names of the fields of an exposed model that are serialized
+    without being named in its fields option: all forward fields minus the
+    excluded ones. Fields named in a fields option are a deliberate choice.
+    """
+    if config["fields"] is not None:
+        return []
+
+    model = config["model"]
+    excluded = set(config["exclude"] or [])
+    return [field.name for field in (*model._meta.fields, *model._meta.many_to_many) if field.name not in excluded]
+
+
+@checks.register()
+def check_settings(app_configs=None, **kwargs):
+    """W005: the HEADLESS setting has a key that is not a Django Headless setting."""
+    # A HEADLESS setting that is not a dictionary raises ImproperlyConfigured
+    # on first use, at startup, so it never reaches the checks.
+    warnings = []
+    for key in headless_settings.user_settings:
+        if key in DEFAULTS:
+            continue
+        matches = get_close_matches(str(key), DEFAULTS, n=1)
+        hint = f'Did you mean "{matches[0]}"?' if matches else "Remove it, or see the settings reference."
+        warnings.append(
+            checks.Warning(
+                f'{SETTINGS_NAMESPACE}["{key}"] is not a Django Headless setting, so it has no effect.',
+                hint=hint,
+                id="headless.W005",
+            )
+        )
+
+    return warnings
+
+
+@checks.register()
+def check_registrations(app_configs=None, **kwargs):
+    """
+    W008: a model is exposed more than once with different options.
+    W010: models are exposed, but no app that serves them is installed.
+    """
+    warnings = []
+
+    for label in sorted(headless_registry.get_conflicting_labels()):
+        warnings.append(
+            checks.Warning(
+                "This model is exposed more than once with different options, for example with both @expose() "
+                "and expose_model(). Only the last registration is in effect.",
+                hint="Expose the model once, with all its options.",
+                obj=headless_registry.get_model(label)["model"],
+                id="headless.W008",
+            )
+        )
+
+    if headless_registry.get_models() and not any(apps.is_installed(app) for app in EXPOSURE_APPS):
+        warnings.append(
+            checks.Warning(
+                "Models are exposed, but no app that serves them is installed, so the API has no routes.",
+                hint='Add "headless.rest" to INSTALLED_APPS, after "headless".',
+                id="headless.W010",
+            )
+        )
+
+    return warnings
+
+
+@checks.register(checks.Tags.security)
+def check_sensitive_fields(app_configs=None, **kwargs):
+    """
+    W006: an exposed model serializes a field that looks like a credential.
+    W007: a user model is exposed without a fields allowlist.
+    """
+    try:
+        from django.contrib.auth.base_user import AbstractBaseUser
+    except ImportError:  # pragma: no cover
+        AbstractBaseUser = None
+
+    warnings = []
+
+    for config in headless_registry.get_models():
+        model = config["model"]
+
+        if AbstractBaseUser is not None and issubclass(model, AbstractBaseUser) and config["fields"] is None:
+            warnings.append(
+                checks.Warning(
+                    "This user model is exposed without a fields option, so the API serializes every field "
+                    "that is not excluded, which can include the password hash, email address and permissions.",
+                    hint='List the fields the API may serialize, e.g. @expose(fields=["username", "first_name"]).',
+                    obj=model,
+                    id="headless.W007",
+                )
+            )
+
+        for name in _implicitly_serialized_fields(config):
+            if is_sensitive_field_name(name):
+                warnings.append(
+                    checks.Warning(
+                        f"The API serializes the field {name}, which looks like a credential.",
+                        hint=f'Add "{name}" to the exclude option, or list it in the fields option '
+                        "if the API should serialize it.",
+                        obj=model,
+                        id="headless.W006",
+                    )
+                )
+
+    return warnings