Import/Export
The django_import_export module integrates django-import-export into Django-CFG, re-exporting its components through the Django-CFG registry and automatically applying Unfold admin styling via custom templates and form classes.
What It Provides
- Registry integration — import admin classes, forms, and resources from
django_cfgdirectly - Unfold styling — import/export buttons and forms use Unfold-compatible form classes and templates automatically
- Zero overhead — thin wrappers around the original library; no behavioural changes
- Full compatibility — 100% compatible with upstream
django-import-export
Installation
pip install django-import-exportThe module is included in Django-CFG and activated automatically when django-import-export is installed. No additional configuration is required.
Quick Start
from django_cfg import ImportExportModelAdmin, BaseResource
from django.contrib import admin
from .models import Vehicle
class VehicleResource(BaseResource):
class Meta:
model = Vehicle
fields = ('id', 'brand', 'model', 'year', 'price', 'mileage')
export_order = ('id', 'brand', 'model', 'year', 'price', 'mileage')
@admin.register(Vehicle)
class VehicleAdmin(ImportExportModelAdmin):
resource_class = VehicleResource
list_display = ('brand', 'model', 'year', 'price')
list_filter = ('brand', 'year')
search_fields = ('brand', 'model')Available Components
All components are importable from django_cfg:
from django_cfg import (
ImportExportMixin,
ImportExportModelAdmin,
ExportMixin,
ImportMixin,
BaseResource,
ImportForm,
ExportForm,
SelectableFieldsExportForm,
)Admin Classes
| Class | Extends | Description |
|---|---|---|
ImportExportModelAdmin | import_export.admin.ImportExportModelAdmin | Full admin class with import and export |
ImportExportMixin | import_export.admin.ImportExportMixin | Mixin for adding import/export to an existing admin class |
ExportMixin | import_export.admin.ExportMixin | Mixin for export-only admin |
ImportMixin | import_export.admin.ImportMixin | Mixin for import-only admin |
Each class applies the correct Unfold-styled template and form class automatically:
ImportExportModelAdminandImportExportMixinusechange_list_import_export.htmlExportMixinuseschange_list_export.htmlImportMixinuseschange_list_import.html
Forms
| Form | Description |
|---|---|
ImportForm | Standard import form, Unfold styled |
ExportForm | Standard export form, Unfold styled |
SelectableFieldsExportForm | Export form with field selection, Unfold styled |
Resources
BaseResource is an alias for import_export.resources.ModelResource. Use it to define which model fields to include in import/export operations:
from django_cfg import BaseResource
from import_export import fields, widgets
class ProductResource(BaseResource):
category_name = fields.Field(
column_name='category',
attribute='category__name',
widget=widgets.ForeignKeyWidget(Category, 'name')
)
class Meta:
model = Product
fields = ('id', 'name', 'category_name', 'price', 'quantity')
export_order = ('id', 'name', 'category_name', 'price', 'quantity')Using Only Export or Only Import
from django_cfg import ExportMixin, ImportMixin, BaseResource
from django.contrib import admin
# Export-only admin
class ReportAdmin(ExportMixin, admin.ModelAdmin):
resource_class = ReportResource
# Import-only admin
class UserImportAdmin(ImportMixin, admin.ModelAdmin):
resource_class = UserResourceCustom Import Form
from django_cfg import ImportForm, ImportExportModelAdmin
from django import forms
class CustomImportForm(ImportForm):
update_existing = forms.BooleanField(
required=False,
initial=True,
help_text='Update existing records if key matches'
)
class ProductAdmin(ImportExportModelAdmin):
import_form_class = CustomImportFormCustom Export Form
from django_cfg import ExportForm, ImportExportModelAdmin
class CustomExportForm(ExportForm):
# Add custom fields to the export form
pass
class ProductAdmin(ImportExportModelAdmin):
export_form_class = CustomExportFormResource Hooks
BaseResource supports the full set of django-import-export lifecycle hooks:
class ProductResource(BaseResource):
class Meta:
model = Product
fields = ('name', 'price', 'sku')
def before_import(self, dataset, **kwargs):
"""Pre-process the entire dataset."""
required = ['name', 'price']
missing = [col for col in required if col not in dataset.headers]
if missing:
raise ValueError(f"Missing required columns: {missing}")
def before_import_row(self, row, **kwargs):
"""Modify a single row before import."""
if 'price' in row:
row['price'] = float(str(row['price']).replace(',', '.'))
def skip_row(self, instance, original, row, import_validation_errors=None):
"""Skip rows that fail custom validation."""
if hasattr(instance, 'price') and instance.price <= 0:
return True
return super().skip_row(instance, original, row, import_validation_errors)
def after_import(self, dataset, result, **kwargs):
"""Post-process after import completes."""
if not result.has_errors():
# trigger notifications or side effects
pass
def dehydrate_price(self, product):
"""Custom export formatting for the price field."""
return f"{product.price:.2f}"Custom Templates
The module ships custom admin templates located in templates/admin/import_export/ that integrate with the Unfold design system:
| Template | Used when |
|---|---|
change_list_import_export.html | Both import and export enabled |
change_list_import.html | Import-only |
change_list_export.html | Export-only |
change_list_import_item.html | Import button component |
change_list_export_item.html | Export button component |
Import/export buttons render as round icon buttons matching the Unfold admin style, positioned next to the standard “Add” button.
Changelist Context
ImportExportMixin and ImportExportModelAdmin inject permission flags into the changelist template context:
extra_context['has_import_permission'] = self.has_import_permission(request)
extra_context['has_export_permission'] = self.has_export_permission(request)This allows templates to conditionally show import/export buttons based on user permissions.
Equivalent Upstream Imports
The module exists to provide a single consistent import path. The underlying library is unchanged:
# Instead of:
from import_export.admin import ImportExportModelAdmin
from import_export.resources import ModelResource
from unfold.contrib.import_export.forms import ImportForm, ExportForm
# Use:
from django_cfg import ImportExportModelAdmin, BaseResource, ImportForm, ExportFormFull Documentation
For complete resource, field, and widget documentation, see the official django-import-export documentation .
TAGS: import-export, admin, data-management, csv, xlsx, unfold DEPENDS_ON: [django-admin, django-unfold]
Django-CFG