mirror of
https://github.com/django-import-export/django-import-export.git
synced 2025-12-11 19:53:58 +03:00
316 lines
10 KiB
ReStructuredText
316 lines
10 KiB
ReStructuredText
==============================
|
||
Installation and configuration
|
||
==============================
|
||
|
||
import-export is available on the Python Package Index (PyPI), so it
|
||
can be installed with standard Python tools like ``pip`` or ``easy_install``::
|
||
|
||
pip install django-import-export
|
||
|
||
This will automatically install the default formats supported by tablib.
|
||
If you need additional formats you should install the extra dependencies as required
|
||
appropriate tablib dependencies (e.g. ``pip install django-import-export[xlsx]``).
|
||
|
||
To install all available formats, use ``pip install django-import-export[all]``.
|
||
|
||
For all formats, see the
|
||
`tablib documentation <https://tablib.readthedocs.io/en/stable/formats.html>`_.
|
||
|
||
Alternatively, you can install the git repository directly to obtain the
|
||
development version::
|
||
|
||
pip install -e git+https://github.com/django-import-export/django-import-export.git#egg=django-import-export
|
||
|
||
Now, you're good to go, unless you want to use import-export from the
|
||
admin as well. In this case, you need to add it to your ``INSTALLED_APPS`` and
|
||
let Django collect its static files.
|
||
|
||
.. code-block:: python
|
||
|
||
# settings.py
|
||
INSTALLED_APPS = (
|
||
...
|
||
'import_export',
|
||
)
|
||
|
||
.. code-block:: shell
|
||
|
||
$ python manage.py collectstatic
|
||
|
||
All prerequisites are set up! See :doc:`getting_started` to learn how to use
|
||
import-export in your project.
|
||
|
||
Settings
|
||
========
|
||
|
||
You can configure the following in your settings file:
|
||
|
||
``IMPORT_EXPORT_USE_TRANSACTIONS``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Controls if resource importing should use database transactions. Defaults to
|
||
``True``. Using transactions makes imports safer as a failure during import
|
||
won’t import only part of the data set.
|
||
|
||
Can be overridden on a ``Resource`` class by setting the
|
||
``use_transactions`` class attribute.
|
||
|
||
``IMPORT_EXPORT_SKIP_ADMIN_LOG``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
If set to ``True``, skips the creation of admin log entries when importing via the
|
||
:ref:`Admin UI<admin-integration>`.
|
||
Defaults to ``False``. This can speed up importing large data sets, at the cost
|
||
of losing an audit trail.
|
||
|
||
Can be overridden on a ``ModelAdmin`` class inheriting from ``ImportMixin`` by
|
||
setting the ``skip_admin_log`` class attribute.
|
||
|
||
.. _import_export_tmp_storage_class:
|
||
|
||
``IMPORT_EXPORT_TMP_STORAGE_CLASS``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
A string path to the preferred temporary storage module.
|
||
|
||
Controls which storage class to use for storing the temporary uploaded file
|
||
during imports. Defaults to ``import_export.tmp_storages.TempFolderStorage``.
|
||
|
||
Can be overridden on a ``ModelAdmin`` class inheriting from ``ImportMixin`` by
|
||
setting the ``tmp_storage_class`` class attribute.
|
||
|
||
.. _import_export_default_file_storage:
|
||
|
||
``IMPORT_EXPORT_DEFAULT_FILE_STORAGE``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
A string path to a customized storage implementation.
|
||
|
||
This setting is deprecated and only applies if using Django with a version less than 4.2,
|
||
and will be removed in a future release.
|
||
|
||
.. _import_export_import_permission_code:
|
||
|
||
``IMPORT_EXPORT_IMPORT_PERMISSION_CODE``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
If set, lists the permission code that is required for users to perform the
|
||
'import' action. Defaults to ``None``, which means all users can perform
|
||
imports.
|
||
|
||
Django’s built-in permissions have the codes ``add``, ``change``, ``delete``,
|
||
and ``view``. You can also add your own permissions. For example, if you set this
|
||
value to 'import', then you can define an explicit permission for import in the example
|
||
app with:
|
||
|
||
.. code-block:: python
|
||
|
||
from core.models import Book
|
||
from django.contrib.auth.models import Permission
|
||
from django.contrib.contenttypes.models import ContentType
|
||
|
||
content_type = ContentType.objects.get_for_model(Book)
|
||
permission = Permission.objects.create(
|
||
codename="import_book",
|
||
name="Can import book",
|
||
content_type=content_type,
|
||
)
|
||
|
||
Now only users who are assigned 'import_book' permission will be able to perform
|
||
imports. For more information refer to the
|
||
`Django auth <https://docs.djangoproject.com/en/stable/topics/auth/default/>`_
|
||
documentation.
|
||
|
||
.. _import_export_export_permission_code:
|
||
|
||
``IMPORT_EXPORT_EXPORT_PERMISSION_CODE``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Defines the same behaviour as :ref:`IMPORT_EXPORT_IMPORT_PERMISSION_CODE`, but for
|
||
export.
|
||
|
||
``IMPORT_EXPORT_CHUNK_SIZE``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
An integer that defines the size of chunks when iterating a QuerySet for data
|
||
exports. Defaults to ``100``. You may be able to save memory usage by
|
||
decreasing it, or speed up exports by increasing it.
|
||
|
||
Can be overridden on a ``Resource`` class by setting the ``chunk_size`` class
|
||
attribute.
|
||
|
||
.. _import_export_skip_admin_confirm:
|
||
|
||
``IMPORT_EXPORT_SKIP_ADMIN_CONFIRM``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
If ``True``, no import confirmation page will be presented to the user in the Admin UI.
|
||
The file will be imported in a single step.
|
||
|
||
By default, the import will occur in a transaction.
|
||
If the import causes any runtime errors (including validation errors),
|
||
then the errors are presented to the user and then entire transaction is rolled back.
|
||
|
||
Note that if you disable transaction support via configuration (or if your database
|
||
does not support transactions), then validation errors will still be presented to the user
|
||
but valid rows will have imported.
|
||
|
||
This flag can be enabled for the model admin using the :attr:`~import_export.mixins.BaseImportMixin.skip_import_confirm`
|
||
flag.
|
||
|
||
.. _import_export_skip_admin_export_ui:
|
||
|
||
``IMPORT_EXPORT_SKIP_ADMIN_EXPORT_UI``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
A boolean value which will skip the :ref:`export form<admin_ui_exporting>` in the Admin UI, when the export is
|
||
initiated from the :ref:`change list page<admin_ui_exporting>`.
|
||
The file will be exported in a single step.
|
||
|
||
If enabled:
|
||
|
||
* the first element in the :attr:`~import_export.mixins.BaseImportExportMixin.resource_classes` list will be used.
|
||
* the first element in the :ref:`export_formats` list will be used.
|
||
|
||
This flag can be enabled for the model admin using the :attr:`~import_export.mixins.BaseExportMixin.skip_export_form`
|
||
flag.
|
||
|
||
.. _import_export_skip_admin_action_export_ui:
|
||
|
||
``IMPORT_EXPORT_SKIP_ADMIN_ACTION_EXPORT_UI``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
A boolean value which will skip the :ref:`export form<admin_ui_exporting>` in the Admin UI, but only when the export is
|
||
requested from an :ref:`Admin UI action<export_via_admin_action>`, or from the 'Export' button on the
|
||
:ref:`change form <export_from_model_change_form>`.
|
||
|
||
See also :ref:`IMPORT_EXPORT_SKIP_ADMIN_EXPORT_UI`.
|
||
|
||
This flag can be enabled for the model admin using the
|
||
:attr:`~import_export.mixins.BaseExportMixin.skip_export_form_from_action` flag.
|
||
|
||
.. _import_export_escape_formulae_on_export:
|
||
|
||
``IMPORT_EXPORT_ESCAPE_FORMULAE_ON_EXPORT``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
If set to ``True``, strings will be sanitized by removing any leading '=' character. This is to prevent execution of
|
||
Excel formulae. By default this is ``False``.
|
||
|
||
.. _import_export_escape_illegal_chars_on_export:
|
||
|
||
``IMPORT_EXPORT_ESCAPE_ILLEGAL_CHARS_ON_EXPORT``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
If an export to XLSX format generates
|
||
`IllegalCharacterError <https://openpyxl.readthedocs.io/en/latest/api/openpyxl.utils.exceptions.html>`_, then
|
||
if this flag is ``True`` strings will be sanitized by removing any invalid Excel characters,
|
||
replacing them with the unicode replacement character.
|
||
By default this is ``False``, meaning that ``IllegalCharacterError`` is caught and re-raised as ``ValueError``.
|
||
|
||
.. _import_export_formats:
|
||
|
||
``IMPORT_EXPORT_FORMATS``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
A list that defines which file formats will be allowed during imports and exports. Defaults
|
||
to ``import_export.formats.base_formats.DEFAULT_FORMATS``.
|
||
The values must be those provided in ``import_export.formats.base_formats`` e.g
|
||
|
||
.. code-block:: python
|
||
|
||
# settings.py
|
||
from import_export.formats.base_formats import XLSX
|
||
IMPORT_EXPORT_FORMATS = [XLSX]
|
||
|
||
This can be set for a specific model admin by declaring the ``formats`` attribute.
|
||
|
||
.. _import_formats:
|
||
|
||
``IMPORT_FORMATS``
|
||
~~~~~~~~~~~~~~~~~~
|
||
|
||
A list that defines which file formats will be allowed during imports. Defaults
|
||
to ``IMPORT_EXPORT_FORMATS``.
|
||
The values must be those provided in ``import_export.formats.base_formats`` e.g
|
||
|
||
.. code-block:: python
|
||
|
||
# settings.py
|
||
from import_export.formats.base_formats import CSV, XLSX
|
||
IMPORT_FORMATS = [CSV, XLSX]
|
||
|
||
This can be set for a specific model admin by declaring the ``import_formats`` attribute.
|
||
|
||
.. _export_formats:
|
||
|
||
``EXPORT_FORMATS``
|
||
~~~~~~~~~~~~~~~~~~
|
||
|
||
A list that defines which file formats will be allowed during exports. Defaults
|
||
to ``IMPORT_EXPORT_FORMATS``.
|
||
The values must be those provided in ``import_export.formats.base_formats`` e.g
|
||
|
||
.. code-block:: python
|
||
|
||
# settings.py
|
||
from import_export.formats.base_formats import XLSX
|
||
EXPORT_FORMATS = [XLSX]
|
||
|
||
This can be set for a specific model admin by declaring the ``export_formats`` attribute.
|
||
|
||
.. _import_export_import_ignore_blank_lines:
|
||
|
||
``IMPORT_EXPORT_IMPORT_IGNORE_BLANK_LINES``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
If set to ``True``, rows without content will be ignored in XSLX imports.
|
||
This prevents an old Excel 1.0 bug which causes openpyxl ``max_rows`` to be counting all
|
||
logical empty rows. Some editors (like LibreOffice) might add :math:`2^{20}` empty rows to the
|
||
file, which causes a significant slowdown. By default this is ``False``.
|
||
|
||
.. _exampleapp:
|
||
|
||
Example app
|
||
===========
|
||
|
||
There's an example application that showcases what import_export can do.
|
||
|
||
Before starting, set up a virtual environment ("venv") using :ref:`these instructions<create_venv>`.
|
||
|
||
You can initialize and run the example application as follows::
|
||
|
||
cd tests
|
||
./manage.py makemigrations
|
||
./manage.py migrate
|
||
./manage.py createsuperuser
|
||
./manage.py loaddata author.json category.json book.json
|
||
./manage.py runserver
|
||
|
||
Go to http://127.0.0.1:8000
|
||
|
||
For example import files, see :ref:`getting_started:Test data`.
|
||
|
||
.. _logging:
|
||
|
||
Configure logging
|
||
=================
|
||
|
||
You can adjust the log level to see output as required.
|
||
This is an example configuration to be placed in your application settings::
|
||
|
||
LOGGING = {
|
||
"version" 1,
|
||
"handlers": {
|
||
"console": {"level": "DEBUG", "class": "logging.StreamHandler"},
|
||
},
|
||
"loggers": {
|
||
"django.db.backends": {"level": "INFO", "handlers": ["console"]},
|
||
"import_export": {
|
||
"handlers": ["console"],
|
||
"level": "INFO",
|
||
},
|
||
},
|
||
}
|
||
|