Resources
Resource
- class import_export.resources.Resource(**kwargs)
Resource defines how objects are mapped to their import and export representations and handle importing and exporting data.
- kwargs:
An optional dict of kwargs. Subclasses can use kwargs to pass dynamic values to enhance import / exports.
- after_delete_instance(instance, row, **kwargs)
Override to add additional logic. Does nothing by default.
- Parameters:
instance – A new or existing model instance.
row – A
dict
containing key / value data for the row to be imported.**kwargs – See
import_row()
- after_export(queryset, dataset, **kwargs)
Override to add additional logic. Does nothing by default.
- Parameters:
queryset – The queryset for export.
dataset – A
tablib.Dataset
.**kwargs – Metadata which may be associated with the export.
- after_import(dataset, result, **kwargs)
Override to add additional logic. Does nothing by default.
- Parameters:
dataset – A
tablib.Dataset
.result – A
import_export.results.Result
implementation containing a summary of the import.**kwargs – See
import_row()
- after_import_row(row, row_result, **kwargs)
Override to add additional logic. Does nothing by default.
- Parameters:
row – A
dict
containing key / value data for the row to be imported.row_result – A
RowResult
instance. References the persistedinstance
as an attribute.**kwargs – See
import_row()
- after_init_instance(instance, new, row, **kwargs)
Override to add additional logic. Does nothing by default.
- Parameters:
instance – A new or existing model instance.
new – a boolean flag indicating whether instance is new or existing.
row – A
dict
containing key / value data for the row to be imported.**kwargs – See
import_row()
- after_save_instance(instance, row, **kwargs)
Override to add additional logic. Does nothing by default.
- Parameters:
instance – A new or existing model instance.
row – A
dict
containing key / value data for the row to be imported.**kwargs – See
import_row()
- before_delete_instance(instance, row, **kwargs)
Override to add additional logic. Does nothing by default.
- Parameters:
instance – A new or existing model instance.
row – A
dict
containing key / value data for the row to be imported.**kwargs – See
import_row()
- before_export(queryset, **kwargs)
Override to add additional logic. Does nothing by default.
- Parameters:
queryset – The queryset for export.
**kwargs – Metadata which may be associated with the export.
- before_import(dataset, **kwargs)
Override to add additional logic. Does nothing by default.
- Parameters:
dataset – A
tablib.Dataset
.**kwargs – See
import_row()
- before_import_row(row, **kwargs)
Override to add additional logic. Does nothing by default.
- Parameters:
row – A
dict
containing key / value data for the row to be imported.**kwargs – See
import_row()
- before_save_instance(instance, row, **kwargs)
Override to add additional logic. Does nothing by default.
- Parameters:
instance – A new or existing model instance.
row – A
dict
containing key / value data for the row to be imported.**kwargs – See
import_row()
- bulk_create(using_transactions, dry_run, raise_errors, batch_size=None, result=None)
Creates objects by calling
bulk_create
.
- bulk_delete(using_transactions, dry_run, raise_errors, result=None)
Deletes objects by filtering on a list of instances to be deleted, then calling
delete()
on the entire queryset.
- bulk_update(using_transactions, dry_run, raise_errors, batch_size=None, result=None)
Updates objects by calling
bulk_update
.
- delete_instance(instance, row, **kwargs)
Calls
instance.delete()
as long asdry_run
is not set. Ifuse_bulk
then instances are appended to a list for bulk import.- Parameters:
instance – A new or existing model instance.
row – A
dict
containing key / value data for the row to be imported.**kwargs – See
import_row()
- do_instance_save(instance, is_create)
A method specifically to provide a single overridable hook for the instance save operation. For example, this can be overridden to implement update_or_create().
- Parameters:
instance – The model instance to be saved.
is_create – A boolean flag to indicate whether this is a new object to be created, or an existing object to be updated.
- export(queryset=None, **kwargs)
Exports a resource.
- Parameters:
queryset – The queryset for export (optional).
- Returns:
A
tablib.Dataset
.
- filter_export(queryset, **kwargs)
Override to filter an export queryset.
- Parameters:
queryset – The queryset for export (optional).
**kwargs – Metadata which may be associated with the export.
- Returns:
The filtered queryset.
- for_delete(row, instance)
Returns
True
ifrow
importing should delete instance.Default implementation returns
False
. Override this method to handle deletion.- Parameters:
row – A
dict
containing key / value data for the row to be imported.instance – A new or existing model instance.
- get_bulk_update_fields()
Returns the fields to be included in calls to bulk_update().
import_id_fields
are removed because id fields cannot be supplied to bulk_update().
- classmethod get_diff_class()
Returns the class used to display the diff for an imported instance.
- get_diff_headers()
Diff representation headers.
- classmethod get_error_result_class()
Returns the class used to store an error resulting from an import.
- get_field_name(field)
Returns the field name for a given field.
- get_fields(**kwargs)
Returns list of fields (unordered).
- get_instance(instance_loader, row)
Calls the InstanceLoader.
- get_or_init_instance(instance_loader, row)
Either fetches an already existing instance or initializes a new one.
- classmethod get_result_class()
Returns the class used to store the result of an import.
- classmethod get_row_result_class()
Returns the class used to store the result of a row import.
- import_data(dataset, dry_run=False, raise_errors=False, use_transactions=None, collect_failed_rows=False, rollback_on_validation_errors=False, **kwargs)
Imports data from
tablib.Dataset
. Refer to Import workflow for a more complete description of the whole import process.- Parameters:
dataset – A
tablib.Dataset
.raise_errors – Whether errors should be printed to the end user or raised regularly.
use_transactions – If
True
the import process will be processed inside a transaction.collect_failed_rows – If
True
the import process will create a new dataset object comprising failed rows and errors. This can be useful for debugging purposes but will cause higher memory usage for larger datasets. Seefailed_dataset
.rollback_on_validation_errors – If both
use_transactions
androllback_on_validation_errors
are set toTrue
, the import process will be rolled back in case of ValidationError.dry_run – If
dry_run
is set, or an error occurs, if a transaction is being used, it will be rolled back.**kwargs – Metadata which may be associated with the import.
- import_field(field, instance, row, is_m2m=False, **kwargs)
Handles persistence of the field data.
- Parameters:
field – A
import_export.fields.Field
instance.instance – A new or existing model instance.
row – A
dict
containing key / value data for the row to be imported.is_m2m – A boolean value indicating whether or not this is a many-to-many field.
**kwargs – See
import_row()
- import_instance(instance, row, **kwargs)
Traverses every field in this Resource and calls
import_field()
. Ifimport_field()
results in aValueError
being raised for one of more fields, those errors are captured and reraised as a single, multi-field ValidationError.- Parameters:
instance – A new or existing model instance.
row – A
dict
containing key / value data for the row to be imported.**kwargs – See
import_row()
- import_row(row, instance_loader, **kwargs)
Imports data from
tablib.Dataset
. Refer to Import workflow for a more complete description of the whole import process.- Parameters:
row – A
dict
of the ‘row’ to import. A row is a dict of data fields so can be a csv line, a JSON object, a YAML object etc.instance_loader – The instance loader to be used to load the model instance associated with the row (if there is one).
**kwargs – See below.
- Keyword Arguments:
dry_run (
boolean
) – A True value means that no data should be persisted.use_transactions (
boolean
) – A True value means that transactions will be rolled back.row_number (
int
) – The index of the row being imported.
- init_instance(row=None)
Initializes an object. Implemented in
import_export.resources.ModelResource.init_instance()
.
- save_instance(instance, is_create, row, **kwargs)
Takes care of saving the object to the database.
Objects can be created in bulk if
use_bulk
is enabled.- Parameters:
instance – The instance of the object to be persisted.
is_create – A boolean flag to indicate whether this is a new object to be created, or an existing object to be updated.
row – A dict representing the import row.
**kwargs – See :meth:`import_row
- save_m2m(instance, row, **kwargs)
Saves m2m fields.
Model instance need to have a primary key value before a many-to-many relationship can be used.
- Parameters:
instance – A new or existing model instance.
row – A
dict
containing key / value data for the row to be imported.**kwargs – See
import_row()
- skip_row(instance, original, row, import_validation_errors=None)
Returns
True
ifrow
importing should be skipped.Default implementation returns
False
unless skip_unchanged == True and skip_diff == False.If skip_diff is True, then no comparisons can be made because
original
will be None.When left unspecified, skip_diff and skip_unchanged both default to
False
, and rows are never skipped.By default, rows are not skipped if validation errors have been detected during import. You can change this behavior and choose to ignore validation errors by overriding this method.
Override this method to handle skipping rows meeting certain conditions.
Use
super
if you want to preserve default handling while overridingclass YourResource(ModelResource): def skip_row(self, instance, original, row, import_validation_errors=None): # Add code here return super().skip_row(instance, original, row, import_validation_errors=import_validation_errors)
- Parameters:
instance – A new or updated model instance.
original – The original persisted model instance.
row – A
dict
containing key / value data for the row to be imported.import_validation_errors – A
dict
containing key / value data for any identified validation errors.
- validate_instance(instance, import_validation_errors=None, validate_unique=True)
Takes any validation errors that were raised by
import_instance()
, and combines them with validation errors raised by the instance’sfull_clean()
method. The combined errors are then re-raised as single, multi-field ValidationError.If the
clean_model_instances
option is False, the instances’sfull_clean()
method is not called, and only the errors raised byimport_instance()
are re-raised.
ModelResource
- class import_export.resources.ModelResource(**kwargs)
ModelResource is Resource subclass for handling Django models.
- kwargs:
An optional dict of kwargs. Subclasses can use kwargs to pass dynamic values to enhance import / exports.
- after_import(dataset, result, **kwargs)
Reset the SQL sequences after new objects are imported
- classmethod field_from_django_field(field_name, django_field, readonly)
Returns a Resource Field instance for the given Django model field.
- classmethod get_fk_widget(field)
Prepare widget for fk and o2o fields
- classmethod get_m2m_widget(field)
Prepare widget for m2m field
- get_queryset()
Returns a queryset of all objects for this model. Override this if you want to limit the returned queryset.
- init_instance(row=None)
Initializes a new Django model.
- classmethod widget_from_django_field(f, default=<class 'import_export.widgets.Widget'>)
Returns the widget that would likely be associated with each Django type.
Includes mapping of Postgres Array field. In the case that psycopg2 is not installed, we consume the error and process the field regardless.
- classmethod widget_kwargs_for_field(field_name, django_field)
Returns widget kwargs for given field_name.
ResourceOptions (Meta)
- class import_export.options.ResourceOptions
The inner Meta class allows for class-level configuration of how the Resource should behave. The following options are available:
- batch_size = 1000
The batch_size parameter controls how many objects are created in a single query. The default is to create objects in batches of 1000. See bulk_create(). This parameter is only used if
use_bulk
isTrue
.
- chunk_size = None
Controls the chunk_size argument of Queryset.iterator or, if prefetch_related is used, the per_page attribute of Paginator.
- clean_model_instances = False
Controls whether
instance.full_clean()
is called during the import process to identify potential validation errors for each (non skipped) row. The default value isFalse
.
- exclude = None
Controls what introspected fields the Resource should NOT include. A blacklist of fields.
- export_order = None
Controls export order for columns.
- fields = None
Controls what introspected fields the Resource should include. A whitelist of fields.
- force_init_instance = False
If
True
, this parameter will prevent imports from checking the database for existing instances. Enabling this parameter is a performance enhancement if your import dataset is guaranteed to contain new instances.
- import_id_fields = ['id']
Controls which object fields will be used to identify existing instances.
- import_order = None
Controls import order for columns.
- instance_loader_class = None
Controls which class instance will take care of loading existing objects.
- model = None
Django Model class or full application label string. It is used to introspect available fields.
- report_skipped = True
Controls if the result reports skipped rows. Default value is
True
.
- skip_diff = False
Controls whether or not an instance should be diffed following import.
By default, an instance is copied prior to insert, update or delete. After each row is processed, the instance’s copy is diffed against the original, and the value stored in each
RowResult
. If diffing is not required, then disabling the diff operation by setting this value toTrue
improves performance, because the copy and comparison operations are skipped for each row.If enabled, then
skip_row()
checks do not execute, because ‘skip’ logic requires comparison between the stored and imported versions of a row.If enabled, then HTML row reports are also not generated, meaning that the
skip_html_diff
value is ignored.The default value is
False
.
- skip_html_diff = False
Controls whether or not a HTML report is generated after each row. By default, the difference between a stored copy and an imported instance is generated in HTML form and stored in each
RowResult
.The HTML report is used to present changes in the import confirmation page in the admin site, hence when this value is
True
, then changes will not be presented on the confirmation screen.If the HTML report is not required, then setting this value to
True
improves performance, because the HTML generation is skipped for each row. This is a useful optimization when importing large datasets.The default value is
False
.
- skip_unchanged = False
Controls if the import should skip unchanged records. If
True
, then each existing instance is compared with the instance to be imported, and if there are no changes detected, the row is recorded as skipped, and no database update takes place.The advantages of enabling this option are:
Avoids unnecessary database operations which can result in performance improvements for large datasets.
Skipped records are recorded in each
RowResult
.Skipped records are clearly visible in the import confirmation page.
For the default
skip_unchanged
logic to work, theskip_diff
must also beFalse
(which is the default):Default value is
False
.
- store_instance = False
If True, the row instance will be stored in each
RowResult
. Enabling this parameter will increase the memory usage during import which should be considered when importing large datasets.This value will always be set to
True
when importing via the Admin UI. This is so that appropriateLogEntry
instances can be created.
- store_row_values = False
If True, each row’s raw data will be stored in each
RowResult
. Enabling this parameter will increase the memory usage during import which should be considered when importing large datasets.
- use_bulk = False
Controls whether import operations should be performed in bulk. By default, an object’s save() method is called for each row in a data set. When bulk is enabled, objects are saved using bulk operations.
- use_natural_foreign_keys = False
If
True
, this value will be passed to all foreign key widget fields whose models support natural foreign keys. That is, the model has a natural_key function and the manager has aget_by_natural_key()
function.
- use_transactions = None
Controls if import should use database transactions. Default value is
None
meaningsettings.IMPORT_EXPORT_USE_TRANSACTIONS
will be evaluated.
- using_db = None
DB Connection name to use for db transactions. If not provided,
router.db_for_write(model)
will be evaluated and if it’s missing,DEFAULT_DB_ALIAS
constant (“default”) is used.
- widgets = None
This dictionary defines widget kwargs for fields.
modelresource_factory
- resources.modelresource_factory(resource_class=<class 'import_export.resources.ModelResource'>)
Factory for creating
ModelResource
class for given Django model.