Updated opensearch-py to reflect the latest OpenSearch API spec (2024-12-22)

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: saimedhi

CHANGELOG.md

@@ -6,6 +6,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added option to pass custom headers to 'AWSV4SignerAsyncAuth' ([863](https://github.com/opensearch-project/opensearch-py/pull/863))
 - Added sync and async sample that uses `search_after` parameter ([859](https://github.com/opensearch-project/opensearch-py/pull/859))
 ### Updated APIs
+- Updated opensearch-py APIs to reflect [opensearch-api-specification@edf9d6f](https://github.com/opensearch-project/opensearch-api-specification/commit/edf9d6f0dbf1068345b58cb9e2c3464fa9839226)
 ### Changed
 - Small refactor of AWS Signer classes for both sync and async clients ([866](https://github.com/opensearch-project/opensearch-py/pull/866))
 - Small refactor to fix overwriting the module files when generating apis ([874](https://github.com/opensearch-project/opensearch-py/pull/874))

opensearchpy/_async/client/__init__.py

@@ -667,7 +667,7 @@ async def count(
             specified.
         :arg default_operator: The default operator for query string
             query: `AND` or `OR`. This parameter can only be used when the `q` query
-            string parameter is specified. Valid choices are and, or.
+            string parameter is specified. Valid choices are and, AND, or, OR.
         :arg df: Field to use as default where no field prefix is given
             in the query string. This parameter can only be used when the `q` query
             string parameter is specified.
@@ -855,7 +855,7 @@ async def delete_by_query(
         :arg conflicts: What to do if delete by query hits version
             conflicts: `abort` or `proceed`. Valid choices are abort, proceed.
         :arg default_operator: The default operator for query string
-            query: `AND` or `OR`. Valid choices are and, or.
+            query: `AND` or `OR`. Valid choices are and, AND, or, OR.
         :arg df: Field to use as default where no field prefix is given
             in the query string.
         :arg error_trace: Whether to include the stack trace of returned
@@ -1225,7 +1225,7 @@ async def explain(
             parameter can only be used when the `q` query string parameter is
             specified.
         :arg default_operator: The default operator for query string
-            query: `AND` or `OR`. Valid choices are and, or.
+            query: `AND` or `OR`. Valid choices are and, AND, or, OR.
         :arg df: Field to use as default where no field prefix is given
             in the query string. Default is _all.
         :arg error_trace: Whether to include the stack trace of returned
@@ -2020,7 +2020,7 @@ async def reindex_rethrottle(
         headers: Any = None,
     ) -> Any:
         """
-        Changes the number of requests per second for a particular Reindex operation.
+        Changes the number of requests per second for a particular reindex operation.
 
 
         :arg task_id: Identifier for the task.
@@ -2138,8 +2138,6 @@ async def scroll(
         Allows to retrieve a large numbers of results from a single search request.
 
 
-        :arg body: The scroll ID if not passed by URL or query
-            parameter.
         :arg scroll_id: The scroll ID for scrolled search
         :arg error_trace: Whether to include the stack trace of returned
             errors. Default is false.
@@ -2281,7 +2279,7 @@ async def search(
             executing cross-cluster search (CCS) requests. Default is True.
         :arg default_operator: The default operator for query string
             query: AND or OR. This parameter can only be used when the `q` query
-            string parameter is specified. Valid choices are and, or.
+            string parameter is specified. Valid choices are and, AND, or, OR.
         :arg df: Field to use as default where no field prefix is given
             in the query string. This parameter can only be used when the q query
             string parameter is specified.
@@ -2451,6 +2449,7 @@ async def search(
     )
     async def search_shards(
         self,
+        body: Any = None,
         index: Any = None,
         params: Any = None,
         headers: Any = None,
@@ -2460,6 +2459,9 @@ async def search_shards(
         executed against.
 
 
+        :arg body: Defines the parameters that can be used in the
+            `search_shards` endpoint request. See documentation for supported query
+            syntax.
         :arg index: Returns the indexes and shards that a search request
             would be executed against.
         :arg allow_no_indices: If `false`, the request returns an error
@@ -2495,7 +2497,11 @@ async def search_shards(
             libraries that do not accept a request body for non-POST requests.
         """
         return await self.transport.perform_request(
-            "GET", _make_path(index, "_search_shards"), params=params, headers=headers
+            "POST",
+            _make_path(index, "_search_shards"),
+            params=params,
+            headers=headers,
+            body=body,
         )
 
     @query_params(
@@ -2834,7 +2840,7 @@ async def update_by_query(
         :arg conflicts: What to do if update by query hits version
             conflicts: `abort` or `proceed`. Valid choices are abort, proceed.
         :arg default_operator: The default operator for query string
-            query: `AND` or `OR`. Valid choices are and, or.
+            query: `AND` or `OR`. Valid choices are and, AND, or, OR.
         :arg df: Field to use as default where no field prefix is given
             in the query string.
         :arg error_trace: Whether to include the stack trace of returned

opensearchpy/_async/client/cat.py

@@ -70,27 +70,29 @@ async def aliases(
             or use `*` or `_all`.
         :arg error_trace: Whether to include the stack trace of returned
             errors. Default is false.
-        :arg expand_wildcards: Whether to expand wildcard expression to
-            concrete indexes that are open, closed or both.
+        :arg expand_wildcards: Expands wildcard expressions to concrete
+            indexes. Combine multiple values with commas. Supported values are
+            `all`, `open`, `closed`, `hidden`, and `none`.
         :arg filter_path: Used to reduce the response. This parameter
             takes a comma-separated list of filters. It supports using wildcards to
             match any field or part of a field’s name. You can also exclude fields
             with "-".
-        :arg format: A short version of the Accept header (for example,
-            `json`, `yaml`).
-        :arg h: Comma-separated list of column names to display.
-        :arg help: Return help information. Default is false.
+        :arg format: A short version of the `Accept` header, such as
+            `json` or `yaml`.
+        :arg h: A comma-separated list of column names to display.
+        :arg help: Returns help information. Default is false.
         :arg human: Whether to return human readable values for
             statistics. Default is True.
-        :arg local: Return local information, do not retrieve the state
-            from cluster-manager node. Default is false.
+        :arg local: Whether to return information from the local node
+            only instead of from the cluster manager node. Default is false.
         :arg pretty: Whether to pretty format the returned JSON
             response. Default is false.
-        :arg s: Comma-separated list of column names or column aliases
+        :arg s: A comma-separated list of column names or column aliases
             to sort by.
         :arg source: The URL-encoded request definition. Useful for
             libraries that do not accept a request body for non-POST requests.
-        :arg v: Verbose mode. Display column headers. Default is false.
+        :arg v: Enables verbose mode, which displays column headers.
+            Default is false.
         """
         return await self.transport.perform_request(
             "GET", _make_path("_cat", "aliases", name), params=params, headers=headers
@@ -171,36 +173,37 @@ async def allocation(
         much disk space they are using.
 
 
-        :arg node_id: Comma-separated list of node identifiers or names
-            used to limit the returned information.
-        :arg bytes: The unit used to display byte values. Valid choices
+        :arg node_id: A comma-separated list of node IDs or names used
+            to limit the returned information.
+        :arg bytes: The units used to display byte values. Valid choices
             are b, g, gb, k, kb, m, mb, p, pb, t, tb.
-        :arg cluster_manager_timeout: Operation timeout for connection
-            to cluster-manager node.
+        :arg cluster_manager_timeout: A timeout for connection to the
+            cluster manager node.
         :arg error_trace: Whether to include the stack trace of returned
             errors. Default is false.
         :arg filter_path: Used to reduce the response. This parameter
             takes a comma-separated list of filters. It supports using wildcards to
             match any field or part of a field’s name. You can also exclude fields
             with "-".
-        :arg format: A short version of the Accept header (for example,
-            `json`, `yaml`).
-        :arg h: Comma-separated list of column names to display.
-        :arg help: Return help information. Default is false.
+        :arg format: A short version of the HTTP `Accept` header, such
+            as `json` or `yaml`.
+        :arg h: A comma-separated list of column names to display.
+        :arg help: Returns help information. Default is false.
         :arg human: Whether to return human readable values for
             statistics. Default is True.
-        :arg local: Return local information, do not retrieve the state
-            from cluster-manager node. Default is false.
+        :arg local: Returns local information but does not retrieve the
+            state from cluster-manager node. Default is false.
         :arg master_timeout (Deprecated: To promote inclusive language,
-            use `cluster_manager_timeout` instead.): Operation timeout for
-            connection to cluster-manager node.
+            use `cluster_manager_timeout` instead.): A timeout for connection to the
+            cluster manager node.
         :arg pretty: Whether to pretty format the returned JSON
             response. Default is false.
-        :arg s: Comma-separated list of column names or column aliases
+        :arg s: A comma-separated list of column names or column aliases
             to sort by.
         :arg source: The URL-encoded request definition. Useful for
             libraries that do not accept a request body for non-POST requests.
-        :arg v: Verbose mode. Display column headers. Default is false.
+        :arg v: Enables verbose mode, which displays column headers.
+            Default is false.
         """
         return await self.transport.perform_request(
             "GET",
@@ -233,32 +236,33 @@ async def cluster_manager(
         Returns information about the cluster-manager node.
 
 
-        :arg cluster_manager_timeout: Operation timeout for connection
-            to cluster-manager node.
+        :arg cluster_manager_timeout: A timeout for connection to the
+            cluster manager node.
         :arg error_trace: Whether to include the stack trace of returned
             errors. Default is false.
         :arg filter_path: Used to reduce the response. This parameter
             takes a comma-separated list of filters. It supports using wildcards to
             match any field or part of a field’s name. You can also exclude fields
             with "-".
-        :arg format: A short version of the Accept header (for example,
-            `json`, `yaml`).
-        :arg h: Comma-separated list of column names to display.
+        :arg format: A short version of the HTTP `Accept` header, such
+            as `json` or `yaml`.
+        :arg h: A comma-separated list of column names to display.
         :arg help: Return help information. Default is false.
         :arg human: Whether to return human readable values for
             statistics. Default is True.
         :arg local: Return local information, do not retrieve the state
             from cluster-manager node. Default is false.
         :arg master_timeout (Deprecated: To promote inclusive language,
-            use `cluster_manager_timeout` instead.): Operation timeout for
-            connection to cluster-manager node.
+            use `cluster_manager_timeout` instead.): A timeout for connection to the
+            cluster manager node.
         :arg pretty: Whether to pretty format the returned JSON
             response. Default is false.
-        :arg s: Comma-separated list of column names or column aliases
+        :arg s: A comma-separated list of column names or column aliases
             to sort by.
         :arg source: The URL-encoded request definition. Useful for
             libraries that do not accept a request body for non-POST requests.
-        :arg v: Verbose mode. Display column headers. Default is false.
+        :arg v: Enables verbose mode, which displays column headers.
+            Default is false.
         """
         return await self.transport.perform_request(
             "GET", "/_cat/cluster_manager", params=params, headers=headers
@@ -498,8 +502,7 @@ async def indices(
             `json`, `yaml`).
         :arg h: Comma-separated list of column names to display.
         :arg health: The health status used to limit returned indexes.
-            By default, the response includes indexes of any health status. Valid
-            choices are green, red, yellow.
+            By default, the response includes indexes of any health status.
         :arg help: Return help information. Default is false.
         :arg human: Whether to return human readable values for
             statistics. Default is True.

opensearchpy/_async/client/cluster.py

@@ -127,7 +127,7 @@ async def health(
         :arg wait_for_status: One of green, yellow or red. Will wait
             (until the timeout provided) until the status of the cluster changes to
             the one provided or better, i.e. green > yellow > red. By default, will
-            not wait for any status. Valid choices are green, red, yellow.
+            not wait for any status.
         """
         return await self.transport.perform_request(
             "GET",

opensearchpy/_async/client/indices.py

@@ -1638,7 +1638,7 @@ async def validate_query(
             parameter can only be used when the `q` query string parameter is
             specified.
         :arg default_operator: The default operator for query string
-            query: `AND` or `OR`. Valid choices are and, or.
+            query: `AND` or `OR`. Valid choices are and, AND, or, OR.
         :arg df: Field to use as default where no field prefix is given
             in the query string. This parameter can only be used when the `q` query
             string parameter is specified.

opensearchpy/_async/client/list.py

@@ -103,8 +103,7 @@ async def indices(
             `JSON`, `YAML`.
         :arg h: Comma-separated list of column names to display.
         :arg health: The health status used to limit returned indexes.
-            By default, the response includes indexes of any health status. Valid
-            choices are green, red, yellow.
+            By default, the response includes indexes of any health status.
         :arg help: Return help information. Default is false.
         :arg human: Whether to return human readable values for
             statistics. Default is True.

opensearchpy/_async/client/plugins.py

@@ -22,13 +22,15 @@
 from ..plugins.query import QueryClient
 from ..plugins.replication import ReplicationClient
 from ..plugins.rollups import RollupsClient
+from ..plugins.sm import SmClient
 from ..plugins.sql import SqlClient
 from ..plugins.transforms import TransformsClient
 from .client import Client
 from .utils import NamespacedClient
 
 
 class PluginsClient(NamespacedClient):
+    sm: Any
     asynchronous_search: Any
     alerting: Any
     index_management: Any
@@ -45,6 +47,7 @@ class PluginsClient(NamespacedClient):
     def __init__(self, client: Client) -> None:
         super().__init__(client)
 
+        self.sm = SmClient(client)
         self.replication = ReplicationClient(client)
         self.flow_framework = FlowFrameworkClient(client)
         self.asynchronous_search = AsynchronousSearchClient(client)
@@ -66,6 +69,7 @@ def _dynamic_lookup(self, client: Any) -> None:
         # Issue : https://github.com/opensearch-project/opensearch-py/issues/90#issuecomment-1003396742
 
         plugins = [
+            "sm",
             "replication",
             "flow_framework",
             "asynchronous_search",

opensearchpy/_async/plugins/knn.py

@@ -310,7 +310,7 @@ async def stats(
     )
     async def train_model(
         self,
-        body: Any,
+        body: Any = None,
         model_id: Any = None,
         params: Any = None,
         headers: Any = None,
@@ -335,9 +335,6 @@ async def train_model(
         :arg source: The URL-encoded request definition. Useful for
             libraries that do not accept a request body for non-POST requests.
         """
-        if body in SKIP_IN_PATH:
-            raise ValueError("Empty value passed for a required argument 'body'.")
-
         return await self.transport.perform_request(
             "POST",
             _make_path("_plugins", "_knn", "models", model_id, "_train"),

opensearchpy/_async/plugins/observability.py

@@ -135,7 +135,7 @@ async def get_localstats(
         headers: Any = None,
     ) -> Any:
         """
-        Retrieves Local Stats of all observability objects.
+        Retrieves local stats of all observability objects.
 
 
         :arg error_trace: Whether to include the stack trace of returned