Widgets

class import_export.widgets.Widget

A Widget takes care of converting between import and export representations.

This is achieved by the two methods, clean() and render().

clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

render(value, obj=None)

Returns an export representation of a Python value.

For example, if you have an object you want to export, render() takes care of converting the object’s field to a value that can be written to a spreadsheet.

class import_export.widgets.NumberWidget(coerce_to_string=False)

Widget for converting numeric fields.

Parameters:

coerce_to_string – If True, render will return a string representation of the value (None is returned as “”), otherwise the value is returned.

render(value, obj=None)

Returns an export representation of a Python value.

For example, if you have an object you want to export, render() takes care of converting the object’s field to a value that can be written to a spreadsheet.

class import_export.widgets.IntegerWidget(coerce_to_string=False)

Widget for converting integer fields.

clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

class import_export.widgets.DecimalWidget(coerce_to_string=False)

Widget for converting decimal fields.

clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

class import_export.widgets.CharWidget(coerce_to_string=False, allow_blank=False)

Widget for converting text fields.

Parameters:
  • coerce_to_string – If True, the value returned by clean() is cast to a string.

  • allow_blank – If True, and if coerce_to_string is True, then clean() will return null values as empty strings, otherwise as null.

clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

class import_export.widgets.BooleanWidget

Widget for converting boolean fields.

The widget assumes that True, False, and None are all valid values, as to match Django’s BooleanField. That said, whether the database/Django will actually accept NULL values will depend on if you have set null=True on that Django field.

While the BooleanWidget is set up to accept as input common variations of “True” and “False” (and “None”), you may need to munge less common values to True/False/None. Probably the easiest way to do this is to override the before_import_row() function of your Resource class. A short example:

from import_export import fields, resources, widgets

class BooleanExample(resources.ModelResource):
    warn = fields.Field(widget=widgets.BooleanWidget())

    def before_import_row(self, row, row_number=None, **kwargs):
        if "warn" in row.keys():
            # munge "warn" to "True"
            if row["warn"] in ["warn", "WARN"]:
                row["warn"] = True

        return super().before_import_row(row, row_number, **kwargs)
clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

render(value, obj=None)

On export, True is represented as 1, False as 0, and None/NULL as a empty string.

Note that these values are also used on the import confirmation view.

class import_export.widgets.DateWidget(format=None)

Widget for converting date fields.

Takes optional format parameter. If none is set, either settings.DATE_INPUT_FORMATS or "%Y-%m-%d" is used.

clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

render(value, obj=None)

Returns an export representation of a Python value.

For example, if you have an object you want to export, render() takes care of converting the object’s field to a value that can be written to a spreadsheet.

class import_export.widgets.TimeWidget(format=None)

Widget for converting time fields.

Takes optional format parameter. If none is set, either settings.DATETIME_INPUT_FORMATS or "%H:%M:%S" is used.

clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

render(value, obj=None)

Returns an export representation of a Python value.

For example, if you have an object you want to export, render() takes care of converting the object’s field to a value that can be written to a spreadsheet.

class import_export.widgets.DateTimeWidget(format=None)

Widget for converting date fields.

Takes optional format parameter. If none is set, either settings.DATETIME_INPUT_FORMATS or "%Y-%m-%d %H:%M:%S" is used.

clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

render(value, obj=None)

Returns an export representation of a Python value.

For example, if you have an object you want to export, render() takes care of converting the object’s field to a value that can be written to a spreadsheet.

class import_export.widgets.DurationWidget

Widget for converting time duration fields.

clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

render(value, obj=None)

Returns an export representation of a Python value.

For example, if you have an object you want to export, render() takes care of converting the object’s field to a value that can be written to a spreadsheet.

class import_export.widgets.JSONWidget

Widget for a JSON object (especially required for jsonb fields in PostgreSQL database.)

Parameters:

value – Defaults to JSON format.

The widget covers two cases: Proper JSON string with double quotes, else it tries to use single quotes and then convert it to proper JSON.

clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

render(value, obj=None)

Returns an export representation of a Python value.

For example, if you have an object you want to export, render() takes care of converting the object’s field to a value that can be written to a spreadsheet.

class import_export.widgets.ForeignKeyWidget(model, field='pk', use_natural_foreign_keys=False, **kwargs)

Widget for a ForeignKey field which looks up a related model using either the PK or a user specified field that uniquely identifies the instance in both export and import.

The lookup field defaults to using the primary key (pk) as lookup criterion but can be customized to use any field on the related model.

Unlike specifying a related field in your resource like so…

class Meta:
    fields = ('author__name',)

…using a ForeignKeyWidget has the advantage that it can not only be used for exporting, but also importing data with foreign key relationships.

Here’s an example on how to use ForeignKeyWidget to lookup related objects using Author.name instead of Author.pk:

from import_export import fields, resources
from import_export.widgets import ForeignKeyWidget

class BookResource(resources.ModelResource):
    author = fields.Field(
        column_name='author',
        attribute='author',
        widget=ForeignKeyWidget(Author, 'name'))

    class Meta:
        fields = ('author',)
Parameters:
  • model – The Model the ForeignKey refers to (required).

  • field – A field on the related model used for looking up a particular object.

  • use_natural_foreign_keys – Use natural key functions to identify related object, default to False

clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

get_queryset(value, row, *args, **kwargs)

Returns a queryset of all objects for this Model.

Overwrite this method if you want to limit the pool of objects from which the related object is retrieved.

Parameters:
  • value – The field’s value in the datasource.

  • row – The datasource’s current row.

As an example; if you’d like to have ForeignKeyWidget look up a Person by their pre- and lastname column, you could subclass the widget like so:

class FullNameForeignKeyWidget(ForeignKeyWidget):
    def get_queryset(self, value, row, *args, **kwargs):
        return self.model.objects.filter(
            first_name__iexact=row["first_name"],
            last_name__iexact=row["last_name"]
        )
render(value, obj=None)

Returns an export representation of a Python value.

For example, if you have an object you want to export, render() takes care of converting the object’s field to a value that can be written to a spreadsheet.

class import_export.widgets.ManyToManyWidget(model, separator=None, field=None, **kwargs)

Widget that converts between representations of a ManyToMany relationships as a list and an actual ManyToMany field.

Parameters:
  • model – The model the ManyToMany field refers to (required).

  • separator – Defaults to ','.

  • field – A field on the related model. Default is pk.

clean(value, row=None, **kwargs)

Returns an appropriate Python object for an imported value.

For example, if you import a value from a spreadsheet, clean() handles conversion of this value into the corresponding Python object.

Numbers or dates can be cleaned to their respective data types and don’t have to be imported as Strings.

render(value, obj=None)

Returns an export representation of a Python value.

For example, if you have an object you want to export, render() takes care of converting the object’s field to a value that can be written to a spreadsheet.