# Django Admin Query Executor
A powerful Django admin extension that allows you to execute Django ORM queries directly from the admin interface. It supports complex queries including `Q()` objects, annotations, aggregations, and all standard Django ORM methods.
## Features
- **Direct Query Execution**: Execute Django ORM queries directly from the admin changelist view
- **Seamless Integration**: Query results replace the standard admin list view
- **Full Django ORM Support**: Use `Q()`, `F()`, `Count()`, `Sum()`, `Avg()`, and other Django model functions
- **Query History**: Automatically saves your recent queries for quick re-execution
- **Favorite Queries**: Save frequently used queries with custom names
- **Collapsible Interface**: Clean, collapsible UI that doesn't clutter your admin
- **Comprehensive Dark Mode Support**:
- Automatically adapts to system preferences
- Compatible with Django admin's built-in dark mode
- Works with popular admin themes (Grappelli, Jazzmin, etc.)
- Smooth transitions between light and dark themes
- Accessible color contrasts in both modes
- **Security**: Queries execute in a restricted environment with whitelisted functions
- **Smart Result Detection**: Automatically handles both queryset and scalar results
## Installation
```bash
pip install django-admin-query-executor
```
## Quick Start
1. Add `django_admin_query_executor` to your `INSTALLED_APPS`:
```python
INSTALLED_APPS = [
...
'django_admin_query_executor',
...
]
```
2. Add the `QueryExecutorMixin` to your `ModelAdmin` classes:
```python
from django.contrib import admin
from django_admin_query_executor import QueryExecutorMixin
from .models import MyModel
@admin.register(MyModel)
class MyModelAdmin(QueryExecutorMixin, admin.ModelAdmin):
list_display = ['id', 'name', 'created_at']
# Optional: Define custom example queries for this model
query_examples = [
("Active items", "MyModel.objects.filter(is_active=True)"),
("Recent items", "MyModel.objects.filter(created_at__gte=timezone.now() - timedelta(days=7))"),
("Count by status", "MyModel.objects.values('status').annotate(count=Count('id'))"),
]
```
## Usage
1. Navigate to any model's admin changelist that uses `QueryExecutorMixin`
2. Click "Execute Django Query" to expand the query interface
3. Enter your Django ORM query (e.g., `MyModel.objects.filter(status='active')`)
4. Click "Execute Query"
5. The admin list updates to show your query results
### Query Examples
```python
# Filter queries
Book.objects.filter(author__name__icontains='Smith')
Book.objects.filter(Q(title__icontains='Django') | Q(title__icontains='Python'))
# Annotations and aggregations
Book.objects.annotate(review_count=Count('reviews')).filter(review_count__gt=10)
Book.objects.aggregate(avg_price=Avg('price'), total_books=Count('id'))
# Complex queries with joins
Author.objects.filter(books__published_date__year=2023).distinct()
Book.objects.select_related('author', 'publisher').filter(price__lt=50)
# Counting and existence checks
Book.objects.filter(category='Fiction').count()
Book.objects.filter(reviews__rating__gte=4).exists()
```
## Configuration
### Custom Change List Templates
The mixin automatically overrides the ModelAdmin's `change_list_template` if the default template is in use. If your ModelAdmin uses a custom template, the template will need to extend `admin/query_executor_change_list.html`:
```
{% extends "admin/query_executor_change_list.html" %}
```
### Custom Example Queries
Define model-specific example queries by adding a `query_examples` attribute to your ModelAdmin:
```python
class BookAdmin(QueryExecutorMixin, admin.ModelAdmin):
query_examples = [
("Bestsellers", "Book.objects.filter(is_bestseller=True)"),
("By price range", "Book.objects.filter(price__gte=20, price__lte=50)"),
("Review stats", "Book.objects.annotate(avg_rating=Avg('reviews__rating')).filter(avg_rating__gte=4.0)"),
]
```
### Customizing Query History
Control the number of queries saved in history:
```python
class BookAdmin(QueryExecutorMixin, admin.ModelAdmin):
query_history_limit = 10 # Default is 5
```
## Supported Django ORM Features
### Query Methods
- `filter()`, `exclude()`, `get()`
- `order_by()`, `reverse()`, `distinct()`
- `values()`, `values_list()`
- `select_related()`, `prefetch_related()`
- `annotate()`, `aggregate()`
- `first()`, `last()`, `exists()`, `count()`
### Query Expressions
- `Q()` for complex queries
- `F()` for field references
- `Count()`, `Sum()`, `Avg()`, `Max()`, `Min()`
- `Case()`, `When()` for conditional expressions
- `Exists()`, `OuterRef()`, `Subquery()`
### Database Functions
- String functions: `Lower()`, `Upper()`, `Length()`, `Concat()`
- Date functions: `TruncDate()`, `Extract()`, `Now()`
- Type casting: `Cast()`, `Coalesce()`
## Dark Mode Support
The package includes comprehensive dark mode support that:
- **Auto-detects** your system's color scheme preference
- **Integrates seamlessly** with Django admin's native dark mode
- **Supports popular admin themes** including:
- Django's built-in dark mode
- Grappelli dark theme
- Django Jazzmin dark mode
- Django Admin Interface dark themes
- **Provides smooth transitions** when switching between themes
- **Ensures accessibility** with proper color contrasts
- **Includes custom CSS variables** for easy customization
### Customizing Dark Mode Colors
You can override the default colors by adding CSS variables to your admin CSS:
```css
.query-executor-container {
--qe-bg-primary: #1a1a1a;
--qe-text-primary: #ffffff;
--qe-button-primary-bg: #007bff;
/* See query_executor_dark_mode.css for all available variables */
}
```
## Security
The query executor runs in a restricted environment with:
- Whitelisted functions and classes only
- No access to private attributes or methods
- No direct database access beyond Django ORM
- No file system or network access
## Requirements
- Django >= 3.2
- Python >= 3.8
## License
MIT License - see LICENSE file for details
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Changelog
### 1.0.0 (2025-07-17)
- Initial release
- Full Django ORM query support
- Query history and favorites
- Dark mode support
- Collapsible interface
Raw data
{
"_id": null,
"home_page": "https://github.com/j4rf/django-admin-query-executor",
"name": "django-admin-query-executor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Jeff Turner <jeff@torusoft.com>",
"keywords": "django, admin, query, executor, orm, database, django-admin",
"author": "Jeff Turner",
"author_email": "Jeff Turner <jeff@torusoft.com>",
"download_url": "https://files.pythonhosted.org/packages/d7/bc/bc93e159136a9f8e422bfc9d90873e022d19ca2ab3d2632066a45ab63f61/django_admin_query_executor-1.0.0.tar.gz",
"platform": null,
"description": "# Django Admin Query Executor\n\nA powerful Django admin extension that allows you to execute Django ORM queries directly from the admin interface. It supports complex queries including `Q()` objects, annotations, aggregations, and all standard Django ORM methods.\n\n\n\n\n\n## Features\n\n- **Direct Query Execution**: Execute Django ORM queries directly from the admin changelist view\n- **Seamless Integration**: Query results replace the standard admin list view\n- **Full Django ORM Support**: Use `Q()`, `F()`, `Count()`, `Sum()`, `Avg()`, and other Django model functions\n- **Query History**: Automatically saves your recent queries for quick re-execution\n- **Favorite Queries**: Save frequently used queries with custom names\n- **Collapsible Interface**: Clean, collapsible UI that doesn't clutter your admin\n- **Comprehensive Dark Mode Support**:\n - Automatically adapts to system preferences\n - Compatible with Django admin's built-in dark mode\n - Works with popular admin themes (Grappelli, Jazzmin, etc.)\n - Smooth transitions between light and dark themes\n - Accessible color contrasts in both modes\n- **Security**: Queries execute in a restricted environment with whitelisted functions\n- **Smart Result Detection**: Automatically handles both queryset and scalar results\n\n## Installation\n\n```bash\npip install django-admin-query-executor\n```\n\n## Quick Start\n\n1. Add `django_admin_query_executor` to your `INSTALLED_APPS`:\n\n```python\nINSTALLED_APPS = [\n ...\n 'django_admin_query_executor',\n ...\n]\n```\n\n2. Add the `QueryExecutorMixin` to your `ModelAdmin` classes:\n\n```python\nfrom django.contrib import admin\nfrom django_admin_query_executor import QueryExecutorMixin\nfrom .models import MyModel\n\n@admin.register(MyModel)\nclass MyModelAdmin(QueryExecutorMixin, admin.ModelAdmin):\n list_display = ['id', 'name', 'created_at']\n\n # Optional: Define custom example queries for this model\n query_examples = [\n (\"Active items\", \"MyModel.objects.filter(is_active=True)\"),\n (\"Recent items\", \"MyModel.objects.filter(created_at__gte=timezone.now() - timedelta(days=7))\"),\n (\"Count by status\", \"MyModel.objects.values('status').annotate(count=Count('id'))\"),\n ]\n```\n\n## Usage\n\n1. Navigate to any model's admin changelist that uses `QueryExecutorMixin`\n2. Click \"Execute Django Query\" to expand the query interface\n3. Enter your Django ORM query (e.g., `MyModel.objects.filter(status='active')`)\n4. Click \"Execute Query\"\n5. The admin list updates to show your query results\n\n### Query Examples\n\n```python\n# Filter queries\nBook.objects.filter(author__name__icontains='Smith')\nBook.objects.filter(Q(title__icontains='Django') | Q(title__icontains='Python'))\n\n# Annotations and aggregations\nBook.objects.annotate(review_count=Count('reviews')).filter(review_count__gt=10)\nBook.objects.aggregate(avg_price=Avg('price'), total_books=Count('id'))\n\n# Complex queries with joins\nAuthor.objects.filter(books__published_date__year=2023).distinct()\nBook.objects.select_related('author', 'publisher').filter(price__lt=50)\n\n# Counting and existence checks\nBook.objects.filter(category='Fiction').count()\nBook.objects.filter(reviews__rating__gte=4).exists()\n```\n\n## Configuration\n\n### Custom Change List Templates\n\nThe mixin automatically overrides the ModelAdmin's `change_list_template` if the default template is in use. If your ModelAdmin uses a custom template, the template will need to extend `admin/query_executor_change_list.html`:\n\n```\n{% extends \"admin/query_executor_change_list.html\" %}\n```\n\n### Custom Example Queries\n\nDefine model-specific example queries by adding a `query_examples` attribute to your ModelAdmin:\n\n```python\nclass BookAdmin(QueryExecutorMixin, admin.ModelAdmin):\n query_examples = [\n (\"Bestsellers\", \"Book.objects.filter(is_bestseller=True)\"),\n (\"By price range\", \"Book.objects.filter(price__gte=20, price__lte=50)\"),\n (\"Review stats\", \"Book.objects.annotate(avg_rating=Avg('reviews__rating')).filter(avg_rating__gte=4.0)\"),\n ]\n```\n\n### Customizing Query History\n\nControl the number of queries saved in history:\n\n```python\nclass BookAdmin(QueryExecutorMixin, admin.ModelAdmin):\n query_history_limit = 10 # Default is 5\n```\n\n## Supported Django ORM Features\n\n### Query Methods\n- `filter()`, `exclude()`, `get()`\n- `order_by()`, `reverse()`, `distinct()`\n- `values()`, `values_list()`\n- `select_related()`, `prefetch_related()`\n- `annotate()`, `aggregate()`\n- `first()`, `last()`, `exists()`, `count()`\n\n### Query Expressions\n- `Q()` for complex queries\n- `F()` for field references\n- `Count()`, `Sum()`, `Avg()`, `Max()`, `Min()`\n- `Case()`, `When()` for conditional expressions\n- `Exists()`, `OuterRef()`, `Subquery()`\n\n### Database Functions\n- String functions: `Lower()`, `Upper()`, `Length()`, `Concat()`\n- Date functions: `TruncDate()`, `Extract()`, `Now()`\n- Type casting: `Cast()`, `Coalesce()`\n\n## Dark Mode Support\n\nThe package includes comprehensive dark mode support that:\n\n- **Auto-detects** your system's color scheme preference\n- **Integrates seamlessly** with Django admin's native dark mode\n- **Supports popular admin themes** including:\n - Django's built-in dark mode\n - Grappelli dark theme\n - Django Jazzmin dark mode\n - Django Admin Interface dark themes\n- **Provides smooth transitions** when switching between themes\n- **Ensures accessibility** with proper color contrasts\n- **Includes custom CSS variables** for easy customization\n\n### Customizing Dark Mode Colors\n\nYou can override the default colors by adding CSS variables to your admin CSS:\n\n```css\n.query-executor-container {\n --qe-bg-primary: #1a1a1a;\n --qe-text-primary: #ffffff;\n --qe-button-primary-bg: #007bff;\n /* See query_executor_dark_mode.css for all available variables */\n}\n```\n\n## Security\n\nThe query executor runs in a restricted environment with:\n- Whitelisted functions and classes only\n- No access to private attributes or methods\n- No direct database access beyond Django ORM\n- No file system or network access\n\n## Requirements\n\n- Django >= 3.2\n- Python >= 3.8\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Changelog\n\n### 1.0.0 (2025-07-17)\n- Initial release\n- Full Django ORM query support\n- Query history and favorites\n- Dark mode support\n- Collapsible interface\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Execute Django ORM queries directly from the admin interface",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/j4rf/django-admin-query-executor/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/j4rf/django-admin-query-executor/blob/main/README.md",
"Homepage": "https://github.com/j4rf/django-admin-query-executor",
"Issues": "https://github.com/j4rf/django-admin-query-executor/issues",
"Repository": "https://github.com/j4rf/django-admin-query-executor"
},
"split_keywords": [
"django",
" admin",
" query",
" executor",
" orm",
" database",
" django-admin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "af42b1b7bb762237b9a84c881b51bcfd22f2ad721c25aa39df09c0691ecf2a74",
"md5": "aa7bd68833a267fd26d8be88b43926eb",
"sha256": "63ce6f0bc791ead1eda25825f68c19229df7478af258a7681061a5972c8c2682"
},
"downloads": -1,
"filename": "django_admin_query_executor-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aa7bd68833a267fd26d8be88b43926eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16906,
"upload_time": "2025-07-17T17:53:37",
"upload_time_iso_8601": "2025-07-17T17:53:37.179944Z",
"url": "https://files.pythonhosted.org/packages/af/42/b1b7bb762237b9a84c881b51bcfd22f2ad721c25aa39df09c0691ecf2a74/django_admin_query_executor-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d7bcbc93e159136a9f8e422bfc9d90873e022d19ca2ab3d2632066a45ab63f61",
"md5": "a810bddf0e1d847eff6bdbea678b385b",
"sha256": "e098214000c195b187769e1ba96175eb41296517aa74a8dea4e6dce21e1ca17b"
},
"downloads": -1,
"filename": "django_admin_query_executor-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "a810bddf0e1d847eff6bdbea678b385b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20165,
"upload_time": "2025-07-17T17:53:38",
"upload_time_iso_8601": "2025-07-17T17:53:38.682585Z",
"url": "https://files.pythonhosted.org/packages/d7/bc/bc93e159136a9f8e422bfc9d90873e022d19ca2ab3d2632066a45ab63f61/django_admin_query_executor-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 17:53:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "j4rf",
"github_project": "django-admin-query-executor",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-admin-query-executor"
}
JSON
