===============
Getting started
===============

Introduction
============

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

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


.. _base-modelresource:

Creating a resource
===============================

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'

Importing data
==============

Let's import some data!

.. code-block:: python
    :linenos:
    :emphasize-lines: 4,5

    >>> 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`. For more advanced usage of this function,
see :ref:`using_modelresource_factory`.

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.

Deleting data
-------------

To delete objects during import, implement the
:meth:`~import_export.resources.Resource.for_delete` method on
your :class:`~import_export.resources.Resource` class.
You should add custom logic which will signify which rows are to be deleted.

For example, suppose you would like to have a field in the import dataset to indicate which rows should be deleted.
You could include a field called *delete* which has either a 1 or 0 value.

In this case, declare the resource as follows::

    class BookResource(resources.ModelResource):

        def for_delete(self, row, instance):
            return row["delete"] == "1"

        class Meta:
            model = Book

If the delete flag is set on a *'new'* instance (i.e. the row does not already exist in the db) then the row will be
skipped.

.. _exporting_data:

Exporting data
==============

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