django-htmx-base 0.1.2__tar.gz

django_htmx_base-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 retriever-laboratories
+
+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_htmx_base-0.1.2/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: django-htmx-base
+Version: 0.1.2
+Summary: A collection of classes and abstract models for django + htmx projects
+Author-email: Jorge Guerra <jorge@retlabs.cl>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/retriever-laboratories/django-htmx-base
+Keywords: Django,HTMX
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=6.0.2
+Requires-Dist: django-htmx>=1.27.0
+Dynamic: license-file
+
+# django-htmx-base
+
+`django-htmx-base` is a lightweight Django library that provides viewsets, formsets, automated routers, and abstract models designed to eliminate CRUD boilerplate in Django + HTMX projects.
+
+
+---
+
+## Requirements
+
+Before installing, ensure your environment meets the following requirements:
+* **Python:** 3.12+
+* **Django:** 6.0+
+* **django-htmx:** 1.27+
+
+---
+
+## Installation & Quick Start
+
+### 1. Installation
+
+Install directly from GitHub via VCS (version 0.1.1):
+
+**uv:**
+```bash
+uv add git+https://github.com
+```
+
+**pip:**
+```bash
+python -m pip install git+https://github.com
+```
+
+### 2. Configure Django Settings
+
+Add the core application configuration and the required HTMX middleware to your project's `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_htmx",
+    "django_htmx_base",
+]
+
+MIDDLEWARE = [
+    # ...
+    "django_htmx.middleware.HtmxMiddleware",
+]
+```
+
+---
+
+## Usage Guide
+
+### 1. Abstract Models
+
+Inherit from `BaseModel` to quickly apply standard architecture baselines to your database layers:
+
+```python
+# my_app/models.py
+from django.db import models
+from django.urls import reverse
+from django_htmx_base.models import BaseModel
+
+class Product(BaseModel):
+    name = models.CharField(max_length=256, unique=True)
+    description = models.TextField(blank=True)
+
+    class Meta:
+        ordering = ['-id']
+```
+
+Execute your migrations normally inside your primary project environment:
+
+```bash
+python manage.py makemigrations
+python manage.py migrate
+```
+
+### 2. Viewsets and Routing
+
+Combine viewsets and routers to eliminate boilerplate URL configurations and automatically expose structural HTMX URLs to your templates.
+
+```python
+# my_app/views.py
+from django_htmx_base.viewsets import GenericHtmxViewSet
+from .models import Product
+
+class ProductViewSet(GenericHtmxViewSet):
+    """
+    Handles standard CRUD actions and automatically provides 
+    the `view.url_names` context object to your templates.
+    """
+    model = Product
+```
+
+#### Registering the Viewset
+
+Use the `HTMXRouter` to map your viewset to standard URL endpoints seamlessly:
+
+```python
+# my_app/urls.py
+from django.urls import path, include
+from django_htmx_base.routers import HTMXRouter
+from .views import ProductViewSet
+
+router = HTMXRouter()
+router.register(ProductViewSet)
+
+app_name = "my_app"
+
+urlpatterns = [
+    path("products/", include(router.urls)),
+]
+```
+
+### 3. Automated View Routing and Context
+
+The viewset automatically discovers templates inside your application's `templates/[app_label]/` directory. Out of the box, it checks for a modern nested model directory first and falls back to a flat hyphenated filename. 
+
+To enable generic, model-agnostic app fallbacks (e.g., sharing one `list.html` across multiple models), you must explicitly set `use_app_templates = True` on your viewset.
+
+For a viewset handling a `Product` model inside a `products` app, the engine searches for templates in this order:
+
+1. **Nested Model Folder (Default):** `templates/products/product/list.html`
+2. **Flat Model Fallback (Default):** `templates/products/product-list.html`
+3. **Generic App Fallback:** `templates/products/list.html` *(Requires `use_app_templates = True`)*
+
+#### Example Viewset Configuration
+```python
+class ProductViewSet(GenericHtmxViewSet):
+    model = Product
+    
+    # Optional: Enable the generic app-level fallback template
+    use_app_templates = True 
+```
+
+Expose standard execution paths seamlessly to your user interface templates via integrated property-driven attributes:
+
+```html
+<!-- Generic Template Table Row Actions Component -->
+{% for obj in object_list %}
+<tr>
+    <td>{{ obj.name }}</td>
+    <td>
+        <!-- Dynamically resolves view.basename + your htmx action settings safely -->
+        <button hx-get="{% url view.url_names.edit pk=obj.pk %}" hx-target="#modal">Edit</button>
+        <button hx-delete="{% url view.url_names.delete pk=obj.pk %}" hx-confirm="Are you sure?">Delete</button>
+    </td>
+</tr>
+{% endfor %}
+```
+
+---
+
+## Local Development & Contribution
+
+If you want to modify this library, run its independent isolated test sandbox, or contribute fixes, set up your standalone repository workspace:
+
+### 1. Setup Environment
+
+```bash
+# Clone the repository
+git clone https://github.com
+cd django-htmx-base
+
+# Create and activate a standard virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
+
+# Install the package in editable mode with test suites dependencies
+pip install -e .[dev]
+```
+
+### 2. Running the Test Suite
+
+Execute the local test suite runner directly via standard python commands:
+
+```bash
+python runtests.py
+```
+
+If you use the **uv** package manager, you can bypass explicit manual virtual environment setups entirely and execute everything inside an isolated wrapper on the fly:
+
+```bash
+uv run python runtests.py
+```

django_htmx_base-0.1.2/README.md

@@ -0,0 +1,186 @@
+# django-htmx-base
+
+`django-htmx-base` is a lightweight Django library that provides viewsets, formsets, automated routers, and abstract models designed to eliminate CRUD boilerplate in Django + HTMX projects.
+
+
+---
+
+## Requirements
+
+Before installing, ensure your environment meets the following requirements:
+* **Python:** 3.12+
+* **Django:** 6.0+
+* **django-htmx:** 1.27+
+
+---
+
+## Installation & Quick Start
+
+### 1. Installation
+
+Install directly from GitHub via VCS (version 0.1.1):
+
+**uv:**
+```bash
+uv add git+https://github.com
+```
+
+**pip:**
+```bash
+python -m pip install git+https://github.com
+```
+
+### 2. Configure Django Settings
+
+Add the core application configuration and the required HTMX middleware to your project's `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_htmx",
+    "django_htmx_base",
+]
+
+MIDDLEWARE = [
+    # ...
+    "django_htmx.middleware.HtmxMiddleware",
+]
+```
+
+---
+
+## Usage Guide
+
+### 1. Abstract Models
+
+Inherit from `BaseModel` to quickly apply standard architecture baselines to your database layers:
+
+```python
+# my_app/models.py
+from django.db import models
+from django.urls import reverse
+from django_htmx_base.models import BaseModel
+
+class Product(BaseModel):
+    name = models.CharField(max_length=256, unique=True)
+    description = models.TextField(blank=True)
+
+    class Meta:
+        ordering = ['-id']
+```
+
+Execute your migrations normally inside your primary project environment:
+
+```bash
+python manage.py makemigrations
+python manage.py migrate
+```
+
+### 2. Viewsets and Routing
+
+Combine viewsets and routers to eliminate boilerplate URL configurations and automatically expose structural HTMX URLs to your templates.
+
+```python
+# my_app/views.py
+from django_htmx_base.viewsets import GenericHtmxViewSet
+from .models import Product
+
+class ProductViewSet(GenericHtmxViewSet):
+    """
+    Handles standard CRUD actions and automatically provides 
+    the `view.url_names` context object to your templates.
+    """
+    model = Product
+```
+
+#### Registering the Viewset
+
+Use the `HTMXRouter` to map your viewset to standard URL endpoints seamlessly:
+
+```python
+# my_app/urls.py
+from django.urls import path, include
+from django_htmx_base.routers import HTMXRouter
+from .views import ProductViewSet
+
+router = HTMXRouter()
+router.register(ProductViewSet)
+
+app_name = "my_app"
+
+urlpatterns = [
+    path("products/", include(router.urls)),
+]
+```
+
+### 3. Automated View Routing and Context
+
+The viewset automatically discovers templates inside your application's `templates/[app_label]/` directory. Out of the box, it checks for a modern nested model directory first and falls back to a flat hyphenated filename. 
+
+To enable generic, model-agnostic app fallbacks (e.g., sharing one `list.html` across multiple models), you must explicitly set `use_app_templates = True` on your viewset.
+
+For a viewset handling a `Product` model inside a `products` app, the engine searches for templates in this order:
+
+1. **Nested Model Folder (Default):** `templates/products/product/list.html`
+2. **Flat Model Fallback (Default):** `templates/products/product-list.html`
+3. **Generic App Fallback:** `templates/products/list.html` *(Requires `use_app_templates = True`)*
+
+#### Example Viewset Configuration
+```python
+class ProductViewSet(GenericHtmxViewSet):
+    model = Product
+    
+    # Optional: Enable the generic app-level fallback template
+    use_app_templates = True 
+```
+
+Expose standard execution paths seamlessly to your user interface templates via integrated property-driven attributes:
+
+```html
+<!-- Generic Template Table Row Actions Component -->
+{% for obj in object_list %}
+<tr>
+    <td>{{ obj.name }}</td>
+    <td>
+        <!-- Dynamically resolves view.basename + your htmx action settings safely -->
+        <button hx-get="{% url view.url_names.edit pk=obj.pk %}" hx-target="#modal">Edit</button>
+        <button hx-delete="{% url view.url_names.delete pk=obj.pk %}" hx-confirm="Are you sure?">Delete</button>
+    </td>
+</tr>
+{% endfor %}
+```
+
+---
+
+## Local Development & Contribution
+
+If you want to modify this library, run its independent isolated test sandbox, or contribute fixes, set up your standalone repository workspace:
+
+### 1. Setup Environment
+
+```bash
+# Clone the repository
+git clone https://github.com
+cd django-htmx-base
+
+# Create and activate a standard virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
+
+# Install the package in editable mode with test suites dependencies
+pip install -e .[dev]
+```
+
+### 2. Running the Test Suite
+
+Execute the local test suite runner directly via standard python commands:
+
+```bash
+python runtests.py
+```
+
+If you use the **uv** package manager, you can bypass explicit manual virtual environment setups entirely and execute everything inside an isolated wrapper on the fly:
+
+```bash
+uv run python runtests.py
+```

django_htmx_base-0.1.2/django_htmx_base/admin.py

@@ -0,0 +1 @@
+# Register your models here.

django_htmx_base-0.1.2/django_htmx_base/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class BaseConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_htmx_base"
+    label = "base"

django_htmx_base-0.1.2/django_htmx_base/forms.py

@@ -0,0 +1,20 @@
+# django
+from django import forms
+
+# widgets
+from django_htmx_base.widgets import WidgetStylerMixin
+
+
+class BaseForm(WidgetStylerMixin, forms.Form):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.apply_widget_styles()
+
+
+class BaseModelForm(WidgetStylerMixin, forms.ModelForm):
+    class Meta:
+        fields = "__all__"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.apply_widget_styles()

django_htmx_base-0.1.2/django_htmx_base/models.py

@@ -0,0 +1,210 @@
+# standard
+import csv
+from enum import StrEnum
+from io import StringIO
+
+# django
+from django.db import models
+
+
+class FilterInputType(StrEnum):
+    CHECKBOX = "checkbox"
+    DATE = "date"
+    DATETIME_LOCAL = "datetime-local"
+    MULTISELECT = "multiselect"
+    NUMBER = "number"
+    RADIO = "radio"
+    RANGE = "range"
+    SELECT = "select"
+    TEXT = "text"
+    TIME = "time"
+
+
+def BaseField(base_field_class, **kwargs):  # noqa: N802
+    sortable = kwargs.pop("sortable", False)
+    partial = kwargs.pop("partial", None)
+    css_class = kwargs.pop("css_class", "")
+    filtrable = kwargs.pop("filtrable", False)
+    filter_input_type = FilterInputType(
+        kwargs.pop("filter_input_type", FilterInputType.TEXT)
+    )
+
+    field = base_field_class(**kwargs)
+    field.sortable = sortable
+    field.partial = partial
+    field.css_class = css_class
+    field.filtrable = filtrable
+    field.filter_input_type = filter_input_type
+
+    return field
+
+
+class BaseModel(models.Model):
+    """
+    Abstract base for all models
+    """
+
+    # fields
+    created_at = BaseField(
+        models.DateTimeField, auto_now_add=True, editable=False, sortable=True
+    )
+    updated_at = BaseField(models.DateTimeField, auto_now=True, editable=False)
+    is_active = BaseField(
+        models.BooleanField,
+        default=True,
+        filtrable=True,
+        filter_input_type=FilterInputType.SELECT,
+    )
+
+    # view attributes
+    _display_fields = ["id", "created_at", "is_active"]
+    _downloadable = True
+
+    class Meta:
+        abstract = True
+        ordering = ("-created_at",)
+
+    def __str__(self) -> str:
+        return f"{self.__class__.__name__}(id={getattr(self, 'id', None)})"
+
+    @classmethod
+    def get_filtrable_fields(cls):
+        """
+        Returns context-ready filter metadata for each filtrable field.
+        """
+        return [
+            field
+            for field in cls.get_display_fields()
+            if getattr(field, "filtrable", False)
+        ]
+
+    @classmethod
+    def get_filters_objects(cls):
+        filters = []
+
+        for field in cls.get_filtrable_fields():
+            filter_config = {
+                "field": field.name,
+                "filter_input_type": getattr(
+                    field, "filter_input_type", FilterInputType.TEXT
+                ).value,
+            }
+
+            if hasattr(field, "choices") and field.choices:
+                filter_config["options"] = [
+                    {"value": value, "label": label}
+                    for value, label in field.choices
+                    if value not in (None, "")
+                ]
+            elif isinstance(field, models.BooleanField):
+                filter_config["options"] = [
+                    {"value": "True", "label": "True"},
+                    {"value": "False", "label": "False"},
+                ]
+
+            filters.append(filter_config)
+
+        return filters
+
+    @property
+    def filters(self):
+        return self.get_filtrable_fields()
+
+    @property
+    def filters_objects(self):
+        return self.get_filters_objects()
+
+    @classmethod
+    def sortable_fields(cls):
+        """
+        Returns a list of fields that are sortable.
+        """
+        return [
+            field.name
+            for field in cls.get_display_fields()
+            if getattr(field, "sortable", False)
+        ]
+
+    @classmethod
+    def get_display_fields(cls):
+        return [
+            field
+            for field in cls._meta.get_fields()
+            if field.name in cls._display_fields
+        ]
+
+    @property
+    def display_fields(self):
+        return self.get_display_fields()
+
+    def as_list(self):
+        """Ordered values for this instance, matching ``display_fields`` order."""
+        values = []
+        for field in self.display_fields:
+            if getattr(field, "choices", None):
+                value = getattr(self, f"get_{field.name}_display")()
+            else:
+                value = getattr(self, field.name)
+
+            values.append(value)
+
+        return values
+
+    def as_field_values_objects_list(self):
+        """Ordered cells for this instance, matching ``display_fields`` order."""
+        field_objects = []
+
+        for field in self.display_fields:
+            if getattr(field, "choices", None):
+                value = getattr(self, f"get_{field.name}_display")()
+            else:
+                value = getattr(self, field.name)
+
+            field_objects.append(
+                {
+                    "field": field.name,
+                    "value": value,
+                    "partial": getattr(field, "partial", None),
+                    "class": getattr(field, "css_class", ""),
+                }
+            )
+
+        return field_objects
+
+    @classmethod
+    def to_csv(cls, queryset):
+        output = StringIO(newline="")
+        writer = csv.writer(output)
+        writer.writerow(field.name for field in cls.get_display_fields())
+
+        for object in queryset:
+            writer.writerow(object.as_list())
+
+        return output.getvalue()
+
+    @classmethod
+    def as_field_names_objects_list(cls):
+        columns = []
+
+        for field in cls.get_display_fields():
+            column = {
+                "field": field.name,
+                "sortable": getattr(field, "sortable", False),
+                "filtrable": getattr(field, "filtrable", False),
+            }
+
+            partial = getattr(field, "partial", None)
+            if partial:
+                column["partial"] = partial
+
+            css_class = getattr(field, "css_class", None)
+            if css_class:
+                column["class"] = css_class
+
+            columns.append(column)
+
+        return columns
+
+    @classmethod
+    def is_downloadable(cls):
+        return cls._downloadable