getting_started.rst

Getting started

Introduction

This section describes how to get started with import-export. We'll use the example application<exampleapp> as a guide.

import-export can be used programmatically as described here, or it can be integrated with the Django Admin interface<admin-integration>.

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 ~import_export.resources.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  # or 'core.Book'

Importing data

Let's import some data!

>>> import tablib
>>> from import_export import resources
>>> from core.models import Book
>>> book_resource = resources.modelresource_factory(model=Book)()
>>> dataset = tablib.Dataset(['', 'New book'], headers=['id', 'name'])
>>> result = book_resource.import_data(dataset, dry_run=True)
>>> print(result.has_errors())
False
>>> result = book_resource.import_data(dataset, dry_run=False)

In the fourth line we use ~import_export.resources.modelresource_factory to create a default ~import_export.resources.ModelResource. The ModelResource class created this way is equal to the one shown in the example in section base-modelresource.

In fifth line a ~tablib.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 advanced_usage:Create or update model instances.

In the rest of the code we first pretend to import data using ~import_export.resources.Resource.import_data and dry_run set, then check for any errors and actually import data this time.

/import_workflow

for a detailed description of the import workflow and its customization options.

Deleting data

To delete objects during import, implement the ~import_export.resources.Resource.for_delete method on your ~import_export.resources.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 ~import_export.resources.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 admin_security.