djcrud 0.2.0__tar.gz

djcrud-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test-python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - uses: browser-actions/setup-firefox@latest
+      - uses: browser-actions/setup-geckodriver@latest
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install package and test dependencies
+        run: |
+          pip install -U pip
+          pip install -U django
+          pip install --pre -e ".[dev]"
+
+      - name: Run unit and integration tests
+        run: pytest -m "not splinter" -n auto
+
+      - name: Run browser tests
+        run: pytest -m splinter -n 0 --splinter-headless
+
+  test-js:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - run: npm ci
+      - run: npm test

djcrud-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Docs
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package and doc dependencies
+        run: pip install --pre -e ".[dev,docs]" -r docs/requirements.txt
+
+      - name: Validate tutorial example apps
+        run: pytest -m tutorial -n 0
+
+      - name: Build Sphinx HTML
+        run: make -C docs html
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

djcrud-0.2.0/.github/workflows/install-test.yml

@@ -0,0 +1,81 @@
+name: Installation Test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install djcrud
+        run: |
+          pip install -U pip
+          pip install --pre .
+
+      - name: Create test Django project
+        run: |
+          mkdir -p /tmp/djcrud-test
+          cd /tmp/djcrud-test
+          django-admin startproject testproject
+          cd testproject
+
+      - name: Configure settings
+        run: |
+          cd /tmp/djcrud-test/testproject
+          cat >> testproject/settings.py << 'EOF'
+
+          # djcrud configuration
+          import djcrud.settings
+
+          INSTALLED_APPS = djcrud.settings.INSTALLED_APPS + [
+              "django.contrib.admin",
+              "django.contrib.auth",
+              "django.contrib.contenttypes",
+              "django.contrib.sessions",
+              "django.contrib.messages",
+              "django.contrib.staticfiles",
+          ]
+
+          MIDDLEWARE = [
+              "django.middleware.security.SecurityMiddleware",
+              "django.contrib.sessions.middleware.SessionMiddleware",
+              "djcrud_api.middleware.BearerCsrfMiddleware",
+              "django.middleware.locale.LocaleMiddleware",
+              "django.middleware.common.CommonMiddleware",
+              "django.middleware.csrf.CsrfViewMiddleware",
+              "django.contrib.auth.middleware.AuthenticationMiddleware",
+              "djcrud_api.middleware.BearerUserMiddleware",
+              "django.contrib.messages.middleware.MessageMiddleware",
+              "django.middleware.clickjacking.XFrameOptionsMiddleware",
+          ]
+          EOF
+
+      - name: Configure URLs
+        run: |
+          cd /tmp/djcrud-test/testproject
+          cat > testproject/urls.py << 'EOF'
+          from django.contrib import admin
+          from django.urls import path
+          import djcrud
+
+          urlpatterns = djcrud.site.build().urlpatterns + [
+              path("admin/", admin.site.urls),
+          ]
+          EOF
+
+      - name: Run migrations
+        run: |
+          cd /tmp/djcrud-test/testproject
+          python manage.py migrate --no-input
+
+      - name: Verify installation
+        run: |
+          cd /tmp/djcrud-test/testproject
+          python manage.py check

djcrud-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  test-python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - uses: browser-actions/setup-firefox@latest
+      - uses: browser-actions/setup-geckodriver@latest
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install package and test dependencies
+        run: |
+          pip install -U pip
+          pip install -U django
+          pip install --pre -e ".[dev]"
+
+      - name: Run unit and integration tests
+        run: pytest -m "not splinter" -n auto
+
+      - name: Run browser tests
+        run: pytest -m splinter -n 0 --splinter-headless
+
+  test-js:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - run: npm ci
+      - run: npm test
+
+  publish:
+    needs: [test-python, test-js]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

djcrud-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__
+db.sqlite3
+docs/_build/
+.claude/
+build/
+dist/
+node_modules/
+*egg-info*
+tests.test_*/
+/screenshots/

djcrud-0.2.0/CLAUDE.md

@@ -0,0 +1,282 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**djcrud** is a Python/Django MVC framework that provides a thin abstraction layer over Django, enabling faster development through convention over configuration. It removes repetitive wiring while keeping Django's models, permissions, and generic views intact.
+
+- **Language:** Python 3.8+
+- **Framework:** Django 5.1+
+- **Philosophy:** Structure is code, not configuration; sane defaults with surgical overrides
+
+## Common Development Commands
+
+### Running Tests
+
+```bash
+# Fast Python tests (parallel)
+pytest -m "not splinter" -n auto
+
+# Browser tests (serial, requires Firefox + geckodriver)
+pytest -m splinter -n 0 --splinter-headless
+
+# Single test file
+pytest tests/test_stage0.py -v
+
+# JavaScript tests (Vitest with happy-dom)
+npm test
+
+# Tutorial validation
+pytest -m tutorial -n 0
+
+# Full test suite
+tox
+```
+
+**Important Test Markers:**
+- `splinter` - Browser tests; must use `-n 0` (serial execution)
+- `docs_screenshot` - Generates PNG screenshots for documentation
+- `tutorial` - Validates literalinclude paths in docs
+- `django_db` - Tests requiring database access
+
+### Development Setup
+
+```bash
+# Development install with all extras
+pip install --pre -e ".[dev,docs]"
+
+# JavaScript tools (optional, for JS unit tests)
+npm ci
+```
+
+Note: The `--pre` flag is required for pre-release dependency versions (django-autocomplete-light>=5.1).
+
+### Running the Example Project
+
+```bash
+# From repository root
+python manage.py migrate
+python manage.py runserver
+
+# Login at http://localhost:8000/auth/login/
+# Username: su
+# Password: su
+```
+
+The example project in `src/djcrud_example/` includes all djcrud apps and tutorial stages (stage0-4).
+
+### Documentation
+
+```bash
+# Build Sphinx documentation
+make -C docs html
+
+# Regenerate screenshots for documentation
+pytest tests/test_docs_screenshots.py -n0 --splinter-headless
+```
+
+### Code Quality
+
+```bash
+# Format code (line length: 88)
+black .
+
+# Lint code
+ruff check .
+```
+
+## Core Architecture
+
+### Route Hierarchy Pattern
+
+Routers nest views in code rather than urls.py configuration. Structure: **Site → Routers → Views**
+
+```python
+# Example: ItemRouter contains ListView, DetailView, CreateView, etc.
+class ItemRouter(djcrud.ModelRouter):
+    model = Item
+
+djcrud.site.routes.append(ItemRouter)
+```
+
+**Key files:** `src/djcrud/route.py`, `src/djcrud/router.py`
+
+### Registry Pattern
+
+Routes are managed by an ordered registry allowing surgical overrides by codename:
+
+```python
+class ItemRouter(djcrud.ModelRouter):
+    model = Item
+    routes = djcrud.ModelRouter.routes + [
+        djcrud.generic.ListView.clone(site_search=True),  # Override default ListView
+    ]
+```
+
+**Key file:** `src/djcrud/registry.py`
+
+### Clonable Pattern
+
+Views and controllers use `.clone()` for runtime specialization without defining new module-level classes:
+
+```python
+MyView.clone(
+    permission_shortcode='custom',
+    site_search=True,
+)
+```
+
+**Key file:** `src/djcrud/clonable.py`
+
+### Mixin Composition
+
+Views are built from composable mixins providing focused features:
+
+- **JsonMixin** - JSON serialization via model router
+- **FilterMixin** - QuerySet filtering with django-filter
+- **SearchMixin** - Full-text search
+- **PaginationMixin** - Pagination with django-tables2
+- **ObjectMixin** - Single object views (Detail, Update, Delete)
+- **FormMixin** - Form handling with crispy-forms
+- **ListActionMixin** - Bulk actions on list views
+
+**Key directory:** `src/djcrud/views/`
+
+### Permission Model
+
+Three-tier permission checking: **View → Router → Django backend**
+
+CRUD operations map to Django permissions:
+- `add_<model>` - Create permission
+- `change_<model>` - Update permission
+- `delete_<model>` - Delete permission
+- `view_<model>` - Read permission
+
+Permissions are checked before dispatch.
+
+**Key file:** `src/djcrud/view.py`
+
+### ModelRouter Pattern
+
+A **ModelRouter** automatically generates CRUD routes for a Django model:
+
+```python
+class ItemRouter(djcrud.ModelRouter):
+    model = Item
+    icon = 'inbox'      # Bootstrap Icons name
+    color = 'primary'   # Bulma color
+
+    def get_queryset(self, view):
+        """Override to scope data per user"""
+        return self.model.objects.filter(owner=view.request.user)
+```
+
+Routes generated: ListView, DetailView, CreateView, UpdateView, DeleteView, DeleteObjectsView (bulk delete)
+
+**Key files:** `src/djcrud/__init__.py`, `src/djcrud/model.py`
+
+### Template API Pattern
+
+Views are exposed directly to templates - no custom `get_context_data()` needed:
+
+```html
+{{ view.title }}
+{{ view.breadcrumbs }}
+{{ view.model_meta.verbose_name_plural }}
+```
+
+**Key file:** `src/djcrud/views/template.py`
+
+### Autodiscovery Pattern
+
+Like Django admin, djcrud uses autodiscovery:
+
+```python
+# In urls.py
+urlpatterns = djcrud.site.build().urlpatterns
+
+# In each app's djcrud.py
+class MyRouter(djcrud.ModelRouter):
+    model = MyModel
+
+djcrud.site.routes.append(MyRouter)
+```
+
+The `site.build()` call imports all `djcrud.py` modules from installed apps.
+
+**Key file:** `src/djcrud/__init__.py` - Site class with `autodiscover()` and `build()`
+
+### JSON REST API
+
+Views support dual HTML/JSON responses:
+- Detects JSON requests via Content-Type or Accept headers
+- REST methods: GET, POST, PUT, PATCH, DELETE
+- JSON serialization via `ModelRouter.serialize()`
+- Swagger/OpenAPI schema generation available
+
+**Key file:** `src/djcrud/views/json.py`
+
+## Project Structure
+
+```
+src/djcrud/              Core framework
+src/djcrud_bulma/        Bulma CSS template pack with static assets
+src/djcrud_auth/         Authentication router (login, logout, password)
+src/djcrud_api/          JSON REST API with Swagger UI and token auth
+src/djcrud_dal/          Django-autocomplete-light integration
+src/djcrud_dal_topbar/   Site search in navbar
+src/djcrud_history/      Audit logging with LogEntry models
+src/djcrud_debug/        Route introspection (debug only, superuser)
+src/djcrud_example/      Example Django project with tutorial apps (stage0-4)
+tests/                  Test suite with conftest.py fixtures
+docs/                   Sphinx documentation
+```
+
+## Philosophy
+
+These principles guide djcrud's design (from `docs/philosophy.rst`):
+
+- **Structure is code, not configuration** - Routers and views nested in Python, not urls.py
+- **Sane defaults, surgical overrides** - Works out of the box; customize via `clone()` and registry
+- **View is the template API** - View object exposed to templates directly
+- **Security and data scope in one place** - Permissions and queryset filtering in router
+- **Menus introspected, not hardcoded** - Views carry tags; navigation built from `get_tagged_views()`
+- **Composition over monoliths** - Generic views are stacks of small mixins
+- **Django all the way down** - Uses Django's `user.has_perm()`, generic views, standard urlpatterns
+
+## JavaScript Architecture
+
+- **Custom elements** with light DOM (no Shadow DOM)
+- **ES modules**, no bundler
+- **Unpoly compilers** for progressive enhancement
+- Listen for `up:fragment:inserted` for Unpoly compatibility
+- Config via HTML attributes and `data-*` hooks
+
+**JavaScript files:** `src/djcrud_bulma/static/djcrud_bulma/js/`
+
+## Important Dependencies
+
+**Core:**
+- django-tables2 (table rendering)
+- django-crispy-forms (form layout)
+- django-filter (QuerySet filtering)
+- django-autocomplete-light (autocomplete widgets)
+- djhacker (model patching)
+
+**Install order matters:** `dal` and `dal_select2` must come **before** `django.contrib.admin` in INSTALLED_APPS
+
+**Frontend:**
+- Unpoly.js (AJAX navigation)
+- Bootstrap Icons
+- Bulma CSS (with djcrud_bulma template pack)
+
+## Extension Packages
+
+- **djcrud_bulma** - Bulma CSS template pack with HTML templates and static assets
+- **djcrud_auth** - Authentication views (login, logout, password change)
+- **djcrud_api** - JSON REST API with schema, Swagger UI, Bearer token auth
+- **djcrud_dal** - Zero-config autocomplete for relation fields
+- **djcrud_dal_topbar** - Site search widget in navbar
+- **djcrud_debug** - Debug routing introspection (superuser only)
+- **djcrud_history** - Audit logging and global log-entry browser

djcrud-0.2.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: djcrud
+Version: 0.2.0
+Summary: Django CRUD utilities
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: django>=5.1
+Requires-Dist: django-tables2>=2.7
+Requires-Dist: django-crispy-forms>=2.0
+Requires-Dist: django-filter
+Requires-Dist: django-autocomplete-light>=5.1rc1
+Requires-Dist: django-querysetsequence>=0.11
+Requires-Dist: djhacker
+Requires-Dist: crispy-bulma>=0.1
+Provides-Extra: api
+Provides-Extra: swagger
+Provides-Extra: bulma
+Requires-Dist: django-crispy-forms>=2.0; extra == "bulma"
+Requires-Dist: crispy-bulma>=0.1; extra == "bulma"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-django>=4.5; extra == "dev"
+Requires-Dist: pytest-splinter>=3.3; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: tox>=4; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+
+# djcrud
+
+**Faster Django development by getting more out of less.**
+
+djcrud is a thin MVC layer on top of Django. Declare controllers and views in
+code, get secure CRUD and routing by default, and expose the view object
+directly to templates.
+
+Read the [philosophy](https://jpic.github.io/djcrud/philosophy.html) for the
+full rationale.
+
+## Install
+
+```bash
+pip install --pre djcrud
+```
+
+Note: The `--pre` flag is required for pre-release dependency versions.
+
+See [installation](https://jpic.github.io/djcrud/install.html) for setup, or
+try the [demo](https://jpic.github.io/djcrud/demo.html) to explore the example
+project.
+
+## Quick start
+
+```python
+# myapp/djcrud.py
+import djcrud
+
+from .models import YourModel
+
+
+class YourModelRouter(djcrud.ModelRouter):
+    model = YourModel
+
+
+djcrud.site.routes.append(YourModelRouter)
+```
+
+```python
+# urls.py
+import djcrud
+
+urlpatterns = djcrud.site.build().urlpatterns
+```
+
+Add `myapp` to `INSTALLED_APPS`. `build()` autodiscovers each app's `djcrud.py`
+(like Django admin) — the import runs `routes.append()` before the route
+registry is built.
+
+## Documentation
+
+- [Philosophy](https://jpic.github.io/djcrud/philosophy.html)
+- [Install](https://jpic.github.io/djcrud/install.html)
+- [Demo](https://jpic.github.io/djcrud/demo.html) — Try the example project
+- [Tutorial](https://jpic.github.io/djcrud/tutorial/)
+- [Reference](https://jpic.github.io/djcrud/reference/)
+
+## Contributing
+
+See the [contributing guide](https://jpic.github.io/djcrud/contributing.html)
+for development setup, running tests, updating documentation screenshots, and
+JavaScript conventions. Source: [`docs/contributing.rst`](docs/contributing.rst).
+
+## License
+
+MIT