django-admin-grpc

Django Admin backed by gRPC services — no ORM required.

django-admin-grpc lets you expose remote gRPC microservices inside Django Admin with full list, create, update, delete and search support. You define a resource schema, wire a gRPC adapter, and register a single admin class — the package handles forms, pagination, filtering, and error mapping for you.

Installation

pip install django-admin-grpc

Add the app to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django_admin_grpc",
]

Quick Start

# resources.py
from django_admin_grpc.resources import (
    BaseGrpcResource,
    BooleanFieldConfig,
    CharFieldConfig,
    FloatFieldConfig,
)

class Product(BaseGrpcResource):
    class Meta:
        app_label = "catalog"
        model_name = "product"
        verbose_name = "Product"
        pk_field = "id"

    fields = [
        CharFieldConfig(name="id"),
        CharFieldConfig(name="name", max_length=200),
        FloatFieldConfig(name="price"),
        BooleanFieldConfig(name="active", initial=True),
    ]

That is all. Django Admin now shows list, add, change, and delete screens powered by your gRPC service.

Package Architecture

How to Define a New Resource

A resource is a Python class that tells Django Admin what columns exist, what types they are, and which one is the primary key.

from django_admin_grpc.resources import (
    BaseGrpcResource,
    BooleanFieldConfig,
    CharFieldConfig,
    FKFieldConfig,
    IntegerFieldConfig,
)

class NetworkRule(BaseGrpcResource):
    class Meta:
        app_label = "network"
        model_name = "networkrule"
        verbose_name = "Network Rule"
        verbose_name_plural = "Network Rules"
        pk_field = "rule_id"

    fields = [
        CharFieldConfig(name="rule_id", label="Rule ID"),
        CharFieldConfig(name="name", max_length=120),
        IntegerFieldConfig(name="priority"),
        BooleanFieldConfig(name="active", initial=True),
        FKFieldConfig(
            name="partner_id",
            label="Partner",
            model="contacts.Contact",      # resolves via Django ORM
            display_field="name",
            required=False,
        ),
    ]

Supported field types:

Common field options (all subclasses):

• name — field identifier (required).
• label — human label (default: auto-title-cased name).
• required — whether the form field is required (default: True).
• help_text — shown below the form field.
• initial — default value.
• source — name of the attribute in the gRPC response if it differs from name.

Type-specific options:

• CharFieldConfig: max_length — max characters allowed.
• ChoicesFieldConfig: choices — list of (value, label) tuples.
• FKFieldConfig:
  • model — "app_label.ModelName" for Django FK resolution.
  • to_field — model field to use as the FK value.
  • display_field — field to show in detail views; omitted means show the raw FK value.
  • service — service name in the adapter registry for gRPC FK resolution.
  • get_method — adapter method to call for gRPC FK resolution (default: get).
  • choices — static (value, label) select options for service/custom FK fields.
  • choices_loader — callable returning (value, label) options for service/custom FK fields.

How to Wire gRPC Stubs

An adapter bridges Django Admin and your gRPC service. Subclass BaseGrpcServiceAdapter and implement at least list and get. Implement create, update, and delete only if you need write access.

from django_admin_grpc.adapters import BaseGrpcServiceAdapter
from django_admin_grpc.paginator import PagedResult
import grpc

class NetworkRulesAdapter(BaseGrpcServiceAdapter):
    service_name = "network_rules"

    def __init__(self):
        self._channel = None

    @property
    def channel(self):
        if self._channel is None:
            raw = grpc.insecure_channel("network-service:50051")
            self._channel = self._wrap_channel(raw)
        return self._channel

    def list(self, resource_class, page=1, page_size=25, filters=None):
        stub = NetworkRulesStub(self.channel)
        request = ListRulesRequest(page=page, page_size=page_size)
        response = stub.ListRules(request)
        items = [resource_class.from_response(r) for r in response.rules]
        return PagedResult(items=items, total=response.total)

    def get(self, resource_class, pk):
        stub = NetworkRulesStub(self.channel)
        response = stub.GetRule(GetRuleRequest(rule_id=pk))
        return resource_class.from_response(response)

    def create(self, resource_class, data):
        stub = NetworkRulesStub(self.channel)
        request = CreateRuleRequest(**data)
        response = stub.CreateRule(request)
        return resource_class.from_response(response)

    def update(self, resource_class, pk, data):
        stub = NetworkRulesStub(self.channel)
        request = UpdateRuleRequest(rule_id=pk, **data)
        response = stub.UpdateRule(request)
        return resource_class.from_response(response)

    def delete(self, resource_class, pk):
        stub = NetworkRulesStub(self.channel)
        stub.DeleteRule(DeleteRuleRequest(rule_id=pk))
        return True

Registering via the adapter registry (optional):

from django_admin_grpc.registry import adapter_registry

adapter = NetworkRulesAdapter()
adapter_registry.register("network_rules", adapter)

When registered by name, the admin class can reference it with service_name = "network_rules" instead of adapter_class.

How to Register in Django Admin

Register the resource's fake model with a GrpcResourceAdmin subclass:

from django.contrib import admin
from django_admin_grpc.admin import GrpcResourceAdmin

from .resources import NetworkRule
from .adapters import NetworkRulesAdapter

@admin.register(NetworkRule.admin_model())
class NetworkRuleAdmin(GrpcResourceAdmin):
    resource_class = NetworkRule
    adapter_class = NetworkRulesAdapter   # or service_name = "network_rules"

    list_display = ["rule_id", "name", "active"]
    list_filter = ["active"]
    search_fields = ["name"]

    grpc_enable_create = True
    grpc_enable_update = True
    grpc_enable_delete = True
    grpc_form_fields = ["name", "priority", "active", "partner_id"]

Resource.admin_model() builds a lightweight compatible class with _meta, objects, DoesNotExist, and MultipleObjectsReturned so that Django's ModelAdmin machinery works without a real ORM model.

How to Customize Forms

By default, forms are built automatically from grpc_form_fields and the resource's field config list. You can override widgets or build the form class yourself.

Custom widgets per field:

class ProductAdmin(GrpcResourceAdmin):
    resource_class = Product
    adapter_class = CatalogAdapter
    grpc_form_fields = ["name", "description", "price"]

    def _build_form_class(self):
        return self.resource_class.build_form_class(widgets={
            "description": forms.Textarea(attrs={"rows": 8}),
            "price": forms.NumberInput(attrs={"step": "0.01"}),
        })

Using build_form_class() on the resource:

from django import forms

form_class = Product.build_form_class(widgets={
    "name": forms.TextInput(attrs={"class": "vTextField"}),
})

Filtering which fields appear:

Set grpc_form_fields to a subset of the resource's fields. Only those fields will be rendered in add/change views.

Customizing create/update payloads:

Override get_grpc_create_data and get_grpc_update_data on the admin class to transform cleaned_data before it reaches the adapter:

class ProductAdmin(GrpcResourceAdmin):
    def get_grpc_create_data(self, cleaned_data):
        data = dict(cleaned_data)
        data["created_by"] = self.request.user.username
        return data

How to Customize Permissions

Permissions are controlled by three flags on the admin class:

class ProductAdmin(GrpcResourceAdmin):
    grpc_enable_create = True   # show "Add" button
    grpc_enable_update = True   # allow editing in change view
    grpc_enable_delete = True   # show delete button and bulk delete action

These flags are ANDed with adapter capability: if the adapter does not implement create(), the add view is disabled automatically even when grpc_enable_create = True.

Hook methods for dynamic permission checks:

class ProductAdmin(GrpcResourceAdmin):
    def has_add_permission(self, request):
        return request.user.is_superuser and super().has_add_permission(request)

    def has_delete_permission(self, request, obj=None):
        return request.user.groups.filter(name="Admins").exists()

How to Customize List Pages

GrpcResourceAdmin supports the standard ModelAdmin list options:

class ProductAdmin(GrpcResourceAdmin):
    list_display = ["id", "name", "price", "active"]
    list_filter = ["active", "category_id"]
    search_fields = ["name", "description"]
    list_per_page = 25

Filter configuration:

For list filters to work, declare grpc_filter_config as a list or dict:

class ProductAdmin(GrpcResourceAdmin):
    # Simple list — fields are auto-detected by type
    grpc_filter_config = ["active", "category_id"]

    # Dict form — override type or choices per field
    grpc_filter_config = {
        "active": {"type": "boolean"},
        "status": {"type": "choices", "choices": [("draft", "Draft"), ("live", "Live")]},
        "name": {"type": "text", "label": "Product Name"},
    }

Supported filter types: boolean, choices, text. The admin renders a sidebar filter panel just like standard Django Admin.

Pagination:

By default the adapter receives page (1-indexed) and page_size. Return a PagedResult from adapter.list():

PagedResult(items=instances, total=total_count, page=page, page_size=page_size)

For cursor-based pagination, set grpc_cursor_pagination = True on the admin. The adapter will receive page_size and filters["cursor"]. Return the next cursor in PagedResult.next_cursor.

How to Customize Actions

Bulk delete is built in. When grpc_enable_delete = True and the adapter supports delete, a "Delete selected records" action appears in the dropdown.

Adding custom actions:

from django.contrib import messages

class ProductAdmin(GrpcResourceAdmin):
    actions = ["activate_selected"]

    @admin.action(description="Activate selected products")
    def activate_selected(self, request, queryset):
        adapter = self.get_adapter()
        for obj in queryset:
            adapter.update(self.resource_class, obj.pk, {"active": True})
        messages.success(request, "Selected products activated.")

Because queryset is a GrpcFakeQuerySet, iterate over it to access the wrapped resource instances.

Error Handling

gRPC errors are caught at the adapter boundary and mapped to typed exceptions. The admin displays them as Django messages.

Mapping errors in your adapter:

from django_admin_grpc.exceptions import map_grpc_error

class MyAdapter(BaseGrpcServiceAdapter):
    def get(self, resource_class, pk):
        try:
            return self.stub.Get(...)
        except grpc.RpcError as exc:
            raise self._map_rpc_error(exc)

You can also catch the typed exceptions in custom admin methods if you need special handling.

Customizing Appearance

Custom Widgets

You can override widgets per field when building the form class:

from django import forms
from django_admin_grpc.admin import GrpcResourceAdmin

class ProductAdmin(GrpcResourceAdmin):
    resource_class = Product
    adapter_class = CatalogAdapter
    grpc_form_fields = ["name", "description", "price", "active"]

    def _build_form_class(self):
        return self.resource_class.build_form_class(
            widgets={
                "description": forms.Textarea(attrs={"rows": 8}),
                "price": forms.NumberInput(attrs={"step": "0.01"}),
            }
        )

Or set defaults globally in settings.py:

GRPC_ADMIN = {
    "DEFAULT_WIDGETS": {
        "char": forms.TextInput,
        "text": forms.Textarea,
        "boolean": forms.CheckboxInput,
    },
}

Custom Admin Base Class

GrpcResourceAdmin inherits from Django's ModelAdmin. If you use a custom admin theme (e.g. django-unfold, django-jazzmin, etc.), subclass with the theme's ModelAdmin after GrpcResourceAdmin:

from django.contrib import admin
from django_admin_grpc.admin import GrpcResourceAdmin
from unfold.admin import ModelAdmin as UnfoldModelAdmin

class MyGrpcAdmin(GrpcResourceAdmin, UnfoldModelAdmin):
    pass

@admin.register(Product.admin_model())
class ProductAdmin(MyGrpcAdmin):
    resource_class = Product
    adapter_class = CatalogAdapter

Alternatively, use the factory helper:

MyGrpcAdmin = GrpcResourceAdmin.with_base(UnfoldModelAdmin)

Custom Templates

You can override templates per-resource via the resource Meta class:

class Product(BaseGrpcResource):
    class Meta:
        app_label = "catalog"
        change_form_template = "myapp/product_change_form.html"
        delete_confirm_template = "myapp/product_delete_confirm.html"

Or globally via settings.py:

GRPC_ADMIN = {
    "DEFAULT_CHANGE_FORM_TEMPLATE": "myapp/change_form.html",
    "DEFAULT_DELETE_CONFIRM_TEMPLATE": "myapp/delete_confirm.html",
    "DEFAULT_CURSOR_PAGINATION_TEMPLATE": "myapp/cursor_pagination.html",
}

Configuration

Set these in your Django settings.py:

Example Project

An example Django project is included in the example/ directory. It demonstrates a catalog microservice with in-memory adapters so you can run the admin locally without a real gRPC server.

cd example
python manage.py migrate
python manage.py runserver

Browse to /admin/ to see Products and Categories backed by gRPC-style adapters.

Contributing

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/my-change.
3. Install dev dependencies: pip install -e '.[dev]'.
4. Run tests: pytest.
5. Open a pull request.

Please include tests for new functionality and keep line coverage at 80% or higher.

License

MIT License. See LICENSE for details.