Verbatim extensions as an argument

docs/conf.py

@@ -74,6 +74,7 @@
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
 language = 'en'
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

pygbif/occurrences/download.py

@@ -74,7 +74,7 @@ def _check_environ(variable, value):
 
 # download function
 def download(
-    queries, format="SIMPLE_CSV", user=None, pwd=None, email=None, pred_type="and"
+    queries, format="SIMPLE_CSV", user=None, pwd=None, email=None, pred_type="and", verbatim_extensions=None, prep=False
 ):
     """
     Spin up a download request for GBIF occurrence data.
@@ -93,6 +93,8 @@ def download(
         Set in your env vars with the option ``GBIF_PWD``
     :param email: (character) Email address to receive download notice done
         email. Required. Set in your env vars with the option ``GBIF_EMAIL``
+    :param verbatim_extensions: (list) A list of verbatim extensions to include in the download. For example, ['http://rs.gbif.org/terms/1.0/DNADerivedData', 'http://rs.tdwg.org/dwc/terms/MeasurementOrFact']
+    :prep: (logical) If True, the function will return the payload that would be sent to the API, but will not actually send the request. Default: False
 
     Argument passed have to be passed as characters (e.g., ``country = US``),
     with a space between key (``country``), operator (``=``), and value (``US``).
@@ -254,6 +256,9 @@ def download(
     req = GbifDownload(user, email)
     req.format = format
 
+    if is_not_none(verbatim_extensions):
+        req.verbatim_extensions = verbatim_extensions
+
     if isinstance(queries, dict):
         req.predicate = queries
 
@@ -267,8 +272,10 @@ def download(
         req.main_pred_type = pred_type
         for predicate in keyval:
             req.add_predicate_dict(predicate)
-
-    out = req.post_download(user, pwd)
+    if prep:
+        out = "Prepared but not sent to GBIF API"
+    else:     
+        out = req.post_download(user, pwd)
     return out, req.payload
 
 
@@ -288,6 +295,7 @@ def __init__(self, creator, email, polygon=None):
         self.predicates = []
         self._main_pred_type = "and"
         self._predicate = {"type": self._main_pred_type, "predicates": self.predicates}
+        self._verbatim_extensions = None
 
         self.url = "http://api.gbif.org/v1/occurrence/download/request"
         self.header = {
@@ -302,7 +310,6 @@ def __init__(self, creator, email, polygon=None):
                 ]
             ),
         }
-
         self.payload = {
             "creator": creator,
             "notification_address": [email],
@@ -353,6 +360,23 @@ def predicate(self, value):
             self.payload["predicate"] = self._predicate
         else:
             raise Exception("predicate must be a dictionary")
+
+    @property
+    def verbatim_extensions(self):
+        """get verbatim extensions"""
+        return self._verbatim_extensions
+
+    @verbatim_extensions.setter
+    def verbatim_extensions(self, value):
+        """set verbatim extensions
+
+        :param value: list of verbatim extensions to include in the download
+        """
+        if(self.format == "DWCA"): 
+            self._verbatim_extensions = value
+            self.payload["verbatimExtensions"] = self._verbatim_extensions
+        else: 
+            raise Exception("verbatim_extensions can only be used with the DWCA format")    
 
     @property
     def format(self):

test/test-occurrences-download_request.py

@@ -1,6 +1,7 @@
 import time
 import requests
 import unittest
+import pytest
 
 from pygbif.occurrences.download import GbifDownload, download
 
@@ -195,3 +196,20 @@ def test_geometry_predicate(self):
             payload["predicate"]["predicates"][0],
             {"type": "within", "geometry": "POLYGON((-82.7 36.9, -85.0 35.6, -81.0 33.5, -79.4 36.3, -79.4 36.3, -82.7 36.9))"},
         )
+
+    def test_verbatim_extension(self):
+        dl_key, payload = download(
+            ["taxonKey = 1"], user="dummy", email="dummy", pwd="dummy", format="DWCA", verbatim_extensions = ["http://rs.tdwg.org/ac/terms/Multimedia","http://data.ggbn.org/schemas/ggbn/terms/Amplification"]
+        )
+
+        self.assertListEqual(
+            payload["verbatimExtensions"],
+            ["http://rs.tdwg.org/ac/terms/Multimedia","http://data.ggbn.org/schemas/ggbn/terms/Amplification"],
+        )
+
+    def test_verbatim_extension_fails_well(self):
+        with self.assertRaisesRegex(Exception, "verbatim_extensions can only be used with the DWCA format"):
+            dl_key, payload = download(
+                ["taxonKey = 1"], user="dummy", email="dummy", pwd="dummy", format="SIMPLE_CSV", verbatim_extensions = ["http://rs.tdwg.org/ac/terms/Multimedia","http://data.ggbn.org/schemas/ggbn/terms/Amplification"]
+            )
+