Release Notes
v4.2
When exporting via admin action, the queryset is now filtered on
get_queryset()
instead of the Model’s default queryset. This should have no impact on existing implementations.This change also made
get_valid_export_item_pks()
obsolete, as the ModelAdmin’sget_export_queryset()
, or ModelAdmin’s get_queryset can be used instead. Theget_valid_export_item_pks()
method is now deprecated.See PR 1890.
Removed internal method
_get_enabled_export_fields()
in favour of passing the selected fields list as a new parameter toexport_resource()
andget_export_headers()
.Hide the “Resource” form when it only has one option, to avoid potentially confusing text in the interface like “Resource: BookResource”. To undo this change, use a form subclass that changes the field’s widget to a
django.forms.Select
. See 1908tablib has been upgraded from v3.5.0 to 3.6.1. This upgrade removes tablib’s dependency on MarkupPy in favour of
ElementTree
. If you export to HTML, then this change may affect your output format, particularly if you have already escaped HTML characters in the text.See issue 1627.
Breaking changes
This release fixes a regression introduced in v4. From v4.2, numeric, boolean and date/time widgets are written as native values to spreadsheet formats (ODS, XLS, XLSX). This was the default behavior in v3. See documentation.
This means that the
coerce_to_string
value which is passed toWidget
is now ignored if you are exporting to a spreadsheet format from the Admin interface.If you have subclassed
Widget
,Field
orResource
, then you may need to adjust your code to include the**kwargs
param as follows:
Previous |
New |
---|---|
|
|
|
|
|
|
|
|
v4.1
The Resource.get_fields()
method is no longer called within the package and has been deprecated.
If you have overridden this method then it should be removed.
v4.0
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.
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 torender()
is deprecated. Therender()
method should not need to have a reference to model instance. The call torender()
fromexport()
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 byresource_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 |
---|---|---|
|
|
|
|
|
|
Parameter changes
This section describes methods in which the parameters have changed.
Previous |
New |
Summary |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
import_export.mixins.BaseImportExportMixin
Parameter changes
Previous |
New |
Summary |
---|---|---|
|
|
|
|
|
|
import_export.mixins.BaseImportMixin
Parameter changes
Previous |
New |
Summary |
---|---|---|
|
|
|
|
|
|
|
|
|
import_export.mixins.BaseExportMixin
Parameter changes
Previous |
New |
Summary |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
import_export.fields.Field
Parameter changes
Previous |
New |
Summary |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
---|---|---|
|
|
|