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<changelog>
for more information. Please ensure you test thoroughly before deploying v4 to production.
This guide describes the major changes and how to upgrade.
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]
~import_export.widgets.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.
The following widgets have had validation error messages updated:
~import_export.widgets.DateWidget
~import_export.widgets.TimeWidget
~import_export.widgets.DateTimeWidget
~import_export.widgets.DurationWidget
We have standardized the export output which is returned from ~import_export.widgets.Widget.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.
Refer to the documentation<api_widgets>
for more information.
Export field order ------------
The ordering rules for exported fields has been standardized. See documentation<field_ordering>
.
- The
obj
param passed to~import_export.widgets.Widget.render
is deprecated. The~import_export.widgets.Widget.render
method should not need to have a reference to model instance. - Use of
ExportViewFormMixin
is deprecated. See this issue. - See
renamed_methods
.
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 ~import_export.results.RowResult
so that they can be recorded in each LogEntry
.
This only occurs for delete operations initiated from the Admin UI.
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_via_admin_action>
.
The success message shown on successful import has been updated to include the number of 'deleted' and 'skipped' rows. See this PR.
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_export.admin.ImportMixin.import_error_display
on the Admin class definition. For example:
class BookAdmin(ImportExportModelAdmin):
import_error_display = ("message", "row", "traceback")
See this issue.
v4 of import-export contains a number of minor changes to the API.
If you have customized import-export by overriding methods, then you will 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.
Refer to this PR for more information.
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.
Previous | New | Summary |
---|---|---|
import_obj(self, obj, data, dry_run, **kwargs) |
import_instance(self, instance, row, **kwargs) |
|
after_import_instance(self, instance, new, row_number=None, **kwargs) |
after_init_instance(self, instance, new, row, **kwargs) |
|
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) |
|
after_import(self, dataset, result, using_transactions, dry_run, **kwargs) |
after_import(self, dataset, result, **kwargs) |
|
before_import_row(self, row, row_number=None, **kwargs) |
before_import_row(self, row, **kwargs) |
|
after_import_row(self, row, row_result, row_number=None, **kwargs) |
after_import_row(self, row, row_result, **kwargs) |
|
import_row(self, row, instance_loader, using_transactions=True, dry_run=False, **kwargs) |
import_row(self, row, instance_loader, **kwargs) |
|
save_instance(self, instance, is_create, using_transactions=True, dry_run=False) |
save_instance(self, instance, is_create, row, ***kwargs) |
|
save_m2m(self, obj, data, using_transactions, dry_run) |
save_m2m(self, instance, row, **kwargs) |
|
before_save_instance(self, instance, using_transactions, dry_run) |
before_save_instance(self, instance, row, **kwargs) |
|
after_save_instance(self, instance, using_transactions, dry_run) |
after_save_instance(self, instance, row, **kwargs) |
|
delete_instance(self, instance, using_transactions=True, dry_run=False) |
delete_instance(self, instance, row, **kwargs) |
|
before_delete_instance(self, instance, dry_run) |
before_delete_instance(self, instance, row, **kwargs) |
|
after_delete_instance(self, instance, dry_run) |
after_delete_instance(self, instance, row, **kwargs) |
|
before_export(self, queryset, *args, **kwargs) |
before_export(self, queryset, **kwargs) |
|
after_export(self, queryset, data, *args, **kwargs) |
after_export(self, queryset, dataset, **kwargs) |
|
filter_export(self, queryset, *args, **kwargs) |
filter_export(self, queryset, **kwargs) |
|
export_field(self, field, obj) |
export_field(self, field, instance) |
|
export(self, *args, queryset=None, **kwargs) |
export(self, queryset=None, **kwargs) |
|
Previous | New | Summary |
---|---|---|
get_import_resource_kwargs(self, request, *args, **kwargs) |
get_import_resource_kwargs(self, request, **kwargs) |
|
Previous | New | Summary |
---|---|---|
get_export_resource_kwargs(self, request, *args, **kwargs) |
get_export_resource_kwargs(self, request, **kwargs) |
|
get_export_resource_kwargs(self, request, *args, **kwargs) |
get_export_resource_kwargs(self, request, **kwargs) |
|
get_data_for_export(self, request, *args, **kwargs) |
get_data_for_export(self, request, queryset, **kwargs) |
|
Previous | New | Summary |
---|---|---|
clean(self, data, **kwargs) |
clean(self, row, **kwargs) |
|
get_value(self, instance) |
get_value(self, obj) |
|
save(self, obj, data, is_m2m=False, **kwargs) |
save(self, instance, row, is_m2m=False, **kwargs) |
|
export(self, obj) |
export(self, instance) |
|
If you have subclassed one of the ~import_export.forms
then you may need to modify the parameters passed to constructors.
The input_format
field of ~import_export.forms.ImportForm
has been moved to the parent class (~import_export.forms.ImportExportFormBase
) and renamed to format
.
Previous | New | Summary |
---|---|---|
__init__(self, *args, resources=None, **kwargs) |
__init__(self, formats, resources, *args, **kwargs) |
|