Metadata-Version: 2.4
Name: django-heluca-themis
Version: 1.1.2
Summary: Django app providing user preferences, theme management, API key management, Casdoor SSO adapters, and standard navigation templates
Author-email: Robert Helewka <r@helu.ca>
License: MIT
Project-URL: Homepage, https://helu.ca
Project-URL: Repository, ssh://git@git.helu.ca:22022/r/themis.git
Keywords: django,user-profile,themes,daisyui,preferences,heluca
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django<6.0,>=5.2
Requires-Dist: djangorestframework<4.0,>=3.14
Requires-Dist: cryptography<45.0,>=41.0
Requires-Dist: django-allauth[openid_connect,socialaccount]<66.0,>=65.0
Provides-Extra: dev
Requires-Dist: drf-spectacular>=0.26.0; extra == "dev"
Requires-Dist: django-filter>=23.0; extra == "dev"
Dynamic: license-file

# Themis

Reusable Django app providing user preferences, DaisyUI theme management, API key management, and standard navigation templates for all Heluca applications.

*Themis — titan of order, custom, and law.*

## Features

- **User Preferences** — timezone (home + traveling), date/time/number formatting, week start day
- **DaisyUI Themes** — 32 built-in themes, separate light/dark selection, auto (system) mode
- **Notifications** — in-app notification bell, JS polling, browser desktop notifications, user preferences
- **API Key Management** — encrypted storage with per-key instructions and documentation links
- **Standard Navigation** — consistent navbar, user menu, notification bell, theme toggle, and bottom nav across all apps
- **Middleware** — automatic timezone activation and theme context
- **Formatting Utilities** — date, time, number formatting respecting user preferences
- **Health Checks** — Kubernetes-ready `/ready/` and `/live/` endpoints
- **REST API** — complete API for profiles, keys, and notifications

## Installation

```bash
pip install git+ssh://git@git.helu.ca:22022/r/themis.git
```

## Quick Start

1. Add to `INSTALLED_APPS`:
```python
INSTALLED_APPS = [
    ...
    "rest_framework",
    "themis",
    ...
]
```

2. Configure middleware:
```python
MIDDLEWARE = [
    ...
    "themis.middleware.TimezoneMiddleware",
    "themis.middleware.ThemeMiddleware",
    ...
]
```

3. Configure context processors:
```python
TEMPLATES = [{
    "OPTIONS": {
        "context_processors": [
            ...
            "themis.context_processors.themis_settings",
            "themis.context_processors.user_preferences",
            "themis.context_processors.notifications",
            "themis.context_processors.navigation",
        ],
    },
}]
```

4. Include URLs:
```python
urlpatterns = [
    ...
    path("", include("themis.urls")),
    path("api/v1/", include("themis.api.urls")),
    ...
]
```

5. Configure app settings:
```python
THEMIS_APP_NAME = "My Application"

# Register navigation entries (block-based extension can't cross {% include %},
# so the chrome iterates these instead). Each entry: label, named URL, optional
# SVG icon `d` path. Bad url_names are skipped with a warning, not a 500.
THEMIS_NAV_ITEMS = [
    {"label": "Home", "url_name": "core:home"},
    {"label": "Mail", "url_name": "mail:account_list"},
]
THEMIS_USER_MENU_ITEMS = [
    {"label": "Mail Accounts", "url_name": "mail:account_list"},
]
```

6. Run migrations:
```bash
python manage.py migrate
```

7. Extend the base template:
```html
{% extends "themis/base.html" %}

{% block nav_items %}
<li><a href="{% url 'dashboard' %}">Dashboard</a></li>
{% endblock %}

{% block content %}
<h1 class="text-2xl font-bold">My App</h1>
{% endblock %}
```

## Casdoor SSO (optional)

Themis ships generic django-allauth adapters for Casdoor OIDC. They map the
Casdoor `groups` claim to Django groups, set `is_staff` from configurable
staff groups, and block superusers from SSO (they must use local auth).

```python
SOCIALACCOUNT_ADAPTER = "themis.adapters.CasdoorAccountAdapter"
ACCOUNT_ADAPTER = "themis.adapters.LocalAccountAdapter"
```

Optional settings:

- `THEMIS_STAFF_GROUPS` — Casdoor groups granting `is_staff`
  (default `["staff", "sme", "admin"]`).
- `THEMIS_GROUP_MAPPING` — Casdoor group name → Django group name.
- `THEMIS_ORG_ADAPTER` — dotted path to `fn(user, org_identifier)` invoked
  with the Casdoor `organization` claim, for apps with an Organization model.
  Omit it (the default) to skip organization mapping.

For sandbox environments with self-signed Casdoor certs, import the SSL bypass
at the top of `settings.py` **before** any requests are made (activates only
when `CASDOOR_SSL_VERIFY=false`):

```python
import themis.ssl_patch  # noqa: F401
```

## Documentation

- **[Themis App](docs/Themis_V1-00.md)** — Full documentation
- **[Notification Trigger Pattern](docs/Pattern_Notification_V1-00.md)** — How to trigger notifications from your app
- **[Organization Pattern](docs/Pattern_Organization_V1-00.md)** — Standard Organization model pattern
- **[Red Panda Standards](docs/Red%20Panda%20Standards_Django_V1-00.md)** — Django development standards
- **[Documentation Style Guide](docs/DocumentationStyleGuide_Markdown_V1-00.md)** — Documentation standards

## 🐾 Red Panda Approval™

This project follows Red Panda Approval standards — our gold standard for Django application quality.

### The 5 Sacred Django Criteria
1. **Fresh Migration Test** — Clean migrations from empty database
2. **Elegant Simplicity** — No unnecessary complexity
3. **Observable & Debuggable** — Proper logging and error handling
4. **Consistent Patterns** — Follow Django conventions
5. **Actually Works** — Passes all checks and serves real user needs

## License

MIT License — see [LICENSE](LICENSE) file for details.

## Author

Robert Helewka <r@helu.ca>

## Package Information

- **Package Name:** django-heluca-themis
- **Version:** 1.0.0
- **Django:** >=5.2, <6.0
- **Python:** >=3.10
