0
# Django Import Export
1
2
Django Import Export is a Django application and library for importing and exporting data with included admin integration. It enables developers to handle import/export operations from/to various file formats (CSV, XLSX, JSON, YAML, HTML, pandas) through both programmatic APIs and Django Admin UI integration.
3
4
## Package Information
5
6
- **Package Name**: django-import-export
7
- **Language**: Python
8
- **Framework**: Django
9
- **Installation**: `pip install django-import-export`
10
11
## Core Imports
12
13
```python
14
from import_export import resources, fields, widgets
15
from import_export.admin import ImportExportModelAdmin, ExportActionModelAdmin
16
from import_export import results, exceptions
17
```
18
19
For format handling:
20
21
```python
22
from import_export.formats.base_formats import CSV, XLSX, JSON, YAML, TSV
23
```
24
25
For advanced usage:
26
27
```python
28
from import_export.instance_loaders import CachedInstanceLoader
29
from import_export.signals import post_import, post_export
30
from import_export.forms import ImportForm, ExportForm
31
```
32
33
## Basic Usage
34
35
```python
36
from django.db import models
37
from import_export import resources, fields, widgets
38
from import_export.admin import ImportExportModelAdmin
39
40
# Define a model
41
class Book(models.Model):
42
title = models.CharField(max_length=200)
43
author = models.CharField(max_length=100)
44
published_date = models.DateField()
45
isbn = models.CharField(max_length=13)
46
47
# Define a resource for the model
48
class BookResource(resources.ModelResource):
49
title = fields.Field(attribute='title', column_name='Book Title')
50
author = fields.Field(attribute='author', column_name='Author Name')
51
published_date = fields.Field(
52
attribute='published_date',
53
column_name='Publication Date',
54
widget=widgets.DateWidget(format='%Y-%m-%d')
55
)
56
isbn = fields.Field(attribute='isbn', column_name='ISBN')
57
58
class Meta:
59
model = Book
60
fields = ('title', 'author', 'published_date', 'isbn')
61
export_order = ('title', 'author', 'published_date', 'isbn')
62
63
# Use in Django admin
64
class BookAdmin(ImportExportModelAdmin):
65
resource_class = BookResource
66
list_display = ['title', 'author', 'published_date']
67
68
# Programmatic usage
69
resource = BookResource()
70
71
# Export data
72
dataset = resource.export()
73
csv_data = dataset.csv
74
75
# Import data from CSV
76
from tablib import Dataset
77
dataset = Dataset()
78
dataset.csv = csv_data
79
result = resource.import_data(dataset, dry_run=True)
80
81
if not result.has_errors():
82
resource.import_data(dataset, dry_run=False)
83
```
84
85
## Architecture
86
87
Django Import Export is built around several key components that work together to provide flexible data import/export capabilities:
88
89
- **Resources**: Define how model data maps to import/export formats
90
- **Fields**: Handle individual field mapping and transformation
91
- **Widgets**: Transform data between Python objects and serialized formats
92
- **Admin Integration**: Seamless Django admin interface for import/export operations
93
- **Format Support**: Multiple file format support through tablib integration
94
- **Instance Loaders**: Efficient data loading strategies for performance optimization
95
96
The declarative approach using Resource classes allows for powerful customization while maintaining simplicity for common use cases.
97
98
## Capabilities
99
100
### Resources and Fields
101
102
Core system for defining how Django models map to import/export data, including field mapping, data transformation, and business logic hooks.
103
104
```python { .api }
105
class Resource(metaclass=DeclarativeMetaclass):
106
def __init__(self, **kwargs): ...
107
def import_data(self, dataset, dry_run=False, raise_errors=False, use_transactions=None, collect_failed_rows=False, rollback_on_validation_errors=False, **kwargs) -> Result: ...
108
def export(self, queryset=None, **kwargs) -> Dataset: ...
109
def import_row(self, row, instance_loader, **kwargs) -> RowResult: ...
110
def get_or_init_instance(self, instance_loader, row) -> tuple: ...
111
def validate_instance(self, instance, import_validation_errors=None, validate_unique=True): ...
112
def save_instance(self, instance, is_create, row, **kwargs): ...
113
def bulk_create(self, using_transactions, dry_run, raise_errors, batch_size=None, result=None): ...
114
def bulk_update(self, using_transactions, dry_run, raise_errors, batch_size=None, result=None): ...
115
def bulk_delete(self, using_transactions, dry_run, raise_errors, result=None): ...
116
# Hook methods for customization
117
def before_import(self, dataset, **kwargs): ...
118
def after_import(self, dataset, result, **kwargs): ...
119
def before_import_row(self, row, **kwargs): ...
120
def after_import_row(self, row, row_result, **kwargs): ...
121
122
class ModelResource(Resource, metaclass=ModelDeclarativeMetaclass):
123
def get_queryset(self) -> QuerySet: ...
124
def field_from_django_field(self, field_name, django_field, readonly) -> Field: ...
125
126
class Field:
127
def __init__(self, attribute=None, column_name=None, widget=None, default=NOT_PROVIDED, readonly=False, saves_null_values=True, dehydrate_method=None, m2m_add=False): ...
128
def clean(self, row, **kwargs): ...
129
def export(self, instance, **kwargs): ...
130
def save(self, instance, row, is_m2m=False, **kwargs): ...
131
```
132
133
[Resources and Fields](./resources-fields.md)
134
135
### Django Admin Integration
136
137
Complete Django admin integration with import/export functionality, including file upload, validation, confirmation workflows, and error handling.
138
139
```python { .api }
140
class ImportMixin(BaseImportMixin, ImportExportMixinBase):
141
def import_action(self, request, **kwargs): ...
142
def process_import(self, request, **kwargs): ...
143
def has_import_permission(self, request): ...
144
145
class ExportMixin(BaseExportMixin, ImportExportMixinBase):
146
def export_action(self, request): ...
147
def get_export_data(self, file_format, request, queryset, **kwargs): ...
148
def has_export_permission(self, request): ...
149
150
class ImportExportModelAdmin(ImportExportMixin, admin.ModelAdmin): ...
151
class ExportActionModelAdmin(ExportActionMixin, admin.ModelAdmin): ...
152
```
153
154
[Django Admin Integration](./admin-integration.md)
155
156
### Widgets and Data Transformation
157
158
Comprehensive widget system for transforming data between Python objects and serialized formats, including support for various data types and relationships.
159
160
```python { .api }
161
class Widget:
162
def clean(self, value, row=None, **kwargs): ...
163
def render(self, value, obj=None, **kwargs): ...
164
165
class ForeignKeyWidget(Widget):
166
def __init__(self, model, field="pk", use_natural_foreign_keys=False, key_is_id=False, **kwargs): ...
167
def get_queryset(self, value, row, *args, **kwargs): ...
168
169
class ManyToManyWidget(Widget):
170
def __init__(self, model, separator=None, field=None, **kwargs): ...
171
172
# Data type widgets
173
class DateWidget(Widget): ...
174
class DateTimeWidget(Widget): ...
175
class BooleanWidget(Widget): ...
176
class JSONWidget(Widget): ...
177
```
178
179
[Widgets and Data Transformation](./widgets-transformation.md)
180
181
### File Formats and Export/Import
182
183
Support for multiple file formats through tablib integration, including CSV, XLSX, JSON, YAML, and more, with configurable format options.
184
185
```python { .api }
186
class Format:
187
def create_dataset(self, in_stream): ...
188
def export_data(self, dataset, **kwargs): ...
189
def is_binary(self): ...
190
def get_extension(self): ...
191
192
class CSV(TextFormat): ...
193
class XLSX(TablibFormat): ...
194
class JSON(TextFormat): ...
195
class YAML(TextFormat): ...
196
197
# Format utilities
198
def get_format_class(format_name, file_name, encoding=None): ...
199
def get_default_format_names(): ...
200
```
201
202
[File Formats](./file-formats.md)
203
204
### Forms and UI Components
205
206
Form classes for handling file uploads, format selection, field selection, and import confirmation workflows in web interfaces.
207
208
```python { .api }
209
class ImportForm(ImportExportFormBase):
210
def __init__(self, import_formats, **kwargs): ...
211
212
class ConfirmImportForm(forms.Form):
213
def __init__(self, confirm_form_class, import_form_data, **kwargs): ...
214
215
class ExportForm(ImportExportFormBase): ...
216
class SelectableFieldsExportForm(ExportForm): ...
217
```
218
219
[Forms and UI Components](./forms-ui.md)
220
221
### Management Commands
222
223
Django management commands for command-line import and export operations, supporting various formats and configuration options.
224
225
```python { .api }
226
# Export command
227
python manage.py export <format> <resource> [--encoding=<encoding>]
228
229
# Import command
230
python manage.py import <format> <resource> <file> [--encoding=<encoding>] [--dry-run]
231
```
232
233
[Management Commands](./management-commands.md)
234
235
## Error Handling and Results
236
237
Django Import Export provides comprehensive error handling and result tracking through specialized exception classes and result containers.
238
239
```python { .api }
240
class ImportExportError(Exception): ...
241
class FieldError(ImportExportError): ...
242
class ImportError(ImportExportError):
243
def __init__(self, error, number=None, row=None): ...
244
245
class Result:
246
def has_errors(self): ...
247
def has_validation_errors(self): ...
248
def valid_rows(self): ...
249
250
class RowResult:
251
IMPORT_TYPE_UPDATE = 'update'
252
IMPORT_TYPE_NEW = 'new'
253
IMPORT_TYPE_DELETE = 'delete'
254
IMPORT_TYPE_SKIP = 'skip'
255
IMPORT_TYPE_ERROR = 'error'
256
IMPORT_TYPE_INVALID = 'invalid'
257
258
def is_update(self): ...
259
def is_new(self): ...
260
def is_error(self): ...
261
```
262
263
## Signals and Hooks
264
265
Signal support for extending import/export workflows with custom processing logic.
266
267
```python { .api }
268
from import_export.signals import post_import, post_export
269
270
# Django signals
271
post_import = Signal() # Args: model
272
post_export = Signal() # Args: model
273
```
274
275
## Instance Loaders
276
277
Performance optimization for loading existing instances during import operations.
278
279
```python { .api }
280
class BaseInstanceLoader:
281
def get_instance(self, row): ...
282
283
class ModelInstanceLoader(BaseInstanceLoader):
284
def __init__(self, resource_class, dataset=None): ...
285
286
class CachedInstanceLoader(ModelInstanceLoader):
287
# Pre-loads instances for performance
288
def __init__(self, resource_class, dataset=None): ...
289
```
290
291
## Configuration Options
292
293
Resource configuration through Meta class options.
294
295
```python { .api }
296
class Meta:
297
model = None # Django model class
298
fields = None # Field whitelist
299
exclude = None # Field blacklist
300
import_id_fields = ('id',) # Instance identification fields
301
import_order = () # Import field order
302
export_order = () # Export field order
303
use_transactions = None # Transaction usage
304
skip_unchanged = False # Skip unchanged records
305
clean_model_instances = False # Call full_clean()
306
use_bulk = False # Enable bulk operations
307
batch_size = 1000 # Bulk operation batch size
308
```
309
310
## Types
311
312
```python { .api }
313
from typing import Dict, List, Optional, Union, Any, Tuple
314
from django.db.models import Model, QuerySet
315
from django.core.exceptions import ValidationError
316
from tablib import Dataset
317
318
# Core types
319
ResourceOptions = Dict[str, Any]
320
WidgetKwargs = Dict[str, Any]
321
RowData = Dict[str, Any]
322
ImportResult = Result
323
ExportDataset = Dataset
324
InstanceTuple = Tuple[Model, bool] # (instance, created)
325
ErrorList = List[Union[Exception, ValidationError]]
326
327
# Metaclasses and constants
328
DeclarativeMetaclass = type # Metaclass for declarative resource definition
329
ModelDeclarativeMetaclass = type # Metaclass for model-based resources
330
NOT_PROVIDED = object() # Sentinel value for unset field defaults
331
332
# Result classes
333
class Result:
334
rows: List[RowResult]
335
invalid_rows: List[dict]
336
error_rows: List[dict]
337
totals: Dict[str, int]
338
339
class RowResult:
340
IMPORT_TYPE_NEW = 'new'
341
IMPORT_TYPE_UPDATE = 'update'
342
IMPORT_TYPE_DELETE = 'delete'
343
IMPORT_TYPE_SKIP = 'skip'
344
IMPORT_TYPE_ERROR = 'error'
345
IMPORT_TYPE_INVALID = 'invalid'
346
```