Restore and deprecate client.tasks.get() without task_id

Author: sethmlarson

elasticsearch/client/tasks.py

@@ -1,3 +1,4 @@
+import warnings
 from .utils import NamespacedClient, query_params, _make_path, SKIP_IN_PATH
 
 
@@ -58,7 +59,7 @@ def cancel(self, task_id=None, params=None, headers=None):
         )
 
     @query_params("timeout", "wait_for_completion")
-    def get(self, task_id, params=None, headers=None):
+    def get(self, task_id=None, params=None, headers=None):
         """
         Returns information about a task.
         `<https://www.elastic.co/guide/en/elasticsearch/reference/master/tasks.html>`_
@@ -70,7 +71,11 @@ def get(self, task_id, params=None, headers=None):
             complete (default: false)
         """
         if task_id in SKIP_IN_PATH:
-            raise ValueError("Empty value passed for a required argument 'task_id'.")
+            warnings.warn(
+                "Calling client.tasks.get() without a task_id is deprecated "
+                "and will be removed in v8.0. Use client.tasks.list() instead.",
+                DeprecationWarning,
+            )
 
         return self.transport.perform_request(
             "GET", _make_path("_tasks", task_id), params=params, headers=headers

test_elasticsearch/test_client/__init__.py

@@ -1,4 +1,5 @@
 from __future__ import unicode_literals
+import warnings
 
 from elasticsearch.client import _normalize_hosts, Elasticsearch
 
@@ -110,3 +111,27 @@ def test_index_uses_put_if_id_is_not_empty(self):
         self.client.index(index="my-index", id=0, body={})
 
         self.assert_url_called("PUT", "/my-index/_doc/0")
+
+    def test_tasks_get_without_task_id_deprecated(self):
+        warnings.simplefilter("always", DeprecationWarning)
+        with warnings.catch_warnings(record=True) as w:
+            self.client.tasks.get()
+
+        self.assert_url_called("GET", "/_tasks")
+        self.assertEquals(len(w), 1)
+        self.assertIs(w[0].category, DeprecationWarning)
+        self.assertEquals(
+            str(w[0].message),
+            "Calling client.tasks.get() without a task_id is deprecated "
+            "and will be removed in v8.0. Use client.tasks.list() instead.",
+        )
+
+    def test_tasks_get_with_task_id_not_deprecated(self):
+        warnings.simplefilter("always", DeprecationWarning)
+        with warnings.catch_warnings(record=True) as w:
+            self.client.tasks.get("task-1")
+            self.client.tasks.get(task_id="task-2")
+
+        self.assert_url_called("GET", "/_tasks/task-1")
+        self.assert_url_called("GET", "/_tasks/task-2")
+        self.assertEquals(len(w), 0)

utils/generate_api.py

@@ -139,6 +139,13 @@ def all_parts(self):
                 p in url.get("parts", {}) for url in self._def["url"]["paths"]
             )
 
+            # This piece of logic corresponds to calling
+            # client.tasks.get() w/o a task_id which was erroneously
+            # allowed in the 7.1 client library. This functionality
+            # is deprecated and will be removed in 8.x.
+            if self.namespace == "tasks" and self.name == "get":
+                parts["task_id"]["required"] = False
+
         for k, sub in SUBSTITUTIONS.items():
             if k in parts:
                 parts[sub] = parts.pop(k)

utils/generate_examples.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python
+
+import os
+import json
+import re
+from itertools import chain
+from subprocess import check_call
+
+import black
+from click.testing import CliRunner
+from jinja2 import Environment, FileSystemLoader
+from pathlib import Path
+
+
+base_dir = Path(__file__).absolute().parent.parent
+asciidocs_dir = base_dir / "docs/asciidocs"
+flight_recorder_dir = base_dir.parent / "clients-flight-recorder"
+report_path = flight_recorder_dir / "recordings/docs/parsed-alternative-report.json"
+
+asciidocs_template = """[source, python]
+----
+%s
+----
+"""
+
+
+def main():
+    for filepath in asciidocs_dir.iterdir():
+        if filepath.name.endswith(".asciidoc"):
+            filepath.unlink()
+
+    if not flight_recorder_dir.exists() or not report_path.exists():
+        raise RuntimeError(f"clients-flight-recorder repository not checked out at {flight_recorder_dir}")
+
+    with report_path.open() as f:
+        report = json.loads(f.read())
+
+
+if __name__ == "__main__":
+    main()

utils/templates/overrides/tasks/get

@@ -0,0 +1,12 @@
+{% extends "base" %}
+{% block request %}
+        if task_id in SKIP_IN_PATH:
+            warnings.warn(
+                "Calling client.tasks.get() without a task_id is deprecated "
+                "and will be removed in v8.0. Use client.tasks.list() instead.",
+                DeprecationWarning,
+            )
+
+        {{ super()|trim }}
+{% endblock %}
+