Release Notes

v4

v4 introduces significant updates to import-export. We have taken the opportunity to introduce breaking changes in order to fix some long-standing issues.

Refer to the changelog for more information. Please ensure you test thoroughly before deploying v4 to production.

This guide describes the major changes and how to upgrade.

Installation

We have modified installation methods to allow for optional dependencies. This means that you have to explicitly declare dependencies when installing import-export.

If you are not sure, or want to preserve the pre-v4 behaviour, then ensure that import-export is installed as follows (either in your requirements file or during installation):

django-import-export[all]

Functional changes

CharWidget

Constructor arguments are dynamically set during instantiation based on the properties of the underlying Django db CharField. If the db field has blank set to True, then incoming values of empty strings or null are stored as empty strings. See CharWidget.

clean() will now return a string type as the default. The coerce_to_string option introduced in v3 is no longer used in this method.

Validation error messages

The following widgets have had validation error messages updated:

Export format

We have standardized the export output which is returned from render().

Prior to v4, the export format returned from render() varied between Widget implementations. In v4, return values are rendered as strings by default (where applicable), with None values returned as empty strings. Widget params can modify this behavior.

This causes a change when exporting to Excel. In v3, certain fields, such as numeric values, were rendered as their native type. In v4, all fields are now rendered as strings. To preserve the v3 behavior when exporting to Excel, set the coerce_to_string param to False. See documentation.

Widget API documentation.

Export field order

The ordering rules for exported fields has been standardized. See documentation.

Error output

If the raise_errors parameter of import_data() is True, then an instance of ImportError is raised. This exception wraps the underlying exception.

See this PR.

Check import_id_fields

Prior to v4 we had numerous issues where users were confused when imports failed due to declared import_id_fields not being present in the dataset. We added functionality in v4 to check for this and to raise a clearer error message.

In some use-cases, it is a requirement that import_id_fields are not in the dataset, and are generated dynamically. If this affects your implementation, start with the documentation here.

Deprecations

  • The obj param passed to render() is deprecated. The render() method should not need to have a reference to model instance. The call to render() from export() has been removed.

  • Use of ExportViewFormMixin is deprecated. See this issue.

  • See Renamed methods.

  • In the Admin UI, the declaration of resource_class is replaced by resource_classes:

    class BookAdmin(ImportExportModelAdmin):
      # remove this line
      # resource_class = BookResource
      # replace with this
      resource_classes = [BookResource]
    

Admin UI

LogEntry

LogEntry instances are created during import for creates, updates and deletes. The functionality to store LogEntry has changed in v4 in order to address a deprecation in Django 5. For this to work correctly, deleted instances are now always copied and retained in each RowResult so that they can be recorded in each LogEntry.

This only occurs for delete operations initiated from the Admin UI.

Export action

The export action has been updated to include the export workflow. Prior to v4, it was possible to select export selected items using an export admin action. However this meant that the export workflow was skipped and it was not possible to select the export resource. This has been fixed in v4 so that export workflow is now present when exporting via the Admin UI action. For more information see export documentation.

Export selected fields

The export ‘confirm’ page now includes selectable fields for export. If you wish to revert to the previous (v3) version of the export confirm screen, add a export_form_class declaration to your Admin class subclass, for example:

class BookAdmin(ImportExportModelAdmin):
  export_form_class = ExportForm

Success message

The success message shown on successful import has been updated to include the number of ‘deleted’ and ‘skipped’ rows. See this PR.

Import error messages

The default error message for import errors has been modified to simplify the format. Error messages now contain the error message only by default. The row and traceback are not presented.

The original format can be restored by setting import_error_display on the Admin class definition. For example:

class BookAdmin(ImportExportModelAdmin):
  import_error_display = ("message", "row", "traceback")

See this issue.

API changes

v4 of import-export contains a number of changes to the API. These changes are summarized in the table below. Refer to this PR for detailed information.

If you have customized import-export by overriding methods, then you may have to modify your installation before working with v4.

If you have not overridden any methods then you should not be affected by these changes and no changes to your code should be necessary.

The API changes include changes to method arguments, although some method names have changed.

Methods which process row data have been updated so that method args are standardized. This has been done to resolve inconsistency issues where the parameters differed between method calls, and to allow easier extensibility.

import_export.resources.Resource

Renamed methods

Previous

New

Summary

import_obj(self, obj, data, dry_run, **kwargs)

import_instance(self, instance, row, **kwargs)

  • obj param renamed to instance

  • data param renamed to row

  • dry_run param now in kwargs

after_import_instance(self, instance, new, row_number=None, **kwargs)

after_init_instance(self, instance, new, row, **kwargs)

  • row added as mandatory arg

  • row_number now in kwargs

Parameter changes

This section describes methods in which the parameters have changed.

Previous

New

Summary

before_import(self, dataset, using_transactions, dry_run, **kwargs)

before_import(self, dataset, **kwargs)

  • using_transactions param now in kwargs

  • dry_run param now in kwargs

after_import(self, dataset, result, using_transactions, dry_run, **kwargs)

after_import(self, dataset, result, **kwargs)

  • using_transactions param now in kwargs

  • dry_run param now in kwargs

before_import_row(self, row, row_number=None, **kwargs)

before_import_row(self, row, **kwargs)

  • row_number now in kwargs

after_import_row(self, row, row_result, row_number=None, **kwargs)

after_import_row(self, row, row_result, **kwargs)

  • row_number now in kwargs

import_row(self, row, instance_loader, using_transactions=True, dry_run=False, **kwargs)

import_row(self, row, instance_loader, **kwargs)

  • dry_run param now in kwargs

  • using_transactions param now in kwargs

save_instance(self, instance, is_create, using_transactions=True, dry_run=False)

save_instance(self, instance, is_create, row, ***kwargs)

  • dry_run param now in kwargs

  • using_transactions param now in kwargs

  • row added as mandatory arg

save_m2m(self, obj, data, using_transactions, dry_run)

save_m2m(self, instance, row, **kwargs)

  • row added as mandatory arg

  • obj renamed to instance

  • data renamed to row

  • dry_run param now in kwargs

  • using_transactions param now in kwargs

before_save_instance(self, instance, using_transactions, dry_run)

before_save_instance(self, instance, row, **kwargs)

  • row added as mandatory arg

  • dry_run param now in kwargs

  • using_transactions param now in kwargs

after_save_instance(self, instance, using_transactions, dry_run)

after_save_instance(self, instance, row, **kwargs)

  • row added as mandatory arg

  • dry_run param now in kwargs

  • using_transactions param now in kwargs

delete_instance(self, instance, using_transactions=True, dry_run=False)

delete_instance(self, instance, row, **kwargs)

  • row added as mandatory arg

  • dry_run param now in kwargs

  • using_transactions param now in kwargs

before_delete_instance(self, instance, dry_run)

before_delete_instance(self, instance, row, **kwargs)

  • row added as mandatory arg

  • dry_run param now in kwargs

  • using_transactions param now in kwargs

after_delete_instance(self, instance, dry_run)

after_delete_instance(self, instance, row, **kwargs)

  • row added as mandatory arg

  • dry_run param now in kwargs

  • using_transactions param now in kwargs

import_field(self, field, obj, data, is_m2m=False, **kwargs)

import_field(self, field, instance, row, is_m2m=False, **kwargs):

  • obj renamed to instance

  • data renamed to row

before_export(self, queryset, *args, **kwargs)

before_export(self, queryset, **kwargs)

  • unused *args list removed

after_export(self, queryset, data, *args, **kwargs)

after_export(self, queryset, dataset, **kwargs)

  • unused *args list removed

  • data renamed to dataset

filter_export(self, queryset, *args, **kwargs)

filter_export(self, queryset, **kwargs)

  • unused *args list removed

export_field(self, field, obj)

export_field(self, field, instance)

  • obj renamed to instance

export_resource(self, obj)

export_resource(self, instance, fields=None)

  • obj renamed to instance

  • fields passed as kwarg

export(self, *args, queryset=None, **kwargs)

export(self, queryset=None, **kwargs)

  • unused *args list removed

get_export_headers(self)

get_export_headers(self, fields=None)

  • fields passed as kwarg

import_export.mixins.BaseImportExportMixin

Parameter changes

Previous

New

Summary

get_resource_classes(self)

get_resource_classes(self, request)

  • Added request param

get_resource_kwargs(self, request, *args, **kwargs)

get_resource_kwargs(self, request, **kwargs)

  • unused *args list removed

import_export.mixins.BaseImportMixin

Parameter changes

Previous

New

Summary

get_import_resource_kwargs(self, request, *args, **kwargs)

get_import_resource_kwargs(self, request, **kwargs)

  • unused *args list removed

get_import_resource_classes(self)

get_import_resource_classes(self, request)

  • Added request param

choose_import_resource_class(self, form)

choose_import_resource_class(self, form, request)

  • Added request param

import_export.mixins.BaseExportMixin

Parameter changes

Previous

New

Summary

get_export_resource_classes(self)

get_export_resource_classes(self, request)

  • Added request param

get_export_resource_kwargs(self, request, *args, **kwargs)

get_export_resource_kwargs(self, request, **kwargs)

  • unused *args list removed

get_data_for_export(self, request, queryset, *args, **kwargs)

get_data_for_export(self, request, queryset, **kwargs)

  • unused *args list removed

choose_export_resource_class(self, form)

choose_export_resource_class(self, form, request)

  • Added request param

import_export.fields.Field

Parameter changes

Previous

New

Summary

clean(self, data, **kwargs)

clean(self, row, **kwargs)

  • data renamed to row

get_value(self, instance)

get_value(self, obj)

  • obj renamed to instance

save(self, obj, data, is_m2m=False, **kwargs)

save(self, instance, row, is_m2m=False, **kwargs)

  • obj renamed to instance

  • data renamed to row

export(self, obj)

export(self, instance)

  • obj renamed to instance

import_export.forms.ImportExportFormBase

If you have subclassed one of the forms then you may need to modify the parameters passed to constructors.

The input_format field of ImportForm has been moved to the parent class (ImportExportFormBase) and renamed to format.

The file_format field of ExportForm has been removed and is now replaced by format.

Parameter changes

Previous

New

Summary

__init__(self, *args, resources=None, **kwargs)

__init__(self, formats, resources, **kwargs)

  • formats added as a mandatory arg

  • resources added as a mandatory arg

  • unused *args list removed