Rename QgsVectorLayerImport to QgsVectorLayerExporter

Since the majority of users of this class will be exporting
an existing map layer to a data provider, the QgsVectorLayerImport
name is misleading and suggests that this class is designed
just to bring layers "into" QGIS.

Explicitly naming the class "Exporter" should help API users
discover this class.

Also cleanup API and improve docs

Author: nyalldawson

doc/api_break.dox

@@ -186,6 +186,7 @@ Renamed Classes        {#qgis_api_break_3_0_renamed_classes}
 <tr><td>QgsVectorGradientColorRampV2DialogBase<td>QgsGradientColorRampDialogBase
 <tr><td>QgsVectorGradientRampV2<td>QgsVectorGradientRamp
 <tr><td>QgsVectorJoinInfo<td>QgsVectorLayerJoinInfo
+<tr><td>QgsVectorLayerImport<td>QgsVectorLayerExporter
 <tr><td>QgsVectorLayersetRendererV2<td>QgsVectorLayersetRenderer
 <tr><td>QgsVectorRandomColorRampV2<td>QgsLimitedRandomColorRamp
 <tr><td>QgsVectorRandomColorRampV2Dialog<td>QgsLimitedRandomColorRampDialog
@@ -2180,15 +2181,19 @@ QgsVectorLayerEditUtils        {#qgis_api_break_3_0_QgsVectorLayerEditUtils}
 - cache() has been removed.
 
 
-QgsVectorLayerImport        {#qgis_api_break_3_0_QgsVectorLayerImport}
+QgsVectorLayerExporter (renamed from QgsVectorLayerImport) {#qgis_api_break_3_0_QgsVectorLayerExporter}
 --------------------
 
-- QgsVectorLayerImport now takes references instead of pointers to QgsCoordinateReferenceSystem objects. Since
+- QgsVectorLayerExporter now takes references instead of pointers to QgsCoordinateReferenceSystem objects. Since
 QgsCoordinateReferenceSystem is now implicitly shared, using references to QgsCoordinateReferenceSystem rather than
 pointers makes for more robust, safer code. Use an invalid (default constructed) QgsCoordinateReferenceSystem
 in code which previously passed a null pointer to QgsVectorLayerImport.
+- importLayer was renamed to exportLayer
 - The unused QProgressBar argument in the QgsVectorLayerImport was removed
-- ErrUserCancelled (ImportError enum value) has been renamed to ErrUserCanceled  <!--#spellok-->
+- ImportError was renamed to ExportError
+- The unused enum value ErrDriverNotFound was removed
+- hasError() was renamed to errorCode()
+- ErrUserCancelled (ExportError enum value) has been renamed to ErrUserCanceled  <!--#spellok-->
 
 
 QgsVectorLayerJoinBuffer        {#qgis_api_break_3_0_QgsVectorLayerJoinBuffer}

python/core/core.sip

@@ -165,8 +165,8 @@
 %Include qgsvectorlayercache.sip
 %Include qgsvectorlayereditbuffer.sip
 %Include qgsvectorlayereditpassthrough.sip
+%Include qgsvectorlayerexporter.sip
 %Include qgsvectorlayerfeaturecounter.sip
-%Include qgsvectorlayerimport.sip
 %Include qgsvectorlayerjoinbuffer.sip
 %Include qgsvectorlayerjoininfo.sip
 %Include qgsvectorlayertools.sip

python/core/qgsvectorlayerimport.sip renamed to python/core/qgsvectorlayerexporter.sip

@@ -1,7 +1,7 @@
 /************************************************************************
  * This file has been generated automatically from                      *
  *                                                                      *
- * src/core/qgsvectorlayerimport.h                                      *
+ * src/core/qgsvectorlayerexporter.h                                    *
  *                                                                      *
  * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
  ************************************************************************/
@@ -10,24 +10,29 @@
 
 
 
-class QgsVectorLayerImport : QgsFeatureSink
+class QgsVectorLayerExporter : QgsFeatureSink
 {
 %Docstring
- A convenience class for writing vector files to disk.
-There are two possibilities how to use this class:
-1. static call to QgsVectorFileWriter.writeAsShapefile(...) which saves the whole vector layer
-2. create an instance of the class and issue calls to addFeature(...)
+ A convenience class for exporting vector layers to a destination data provider.
+
+ QgsVectorLayerExporter can be used in two ways:
+
+ 1. Using a static call to QgsVectorLayerExporter.exportLayer(...) which exports the
+ entire layer to the destination provider.
+
+ 2. Create an instance of the class and issue calls to addFeature(...)
+
+.. versionadded:: 3.0
 %End
 
 %TypeHeaderCode
-#include "qgsvectorlayerimport.h"
+#include "qgsvectorlayerexporter.h"
 %End
   public:
 
-    enum ImportError
+    enum ExportError
     {
       NoError,
-      ErrDriverNotFound,
       ErrCreateDataSource,
       ErrCreateLayer,
       ErrAttributeTypeUnsupported,
@@ -41,7 +46,7 @@ There are two possibilities how to use this class:
       ErrUserCanceled,
     };
 
-    static ImportError importLayer( QgsVectorLayer *layer,
+    static ExportError exportLayer( QgsVectorLayer *layer,
                                     const QString &uri,
                                     const QString &providerKey,
                                     const QgsCoordinateReferenceSystem &destCRS,
@@ -64,18 +69,18 @@ There are two possibilities how to use this class:
  \param options optional provider dataset options
  \param progress optional progress dialog to show progress of export
  :return: NoError for a successful export, or encountered error
- :rtype: ImportError
+ :rtype: ExportError
 %End
 
-    QgsVectorLayerImport( const QString &uri,
-                          const QString &provider,
-                          const QgsFields &fields,
-                          QgsWkbTypes::Type geometryType,
-                          const QgsCoordinateReferenceSystem &crs,
-                          bool overwrite = false,
-                          const QMap<QString, QVariant> *options = 0 );
+    QgsVectorLayerExporter( const QString &uri,
+                            const QString &provider,
+                            const QgsFields &fields,
+                            QgsWkbTypes::Type geometryType,
+                            const QgsCoordinateReferenceSystem &crs,
+                            bool overwrite = false,
+                            const QMap<QString, QVariant> *options = 0 );
 %Docstring
- Constructor for QgsVectorLayerImport.
+ Constructor for QgsVectorLayerExporter.
  \param uri URI for destination data source
  \param provider string key for destination data provider
  \param fields fields to include in created layer
@@ -87,20 +92,27 @@ There are two possibilities how to use this class:
 %End
 
 
-    ImportError hasError();
+    ExportError errorCode() const;
 %Docstring
-Checks whether there were any errors
- :rtype: ImportError
+ Returns any encountered error code, or false if no error was encountered.
+.. seealso:: errorMessage()
+.. seealso:: errorCount()
+ :rtype: ExportError
 %End
 
-    QString errorMessage();
+    QString errorMessage() const;
 %Docstring
-Retrieves error message
+ Returns any error message encountered during the export.
+.. seealso:: errorCount()
+.. seealso:: errorCode()
  :rtype: str
 %End
 
     int errorCount() const;
 %Docstring
+ Returns the number of error messages encountered during the export.
+.. seealso:: errorMessage()
+.. seealso:: errorCode()
  :rtype: int
 %End
 
@@ -109,19 +121,19 @@ Retrieves error message
     virtual bool addFeature( QgsFeature &feature );
 
 
-    ~QgsVectorLayerImport();
+    ~QgsVectorLayerExporter();
 %Docstring
-Close the new created layer
+ Finalizes the export and closes the new created layer.
 %End
 
   private:
-    QgsVectorLayerImport( const QgsVectorLayerImport &rh );
+    QgsVectorLayerExporter( const QgsVectorLayerExporter &rh );
 };
 
 /************************************************************************
  * This file has been generated automatically from                      *
  *                                                                      *
- * src/core/qgsvectorlayerimport.h                                      *
+ * src/core/qgsvectorlayerexporter.h                                    *
  *                                                                      *
  * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
  ************************************************************************/

python/plugins/db_manager/db_model.py

@@ -36,7 +36,7 @@
 from . import resources_rc  # NOQA
 
 try:
-    from qgis.core import QgsVectorLayerImport  # NOQA
+    from qgis.core import QgsVectorLayerExporter  # NOQA
     isImportVectorAvail = True
 except:
     isImportVectorAvail = False

python/plugins/db_manager/db_plugins/oracle/TODO.md

@@ -23,11 +23,11 @@
   modify field dialog. #13089
 
 * Import Table does not work because of a problem in
-  QgsVectorLayerImport. After the creation of the table, QGIS tries to
+  QgsVectorLayerExporter. After the creation of the table, QGIS tries to
   open the layer but, as there is no geometries in it, QGIS can't
   determinate the geometry type of the layer and refuses to open
   it. Then, no data importation can occur. Must dig into
-  src/core/qgsvectorlayerimport.cpp and into the provider code.
+  src/core/qgsvectorlayerexporter.cpp and into the provider code.
   See #13096 .
 
 # Future work

python/plugins/db_manager/dlg_export_vector.py

@@ -27,7 +27,11 @@
 from qgis.PyQt.QtWidgets import QDialog, QFileDialog, QMessageBox, QApplication
 from qgis.PyQt.QtGui import QCursor
 
-from qgis.core import QgsVectorFileWriter, QgsVectorDataProvider, QgsCoordinateReferenceSystem, QgsVectorLayerImport, QgsSettings
+from qgis.core import (QgsVectorFileWriter,
+                       QgsVectorDataProvider,
+                       QgsCoordinateReferenceSystem,
+                       QgsVectorLayerExporter,
+                       QgsSettings)
 
 from .ui.ui_DlgExportVector import Ui_DbManagerDlgExportVector as Ui_Dialog
 
@@ -175,8 +179,8 @@ def accept(self):
                 self.inLayer.setCrs(inCrs)
 
             # do the export!
-            ret, errMsg = QgsVectorLayerImport.importLayer(self.inLayer, uri, providerName, outCrs, False,
-                                                           False, options)
+            ret, errMsg = QgsVectorLayerExporter.exportLayer(self.inLayer, uri, providerName, outCrs, False,
+                                                             False, options)
         except Exception as e:
             ret = -1
             errMsg = str(e)

python/plugins/db_manager/dlg_import_vector.py

@@ -28,7 +28,14 @@
 from qgis.PyQt.QtWidgets import QDialog, QFileDialog, QMessageBox, QApplication
 from qgis.PyQt.QtGui import QCursor
 
-from qgis.core import QgsDataSourceUri, QgsVectorLayer, QgsMapLayer, QgsProviderRegistry, QgsCoordinateReferenceSystem, QgsVectorLayerImport, QgsProject, QgsSettings
+from qgis.core import (QgsDataSourceUri,
+                       QgsVectorLayer,
+                       QgsMapLayer,
+                       QgsProviderRegistry,
+                       QgsCoordinateReferenceSystem,
+                       QgsVectorLayerExporter,
+                       QgsProject,
+                       QgsSettings)
 from qgis.gui import QgsMessageViewer
 
 from .ui.ui_DlgImportVector import Ui_DbManagerDlgImportVector as Ui_Dialog
@@ -353,7 +360,7 @@ def accept(self):
             onlySelected = self.chkSelectedFeatures.isChecked()
 
             # do the import!
-            ret, errMsg = QgsVectorLayerImport.importLayer(self.inLayer, uri, providerName, outCrs, onlySelected, False, options)
+            ret, errMsg = QgsVectorLayerExporter.exportLayer(self.inLayer, uri, providerName, outCrs, onlySelected, False, options)
         except Exception as e:
             ret = -1
             errMsg = str(e)

python/plugins/processing/algs/qgis/ImportIntoPostGIS.py

@@ -25,7 +25,7 @@
 
 __revision__ = '$Format:%H$'
 
-from qgis.core import (QgsVectorLayerImport,
+from qgis.core import (QgsVectorLayerExporter,
                        QgsSettings,
                        QgsApplication,
                        QgsProcessingUtils)
@@ -164,7 +164,7 @@ def processAlgorithm(self, context, feedback):
         if encoding:
             layer.setProviderEncoding(encoding)
 
-        (ret, errMsg) = QgsVectorLayerImport.importLayer(
+        (ret, errMsg) = QgsVectorLayerExporter.exportLayer(
             layer,
             uri.uri(),
             providerName,

python/plugins/processing/algs/qgis/ImportIntoSpatialite.py

@@ -26,7 +26,7 @@
 __revision__ = '$Format:%H$'
 
 from qgis.core import (QgsDataSourceUri,
-                       QgsVectorLayerImport,
+                       QgsVectorLayerExporter,
                        QgsApplication,
                        QgsProcessingUtils)
 
@@ -134,7 +134,7 @@ def processAlgorithm(self, context, feedback):
         if encoding:
             layer.setProviderEncoding(encoding)
 
-        (ret, errMsg) = QgsVectorLayerImport.importLayer(
+        (ret, errMsg) = QgsVectorLayerExporter.exportLayer(
             layer,
             uri.uri(),
             providerName,

src/core/CMakeLists.txt

@@ -270,7 +270,7 @@ SET(QGIS_CORE_SRCS
   qgsvectorlayereditpassthrough.cpp
   qgsvectorlayereditutils.cpp
   qgsvectorlayerfeatureiterator.cpp
-  qgsvectorlayerimport.cpp
+  qgsvectorlayerexporter.cpp
   qgsvectorlayerjoinbuffer.cpp
   qgsvectorlayerlabeling.cpp
   qgsvectorlayerlabelprovider.cpp
@@ -819,7 +819,7 @@ SET(QGIS_CORE_HDRS
   qgsvectorlayerdiagramprovider.h
   qgsvectorlayereditutils.h
   qgsvectorlayerfeatureiterator.h
-  qgsvectorlayerimport.h
+  qgsvectorlayerexporter.h
   qgsvectorlayerjoininfo.h
   qgsvectorlayerlabelprovider.h
   qgsvectorlayerrenderer.h

src/core/processing/qgsprocessingutils.cpp

@@ -19,7 +19,7 @@
 #include "qgsproject.h"
 #include "qgssettings.h"
 #include "qgsprocessingcontext.h"
-#include "qgsvectorlayerimport.h"
+#include "qgsvectorlayerexporter.h"
 #include "qgsvectorfilewriter.h"
 #include "qgsmemoryproviderutils.h"
 
@@ -367,8 +367,8 @@ QgsFeatureSink *QgsProcessingUtils::createFeatureSink( QString &destination, con
     {
       //create empty layer
       {
-        QgsVectorLayerImport import( uri, providerKey, fields, geometryType, crs, false, &options );
-        if ( import.hasError() )
+        QgsVectorLayerExporter import( uri, providerKey, fields, geometryType, crs, false, &options );
+        if ( import.errorCode() )
           return nullptr;
       }