fix #59 add method for cancelling a download request

pygbif/gbifutils.py

@@ -64,6 +64,12 @@ def gbif_POST(url, body, **kwargs):
     stopifnot(out.headers["content-type"])
     return out.json()
 
+def gbif_DELETE(url, body, **kwargs):
+    head = make_ua()
+    out = requests.delete(url, json=False, headers=head, **kwargs)
+    out.raise_for_status()
+    return out.status_code == 204
+
 
 def stopifnot(x, ctype="application/json"):
     if x != ctype:

pygbif/occurrences/__init__.py

@@ -16,6 +16,7 @@
 * `download_meta`: Retrieve occurrence download metadata by unique download key
 * `download_list`: Lists the downloads created by a user
 * `download_get`: Get a download from GBIF
+* `download_cancel`: Cancel a download from GBIF
 """
 
 from .search import search
@@ -29,4 +30,4 @@
     count_schema,
     count_publishingcountries,
 )
-from .download import download, download_meta, download_list, download_get
+from .download import download, download_meta, download_list, download_get, download_cancel

pygbif/occurrences/download.py

@@ -6,7 +6,7 @@
 import requests
 
 from .. import package_metadata, occurrences
-from ..gbifutils import is_not_none, is_none, stop, gbif_GET, gbif_GET_write
+from ..gbifutils import is_not_none, is_none, stop, gbif_GET, gbif_GET_write, gbif_DELETE
 import logging
 
 def _parse_args(x):
@@ -342,6 +342,32 @@ def download_meta(key, **kwargs):
     url = "http://api.gbif.org/v1/occurrence/download/" + key
     return gbif_GET(url, {}, **kwargs)
 
+def download_cancel(key, user=None, pwd=None, **kwargs):
+    """
+    Delete a download request by its unique key. Further
+    named arguments passed on to ``requests.get`` can be included as additional
+    arguments
+
+    :param key: [str] A key generated from a request, like that from ``download``
+    :param user: [str] A user name, look at env var ``GBIF_USER`` first
+    :param pwd: [str] Your password, look at env var ``GBIF_PWD`` first
+
+    :return: a bool, `True` if cancel request successful, otherwise `False`
+
+    Usage::
+
+      from pygbif import occurrences as occ
+      # first, make a download request
+      x = occ.download('taxonKey = 156780401')
+      occ.download_meta(x[0])
+      # then cancel it - do so before the download is ready, or it will have no effect
+      occ.download_cancel(key = x[0])
+    """
+    user = _check_environ("GBIF_USER", user)
+    pwd = _check_environ("GBIF_PWD", pwd)
+
+    url = "http://api.gbif.org/v1/occurrence/download/request/" + key
+    return gbif_DELETE(url, {}, auth=(user, pwd), **kwargs)
 
 def download_list(user=None, pwd=None, limit=20, offset=0):
     """

pygbif/package_metadata.py

@@ -1,4 +1,4 @@
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 __title__ = "pygbif"
 __author__ = "Scott Chamberlain"
 __license__ = "MIT"

test/test-occurrences-download_cancel.py

@@ -0,0 +1,12 @@
+"""Tests for occurrences module - download_cancle methods"""
+from pygbif import occurrences as occ
+import vcr
+
+@vcr.use_cassette("test/vcr_cassettes/test_download_cancel.yaml", filter_headers=['authorization'])
+def test_download_cancel():
+    "occurrences.download_cancel - basic test"
+    name_key = '156780401' # for "Bear picornavirus 1"
+    res = occ.download('taxonKey = ' + name_key)
+    download_key = res[0]
+    out = occ.download_cancel(download_key)
+    assert True == out

test/vcr_cassettes/test_download_cancel.yaml

@@ -0,0 +1,50 @@
+interactions:
+- request:
+    body: 'false'
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '5'
+      Content-Type:
+      - application/json
+      user-agent:
+      - python-requests/2.25.1,pygbif/0.5.1
+    method: DELETE
+    uri: http://api.gbif.org/v1/occurrence/download/request/0003970-140910143529206
+  response:
+    body:
+      string: ''
+    headers:
+      Age:
+      - '0'
+      Cache-Control:
+      - no-cache, no-store, max-age=0, must-revalidate
+      Connection:
+      - keep-alive
+      Date:
+      - Thu, 28 Jan 2021 02:30:43 GMT
+      Expires:
+      - '0'
+      Pragma:
+      - no-cache
+      Vary:
+      - Origin, Access-Control-Request-Method, Access-Control-Request-Headers
+      Via:
+      - 1.1 varnish (Varnish/6.0)
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - DENY
+      X-Varnish:
+      - '955582058'
+      X-XSS-Protection:
+      - 1; mode=block
+    status:
+      code: 204
+      message: No Content
+version: 1