django-headless 1.0.0b1__tar.gz

django_headless-1.0.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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.0b1/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.3
+Name: django-headless
+Version: 1.0.0b1
+Summary: Automagically create a REST API for you Django models
+License: MIT
+Author: Leon van der Grient
+Author-email: leon@devtastic.io
+Requires-Python: >=3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: rich
+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-3.10%2B-blue.svg)](https://www.djangoproject.com/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+With Django Headless you quickly create a REST API for your models, making it easy to turn Django into a powerful headless CMS.
+
+## ✨ Features
+
+- **🎯 Zero configuration**: Add `@headless` decorator to any model and get instant REST endpoints
+- **🤝 Plays nice**: Seamlessly integrates with existing Django applications
+- **💈 Supports singletons**: Special handling for singleton models (settings, configurations, etc.)
+- **🔍 Flexible filtering**: Optional filtering backend based on Django ORM lookups
+- **🛡️ Secure**: Inherits Django's security features and permissions system
+
+## 🚀 Quick Start
+
+### Installation
+
+☝️ Django Headless depends on Django and Django Rest Framework.
+
+```bash
+pip install django-headless
+```
+
+### Add to Django Settings
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    'django.contrib.admin',
+    'django.contrib.auth',
+    'django.contrib.contenttypes',
+    'django.contrib.sessions',
+    'django.contrib.messages',
+    'django.contrib.staticfiles',
+    'rest_framework',
+    'headless',  # Add this
+    # ... your apps
+]
+
+# Optional: add the lookup filter backend
+REST_FRAMEWORK = {
+    "DEFAULT_FILTER_BACKENDS": [
+        "headless.rest.filters.LookupFilter",
+    #... other DRF config
+}
+```
+
+### Create Your First Headless Model
+
+```python
+# models.py
+from django.db import models
+from headless import headless
+
+@headless()
+class BlogPost(models.Model):
+    title = models.CharField(max_length=200)
+    content = models.TextField()
+    published = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return self.title
+```
+
+### Add URLs
+
+```python
+# urls.py
+from django.contrib import admin
+from django.urls import path, include
+
+urlpatterns = [
+    path('admin/', admin.site.urls),
+    path('api/', include('headless.urls')),
+]
+```
+
+That's it! 🎉 Your model is now available via REST API at `/api/blog-post/`
+
+## 📖 Usage Examples
+
+### Basic Model Registration
+
+```python
+from headless import headless
+
+@headless()
+class Article(models.Model):
+    title = models.CharField(max_length=200)
+    content = models.TextField()
+    author = models.ForeignKey(User, on_delete=models.CASCADE)
+```
+
+**Generated endpoints:**
+- `GET /api/article/` - List all articles
+- `POST /api/article/` - Create new article
+- `GET /api/article/{id}/` - Retrieve specific article
+- `PUT /api/article/{id}/` - Update article
+- `PATCH /api/article/{id}/` - Partially update article
+- `DELETE /api/article/{id}/` - Delete article
+
+### Singleton Models
+
+Perfect for site settings, configurations, or any model that should have only one instance:
+
+```python
+@headless(singleton=True)
+class SiteConfiguration(models.Model):
+    site_name = models.CharField(max_length=100)
+    maintenance_mode = models.BooleanField(default=False)
+    contact_email = models.EmailField()
+    
+    class Meta:
+        verbose_name = "Site Configuration"
+```
+
+**Generated endpoints:**
+- `GET /api/site-configuration/` - Get configuration
+- `PUT /api/site-configuration/` - Update configuration
+- `PATCH /api/site-configuration/` - Partial update
+
+### Advanced Filtering
+
+Django Headless supports Django ORM lookups for powerful filtering.
+Add the LookupFilter backend to your default filter backends:
+
+```python
+REST_FRAMEWORK = {
+    "DEFAULT_FILTER_BACKENDS": [
+        "headless.rest.filters.LookupFilter",
+    #... other DRF config
+}
+```
+
+**Filter examples:**
+```bash
+# Basic filtering
+GET /api/blogpost/?published=true
+
+# Field lookups
+GET /api/blogpost/?title__icontains=django
+GET /api/blogpost/?created_at__gte=2023-01-01
+GET /api/blogpost/?author__username=john
+
+# Multiple filters
+GET /api/blogpost/?published=true&created_at__year=2023
+```
+
+Values are automatically cast based on the field type. Booleans can be represented
+as `true`, `1` or `on` (and `false`, `0` or `off`). Multi-value lookups can be comma-separated (e.g. `id__in=1,2,3`).
+
+
+## 🎛️ Configuration Options
+
+The `@headless` decorator accepts the following configuration options:
+
+| Option | Type | Default | Description                                                        |
+|--------|------|---------|--------------------------------------------------------------------|
+| `singleton` | `bool` | `False` | Creates singleton endpoints (no create, list and delete endpoints) |
+
+
+
+### Global Settings
+
+```python
+# settings.py
+HEADLESS =  {
+    "NON_FILTER_FIELDS": [
+        "search",
+        "limit",
+        "page",
+        "fields",
+        "exclude",
+        "expand",
+    ],
+    "FILTER_EXCLUSION_SYMBOL": "~",
+}
+```
+
+## 🛠️ Requirements
+
+- Python 3.10+
+- Django 5.0+
+- Django REST Framework 3.16+
+
+## 🤝 Contributing
+
+We welcome contributions! Here's how to get started:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for your changes
+5. Run the test suite (`python manage.py test`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/StructuralRealist/django-headless.git
+cd django-headless
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements-dev.txt
+
+# Run tests
+python manage.py test
+
+# Run example project
+cd example_project
+python manage.py migrate
+python manage.py runserver
+```
+
+## 📚 Documentation
+
+For detailed documentation, visit [djangoheadless.org](https://djangoheadless.org)
+
+## 🐛 Issues & Support
+
+- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/StructuralRealist/django-headless/issues)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/StructuralRealist/django-headless/discussions)
+- 📧 **Email**: leon@devtastic.io
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built on the shoulders of [Django](https://www.djangoproject.com/) and [Django REST Framework](https://www.django-rest-framework.org/)
+- Inspired by the headless CMS and Jamstack movement
+- Thanks to all contributors and the Django community
+
+## 🔗 Links
+
+- [PyPI Package](https://pypi.org/project/django-headless/)
+- [Documentation](https:/djangoheadless.org)
+- [GitHub Repository](https://github.com/StructuralRealist/django-headless)
+- [Changelog](CHANGELOG.md)
+
+---
+
+Made in Europe 🇪🇺 with 💚 for Django

django_headless-1.0.0b1/README.md

@@ -0,0 +1,256 @@
+# 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-3.10%2B-blue.svg)](https://www.djangoproject.com/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+With Django Headless you quickly create a REST API for your models, making it easy to turn Django into a powerful headless CMS.
+
+## ✨ Features
+
+- **🎯 Zero configuration**: Add `@headless` decorator to any model and get instant REST endpoints
+- **🤝 Plays nice**: Seamlessly integrates with existing Django applications
+- **💈 Supports singletons**: Special handling for singleton models (settings, configurations, etc.)
+- **🔍 Flexible filtering**: Optional filtering backend based on Django ORM lookups
+- **🛡️ Secure**: Inherits Django's security features and permissions system
+
+## 🚀 Quick Start
+
+### Installation
+
+☝️ Django Headless depends on Django and Django Rest Framework.
+
+```bash
+pip install django-headless
+```
+
+### Add to Django Settings
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    'django.contrib.admin',
+    'django.contrib.auth',
+    'django.contrib.contenttypes',
+    'django.contrib.sessions',
+    'django.contrib.messages',
+    'django.contrib.staticfiles',
+    'rest_framework',
+    'headless',  # Add this
+    # ... your apps
+]
+
+# Optional: add the lookup filter backend
+REST_FRAMEWORK = {
+    "DEFAULT_FILTER_BACKENDS": [
+        "headless.rest.filters.LookupFilter",
+    #... other DRF config
+}
+```
+
+### Create Your First Headless Model
+
+```python
+# models.py
+from django.db import models
+from headless import headless
+
+@headless()
+class BlogPost(models.Model):
+    title = models.CharField(max_length=200)
+    content = models.TextField()
+    published = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return self.title
+```
+
+### Add URLs
+
+```python
+# urls.py
+from django.contrib import admin
+from django.urls import path, include
+
+urlpatterns = [
+    path('admin/', admin.site.urls),
+    path('api/', include('headless.urls')),
+]
+```
+
+That's it! 🎉 Your model is now available via REST API at `/api/blog-post/`
+
+## 📖 Usage Examples
+
+### Basic Model Registration
+
+```python
+from headless import headless
+
+@headless()
+class Article(models.Model):
+    title = models.CharField(max_length=200)
+    content = models.TextField()
+    author = models.ForeignKey(User, on_delete=models.CASCADE)
+```
+
+**Generated endpoints:**
+- `GET /api/article/` - List all articles
+- `POST /api/article/` - Create new article
+- `GET /api/article/{id}/` - Retrieve specific article
+- `PUT /api/article/{id}/` - Update article
+- `PATCH /api/article/{id}/` - Partially update article
+- `DELETE /api/article/{id}/` - Delete article
+
+### Singleton Models
+
+Perfect for site settings, configurations, or any model that should have only one instance:
+
+```python
+@headless(singleton=True)
+class SiteConfiguration(models.Model):
+    site_name = models.CharField(max_length=100)
+    maintenance_mode = models.BooleanField(default=False)
+    contact_email = models.EmailField()
+    
+    class Meta:
+        verbose_name = "Site Configuration"
+```
+
+**Generated endpoints:**
+- `GET /api/site-configuration/` - Get configuration
+- `PUT /api/site-configuration/` - Update configuration
+- `PATCH /api/site-configuration/` - Partial update
+
+### Advanced Filtering
+
+Django Headless supports Django ORM lookups for powerful filtering.
+Add the LookupFilter backend to your default filter backends:
+
+```python
+REST_FRAMEWORK = {
+    "DEFAULT_FILTER_BACKENDS": [
+        "headless.rest.filters.LookupFilter",
+    #... other DRF config
+}
+```
+
+**Filter examples:**
+```bash
+# Basic filtering
+GET /api/blogpost/?published=true
+
+# Field lookups
+GET /api/blogpost/?title__icontains=django
+GET /api/blogpost/?created_at__gte=2023-01-01
+GET /api/blogpost/?author__username=john
+
+# Multiple filters
+GET /api/blogpost/?published=true&created_at__year=2023
+```
+
+Values are automatically cast based on the field type. Booleans can be represented
+as `true`, `1` or `on` (and `false`, `0` or `off`). Multi-value lookups can be comma-separated (e.g. `id__in=1,2,3`).
+
+
+## 🎛️ Configuration Options
+
+The `@headless` decorator accepts the following configuration options:
+
+| Option | Type | Default | Description                                                        |
+|--------|------|---------|--------------------------------------------------------------------|
+| `singleton` | `bool` | `False` | Creates singleton endpoints (no create, list and delete endpoints) |
+
+
+
+### Global Settings
+
+```python
+# settings.py
+HEADLESS =  {
+    "NON_FILTER_FIELDS": [
+        "search",
+        "limit",
+        "page",
+        "fields",
+        "exclude",
+        "expand",
+    ],
+    "FILTER_EXCLUSION_SYMBOL": "~",
+}
+```
+
+## 🛠️ Requirements
+
+- Python 3.10+
+- Django 5.0+
+- Django REST Framework 3.16+
+
+## 🤝 Contributing
+
+We welcome contributions! Here's how to get started:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for your changes
+5. Run the test suite (`python manage.py test`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/StructuralRealist/django-headless.git
+cd django-headless
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements-dev.txt
+
+# Run tests
+python manage.py test
+
+# Run example project
+cd example_project
+python manage.py migrate
+python manage.py runserver
+```
+
+## 📚 Documentation
+
+For detailed documentation, visit [djangoheadless.org](https://djangoheadless.org)
+
+## 🐛 Issues & Support
+
+- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/StructuralRealist/django-headless/issues)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/StructuralRealist/django-headless/discussions)
+- 📧 **Email**: leon@devtastic.io
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built on the shoulders of [Django](https://www.djangoproject.com/) and [Django REST Framework](https://www.django-rest-framework.org/)
+- Inspired by the headless CMS and Jamstack movement
+- Thanks to all contributors and the Django community
+
+## 🔗 Links
+
+- [PyPI Package](https://pypi.org/project/django-headless/)
+- [Documentation](https:/djangoheadless.org)
+- [GitHub Repository](https://github.com/StructuralRealist/django-headless)
+- [Changelog](CHANGELOG.md)
+
+---
+
+Made in Europe 🇪🇺 with 💚 for Django

django_headless-1.0.0b1/headless/__init__.py

@@ -0,0 +1,30 @@
+__title__ = "Django Headless"
+__version__ = "1.0.0-beta.1"
+__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 headless(singleton=False):
+    """
+    Decorator to register a Django model to a registry.
+
+    Usage:
+        @headless()
+        class MyModel(models.Model):
+            pass
+    """
+
+    def decorator(model_class: Type[models.Model]):
+        headless_registry.register(model_class, singleton=singleton)
+
+        return model_class
+
+    return decorator

django_headless-1.0.0b1/headless/apps.py

@@ -0,0 +1,27 @@
+from django.apps import AppConfig
+
+from . import VERSION
+from .utils import is_runserver, log
+
+
+class DjangoHeadlessConfig(AppConfig):
+    name = "headless"
+    label = "headless"
+
+    def ready(self):
+        from .registry import headless_registry
+
+        if is_runserver():
+            log("\n")
+            log("----------------------------------------")
+            log("Django Headless")
+            log(f"Version {VERSION}")
+            log("----------------------------------------")
+            log(":mag:", "Registering models...")
+            log(
+                ":white_check_mark:",
+                f"[green]Found {len(headless_registry)} registered models:[/green]",
+            )
+            for model_config in headless_registry.get_models():
+                model = model_config["model"]
+                print(f"   - {model._meta.verbose_name} ({model.__name__})")

django_headless-1.0.0b1/headless/registry.py

@@ -0,0 +1,52 @@
+from typing import Type, Dict, Optional, TypedDict
+
+from django.db import models
+
+
+class ModelConfig(TypedDict):
+    model: Type[models.Model]
+    singleton: bool
+
+
+class HeadlessRegistry:
+    """
+    A registry to store registered Django models.
+    """
+
+    def __init__(self):
+        self._models: Dict[str, ModelConfig] = {}
+
+    def register(self, model_class: Type[models.Model], singleton=False):
+        """
+        Register a model in the registry.
+
+        Args:
+            model_class: The Django model class to register
+            singleton: Whether the model should be registered as a singleton
+        """
+        self._models[model_class._meta.label_lower] = {
+            "model": model_class,
+            "singleton": singleton,
+        }
+
+    def get_model(self, label: str) -> Optional[ModelConfig]:
+        """
+        Get a model by label.
+
+        Args:
+            label: The label of the model to get.
+        """
+        return self._models.get(label.lower())
+
+    def get_models(self) -> list[ModelConfig]:
+        """
+        Get all registered models.
+        """
+        return list(self._models.values())
+
+    def __len__(self):
+        return len(self._models)
+
+
+# Create a default registry
+headless_registry = HeadlessRegistry()

django_headless-1.0.0b1/headless/rest/__init__.py

@@ -0,0 +1 @@
+default_app_config = "headless.rest.apps.DjangoHeadlessRestConfig"

django_headless-1.0.0b1/headless/rest/apps.py

@@ -0,0 +1,73 @@
+from django.apps import AppConfig
+
+from ..utils import is_runserver, camel_to_kebab
+
+
+class DjangoHeadlessRestConfig(AppConfig):
+    name = "headless.rest"
+    label = "headless_rest"
+
+    def ready(self):
+        from django.urls import path
+        from rest_framework import serializers
+        from rest_framework.viewsets import ModelViewSet
+        from ..registry import headless_registry
+        from ..utils import log
+        from .routers import rest_router
+        from .urls import urlpatterns
+        from .viewsets import SingletonViewSet
+
+        if is_runserver():
+            log(":building_construction:", "Setting up REST routes")
+            models = headless_registry.get_models()
+
+            for model_config in models:
+                model_class = model_config["model"]
+                singleton = model_config["singleton"]
+                base_path = camel_to_kebab(model_class.__name__)
+
+                class Serializer(serializers.ModelSerializer):
+                    class Meta:
+                        model = model_class
+                        fields = "__all__"
+
+                if singleton:
+
+                    class ViewSet(SingletonViewSet):
+                        queryset = model_class.objects.first()
+                        serializer_class = Serializer
+
+                    log("   ---", f"{model_class._meta.verbose_name}")
+                    log("     |---", f"GET /{base_path}")
+                    log("     |---", f"PUT /{base_path}")
+                    log("     |---", f"PATCH /{base_path}")
+                    log("\n")
+                    urlpatterns.append(
+                        path(
+                            base_path,
+                            ViewSet.as_view(
+                                {
+                                    "get": "retrieve",
+                                    "put": "update",
+                                    "patch": "partial_update",
+                                }
+                            ),
+                        )
+                    )
+
+                else:
+
+                    class ViewSet(ModelViewSet):
+                        queryset = model_class.objects.all()
+                        serializer_class = Serializer
+
+                    log("   ---", f"{model_class._meta.verbose_name}")
+                    log("     |--", f"GET /{base_path}")
+                    log("     |--", f"GET /{base_path}/{{id}}")
+                    log("     |--", f"PUT /{base_path}/{{id}}")
+                    log("     |--", f"PATCH /{base_path}/{{id}}")
+                    log("     |--", f"POST /{base_path}")
+                    log("     |--", f"DELETE /{base_path}/{{id}}")
+                    log("\n")
+
+                    rest_router.register(base_path, ViewSet)

django_headless-1.0.0b1/headless/rest/filters.py

@@ -0,0 +1,121 @@
+from decimal import Decimal
+
+from django.db import models
+from rest_framework.exceptions import ParseError
+from rest_framework.filters import BaseFilterBackend
+
+from ..settings import headless_settings
+from ..utils import flatten
+
+
+class LookupFilter(BaseFilterBackend):
+    """
+    A permissive filter backend that basically allows every supported lookup
+    for a given field. Automatically handles multi-value lookups and booleans.
+    Also supports exclusion.
+    """
+
+    MULTI_VALUE_LOOKUPS = ["in", "range"]
+
+    EXCLUDE_SYMBOL = headless_settings.FILTER_EXCLUSION_SYMBOL
+
+    NON_FILTER_FIELDS = headless_settings.NON_FILTER_FIELDS
+
+    def filter_queryset(self, request, queryset, view):
+        """
+        Build the queryset based on the query params and the view's model.
+        Only apply filters in list endpoints.
+        """
+        if getattr(view, "action", None) == "list":
+            try:
+                filter_kwargs, exclude_kwargs = self.get_filter_kwargs(
+                    model_class=view.queryset.model,
+                    query_params=request.query_params,
+                )
+            except Exception as e:
+                print(e)
+                raise ParseError(detail="Invalid filter parameters")
+            return queryset.filter(**filter_kwargs).exclude(**exclude_kwargs).distinct()
+
+        return queryset
+
+    def get_filter_kwargs(self, model_class, query_params):
+        filter_kwargs = {}
+        exclude_kwargs = {}
+
+        field_lookups = self.get_field_lookups(model_class=model_class)
+
+        for key, value in query_params.lists():
+            if key in self.NON_FILTER_FIELDS:
+                continue
+            # By default Django supports repeated multi-values (e.g. `a=1&a=2`)
+            # but we allow for comma-seperated multi-values as well (e.g. `a=1,2`).
+            value = flatten([param.split(",") for param in value])
+            is_exclude = key.startswith(self.EXCLUDE_SYMBOL)
+            # The first part of a key is considered the field name
+            field_name = key.split("__")[0]
+            # Get the model field.
+            field = model_class._meta.get_field(field_name)
+            # Get the allowed lookups for this field.
+            lookups = field_lookups.get(field_name, [])
+            try:
+                # The last part of a key is considered its lookup
+                # but it's not required.
+                lookup = key.split("__")[-1]
+                if lookup not in lookups:
+                    lookup = None
+            except IndexError:
+                lookup = None
+
+            # Some lookups allow multiple values, otherwise
+            # the first value is used.
+            is_multi = lookup in self.MULTI_VALUE_LOOKUPS
+            # Depending on the field type we cast the value to
+            # its correct type (i.e. number, boolean, etc.).
+            if is_multi:
+                casted_value = [self.cast_field_value(v, field) for v in value]
+            elif lookup == "isnull":
+                casted_value = value[0] in ["1", "true", "on"]
+            else:
+                casted_value = self.cast_field_value(value[0], field)
+
+            if is_exclude:
+                exclude_kwargs[key] = casted_value
+            else:
+                filter_kwargs[key] = casted_value
+
+        return filter_kwargs, exclude_kwargs
+
+    @staticmethod
+    def get_field_lookups(model_class):
+        """
+        Allow all supported lookups.
+        """
+        field_lookups = {}
+        for model_field in model_class._meta.get_fields():
+            lookup_list = model_field.get_lookups().keys()
+            field_lookups[model_field.name] = lookup_list
+        return field_lookups
+
+    def cast_field_value(self, value: str, field):
+        value = value.strip().lower()
+
+        if isinstance(field, models.BooleanField):
+            if value in ["1", "true", "on"]:
+                return True
+            if value in ["0", "false", "off"]:
+                return False
+        if isinstance(field, models.NullBooleanField):
+            if value in ["null", "none", "empty"]:
+                return None
+
+        if isinstance(field, models.IntegerField):
+            return int(value)
+
+        if isinstance(field, models.DecimalField):
+            return Decimal(value)
+
+        if isinstance(field, models.FloatField):
+            return float(value)
+
+        return value

django_headless-1.0.0b1/headless/rest/routers.py

@@ -0,0 +1,3 @@
+from rest_framework.routers import DefaultRouter
+
+rest_router = DefaultRouter(trailing_slash=False)

django_headless-1.0.0b1/headless/rest/urls.py

@@ -0,0 +1,3 @@
+from .routers import rest_router
+
+urlpatterns = rest_router.urls

django_headless-1.0.0b1/headless/rest/viewsets.py

@@ -0,0 +1,41 @@
+from rest_framework.exceptions import NotFound
+from rest_framework.viewsets import GenericViewSet
+from rest_framework.mixins import (
+    CreateModelMixin,
+    UpdateModelMixin,
+    RetrieveModelMixin,
+)
+
+
+class SingletonViewSet(
+    GenericViewSet,
+    CreateModelMixin,
+    UpdateModelMixin,
+    RetrieveModelMixin,
+):
+    """
+    A model view set for singleton objects.
+    """
+
+    def update(self, request, *args, **kwargs):
+        """
+        If a singleton doesn't exist, it will be created.
+        """
+        try:
+            return super().update(request, *args, **kwargs)
+        except NotFound:
+            return self.create(request, *args, **kwargs)
+
+    def get_object(self):
+        """
+        Get the first object of the queryset (assuming there is only one object).
+        If a singleton doesn't exist, it will raise a NotFound exception.
+        """
+        obj = self.get_queryset().first()
+
+        if not obj:
+            raise NotFound()
+
+        self.check_object_permissions(self.request, obj)
+
+        return obj

django_headless-1.0.0b1/headless/settings.py

@@ -0,0 +1,144 @@
+"""
+Settings for Django Headless are all namespaced in the HEADLESS setting.
+For example, your project's `settings.py` file might look like this:
+
+HEADLESS = {
+    'FILTER_EXCLUSION_SYMBOL': 'exclude_'
+}
+
+This module provides the `headless_settings` object, that is used to access
+Django Headless settings, checking for user settings first, then falling
+back to the defaults.
+"""
+
+from django.conf import settings
+
+from django.core.signals import setting_changed
+from django.utils.module_loading import import_string
+
+SETTINGS_NAMESPACE = "HEADLESS"
+
+DEFAULTS = {
+    "NON_FILTER_FIELDS": [
+        "search",
+        "limit",
+        "page",
+        "fields",
+        "exclude",
+        "expand",
+    ],
+    "FILTER_EXCLUSION_SYMBOL": "~",
+}
+
+
+# List of settings that may be in string import notation.
+IMPORT_STRINGS = []
+
+
+# List of settings that have been removed
+REMOVED_SETTINGS = []
+
+
+def perform_import(val, setting_name):
+    """
+    If the given setting is a string import notation,
+    then perform the necessary import or imports.
+    """
+    if val is None:
+        return None
+    elif isinstance(val, str):
+        return import_from_string(val, setting_name)
+    elif isinstance(val, (list, tuple)):
+        return [import_from_string(item, setting_name) for item in val]
+    return val
+
+
+def import_from_string(val, setting_name):
+    """
+    Attempt to import a class from a string representation.
+    """
+    try:
+        return import_string(val)
+    except ImportError as e:
+        msg = "Could not import '%s' for Headless setting '%s'. %s: %s." % (
+            val,
+            setting_name,
+            e.__class__.__name__,
+            e,
+        )
+        raise ImportError(msg)
+
+
+class HeadlessSettings:
+    """
+    A settings object that allows Django Headless settings to be accessed as
+    properties. For example:
+
+        from headless.settings import headless_settings
+        print(headless_settings.SINGLETON_ATTR)
+
+    Any setting with string import paths will be automatically resolved
+    and return the class, rather than the string literal.
+    """
+
+    def __init__(self, user_settings=None, defaults=None, import_strings=None):
+        if user_settings:
+            self._user_settings = self.__check_user_settings(user_settings)
+        self.defaults = defaults or DEFAULTS
+        self.import_strings = import_strings or IMPORT_STRINGS
+        self._cached_attrs = set()
+
+    @property
+    def user_settings(self):
+        if not hasattr(self, "_user_settings"):
+            self._user_settings = getattr(settings, SETTINGS_NAMESPACE, {})
+        return self._user_settings
+
+    def __getattr__(self, attr):
+        if attr not in self.defaults:
+            raise AttributeError("Invalid Headless setting: '%s'" % attr)
+
+        try:
+            # Check if present in user settings
+            val = self.user_settings[attr]
+        except KeyError:
+            # Fall back to defaults
+            val = self.defaults[attr]
+
+        # Coerce import strings into classes
+        if attr in self.import_strings:
+            val = perform_import(val, attr)
+
+        # Cache the result
+        self._cached_attrs.add(attr)
+        setattr(self, attr, val)
+        return val
+
+    def __check_user_settings(self, user_settings):
+        SETTINGS_DOC = "https://www.djangoheadless.org/"
+        for setting in REMOVED_SETTINGS:
+            if setting in user_settings:
+                raise RuntimeError(
+                    "The '%s' setting has been removed. Please refer to '%s' for available settings."
+                    % (setting, SETTINGS_DOC)
+                )
+        return user_settings
+
+    def reload(self):
+        for attr in self._cached_attrs:
+            delattr(self, attr)
+        self._cached_attrs.clear()
+        if hasattr(self, "_user_settings"):
+            delattr(self, "_user_settings")
+
+
+headless_settings = HeadlessSettings(None, DEFAULTS, IMPORT_STRINGS)
+
+
+def reload_settings(*args, **kwargs):
+    setting = kwargs["setting"]
+    if setting == SETTINGS_NAMESPACE:
+        headless_settings.reload()
+
+
+setting_changed.connect(reload_settings)

django_headless-1.0.0b1/headless/tests.py

@@ -0,0 +1 @@
+# Create your tests here.

django_headless-1.0.0b1/headless/utils.py

@@ -0,0 +1,53 @@
+import json
+import re
+import sys
+
+from rich.console import Console
+
+console = Console()
+
+
+def log(*args, **kwargs):
+    console.print(*args, **kwargs)
+
+
+def is_jsonable(x):
+    try:
+        json.dumps(x)
+        return True
+    except (TypeError, OverflowError):
+        return False
+
+
+def is_runserver():
+    """
+    Checks if the Django application is started as a server.
+    We'll also assume it started if manage.py is not used (e.g. when Django is started using wsgi/asgi).
+    The main purpose of this check is to not run certain code on other management commands such
+    as `migrate`.
+    """
+    is_manage_cmd = sys.argv[0].endswith("/manage.py")
+
+    return not is_manage_cmd or sys.argv[1] == "runserver"
+
+
+def flatten(xss):
+    return [x for xs in xss for x in xs]
+
+
+def camel_to_kebab(text: str) -> str:
+    """
+    Simpler function that handles basic PascalCase/camelCase conversion.
+
+    Args:
+        text (str): The input string in PascalCase or camelCase
+
+    Returns:
+        str: The converted string in kebab-case
+    """
+    if not text:
+        return text
+
+    # Insert hyphen before any uppercase letter that follows a lowercase letter
+    result = re.sub(r"([a-z])([A-Z])", r"\1-\2", text)
+    return result.lower()

django_headless-1.0.0b1/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "django-headless"
+version = "1.0.0-beta.1"
+description = "Automagically create a REST API for you Django models"
+authors = [
+    {name = "Leon van der Grient",email = "leon@devtastic.io"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "rich"
+]
+
+[tool.poetry]
+packages = [{include = "headless"}]
+
+[tool.poetry.group.dev.dependencies]
+black = "^25.1.0"
+Django= "^5.2.4"
+djangorestframework= "^3.16.0"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"