django-whiteneuron 0.3.1.2__tar.gz → 0.3.8.0__tar.gz

django_whiteneuron-0.3.8.0/PKG-INFO

@@ -0,0 +1,456 @@
+Metadata-Version: 2.4
+Name: django-whiteneuron
+Version: 0.3.8.0
+Summary: A modern Django Admin extension with enhanced UI/UX, dashboard, feedback, file management, rate limiting, IP blacklisting, and advanced admin integrations built on django-unfold.
+Author-email: White Neuron <anhnt@whiteneuron.ai>
+License: MIT License
+        
+        Copyright (c) 2025 Nguyễn Tú Anh
+        
+        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.
+        
+Project-URL: homepage, https://whiteneuron.ai
+Project-URL: repository, https://github.com/White-Neuron/django-whiteneuron
+Project-URL: changelog, https://github.com/White-Neuron/django-whiteneuron/releases
+Project-URL: Bug Tracker, https://github.com/White-Neuron/django-whiteneuron/issues
+Project-URL: PyPI, https://pypi.org/project/django-whiteneuron/
+Keywords: django,plugin,admin,dashboard,whiteneuron
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django-debug-toolbar>=5.0.1
+Requires-Dist: django<7.0.0,>=6.0.8
+Requires-Dist: django-celery-beat>=2.7.0
+Requires-Dist: django-guardian>=2.4.0
+Requires-Dist: django-imagekit>=5.0.0
+Requires-Dist: django-import-export>=4.3.3
+Requires-Dist: django-modeltranslation>=0.19.11
+Requires-Dist: django-ninja>=1.3.0
+Requires-Dist: django-simple-history>=3.8.0
+Requires-Dist: gunicorn>=23.0.0
+Requires-Dist: hiredis>=3.1.0
+Requires-Dist: markdown>=3.7
+Requires-Dist: openai>=1.58.1
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pillow>=12.2.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: redis>=5.2.1
+Requires-Dist: sentry-sdk==2.28.0
+Requires-Dist: django-browser-reload>=1.18.0
+Requires-Dist: whitenoise>=6.9.0
+Requires-Dist: django-crispy-forms>=2.4
+Requires-Dist: django-colorfield>=0.14.0
+Requires-Dist: channels>=4.2.2
+Requires-Dist: channels-redis>=4.2.1
+Requires-Dist: uvicorn>=0.34.3
+Requires-Dist: daphne>=4.2.0
+Requires-Dist: twisted[tls]>=26.4.0rc2
+Requires-Dist: django-ckeditor-5>=0.2.18
+Requires-Dist: django-cors-headers>=4.3.0
+Requires-Dist: django-unfold>=0.92.0
+Requires-Dist: djangoql>=0.18.1
+Requires-Dist: pyopenssl>=26.4.0
+Requires-Dist: md2html-tailwind4==1.5.3
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Dynamic: license-file
+
+# django-whiteneuron
+
+A modern Django Admin extension focused on UI/UX, dashboard, feedback, file management, and advanced admin integrations — built on top of [django-unfold](https://github.com/unfoldadmin/django-unfold).
+
+[![PyPI version](https://img.shields.io/pypi/v/django-whiteneuron)](https://pypi.org/project/django-whiteneuron/)
+[![Python](https://img.shields.io/pypi/pyversions/django-whiteneuron)](https://pypi.org/project/django-whiteneuron/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Downloads](https://img.shields.io/pypi/dm/django-whiteneuron)](https://pypi.org/project/django-whiteneuron/)
+
+![django-whiteneuron](https://raw.githubusercontent.com/White-Neuron/django-whiteneuron/main2.0/docs/images/main.png)
+
+## Current Version
+v0.3.8.0
+
+## Changelog
+
+### Latest: v0.3.8.0 (2026-09-25)
+**Bugfixes: Django 6 format_html crash in Image previews, app mosaic thumbnail URLs, SHOW_FILE_MANAGEMENT sidebar flag**
+- **Fixed**: `Image.imgThumbnail()` and `Image.imgPreview()` admin methods — replaced f-string interpolation inside `format_html()` with the proper template + args pattern; resolves the rendering crash on Django 6 and ensures interpolated values are HTML-escaped.
+- **Fixed**: App changelist mosaic thumbnails (`templates/admin/base/app_change_list.html`) — relative `thumbnail_url` paths are now wrapped in `{% static %}` while absolute/protocol-relative URLs pass through unchanged, fixing broken thumbnail images.
+- **Fixed**: `SHOW_FILE_MANAGEMENT=False` is no longer silently ignored — the Unfold sidebar is built conditionally at definition time instead of post-processing by title match; when disabled, File Management items merge into the System section before Notifications config.
+- **Compatibility**: No breaking changes; safe for all v0.3.x users. Django 6.0.x only.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full version history.
+
+### Latest: v0.3.7.0 (2026-08-23)
+**Security: Patch 6 CVEs across django, cryptography, sqlparse, setuptools**
+- **Fixed**: Upgraded `django` lower bound to patch CVE-2026-15830 (GeoDjango DoS).
+- **Fixed**: Upgraded `pyopenssl` to `>=26.4.0` — patches CVE-2026-69247 (Bleichenbacher oracle attack).
+- **Fixed**: Added `sqlparse >=0.6.0` via transitive deps — patches 3 DoS CVEs (CVE-2026-71491, CVE-2026-54284, CVE-2026-59893).
+- **Fixed**: Added `setuptools >=75.1.0` to build-system — patches CVE-2025-47273.
+- **Compatibility**: No breaking changes; safe for all v0.3.x users. Django 6.0.x only.
+
+### Latest: v0.3.5 (2026-07-15)
+**Feature: Public/private file access control and HTML file support**
+- **Added**: `is_public`, `allowed_users`, `allowed_groups` fields to `BaseFile` model — files can now be marked public or restricted to specific users/groups.
+- **Added**: `_check_access()` permission logic in download/preview views — enforces access control before serving files.
+- **Added**: `HTMLFile` model with inline preview support.
+- **Improved**: Admin UI — public/private badge column, conditional Access Control fieldset for private files.
+- **Compatibility**: No breaking changes; safe for all v0.3.x users.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full version history.
+
+### Latest: v0.3.4.12 (2026-06-27)
+**Cleanup: Remove .DS_Store from tracking, feedback list in admin, remove md2html-tailwind4 uv source**
+- **Removed**: 7 `.DS_Store` files removed from git tracking — added `*/.DS_Store` to `.gitignore`.
+- **Added**: `FeedbackBaseAdmin.render_change_form()` loads and passes `feedback_list` context for displaying feedback entries per model instance in admin change form.
+- **Removed**: `[tool.uv.sources]` block for `md2html-tailwind4` from `pyproject.toml`.
+- **Updated**: Tailwind CSS regenerated with v4.1.16.
+- **Compatibility**: No breaking changes; safe for all v0.3.x users.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full version history.
+
+### Latest: v0.3.4.10 (2026-06-12)
+**Security patch: Upgrade Django to 6.0.6+ (CVE-2026-8404, CVE-2026-48587, CVE-2026-6873)**
+- **Fixed**: Upgraded `django` lower bound from `>=6.0.6` to `>=6.0.6,<7.0.0` — patches 5 security vulnerabilities: CVE-2026-8404 (CVSS 5.3), CVE-2026-48587 (CVSS 5.3), CVE-2026-6873 (CVSS 4.3), CVE-2026-7666 (CVSS 2.3), CVE-2026-35193 (CVSS 2.3).
+- **Compatibility**: No breaking changes; safe for all v0.3.x users. Django 6.0.x only — pinned upper bound `<7.0.0`.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full version history.
+
+### Latest: v0.3.4.8 (2026-05-24)
+**Feature: Badge callback caching layer for dashboard performance optimization**
+- **Added**: Django cache-backed badge callbacks for dashboard model badges with 60s TTL to reduce database queries.
+- **Added**: Per-user cached notification badge with 60s TTL and unauthenticated user guard.
+- **Improved**: Replaced `timezone.now()` with `timezone.localtime()` across all badge queries.
+- **Compatibility**: No breaking changes; safe for all v0.3.x users. Requires Django cache backend configured.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full version history.
+
+### Latest: v0.3.4.6.2 (2026-05-14)
+**Improvement: Configurable rate-limit exempt paths and user activity exclude paths**
+- **Improved**: `RateLimitMiddleware` now reads `RATE_LIMIT_EXEMPT_PATHS` from Django settings — comma-separated list of additional path prefixes to exclude from rate limiting.
+- **Improved**: `UserActivityMiddleware` now reads `USER_ACTIVITY_EXCLUDE_PATHS` from Django settings — semicolon-separated list of `path,condition` pairs for excluding paths from activity tracking and rate limiting.
+- **Compatibility**: No breaking changes; safe for all v0.3.x users. New settings are optional.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full version history.
+
+### Latest: v0.3.3.4 (2026-04-30)
+**Patch release: Remove synchronization module, add language switcher template, update Vietnamese i18n**
+- **Removed**: `synchronization/` module — cleaned up unused sync models, admin, views, tests, and migrations
+- **Added**: Language switcher template for Unfold admin (`language_switch.html`) with multi-language support via `show_languages` context variable
+- **Improved**: Vietnamese translations updated — removed stale synchronization references, added new entries for user profile and HTML editor
+- **Compatibility**: No breaking changes; safe for all v0.3.3.x users
+- **Validation**: Build, migrations (no changes), and manual admin UI/UX validation performed
+- **Upgrade Guidance**: No manual migration required; upgrade recommended for all users on v0.3.3.x
+- **Rollback**: Safe to revert to v0.3.3.3; no schema changes introduced
+
+See [CHANGELOG.md](CHANGELOG.md) for the full version history.
+
+## Table of Contents
+
+- [Changelog](#changelog)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Modules](#modules)
+- [Middleware & Security](#middleware--security)
+- [Frontend](#frontend)
+- [Environment Variables](#environment-variables)
+- [Management Commands](#management-commands)
+- [Building & Releasing](#building--releasing)
+- [Documentation](#documentation)
+- [Contact](#contact)
+
+## Giới thiệu
+
+Xem [docs/INTRODUCTION.md](docs/INTRODUCTION.md) để tìm hiểu chi tiết về django-whiteneuron — tại sao nên dùng, tính năng nổi bật và ai phù hợp.
+
+## Features
+
+| Category | Feature | Description |
+|---|---|---|
+| **Core** | Custom User Model | UUID-based user model with bot support, avatar, biography |
+| **Core** | Soft Delete System | `BaseModel` with soft delete, restore, and audit trail (`created_by`, `updated_by`) |
+| **Core** | Auto Notifications | Real-time WebSocket notifications on CRUD operations via `BaseModel.save()` |
+| **Dashboard** | Admin Dashboard | Custom dashboard callback with badge system, cache-backed for performance |
+| **Security** | Rate Limiting | IP-based and user-based rate limiting with Redis backend (429 responses) |
+| **Security** | IP Blacklist | Static (`.env` CIDR) + dynamic (admin-managed, Redis TTL) blocking |
+| **Security** | UA Blacklist | User-Agent substring/regex matching via admin panel or `.env` |
+| **Tracking** | Activity Logs | `UserActivity`, `AnonymousActivity`, `VisitProfile` — full request audit trail |
+| **Files** | File Management | Excel/PDF upload with SHA-256 integrity verification |
+| **Feedback** | Feedback System | Per-model feedback collection, viewable in admin change forms |
+| **Admin** | Grid View | Card-based user listing with avatar, badges, and role indicators |
+| **Admin** | Import/Export | `django-import-export` integration for data portability |
+| **Admin** | Simple History | `django-simple-history` tracking on all models |
+| **Admin** | Guardian Integration | Object-level permissions via `django-guardian` |
+| **Editor** | CKEditor 5 | Rich text editing with Tailwind-styled output |
+| **Email** | Login Notifications | Auto-generate password + send login email on user creation |
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install django-whiteneuron
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add django-whiteneuron
+```
+
+### Specific version from PyPI
+
+```bash
+uv add "django-whiteneuron==0.3.4.12"
+```
+
+### From GitHub tag
+
+```bash
+uv add "git+https://github.com/White-Neuron/django-whiteneuron.git@v0.3.4.12"
+```
+
+### From local source
+
+```bash
+uv pip install -e .
+```
+
+## Quick Start
+
+```bash
+# 1. Add to INSTALLED_APPS (top of list)
+# settings.py
+INSTALLED_APPS = [
+    "whiteneuron",
+    "whiteneuron.base",
+    "whiteneuron.feedbacks",
+    "whiteneuron.file_management",
+    "whiteneuron.contrib",
+    "whiteneuron.dashboard",
+    # ... your other apps
+]
+
+# 2. Set custom user model
+AUTH_USER_MODEL = "base.User"
+
+# 3. Add middleware (order matters)
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "whiteneuron.base.middleware.RateLimitMiddleware",   # ← immediately after SecurityMiddleware
+    "whitenoise.middleware.WhiteNoiseMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "django.contrib.messages.middleware.MessageMiddleware",
+    "django.middleware.clickjacking.XFrameOptionsMiddleware",
+    "whiteneuron.base.middleware.ReadonlyExceptionHandlerMiddleware",
+    "whiteneuron.base.middleware.UserActivityMiddleware",  # ← after AuthenticationMiddleware
+    "whiteneuron.base.middleware.ThreadLocalMiddleware",
+]
+
+# 4. Run migrations
+python manage.py migrate
+
+# 5. Create superuser and start
+python manage.py createsuperuser
+python manage.py runserver
+```
+
+Access the admin at: `http://127.0.0.1:8000/admin/`
+
+## Configuration
+
+### UNFOLD Settings Example
+
+```python
+from django.templatetags.static import static
+from django.utils.translation import gettext_lazy as _
+
+UNFOLD = {
+    "SITE_HEADER": _("White Neuron"),
+    "SITE_TITLE": _("White Neuron Admin"),
+    "SITE_SUBHEADER": _("Admin panel"),
+    "SITE_ICON": {
+        "light": lambda request: static("base/images/logo/WhiteNeuron.png"),
+        "dark": lambda request: static("base/images/logo/WhiteNeuron.png"),
+    },
+    "SITE_FAVICONS": [
+        {
+            "rel": "icon",
+            "sizes": "32x32",
+            "type": "image/svg+xml",
+            "href": lambda request: static("base/images/logo/WhiteNeuron.png"),
+        },
+    ],
+    "SHOW_HISTORY": False,
+    "SHOW_LANGUAGES": True,
+    "SHOW_VIEW_ON_SITE": True,
+    "SHOW_BACK_BUTTON": True,
+    "DASHBOARD_CALLBACK": "whiteneuron.dashboard.views.dashboard_callback",
+    "LOGIN": {
+        "image": lambda request: static("base/images/login-bg.jpg"),
+    },
+    "STYLES": [
+        lambda request: static("base/css/styles.css"),
+        lambda request: static("base/css/btn-styles.css"),
+        lambda request: static("base/css/loading.css"),
+    ],
+    "SCRIPTS": [
+        lambda request: static("base/js/loading.js"),
+        lambda request: static("base/js/whiteneuron.js"),
+    ],
+    "BORDER_RADIUS": "6px",
+}
+```
+
+## Modules
+
+| Module | Description | Key Models |
+|---|---|---|
+| `whiteneuron.base` | Core models, admin, middleware, utilities | `User`, `BaseModel`, `Image`, `Mail`, `App`, `IPBlacklist`, `UABlacklist` |
+| `whiteneuron.dashboard` | Dashboard callback and badge system | — |
+| `whiteneuron.notification` | WebSocket real-time notifications | `Notification`, `NotificationConfig` |
+| `whiteneuron.file_management` | File upload with integrity verification | `ExcelFile`, `PDFFile` |
+| `whiteneuron.feedbacks` | Per-model feedback collection | — |
+
+## Middleware & Security
+
+### Rate Limiting
+
+```python
+RATE_LIMIT_REQUESTS = 60   # max requests per window (by IP)
+RATE_LIMIT_WINDOW     = 60  # in seconds
+USER_RATE_LIMIT_REQUESTS = 60  # by authenticated user
+USER_RATE_LIMIT_WINDOW   = 60
+```
+
+When limit exceeded:
+- API (`/api/` or `Accept: application/json`) → JSON `{"detail": "Too many requests."}` (429)
+- Browser → renders `429.html` with `Retry-After` header
+
+### IP Blacklist
+
+**Static** — `.env` (CIDR ranges, loaded at startup):
+```env
+IP_BLACKLIST=185.220.101.5,194.165.16.0/22,2001:db8::/32
+```
+
+**Dynamic** — Admin panel + Redis (real-time):
+- Permanent block: leave `blocked_until` empty
+- Temporary block: set `blocked_until` → Redis TTL auto-expires
+
+### UA Blacklist
+
+Static via `.env`:
+```env
+UA_BLACKLIST=GPTBot,ClaudeBot,https://openai.com
+```
+
+Dynamic via admin — supports regex patterns with real-time cache rebuild.
+
+## Frontend (Tailwind 4 + daisyUI 5)
+
+```bash
+npm install -D @tailwindcss/cli@next daisyui@latest
+bash scripts/tailwind.sh
+```
+
+Or directly:
+```bash
+npx @tailwindcss/cli -i styles.css -o whiteneuron/static/base/css/styles.css --minify
+```
+
+## Environment Variables
+
+Copy `env.example` to `.env` and configure. Key variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `SECRET_KEY` | Django secret key | — |
+| `DEBUG` | Debug mode | `True` |
+| `DATABASE` | Database type (`sqlite`/`postgres`) | `sqlite` |
+| `REDIS` / `CACHE_REDIS_LOCATION` | Redis connection | `redis://127.0.0.1:6379` |
+| `CELERY_BROKER_URL` | Celery broker URL | `redis://localhost:6379/0` |
+| `RATE_LIMIT_REQUESTS` | IP rate limit count | `60` |
+| `IP_BLACKLIST` | Static IP blocks (CIDR) | — |
+| `UA_BLACKLIST` | Static UA blocks | — |
+
+See `env.example` for the full list.
+
+## Management Commands
+
+| Command | Description |
+|---|---|
+| `init_admin` | Create initial admin user |
+| `init_guest` | Create guest user account |
+| `init_groupuser` | Initialize group users |
+| `cleanup_old_activities` | Remove old activity records |
+| `update_visit_profiles` | Update visit profile data |
+
+## Building & Releasing
+
+```bash
+bash scripts/build.sh
+```
+
+This builds Tailwind CSS assets, runs migrations, and creates the Python package via `uv build`.
+
+## Error Pages
+
+Templates in `whiteneuron/templates/` are used automatically when `DEBUG=False`:
+
+| Template | Error |
+|---|---|
+| `400.html` | Bad Request |
+| `403.html` | Forbidden |
+| `404.html` | Not Found |
+| `429.html` | Too Many Requests |
+| `500.html` | Server Error |
+
+## Documentation
+
+- **Giới thiệu**: Xem [docs/INTRODUCTION.md](docs/INTRODUCTION.md) — tài liệu giới thiệu dự án, tính năng nổi bật và ai nên dùng.
+- **Hướng dẫn chi tiết**: Xem [docs/GUIDE.md](docs/GUIDE.md) cho tài liệu module, model, middleware và cấu hình đầy đủ.
+- **Changelog**: See [CHANGELOG.md](CHANGELOG.md) for full version history.
+- **CKEditor 5 Customization**: See [docs/CKEDITOR5_CUSTOMIZATION.md](docs/CKEDITOR5_CUSTOMIZATION.md).
+
+## Contact
+
+- Email: [anhnt@whiteneuron.com](mailto:anhnt@whiteneuron.com)
+- Website: [https://whiteneuron.ai](https://whiteneuron.ai)
+- GitHub: [https://github.com/White-Neuron/django-whiteneuron](https://github.com/White-Neuron/django-whiteneuron)
+
+## License
+
+MIT License.