Standardize widget render()

docs/advanced_usage.rst

@@ -143,7 +143,7 @@ There are widgets associated with character data, numeric values, dates, foreign
 widget and associate it with the field.
 
 A :class:`~import_export.resources.ModelResource` creates fields with a default widget for a given field type via
-instrospection.  If the widget should be initialized with different arguments, this can be done via an explicit
+introspection.  If the widget should be initialized with different arguments, this can be done via an explicit
 declaration or via the widgets dict.
 
 For example, the ``published`` field is overridden to use a different date format. This format will be used both for
@@ -156,7 +156,9 @@ importing and exporting resource::
         class Meta:
             model = Book
 
-Alternatively, widget parameters can be overridden using the widgets dict declaration::
+Declaring fields may affect the export order of the fields.  If this is an issue, you can either declare the
+:attr:`~import_export.resources.ResourceOptions.export_order` attribute, or declare widget parameters using the widgets
+dict declaration::
 
     class BookResource(resources.ModelResource):
 
@@ -166,10 +168,26 @@ Alternatively, widget parameters can be overridden using the widgets dict declar
                 'published': {'format': '%d.%m.%Y'},
             }
 
+Modify :meth:`.render` return type
+----------------------------------
+
+By default, :meth:`.render` will return a string type for export.  There may be use cases where a native type is
+required from export.  If so, you can use the ``coerce_to_string`` parameter if the widget supports it.
+
+By default, ``coerce_to_string`` is ``True``, but if you set this to ``False``, then the native type will be returned
+during export::
+
+    class BookResource(resources.ModelResource):
+        published = Field(attribute='published', column_name='published_date',
+            widget=DateWidget(format='%Y-%m-%d', coerce_to_string=False))
+
+        class Meta:
+            model = Book
+
 .. seealso::
 
     :doc:`/api_widgets`
-        available widget types and options.
+        Available widget types and options.
 
 .. _import_model_relations:
 
@@ -899,7 +917,7 @@ return books for the publisher::
 Interoperability with 3rd party libraries
 -----------------------------------------
 
-import_export extends the Django Admin interface.  There is a possibility that clashes may occur with other 3rd party
+import-export extends the Django Admin interface.  There is a possibility that clashes may occur with other 3rd party
 libraries which also use the admin interface.
 
 django-admin-sortable2
@@ -930,11 +948,6 @@ Refer to `this PR <https://github.com/django-import-export/django-import-export/
 
 .. _admin_security:
 
-.. warning::
-    If you use django-import-export using with `django-debug-toolbar <https://pypi.org/project/django-debug-toolbar>`_.
-    then you need to configure debug_toolbar=False or DEBUG=False,
-    otherwise the import/export time will increase ~10 times.
-
 Security
 --------
 

docs/changelog.rst

@@ -15,6 +15,7 @@ Please refer to :doc:`release notes<release_notes>`.
 - Enable optional tablib dependencies (#1647)
 - Removed unused method ``utils.original()``
 - Clarified ``skip_diff`` documentation (#1655)
+- Standardised interface of :meth:`~import_export.widgets.Widget.render` (#1657)
 
 4.0.0-alpha.5 (2023-09-22)
 --------------------------

docs/conf.py

@@ -24,6 +24,8 @@
     "sphinx.ext.autosectionlabel",
 ]
 
+autoclass_content = "both"
+
 autosectionlabel_prefix_document = True
 
 # Add any paths that contain templates here, relative to this directory.

docs/faq.rst

@@ -180,3 +180,19 @@ with this issue.  Refer to `this comment <https://github.com/django-import-expor
 
 This indicates that the change_list_template attribute could not be set, most likely due to a clash with a third party
 library.  Refer to :ref:`interoperability`.
+
+``FileNotFoundError`` during Admin import 'confirm' step
+--------------------------------------------------------
+
+You may receive an error during import such as::
+
+  FileNotFoundError [Errno 2] No such file or directory: '/tmp/tmp5abcdef'
+
+This usually happens because you are running the Admin site in a multi server or container environment.
+During import, the import file has to be stored temporarily and then retrieved for storage after confirmation.
+Therefore ``FileNotFoundError`` error can occur because the temp storage is not available to the server process after
+confirmation.
+
+To resolve this, you should avoid using temporary file system storage in multi server environments.
+
+Refer to :ref:`import process<import-process>` for more information.

docs/installation.rst

@@ -2,7 +2,7 @@
 Installation and configuration
 ==============================
 
-import_export is available on the Python Package Index (PyPI), so it
+import-export is available on the Python Package Index (PyPI), so it
 can be installed with standard Python tools like ``pip`` or ``easy_install``::
 
   pip install django-import-export
@@ -38,9 +38,7 @@ let Django collect its static files.
     $ python manage.py collectstatic
 
 All prerequisites are set up! See :doc:`getting_started` to learn how to use
-import_export in your project.
-
-
+import-export in your project.
 
 Settings
 ========

docs/release_notes.rst

@@ -5,27 +5,51 @@ Release Notes
 v4
 ==
 
-v4 introduces breaking changes in order to address some long-standing issues.
-In all cases, please test thoroughly before deploying v4 to production.
+v4 introduces breaking changes in order to fix some long-standing issues.
+Refer to the :doc:`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.
 
 Installation
 ============
 
 We have modified installation methods to allow for optional dependencies.
-This means that you have to explicitly declare dependencies when installing import_export.
+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
+import-export is installed as follows (either in your requirements file or during
 installation)::
 
   django-import-export[all]
 
+
+CharWidget
+==========
+
+:meth:`~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.
+
+Export format
+=============
+
+We have standardized the export output which is returned from
+:meth:`~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 :doc:`documentation<api_widgets>` for more information.
+
+The ``obj`` param passed to :meth:`~import_export.widgets.Widget.render` is deprecated.
+The :meth:`~import_export.widgets.Widget.render` method should not need to have a reference to
+model instance.
+
 API changes
 ===========
 
-v4 of import_export (released Q4 2023) contains a number of minor changes to the API.
+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
@@ -35,8 +59,6 @@ should be necessary.
 The API changes include changes to method arguments, although some method names have
 changed.
 
-Test thoroughly before deploying v4 to production.
-
 Refer to
 `this PR <https://github.com/django-import-export/django-import-export/pull/1641/>`_
 for more information.

import_export/fields.py

@@ -8,13 +8,13 @@
 
 class Field:
     """
-    Field represent mapping between `object` field and representation of
-    this field.
+    ``Field`` represents a mapping between an ``instance`` field and a representation of
+    the field's data.
 
-    :param attribute: A string of either an instance attribute or callable off
-        the object.
+    :param attribute: A string of either an instance attribute or callable of
+        the instance.
 
-    :param column_name: Lets you provide a name for the column that represents
+    :param column_name: An optional column name for the column that represents
         this field in the export.
 
     :param widget: Defines a widget that will be used to represent this
@@ -24,12 +24,16 @@ class Field:
         during import.
 
     :param default: This value will be returned by
-        :meth:`~import_export.fields.Field.clean` if this field's widget did
-        not return an adequate value.
+        :meth:`~import_export.fields.Field.clean` if this field's widget returned
+        a value defined in :attr:`~import_export.fields.empty_values`.
+
+    :param saves_null_values: Controls whether null values are saved on the instance.
+      This can be used if the widget returns null, but there is a default instance
+      value which should not be overwritten.
 
-    :param saves_null_values: Controls whether null values are saved on the object
     :param dehydrate_method: Lets you choose your own method for dehydration rather
         than using `dehydrate_{field_name}` syntax.
+
     :param m2m_add: changes save of this field to add the values, if they do not exist,
         to a ManyToMany field instead of setting all values.  Only useful if field is
         a ManyToMany field.
@@ -93,7 +97,7 @@ def clean(self, row, **kwargs):
 
     def get_value(self, instance):
         """
-        Returns the value of the object's attribute.
+        Returns the value of the instance's attribute.
         """
         if self.attribute is None:
             return None
@@ -119,7 +123,7 @@ def get_value(self, instance):
 
     def save(self, instance, row, is_m2m=False, **kwargs):
         """
-        If this field is not declared readonly, the object's attribute will
+        If this field is not declared readonly, the instance's attribute will
         be set to the value returned by :meth:`~import_export.fields.Field.clean`.
         """
         if not self.readonly:
@@ -142,8 +146,6 @@ def export(self, instance):
         representation.
         """
         value = self.get_value(instance)
-        if value is None:
-            return ""
         return self.widget.render(value, instance)
 
     def get_dehydrate_method(self, field_name=None):