Getting started
Introduction
This section describes how to get started with import-export. We’ll use the example application as a guide.
import-export can be used programmatically as described here, or it can be integrated with the Django Admin interface.
Test data
There are sample files which can be used to test importing data in the tests/core/exports directory.
The test models
For example purposes, we’ll use a simplified book app. Here is our
models.py
:
# app/models.py
class Author(models.Model):
name = models.CharField(max_length=100)
def __str__(self):
return self.name
class Category(models.Model):
name = models.CharField(max_length=100)
def __str__(self):
return self.name
class Book(models.Model):
name = models.CharField('Book name', max_length=100)
author = models.ForeignKey(Author, blank=True, null=True)
author_email = models.EmailField('Author email', max_length=75, blank=True)
imported = models.BooleanField(default=False)
published = models.DateField('Published', blank=True, null=True)
price = models.DecimalField(max_digits=10, decimal_places=2, null=True, blank=True)
categories = models.ManyToManyField(Category, blank=True)
def __str__(self):
return self.name
Creating a resource
To integrate import-export with our Book
model, we will create a
ModelResource
class in admin.py
that will
describe how this resource can be imported or exported:
# app/admin.py
from import_export import resources
from core.models import Book
class BookResource(resources.ModelResource):
class Meta:
model = Book
Importing data
Let’s import some data!
1>>> import tablib
2>>> from import_export import resources
3>>> from core.models import Book
4>>> book_resource = resources.modelresource_factory(model=Book)()
5>>> dataset = tablib.Dataset(['', 'New book'], headers=['id', 'name'])
6>>> result = book_resource.import_data(dataset, dry_run=True)
7>>> print(result.has_errors())
8False
9>>> result = book_resource.import_data(dataset, dry_run=False)
In the fourth line we use modelresource_factory()
to create a default ModelResource
.
The ModelResource
class created this way is equal to the one shown in the
example in section Creating a resource.
In fifth line a Dataset
with columns id
and name
, and
one book entry, are created. A field (or combination of fields) which uniquely identifies an instance always needs to
be present. This is so that the import process can manage creates / updates. In this case, we use id
.
For more information, see Create or update model instances.
In the rest of the code we first pretend to import data using
import_data()
and dry_run
set,
then check for any errors and actually import data this time.
See also
- Import data workflow
for a detailed description of the import workflow and its customization options.
Deleting data
To delete objects during import, implement the
for_delete()
method on
your Resource
class.
The following is an example resource which expects a delete
field in the
dataset. An import using this resource will delete model instances for rows
that have their column delete
set to 1
:
class BookResource(resources.ModelResource):
delete = fields.Field(widget=widgets.BooleanWidget())
def for_delete(self, row, instance):
return self.fields['delete'].clean(row)
class Meta:
model = Book
Exporting data
Now that we have defined a ModelResource
class,
we can export books:
>>> from core.admin import BookResource
>>> dataset = BookResource().export()
>>> print(dataset.csv)
id,name,author,author_email,imported,published,price,categories
2,Some book,1,,0,2012-12-05,8.85,1
Warning
Data exported programmatically is not sanitized for malicious content. You will need to understand the implications of this and handle accordingly. See Security.