django-admin-autoapi 0.1.0__tar.gz

django_admin_autoapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Chris Spence
+
+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_autoapi-0.1.0/PKG-INFO

@@ -0,0 +1,386 @@
+Metadata-Version: 2.4
+Name: django-admin-autoapi
+Version: 0.1.0
+Summary: Zero-config REST API generation for Django Admin
+Author-email: Chris Spence <chris@example.com>
+Maintainer-email: Chris Spence <chris@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/chrisspen/django-admin-autoapi
+Project-URL: Documentation, https://github.com/chrisspen/django-admin-autoapi#readme
+Project-URL: Repository, https://github.com/chrisspen/django-admin-autoapi.git
+Project-URL: Issues, https://github.com/chrisspen/django-admin-autoapi/issues
+Project-URL: Changelog, https://github.com/chrisspen/django-admin-autoapi/blob/main/CHANGELOG.md
+Keywords: django,admin,rest,api,automatic,zero-config
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Requires-Dist: djangorestframework>=3.14
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-django>=4.5; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.12; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: tox>=4.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+<img src="./assets/logo-clear2-medium.png" alt="django-admin-autoapi logo">
+</div>
+
+
+# django-admin-autoapi
+
+Zero-configuration REST API generation for Django Admin. Automatically expose your admin-registered models via a REST API with token authentication and Django model permissions.
+
+## Features
+
+- **Zero Configuration**: Models registered with the admin are automatically available via REST API
+- **Token Authentication**: Uses Django REST Framework's token authentication
+- **Permission Integration**: Leverages Django's built-in model permissions (view, add, change, delete)
+- **Field Selection**: Request only the fields you need with `?fields=name,email`
+- **Filtering**: Filter querysets with query parameters like `?status=published`
+- **Ordering**: Sort results with `?order_by=name` or `?order_by=-created_at`
+- **Pagination**: Built-in pagination with configurable page size
+- **Calculated Fields**: Expose model properties via `api_calculated_fields`
+
+## Installation
+
+```bash
+pip install django-admin-autoapi
+```
+
+Add to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # Django apps
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    # ...
+
+    # Required
+    "rest_framework",
+    "rest_framework.authtoken",
+    "django_admin_autoapi",
+
+    # Your apps
+    "myapp",
+]
+```
+
+Configure Django REST Framework:
+
+```python
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "rest_framework.authentication.TokenAuthentication",
+        "rest_framework.authentication.SessionAuthentication",
+    ],
+    "DEFAULT_PERMISSION_CLASSES": [
+        "rest_framework.permissions.IsAuthenticated",
+    ],
+    "PAGE_SIZE": 25,
+}
+```
+
+## Usage
+
+### Basic Setup
+
+Replace Django's default admin site with the AutoAPI admin site:
+
+```python
+# myapp/admin.py
+from django.contrib import admin
+from django_admin_autoapi.sites import site
+
+from .models import Author, Book
+
+# Register models with the AutoAPI admin site
+site.register(Author)
+site.register(Book)
+```
+
+Update your URL configuration:
+
+```python
+# urls.py
+from django_admin_autoapi.sites import site
+
+urlpatterns = [
+    path("admin/", site.urls),
+]
+```
+
+That's it! Your models are now available via REST API at:
+
+- `GET /admin/api/` - List all available endpoints
+- `GET /admin/api/myapp/author/` - List authors
+- `GET /admin/api/myapp/author/123/` - Retrieve author 123
+- `POST /admin/api/myapp/author/` - Create author
+- `PATCH /admin/api/myapp/author/123/` - Update author 123
+- `DELETE /admin/api/myapp/author/123/` - Delete author 123
+
+### Authentication
+
+Get a token for a user:
+
+```bash
+# Create a token (in Django shell or via management command)
+from rest_framework.authtoken.models import Token
+token = Token.objects.create(user=user)
+```
+
+Use the token in API requests:
+
+```bash
+curl -H "Authorization: Token your-token-here" \
+     http://localhost:8000/admin/api/myapp/author/
+```
+
+### Field Selection
+
+Request only specific fields:
+
+```bash
+# Only get id, name, and email
+curl -H "Authorization: Token ..." \
+     "http://localhost:8000/admin/api/myapp/author/?fields=name,email"
+```
+
+### Filtering
+
+Filter results with query parameters:
+
+```bash
+# Filter by status
+curl -H "Authorization: Token ..." \
+     "http://localhost:8000/admin/api/myapp/book/?status=published"
+
+# Filter by related field
+curl -H "Authorization: Token ..." \
+     "http://localhost:8000/admin/api/myapp/book/?author=123"
+
+# Django-style lookups
+curl -H "Authorization: Token ..." \
+     "http://localhost:8000/admin/api/myapp/book/?title__contains=Django"
+```
+
+### Ordering
+
+Sort results:
+
+```bash
+# Sort by name ascending
+curl -H "Authorization: Token ..." \
+     "http://localhost:8000/admin/api/myapp/author/?order_by=name"
+
+# Sort by created_at descending
+curl -H "Authorization: Token ..." \
+     "http://localhost:8000/admin/api/myapp/author/?order_by=-created_at"
+
+# Multiple fields
+curl -H "Authorization: Token ..." \
+     "http://localhost:8000/admin/api/myapp/book/?order_by=author,-title"
+```
+
+### Calculated Fields
+
+Expose model properties in the API:
+
+```python
+class Author(models.Model):
+    first_name = models.CharField(max_length=100)
+    last_name = models.CharField(max_length=100)
+    email = models.EmailField()
+
+    # List properties to expose via API
+    api_calculated_fields = ["full_name", "display_name"]
+
+    @property
+    def full_name(self):
+        return f"{self.first_name} {self.last_name}"
+
+    @property
+    def display_name(self):
+        return f"{self.full_name} <{self.email}>"
+```
+
+### Custom Admin Classes
+
+Use the mixin with custom ModelAdmin classes:
+
+```python
+from django.contrib import admin
+from django_admin_autoapi.sites import site
+from django_admin_autoapi.mixins import AutoAPIMixin
+
+class AuthorAdmin(AutoAPIMixin, admin.ModelAdmin):
+    list_display = ["name", "email", "is_active"]
+    list_filter = ["is_active"]
+    search_fields = ["name", "email"]
+
+site.register(Author, AuthorAdmin)
+```
+
+### Read-Only API
+
+For read-only API access, use the read-only mixin:
+
+```python
+from django_admin_autoapi.mixins import ReadOnlyAutoAPIMixin
+
+class ReportAdmin(ReadOnlyAutoAPIMixin, admin.ModelAdmin):
+    list_display = ["title", "created_at"]
+
+site.register(Report, ReportAdmin)
+```
+
+## Permissions
+
+The API respects Django's built-in model permissions:
+
+| HTTP Method | Required Permission |
+|------------|---------------------|
+| GET | `app.view_model` |
+| POST | `app.add_model` |
+| PUT/PATCH | `app.change_model` |
+| DELETE | `app.delete_model` |
+
+Users must have `is_staff=True` and the appropriate permissions to access the API.
+
+## Pagination
+
+Responses are paginated by default:
+
+```json
+{
+    "count": 100,
+    "next": "http://localhost:8000/admin/api/myapp/author/?page=2",
+    "previous": null,
+    "results": [
+        {"id": 1, "name": "Author 1", ...},
+        {"id": 2, "name": "Author 2", ...},
+        ...
+    ]
+}
+```
+
+Configure pagination in settings:
+
+```python
+REST_FRAMEWORK = {
+    "PAGE_SIZE": 25,  # Default items per page
+    "MAX_PAGE_SIZE": 1000,  # Maximum items per page
+}
+```
+
+Request a specific page size:
+
+```bash
+curl "http://localhost:8000/admin/api/myapp/author/?limit=50"
+```
+
+## API Index
+
+Get a list of all available endpoints:
+
+```bash
+curl -H "Authorization: Token ..." \
+     http://localhost:8000/admin/api/
+```
+
+Response:
+
+```json
+{
+    "endpoints": [
+        {
+            "model": "myapp.author",
+            "list_url": "/admin/api/myapp/author/",
+            "detail_url": "/admin/api/myapp/author/<pk>/",
+            "verbose_name": "author",
+            "verbose_name_plural": "authors"
+        },
+        ...
+    ],
+    "count": 5
+}
+```
+
+## Configuration
+
+### Custom Admin Site Name
+
+```python
+from django_admin_autoapi.sites import AutoAPIAdminSite
+
+site = AutoAPIAdminSite(name="myadmin")
+```
+
+### Disable API for Specific Models
+
+Register with the standard Django admin instead of the AutoAPI site:
+
+```python
+from django.contrib import admin
+from django_admin_autoapi.sites import site
+
+# This model gets an API
+site.register(PublicModel)
+
+# This model doesn't get an API
+admin.site.register(InternalModel)
+```
+
+## Requirements
+
+- Python 3.11+
+- Django 4.2+
+- Django REST Framework 3.14+
+
+## Development
+
+Run tests across Python and Django versions:
+
+```bash
+./test.sh
+```
+
+Or run a specific environment:
+
+```bash
+./test.sh -e py312-django50
+```
+
+Available test environments:
+- `py311-django42` - Python 3.11 + Django 4.2
+- `py311-django50` - Python 3.11 + Django 5.0
+- `py312-django42` - Python 3.12 + Django 4.2
+- `py312-django50` - Python 3.12 + Django 5.0
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.