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
```