Deduplicate params in docstrings

Author: sethmlarson

elasticsearch/__init__.py

@@ -1,23 +1,12 @@
 # flake8: noqa
 from __future__ import absolute_import
 
-VERSION = (7, 5, 1)
+VERSION = (8, 0, 0)
 __version__ = VERSION
 __versionstr__ = ".".join(map(str, VERSION))
 
 import logging
 
-try:  # Python 2.7+
-    from logging import NullHandler
-except ImportError:
-
-    class NullHandler(logging.Handler):
-        def emit(self, record):
-            pass
-
-
-import sys
-
 logger = logging.getLogger("elasticsearch")
 logger.addHandler(logging.NullHandler())
 
@@ -26,4 +15,41 @@ def emit(self, record):
 from .connection_pool import ConnectionPool, ConnectionSelector, RoundRobinSelector
 from .serializer import JSONSerializer
 from .connection import Connection, RequestsHttpConnection, Urllib3HttpConnection
-from .exceptions import *
+from .exceptions import (
+    ImproperlyConfigured,
+    ElasticsearchException,
+    SerializationError,
+    TransportError,
+    NotFoundError,
+    ConflictError,
+    RequestError,
+    ConnectionError,
+    SSLError,
+    ConnectionTimeout,
+    AuthenticationException,
+    AuthorizationException,
+)
+
+__all__ = [
+    "Elasticsearch",
+    "Transport",
+    "ConnectionPool",
+    "ConnectionSelector",
+    "RoundRobinSelector",
+    "JSONSerializer",
+    "Connection",
+    "RequestsHttpConnection",
+    "Urllib3HttpConnection",
+    "ImproperlyConfigured",
+    "ElasticsearchException",
+    "SerializationError",
+    "TransportError",
+    "NotFoundError",
+    "ConflictError",
+    "RequestError",
+    "ConnectionError",
+    "SSLError",
+    "ConnectionTimeout",
+    "AuthenticationException",
+    "AuthorizationException",
+]

elasticsearch/client/__init__.py

@@ -434,8 +434,6 @@ def bulk(self, body, index=None, doc_type=None, params=None, headers=None):
             the returned _source field, can be overridden on each sub-request
         :arg _source_includes: Default list of fields to extract and
             return from the _source field, can be overridden on each sub-request
-        :arg doc_type: Default document type for items which don't
-            provide one
         :arg pipeline: The pipeline id to preprocess incoming documents
             with
         :arg refresh: If `true` then refresh the affected shards to make
@@ -1121,8 +1119,8 @@ def msearch(self, body, index=None, params=None, headers=None):
             the number of shards the search request expands to exceeds the
             threshold. This filter roundtrip can limit the number of shards
             significantly if for instance a shard can not match any documents based
-            on it's rewrite method ie. if date filters are mandatory to match but
-            the shard bounds and the query are disjoint.  Default: 128
+            on its rewrite method ie. if date filters are mandatory to match but the
+            shard bounds and the query are disjoint.
         :arg rest_total_hits_as_int: Indicates whether hits.total should
             be rendered as an integer or an object in the rest search response
         :arg search_type: Search operation type  Valid choices:
@@ -1151,7 +1149,6 @@ def put_script(self, id, body, context=None, params=None, headers=None):
 
         :arg id: Script ID
         :arg body: The document
-        :arg context: Script context
         :arg context: Context name to compile script against
         :arg master_timeout: Specify timeout for connection to master
         :arg timeout: Explicit operation timeout
@@ -1310,12 +1307,11 @@ def scroll(self, body=None, scroll_id=None, params=None, headers=None):
 
         :arg body: The scroll ID if not passed by URL or query
             parameter.
-        :arg scroll_id: The scroll ID
+        :arg scroll_id: The scroll ID for scrolled search
         :arg rest_total_hits_as_int: Indicates whether hits.total should
             be rendered as an integer or an object in the rest search response
         :arg scroll: Specify how long a consistent view of the index
             should be maintained for scrolled search
-        :arg scroll_id: The scroll ID for scrolled search
         """
         if scroll_id in SKIP_IN_PATH and body in SKIP_IN_PATH:
             raise ValueError("You need to supply scroll_id or body.")
@@ -1430,8 +1426,8 @@ def search(self, body=None, index=None, params=None, headers=None):
             the number of shards the search request expands to exceeds the
             threshold. This filter roundtrip can limit the number of shards
             significantly if for instance a shard can not match any documents based
-            on it's rewrite method ie. if date filters are mandatory to match but
-            the shard bounds and the query are disjoint.  Default: 128
+            on its rewrite method ie. if date filters are mandatory to match but the
+            shard bounds and the query are disjoint.
         :arg preference: Specify the node or shard the operation should
             be performed on (default: random)
         :arg q: Query in the Lucene query string syntax

elasticsearch/client/async_search.py

@@ -136,7 +136,7 @@ def submit(self, body=None, index=None, params=None, headers=None):
             be performed on (default: random)
         :arg q: Query in the Lucene query string syntax
         :arg request_cache: Specify if request cache should be used for
-            this request or not, defaults to index level setting
+            this request or not, defaults to true
         :arg routing: A comma-separated list of specific routing values
         :arg search_type: Search operation type  Valid choices:
             query_then_fetch, dfs_query_then_fetch

elasticsearch/client/cat.py

@@ -237,8 +237,6 @@ def recovery(self, index=None, params=None, headers=None):
             yaml
         :arg h: Comma-separated list of column names to display
         :arg help: Return help information
-        :arg index: Comma-separated list or wildcard expression of index
-            names to limit the returned information
         :arg s: Comma-separated list of column names or column aliases
             to sort by
         :arg time: The unit in which to display time values  Valid
@@ -362,12 +360,10 @@ def fielddata(self, fields=None, params=None, headers=None):
         node in the cluster.
         `<https://www.elastic.co/guide/en/elasticsearch/reference/master/cat-fielddata.html>`_
 
-        :arg fields: A comma-separated list of fields to return the
-            fielddata size
-        :arg bytes: The unit in which to display byte values  Valid
-            choices: b, k, kb, m, mb, g, gb, t, tb, p, pb
         :arg fields: A comma-separated list of fields to return in the
             output
+        :arg bytes: The unit in which to display byte values  Valid
+            choices: b, k, kb, m, mb, g, gb, t, tb, p, pb
         :arg format: a short version of the Accept header, e.g. json,
             yaml
         :arg h: Comma-separated list of column names to display

elasticsearch/client/indices.py

@@ -12,7 +12,6 @@ def analyze(self, body=None, index=None, params=None, headers=None):
         :arg body: Define analyzer/tokenizer parameters and the text on
             which the analysis should be performed
         :arg index: The name of the index to scope the operation
-        :arg index: The name of the index to scope the operation
         """
         return self.transport.perform_request(
             "POST",
@@ -514,7 +513,7 @@ def delete_alias(self, index, name, params=None, headers=None):
             "DELETE", _make_path(index, "_alias", name), params=params, headers=headers
         )
 
-    @query_params("create", "flat_settings", "master_timeout", "order", "timeout")
+    @query_params("create", "master_timeout", "order")
     def put_template(self, name, body, params=None, headers=None):
         """
         Creates or updates an index template.
@@ -524,13 +523,10 @@ def put_template(self, name, body, params=None, headers=None):
         :arg body: The template definition
         :arg create: Whether the index template should only be added if
             new or can also replace an existing one
-        :arg flat_settings: Return settings in flat format (default:
-            false)
         :arg master_timeout: Specify timeout for connection to master
         :arg order: The order for this template when merging multiple
             matching ones (higher numbers are merged later, overriding the lower
             numbers)
-        :arg timeout: Explicit operation timeout
         """
         for param in (name, body):
             if param in SKIP_IN_PATH:
@@ -784,8 +780,6 @@ def clear_cache(self, index=None, params=None, headers=None):
             using the `fielddata` parameter (default: all)
         :arg ignore_unavailable: Whether specified concrete indices
             should be ignored when unavailable (missing or closed)
-        :arg index: A comma-separated list of index name to limit the
-            operation
         :arg query: Clear query caches
         :arg request: Clear request cache
         """
@@ -1196,3 +1190,51 @@ def validate_query(
             headers=headers,
             body=body,
         )
+
+    @query_params()
+    def create_data_stream(self, name, body, params=None, headers=None):
+        """
+        Creates or updates a data stream
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/master/data-streams.html>`_
+
+        :arg name: The name of the data stream
+        :arg body: The data stream definition
+        """
+        for param in (name, body):
+            if param in SKIP_IN_PATH:
+                raise ValueError("Empty value passed for a required argument.")
+
+        return self.transport.perform_request(
+            "PUT",
+            _make_path("_data_stream", name),
+            params=params,
+            headers=headers,
+            body=body,
+        )
+
+    @query_params()
+    def delete_data_stream(self, name, params=None, headers=None):
+        """
+        Deletes a data stream.
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/master/data-streams.html>`_
+
+        :arg name: The name of the data stream
+        """
+        if name in SKIP_IN_PATH:
+            raise ValueError("Empty value passed for a required argument 'name'.")
+
+        return self.transport.perform_request(
+            "DELETE", _make_path("_data_stream", name), params=params, headers=headers
+        )
+
+    @query_params()
+    def get_data_streams(self, name=None, params=None, headers=None):
+        """
+        Returns data streams.
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/master/data-streams.html>`_
+
+        :arg name: The comma separated names of data streams
+        """
+        return self.transport.perform_request(
+            "GET", _make_path("_data_streams", name), params=params, headers=headers
+        )

elasticsearch/client/transform.py

@@ -200,7 +200,7 @@ def update_transform(self, transform_id, body, params=None, headers=None):
     )
     def cat_transform(self, transform_id=None, params=None, headers=None):
         """
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-transforms.html>`_
 
         :arg transform_id: The id of the transform for which to get
             stats. '_all' or '*' implies all transforms
@@ -227,7 +227,7 @@ def cat_transform(self, transform_id=None, params=None, headers=None):
 
         return self.transport.perform_request(
             "GET",
-            _make_path("_cat", "transform", transform_id),
+            _make_path("_cat", "transforms", transform_id),
             params=params,
             headers=headers,
         )

elasticsearch/client/watcher.py

@@ -149,9 +149,6 @@ def stats(self, metric=None, params=None, headers=None):
             current_watches, pending_watches
         :arg emit_stacktraces: Emits stack traces of currently running
             watches
-        :arg metric: Controls what additional stat metrics should be
-            include in the response  Valid choices: _all, queued_watches,
-            current_watches, pending_watches
         """
         return self.transport.perform_request(
             "GET",

setup.py

@@ -3,7 +3,7 @@
 from setuptools import setup, find_packages
 import sys
 
-VERSION = (7, 5, 1)
+VERSION = (8, 0, 0)
 __version__ = VERSION
 __versionstr__ = ".".join(map(str, VERSION))
 

utils/generate_api.py

@@ -164,11 +164,14 @@ def ind(item):
     @property
     def params(self):
         parts = self.all_parts
+        params = self._def.get("params", {})
         return chain(
             ((p, parts[p]) for p in parts if parts[p]["required"]),
-            (("body", self.body), ) if self.body else (),
-            ((p, parts[p]) for p in parts if not parts[p]["required"]),
-            sorted(self._def.get("params", {}).items()),
+            (("body", self.body),) if self.body else (),
+            ((p, parts[p]) for p in parts
+             if not parts[p]["required"] and
+             p not in params),
+            sorted(params.items(), key=lambda x: (x[0] not in parts, x[0])),
         )
 
     @property