This section describes how to get started with import-export. We'll use the :ref:`example application<exampleapp>` as a guide.
import-export can be used programmatically as described here, or it can be integrated with the :ref:`Django Admin interface<admin-integration>`.
There are sample files which can be used to test importing data in the tests/core/exports directory.
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
To integrate import-export with our Book
model, we will create a
:class:`~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'
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 :func:`~import_export.resources.modelresource_factory`
to create a default :class:`~import_export.resources.ModelResource`.
The ModelResource
class created this way is equal to the one shown in the
example in section :ref:`base-modelresource`.
In fifth line a :class:`~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 :ref:`advanced_usage:Create or update model instances`.
In the rest of the code we first pretend to import data using
:meth:`~import_export.resources.Resource.import_data` and dry_run
set,
then check for any errors and actually import data this time.
.. seealso:: :doc:`/import_workflow` for a detailed description of the import workflow and its customization options.
To delete objects during import, implement the :meth:`~import_export.resources.Resource.for_delete` method on your :class:`~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
Now that we have defined a :class:`~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 :ref:`admin_security`.