django-admin-forge 0.1.0__tar.gz

django_admin_forge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 django-admin-forge contributors
+
+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_admin_forge-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: django-admin-forge
+Version: 0.1.0
+Summary: A modern, extensible, premium Django admin framework.
+Author: django-admin-forge contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/your-org/django-admin-forge
+Project-URL: Documentation, https://github.com/your-org/django-admin-forge/docs
+Project-URL: Repository, https://github.com/your-org/django-admin-forge
+Project-URL: Issues, https://github.com/your-org/django-admin-forge/issues
+Keywords: django,admin,dashboard,saas,internal-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django<6.0,>=4.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-django>=4.8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Provides-Extra: publish
+Requires-Dist: build>=1.2; extra == "publish"
+Requires-Dist: twine>=6.0; extra == "publish"
+Dynamic: license-file
+
+# django-admin-forge
+
+`django-admin-forge` is a modern, customizable Django admin framework for serious SaaS and enterprise apps.
+
+It keeps Django admin's reliability and model integration, while upgrading the UI/UX, theming, and developer customization surface.
+
+## Highlights
+
+- Django-first admin replacement (`AdminSite`-based)
+- Branded login and modern dashboard
+- Customizable sidebar menus and app/model navigation
+- Dark, light, and system themes
+- Accent color system
+- Improved changelist, filters, bulk actions, and empty states
+- Improved add/edit form layout
+
+## Install
+
+From [PyPI](https://pypi.org/project/django-admin-forge/):
+
+```bash
+pip install django-admin-forge
+```
+
+If you previously tried the `django-forge` distribution name, switch to this package: update `INSTALLED_APPS` and imports to `django_admin_forge`, rename settings `DJANGO_ADMIN_FORGE`, then `pip uninstall django-forge` (if installed) and install as above.
+
+From a wheel or sdist you built locally:
+
+```bash
+python -m pip install build
+python -m build
+pip install dist/django_admin_forge-*.whl
+```
+
+Develop this repository (editable install, tests, lint):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### Publishing to PyPI
+
+1. Configure [PyPI](https://pypi.org/account/) credentials (for example [upload with `twine`](https://twine.readthedocs.io/) or `uv publish`).
+2. Bump `version` in `pyproject.toml`.
+3. Install build tools: `pip install ".[publish]"` (or `pip install build twine`).
+4. Run `python -m build`, then `twine check dist/*` and `twine upload dist/*`.
+
+Use [TestPyPI](https://test.pypi.org/) first if you want a dry run: `twine upload --repository testpypi dist/*`.
+
+## Quick Integration
+
+### 1) Add apps
+
+```python
+INSTALLED_APPS = [
+    "django_admin_forge",
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+    # your apps...
+]
+```
+
+### 2) Use Forge admin URLs
+
+```python
+from django.urls import path
+from django_admin_forge.site import forge_admin_site
+
+urlpatterns = [
+    path("admin/", forge_admin_site.urls),
+]
+```
+
+### 3) Configure `DJANGO_ADMIN_FORGE` (optional but recommended)
+
+```python
+DJANGO_ADMIN_FORGE = {
+    "brand_name": "Forge Admin",
+    "brand_logo_text": "FORGE",
+    "brand_tagline": "Modern Django operations panel",
+    "accent_color": "green",
+    "default_theme": "system",  # "light" | "dark" | "system"
+    "show_sidebar_search": True,
+    "enable_command_bar": True,
+}
+```
+
+## Configuration Reference
+
+Use the `DJANGO_ADMIN_FORGE` setting dictionary.
+
+- `brand_name` (`str`): Header brand name.
+- `brand_logo_text` (`str`): Compact sidebar/logo text.
+- `brand_tagline` (`str`): Login/subtitle branding.
+- `accent_color` (`str`): Accent token used in key actions and highlights.
+- `default_theme` (`"light" | "dark" | "system"`): Initial theme mode.
+- `show_sidebar_search` (`bool`): Sidebar search input visibility.
+- `enable_command_bar` (`bool`): Header search/command input visibility.
+- `menu_icons` (`dict[str, str]`): Overrides for app/model icons.
+- `menu_tabs` (`list[dict]`): Sidebar menu tabs (top and bottom areas).
+- `dashboard_analytics_cards` (`list[dict]`): Override dashboard KPI cards for marketing/business snapshots.
+
+## Accent Colors
+
+Supported `accent_color` values:
+
+`blue`, `green`, `amber`, `violet`, `emerald`, `teal`, `cyan`, `sky`, `indigo`, `purple`, `pink`, `rose`, `red`, `orange`, `yellow`, `lime`, `slate`, `gray`, `zinc`, `neutral`, `stone`
+
+Example:
+
+```python
+DJANGO_ADMIN_FORGE = {
+    "accent_color": "rose",
+}
+```
+
+## Sidebar Menus (`menu_tabs`)
+
+By default, only `Dashboard` is shown.
+
+You can fully configure sidebar tabs:
+
+```python
+DJANGO_ADMIN_FORGE = {
+    "menu_tabs": [
+        {"label": "Dashboard", "url_name": "admin:index", "icon": "layout-grid"},
+        {"label": "Applications", "url_name": "admin:forge-applications", "icon": "layers"},
+        {"label": "Users", "url_name": "admin:auth_user_changelist", "icon": "user"},
+        {"label": "Documentation", "url": "/docs/", "icon": "external-link"},
+    ]
+}
+```
+
+Each tab supports:
+
+- `label` (required)
+- `url_name` (reverse name) or `url` (direct URL)
+- `icon` (optional, defaults to `layout-grid`)
+
+## Menu Icon Overrides (`menu_icons`)
+
+You can override app/model icons by key:
+
+```python
+DJANGO_ADMIN_FORGE = {
+    "menu_icons": {
+        "auth": "shield",                # app-level
+        "auth.user": "user",             # model-level
+        "auth.group": "users",
+        "demo_app.customer": "building",
+    }
+}
+```
+
+Resolution order:
+1. `app_label.model_name`
+2. `model_name`
+3. `app_label`
+4. built-in defaults
+
+## Dashboard Analytics Cards
+
+You can supply custom KPI cards for the dashboard hero section using real model data:
+
+```python
+DJANGO_ADMIN_FORGE = {
+    "dashboard_analytics_cards": [
+        {
+            "label": "Customers",
+            "app_label": "demo_app",
+            "model": "Customer",
+            "metric": "count",
+            "icon": "users",
+            "hint": "Total customer records",
+        },
+        {
+            "label": "Active customers",
+            "app_label": "demo_app",
+            "model": "Customer",
+            "metric": "count",
+            "queryset_filter": {"is_active": True},
+            "icon": "activity",
+            "hint": "is_active = true",
+        },
+    ]
+}
+```
+
+Each card supports:
+- `label` (required)
+- `app_label` and `model` for dynamic model-based metrics
+- `metric` (currently supports `count`)
+- `queryset_filter` (optional exact Django ORM filters)
+- `value` (optional fallback/manual value)
+- `icon`
+- `hint` (or `trend`)
+
+## Demo Project (this repo)
+
+```bash
+python demo/manage.py migrate
+python demo/manage.py createsuperuser
+python demo/manage.py runserver
+```
+
+Open: [http://127.0.0.1:8000/admin/](http://127.0.0.1:8000/admin/)
+
+## Status and Roadmap
+
+Current implementation includes custom site templates, dashboard, apps page, collapsible sidebar, filters modal, improved forms/changelists, search helpers, and theme controls.
+
+Planned next:
+
+- Saved views/filters
+- Dashboard widget API expansion
+- Accessibility and keyboard navigation improvements
+- Packaging/build pipeline polish for production release
+

django_admin_forge-0.1.0/README.md

@@ -0,0 +1,224 @@
+# django-admin-forge
+
+`django-admin-forge` is a modern, customizable Django admin framework for serious SaaS and enterprise apps.
+
+It keeps Django admin's reliability and model integration, while upgrading the UI/UX, theming, and developer customization surface.
+
+## Highlights
+
+- Django-first admin replacement (`AdminSite`-based)
+- Branded login and modern dashboard
+- Customizable sidebar menus and app/model navigation
+- Dark, light, and system themes
+- Accent color system
+- Improved changelist, filters, bulk actions, and empty states
+- Improved add/edit form layout
+
+## Install
+
+From [PyPI](https://pypi.org/project/django-admin-forge/):
+
+```bash
+pip install django-admin-forge
+```
+
+If you previously tried the `django-forge` distribution name, switch to this package: update `INSTALLED_APPS` and imports to `django_admin_forge`, rename settings `DJANGO_ADMIN_FORGE`, then `pip uninstall django-forge` (if installed) and install as above.
+
+From a wheel or sdist you built locally:
+
+```bash
+python -m pip install build
+python -m build
+pip install dist/django_admin_forge-*.whl
+```
+
+Develop this repository (editable install, tests, lint):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### Publishing to PyPI
+
+1. Configure [PyPI](https://pypi.org/account/) credentials (for example [upload with `twine`](https://twine.readthedocs.io/) or `uv publish`).
+2. Bump `version` in `pyproject.toml`.
+3. Install build tools: `pip install ".[publish]"` (or `pip install build twine`).
+4. Run `python -m build`, then `twine check dist/*` and `twine upload dist/*`.
+
+Use [TestPyPI](https://test.pypi.org/) first if you want a dry run: `twine upload --repository testpypi dist/*`.
+
+## Quick Integration
+
+### 1) Add apps
+
+```python
+INSTALLED_APPS = [
+    "django_admin_forge",
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+    # your apps...
+]
+```
+
+### 2) Use Forge admin URLs
+
+```python
+from django.urls import path
+from django_admin_forge.site import forge_admin_site
+
+urlpatterns = [
+    path("admin/", forge_admin_site.urls),
+]
+```
+
+### 3) Configure `DJANGO_ADMIN_FORGE` (optional but recommended)
+
+```python
+DJANGO_ADMIN_FORGE = {
+    "brand_name": "Forge Admin",
+    "brand_logo_text": "FORGE",
+    "brand_tagline": "Modern Django operations panel",
+    "accent_color": "green",
+    "default_theme": "system",  # "light" | "dark" | "system"
+    "show_sidebar_search": True,
+    "enable_command_bar": True,
+}
+```
+
+## Configuration Reference
+
+Use the `DJANGO_ADMIN_FORGE` setting dictionary.
+
+- `brand_name` (`str`): Header brand name.
+- `brand_logo_text` (`str`): Compact sidebar/logo text.
+- `brand_tagline` (`str`): Login/subtitle branding.
+- `accent_color` (`str`): Accent token used in key actions and highlights.
+- `default_theme` (`"light" | "dark" | "system"`): Initial theme mode.
+- `show_sidebar_search` (`bool`): Sidebar search input visibility.
+- `enable_command_bar` (`bool`): Header search/command input visibility.
+- `menu_icons` (`dict[str, str]`): Overrides for app/model icons.
+- `menu_tabs` (`list[dict]`): Sidebar menu tabs (top and bottom areas).
+- `dashboard_analytics_cards` (`list[dict]`): Override dashboard KPI cards for marketing/business snapshots.
+
+## Accent Colors
+
+Supported `accent_color` values:
+
+`blue`, `green`, `amber`, `violet`, `emerald`, `teal`, `cyan`, `sky`, `indigo`, `purple`, `pink`, `rose`, `red`, `orange`, `yellow`, `lime`, `slate`, `gray`, `zinc`, `neutral`, `stone`
+
+Example:
+
+```python
+DJANGO_ADMIN_FORGE = {
+    "accent_color": "rose",
+}
+```
+
+## Sidebar Menus (`menu_tabs`)
+
+By default, only `Dashboard` is shown.
+
+You can fully configure sidebar tabs:
+
+```python
+DJANGO_ADMIN_FORGE = {
+    "menu_tabs": [
+        {"label": "Dashboard", "url_name": "admin:index", "icon": "layout-grid"},
+        {"label": "Applications", "url_name": "admin:forge-applications", "icon": "layers"},
+        {"label": "Users", "url_name": "admin:auth_user_changelist", "icon": "user"},
+        {"label": "Documentation", "url": "/docs/", "icon": "external-link"},
+    ]
+}
+```
+
+Each tab supports:
+
+- `label` (required)
+- `url_name` (reverse name) or `url` (direct URL)
+- `icon` (optional, defaults to `layout-grid`)
+
+## Menu Icon Overrides (`menu_icons`)
+
+You can override app/model icons by key:
+
+```python
+DJANGO_ADMIN_FORGE = {
+    "menu_icons": {
+        "auth": "shield",                # app-level
+        "auth.user": "user",             # model-level
+        "auth.group": "users",
+        "demo_app.customer": "building",
+    }
+}
+```
+
+Resolution order:
+1. `app_label.model_name`
+2. `model_name`
+3. `app_label`
+4. built-in defaults
+
+## Dashboard Analytics Cards
+
+You can supply custom KPI cards for the dashboard hero section using real model data:
+
+```python
+DJANGO_ADMIN_FORGE = {
+    "dashboard_analytics_cards": [
+        {
+            "label": "Customers",
+            "app_label": "demo_app",
+            "model": "Customer",
+            "metric": "count",
+            "icon": "users",
+            "hint": "Total customer records",
+        },
+        {
+            "label": "Active customers",
+            "app_label": "demo_app",
+            "model": "Customer",
+            "metric": "count",
+            "queryset_filter": {"is_active": True},
+            "icon": "activity",
+            "hint": "is_active = true",
+        },
+    ]
+}
+```
+
+Each card supports:
+- `label` (required)
+- `app_label` and `model` for dynamic model-based metrics
+- `metric` (currently supports `count`)
+- `queryset_filter` (optional exact Django ORM filters)
+- `value` (optional fallback/manual value)
+- `icon`
+- `hint` (or `trend`)
+
+## Demo Project (this repo)
+
+```bash
+python demo/manage.py migrate
+python demo/manage.py createsuperuser
+python demo/manage.py runserver
+```
+
+Open: [http://127.0.0.1:8000/admin/](http://127.0.0.1:8000/admin/)
+
+## Status and Roadmap
+
+Current implementation includes custom site templates, dashboard, apps page, collapsible sidebar, filters modal, improved forms/changelists, search helpers, and theme controls.
+
+Planned next:
+
+- Saved views/filters
+- Dashboard widget API expansion
+- Accessibility and keyboard navigation improvements
+- Packaging/build pipeline polish for production release
+

django_admin_forge-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "django-admin-forge"
+version = "0.1.0"
+description = "A modern, extensible, premium Django admin framework."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "django-admin-forge contributors" }
+]
+keywords = ["django", "admin", "dashboard", "saas", "internal-tools"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Django",
+  "Framework :: Django :: 4.2",
+  "Framework :: Django :: 5.0",
+  "Framework :: Django :: 5.1",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+  "Django>=4.2,<6.0"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-django>=4.8",
+  "ruff>=0.6",
+  "build>=1.2",
+]
+publish = [
+  "build>=1.2",
+  "twine>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/your-org/django-admin-forge"
+Documentation = "https://github.com/your-org/django-admin-forge/docs"
+Repository = "https://github.com/your-org/django-admin-forge"
+Issues = "https://github.com/your-org/django-admin-forge/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+django_admin_forge = [
+  "templates/**/*.html",
+  "static/**/*",
+]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = ["src"]
+testpaths = ["tests"]

django_admin_forge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

django_admin_forge-0.1.0/src/django_admin_forge/__init__.py

@@ -0,0 +1,5 @@
+"""django-admin-forge package."""
+
+from .conf import ForgeSettings, get_forge_settings
+
+__all__ = ["ForgeSettings", "get_forge_settings"]

django_admin_forge-0.1.0/src/django_admin_forge/admin.py

@@ -0,0 +1 @@
+"""Admin registrations for django-admin-forge itself."""

django_admin_forge-0.1.0/src/django_admin_forge/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class DjangoAdminForgeConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_admin_forge"
+    verbose_name = "Django Admin Forge"

django_admin_forge-0.1.0/src/django_admin_forge/conf.py

@@ -0,0 +1,65 @@
+from dataclasses import asdict, dataclass, field
+
+from django.conf import settings
+
+ACCENT_HEX = {
+    "blue": "#2563eb",
+    "green": "#16a34a",
+    "amber": "#d97706",
+    "violet": "#7c3aed",
+    "emerald": "#059669",
+    "teal": "#0d9488",
+    "cyan": "#0891b2",
+    "sky": "#0284c7",
+    "indigo": "#4f46e5",
+    "purple": "#9333ea",
+    "pink": "#db2777",
+    "rose": "#e11d48",
+    "red": "#dc2626",
+    "orange": "#ea580c",
+    "yellow": "#ca8a04",
+    "lime": "#65a30d",
+    "slate": "#334155",
+    "gray": "#4b5563",
+    "zinc": "#52525b",
+    "neutral": "#525252",
+    "stone": "#57534e",
+}
+
+
+def _default_menu_tabs() -> list[dict[str, str]]:
+    return [
+        {
+            "label": "Dashboard",
+            "url_name": "admin:index",
+            "icon": "layout-grid",
+        }
+    ]
+
+
+@dataclass(frozen=True)
+class ForgeSettings:
+    brand_name: str = "Forge Admin"
+    brand_logo_text: str = "FORGE"
+    brand_tagline: str = "Modern Django operations panel"
+    accent_color: str = "blue"
+    default_theme: str = "system"  # light | dark | system
+    show_sidebar_search: bool = True
+    enable_command_bar: bool = True
+    menu_icons: dict[str, str] = field(default_factory=dict)
+    menu_tabs: list[dict[str, str]] = field(default_factory=_default_menu_tabs)
+    dashboard_analytics_cards: list[dict] = field(default_factory=list)
+
+    def as_context(self) -> dict:
+        data = asdict(self)
+        accent_name = (self.accent_color or "blue").lower()
+        data["accent_hex"] = ACCENT_HEX.get(accent_name, ACCENT_HEX["blue"])
+        data["accent_color"] = accent_name
+        return data
+
+
+def get_forge_settings() -> ForgeSettings:
+    user_settings = getattr(settings, "DJANGO_ADMIN_FORGE", {})
+    valid_keys = {field.name for field in ForgeSettings.__dataclass_fields__.values()}
+    filtered = {key: value for key, value in user_settings.items() if key in valid_keys}
+    return ForgeSettings(**filtered)