elasticsearch 8.12.1__py3-none-any.whl → 8.13.1__py3-none-any.whl

elasticsearch/_async/client/watcher.py

@@ -24,6 +24,7 @@ from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters
 
 
 class WatcherClient(NamespacedClient):
+
     @_rewrite_parameters()
     async def ack_watch(
         self,
@@ -38,17 +39,23 @@ class WatcherClient(NamespacedClient):
         """
         Acknowledges a watch, manually throttling the execution of the watch's actions.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/watcher-api-ack-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/watcher-api-ack-watch.html>`_
 
         :param watch_id: Watch ID
         :param action_id: A comma-separated list of the action ids to be acked
         """
         if watch_id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'watch_id'")
+        __path_parts: t.Dict[str, str]
         if watch_id not in SKIP_IN_PATH and action_id not in SKIP_IN_PATH:
-            __path = f"/_watcher/watch/{_quote(watch_id)}/_ack/{_quote(action_id)}"
+            __path_parts = {
+                "watch_id": _quote(watch_id),
+                "action_id": _quote(action_id),
+            }
+            __path = f'/_watcher/watch/{__path_parts["watch_id"]}/_ack/{__path_parts["action_id"]}'
         elif watch_id not in SKIP_IN_PATH:
-            __path = f"/_watcher/watch/{_quote(watch_id)}/_ack"
+            __path_parts = {"watch_id": _quote(watch_id)}
+            __path = f'/_watcher/watch/{__path_parts["watch_id"]}/_ack'
         else:
             raise ValueError("Couldn't find a path for the given parameters")
         __query: t.Dict[str, t.Any] = {}
@@ -62,7 +69,12 @@ class WatcherClient(NamespacedClient):
             __query["pretty"] = pretty
         __headers = {"accept": "application/json"}
         return await self.perform_request(  # type: ignore[return-value]
-            "PUT", __path, params=__query, headers=__headers
+            "PUT",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="watcher.ack_watch",
+            path_parts=__path_parts,
         )
 
     @_rewrite_parameters()
@@ -78,13 +90,14 @@ class WatcherClient(NamespacedClient):
         """
         Activates a currently inactive watch.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/watcher-api-activate-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/watcher-api-activate-watch.html>`_
 
         :param watch_id: Watch ID
         """
         if watch_id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'watch_id'")
-        __path = f"/_watcher/watch/{_quote(watch_id)}/_activate"
+        __path_parts: t.Dict[str, str] = {"watch_id": _quote(watch_id)}
+        __path = f'/_watcher/watch/{__path_parts["watch_id"]}/_activate'
         __query: t.Dict[str, t.Any] = {}
         if error_trace is not None:
             __query["error_trace"] = error_trace
@@ -96,7 +109,12 @@ class WatcherClient(NamespacedClient):
             __query["pretty"] = pretty
         __headers = {"accept": "application/json"}
         return await self.perform_request(  # type: ignore[return-value]
-            "PUT", __path, params=__query, headers=__headers
+            "PUT",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="watcher.activate_watch",
+            path_parts=__path_parts,
         )
 
     @_rewrite_parameters()
@@ -112,13 +130,14 @@ class WatcherClient(NamespacedClient):
         """
         Deactivates a currently active watch.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/watcher-api-deactivate-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/watcher-api-deactivate-watch.html>`_
 
         :param watch_id: Watch ID
         """
         if watch_id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'watch_id'")
-        __path = f"/_watcher/watch/{_quote(watch_id)}/_deactivate"
+        __path_parts: t.Dict[str, str] = {"watch_id": _quote(watch_id)}
+        __path = f'/_watcher/watch/{__path_parts["watch_id"]}/_deactivate'
         __query: t.Dict[str, t.Any] = {}
         if error_trace is not None:
             __query["error_trace"] = error_trace
@@ -130,7 +149,12 @@ class WatcherClient(NamespacedClient):
             __query["pretty"] = pretty
         __headers = {"accept": "application/json"}
         return await self.perform_request(  # type: ignore[return-value]
-            "PUT", __path, params=__query, headers=__headers
+            "PUT",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="watcher.deactivate_watch",
+            path_parts=__path_parts,
         )
 
     @_rewrite_parameters()
@@ -146,13 +170,14 @@ class WatcherClient(NamespacedClient):
         """
         Removes a watch from Watcher.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/watcher-api-delete-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/watcher-api-delete-watch.html>`_
 
         :param id: Watch ID
         """
         if id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'id'")
-        __path = f"/_watcher/watch/{_quote(id)}"
+        __path_parts: t.Dict[str, str] = {"id": _quote(id)}
+        __path = f'/_watcher/watch/{__path_parts["id"]}'
         __query: t.Dict[str, t.Any] = {}
         if error_trace is not None:
             __query["error_trace"] = error_trace
@@ -164,7 +189,12 @@ class WatcherClient(NamespacedClient):
             __query["pretty"] = pretty
         __headers = {"accept": "application/json"}
         return await self.perform_request(  # type: ignore[return-value]
-            "DELETE", __path, params=__query, headers=__headers
+            "DELETE",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="watcher.delete_watch",
+            path_parts=__path_parts,
         )
 
     @_rewrite_parameters(
@@ -207,7 +237,7 @@ class WatcherClient(NamespacedClient):
         """
         Forces the execution of a stored watch.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/watcher-api-execute-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/watcher-api-execute-watch.html>`_
 
         :param id: Identifier for the watch.
         :param action_modes: Determines how to handle the watch actions as part of the
@@ -228,9 +258,12 @@ class WatcherClient(NamespacedClient):
             the request. This watch is not persisted to the index and record_execution
             cannot be set.
         """
+        __path_parts: t.Dict[str, str]
         if id not in SKIP_IN_PATH:
-            __path = f"/_watcher/watch/{_quote(id)}/_execute"
+            __path_parts = {"id": _quote(id)}
+            __path = f'/_watcher/watch/{__path_parts["id"]}/_execute'
         else:
+            __path_parts = {}
             __path = "/_watcher/watch/_execute"
         __query: t.Dict[str, t.Any] = {}
         __body: t.Dict[str, t.Any] = body if body is not None else {}
@@ -265,7 +298,13 @@ class WatcherClient(NamespacedClient):
         if __body is not None:
             __headers["content-type"] = "application/json"
         return await self.perform_request(  # type: ignore[return-value]
-            "PUT", __path, params=__query, headers=__headers, body=__body
+            "PUT",
+            __path,
+            params=__query,
+            headers=__headers,
+            body=__body,
+            endpoint_id="watcher.execute_watch",
+            path_parts=__path_parts,
         )
 
     @_rewrite_parameters()
@@ -281,13 +320,14 @@ class WatcherClient(NamespacedClient):
         """
         Retrieves a watch by its ID.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/watcher-api-get-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/watcher-api-get-watch.html>`_
 
         :param id: Watch ID
         """
         if id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'id'")
-        __path = f"/_watcher/watch/{_quote(id)}"
+        __path_parts: t.Dict[str, str] = {"id": _quote(id)}
+        __path = f'/_watcher/watch/{__path_parts["id"]}'
         __query: t.Dict[str, t.Any] = {}
         if error_trace is not None:
             __query["error_trace"] = error_trace
@@ -299,7 +339,12 @@ class WatcherClient(NamespacedClient):
             __query["pretty"] = pretty
         __headers = {"accept": "application/json"}
         return await self.perform_request(  # type: ignore[return-value]
-            "GET", __path, params=__query, headers=__headers
+            "GET",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="watcher.get_watch",
+            path_parts=__path_parts,
         )
 
     @_rewrite_parameters(
@@ -337,7 +382,7 @@ class WatcherClient(NamespacedClient):
         """
         Creates a new watch, or updates an existing one.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/watcher-api-put-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/watcher-api-put-watch.html>`_
 
         :param id: Watch ID
         :param actions:
@@ -356,7 +401,8 @@ class WatcherClient(NamespacedClient):
         """
         if id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'id'")
-        __path = f"/_watcher/watch/{_quote(id)}"
+        __path_parts: t.Dict[str, str] = {"id": _quote(id)}
+        __path = f'/_watcher/watch/{__path_parts["id"]}'
         __query: t.Dict[str, t.Any] = {}
         __body: t.Dict[str, t.Any] = body if body is not None else {}
         if active is not None:
@@ -396,7 +442,13 @@ class WatcherClient(NamespacedClient):
         if __body is not None:
             __headers["content-type"] = "application/json"
         return await self.perform_request(  # type: ignore[return-value]
-            "PUT", __path, params=__query, headers=__headers, body=__body
+            "PUT",
+            __path,
+            params=__query,
+            headers=__headers,
+            body=__body,
+            endpoint_id="watcher.put_watch",
+            path_parts=__path_parts,
         )
 
     @_rewrite_parameters(
@@ -427,7 +479,7 @@ class WatcherClient(NamespacedClient):
         """
         Retrieves stored watches.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/watcher-api-query-watches.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/watcher-api-query-watches.html>`_
 
         :param from_: The offset from the first result to fetch. Needs to be non-negative.
         :param query: Optional, query filter watches to be returned.
@@ -436,6 +488,7 @@ class WatcherClient(NamespacedClient):
         :param size: The number of hits to return. Needs to be non-negative.
         :param sort: Optional sort definition.
         """
+        __path_parts: t.Dict[str, str] = {}
         __path = "/_watcher/_query/watches"
         __query: t.Dict[str, t.Any] = {}
         __body: t.Dict[str, t.Any] = body if body is not None else {}
@@ -475,7 +528,13 @@ class WatcherClient(NamespacedClient):
         if __body is not None:
             __headers["content-type"] = "application/json"
         return await self.perform_request(  # type: ignore[return-value]
-            "POST", __path, params=__query, headers=__headers, body=__body
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            body=__body,
+            endpoint_id="watcher.query_watches",
+            path_parts=__path_parts,
         )
 
     @_rewrite_parameters()
@@ -490,8 +549,9 @@ class WatcherClient(NamespacedClient):
         """
         Starts Watcher if it is not already running.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/watcher-api-start.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/watcher-api-start.html>`_
         """
+        __path_parts: t.Dict[str, str] = {}
         __path = "/_watcher/_start"
         __query: t.Dict[str, t.Any] = {}
         if error_trace is not None:
@@ -504,7 +564,12 @@ class WatcherClient(NamespacedClient):
             __query["pretty"] = pretty
         __headers = {"accept": "application/json"}
         return await self.perform_request(  # type: ignore[return-value]
-            "POST", __path, params=__query, headers=__headers
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="watcher.start",
+            path_parts=__path_parts,
         )
 
     @_rewrite_parameters()
@@ -534,15 +599,18 @@ class WatcherClient(NamespacedClient):
         """
         Retrieves the current Watcher metrics.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/watcher-api-stats.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/watcher-api-stats.html>`_
 
         :param metric: Defines which additional metrics are included in the response.
         :param emit_stacktraces: Defines whether stack traces are generated for each
             watch that is running.
         """
+        __path_parts: t.Dict[str, str]
         if metric not in SKIP_IN_PATH:
-            __path = f"/_watcher/stats/{_quote(metric)}"
+            __path_parts = {"metric": _quote(metric)}
+            __path = f'/_watcher/stats/{__path_parts["metric"]}'
         else:
+            __path_parts = {}
             __path = "/_watcher/stats"
         __query: t.Dict[str, t.Any] = {}
         if emit_stacktraces is not None:
@@ -557,7 +625,12 @@ class WatcherClient(NamespacedClient):
             __query["pretty"] = pretty
         __headers = {"accept": "application/json"}
         return await self.perform_request(  # type: ignore[return-value]
-            "GET", __path, params=__query, headers=__headers
+            "GET",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="watcher.stats",
+            path_parts=__path_parts,
         )
 
     @_rewrite_parameters()
@@ -572,8 +645,9 @@ class WatcherClient(NamespacedClient):
         """
         Stops Watcher if it is running.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/watcher-api-stop.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/watcher-api-stop.html>`_
         """
+        __path_parts: t.Dict[str, str] = {}
         __path = "/_watcher/_stop"
         __query: t.Dict[str, t.Any] = {}
         if error_trace is not None:
@@ -586,5 +660,10 @@ class WatcherClient(NamespacedClient):
             __query["pretty"] = pretty
         __headers = {"accept": "application/json"}
         return await self.perform_request(  # type: ignore[return-value]
-            "POST", __path, params=__query, headers=__headers
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="watcher.stop",
+            path_parts=__path_parts,
         )

elasticsearch/_async/client/xpack.py

@@ -43,12 +43,13 @@ class XPackClient(NamespacedClient):
         """
         Retrieves information about the installed X-Pack features.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/info-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/info-api.html>`_
 
         :param accept_enterprise: If this param is used it must be set to true
         :param categories: A comma-separated list of the information categories to include
             in the response. For example, `build,license,features`.
         """
+        __path_parts: t.Dict[str, str] = {}
         __path = "/_xpack"
         __query: t.Dict[str, t.Any] = {}
         if accept_enterprise is not None:
@@ -65,7 +66,12 @@ class XPackClient(NamespacedClient):
             __query["pretty"] = pretty
         __headers = {"accept": "application/json"}
         return await self.perform_request(  # type: ignore[return-value]
-            "GET", __path, params=__query, headers=__headers
+            "GET",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="xpack.info",
+            path_parts=__path_parts,
         )
 
     @_rewrite_parameters()
@@ -83,12 +89,13 @@ class XPackClient(NamespacedClient):
         """
         Retrieves usage information about the installed X-Pack features.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.12/usage-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.13/usage-api.html>`_
 
         :param master_timeout: Period to wait for a connection to the master node. If
             no response is received before the timeout expires, the request fails and
             returns an error.
         """
+        __path_parts: t.Dict[str, str] = {}
         __path = "/_xpack/usage"
         __query: t.Dict[str, t.Any] = {}
         if error_trace is not None:
@@ -103,5 +110,10 @@ class XPackClient(NamespacedClient):
             __query["pretty"] = pretty
         __headers = {"accept": "application/json"}
         return await self.perform_request(  # type: ignore[return-value]
-            "GET", __path, params=__query, headers=__headers
+            "GET",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="xpack.usage",
+            path_parts=__path_parts,
         )

elasticsearch/_async/helpers.py

@@ -395,7 +395,7 @@ async def async_scan(
     .. code-block:: python
 
         async_scan(
-            es,
+            client,
             query={"query": {"match": {"title": "python"}}},
             index="orders-*"
         )

elasticsearch/_otel.py

@@ -0,0 +1,92 @@
+#  Licensed to Elasticsearch B.V. under one or more contributor
+#  license agreements. See the NOTICE file distributed with
+#  this work for additional information regarding copyright
+#  ownership. Elasticsearch B.V. licenses this file to you under
+#  the Apache License, Version 2.0 (the "License"); you may
+#  not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+# 	http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing,
+#  software distributed under the License is distributed on an
+#  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#  KIND, either express or implied.  See the License for the
+#  specific language governing permissions and limitations
+#  under the License.
+
+from __future__ import annotations
+
+import contextlib
+import os
+from typing import TYPE_CHECKING, Generator, Mapping
+
+if TYPE_CHECKING:
+    from typing import Literal
+
+try:
+    from opentelemetry import trace
+
+    _tracer: trace.Tracer | None = trace.get_tracer("elasticsearch-api")
+except ModuleNotFoundError:
+    _tracer = None
+
+from elastic_transport import OpenTelemetrySpan
+
+# Valid values for the enabled config are 'true' and 'false'. Default is 'true'.
+ENABLED_ENV_VAR = "OTEL_PYTHON_INSTRUMENTATION_ELASTICSEARCH_ENABLED"
+# Describes how to handle search queries in the request body when assigned to
+# a span attribute.
+# Valid values are 'omit' and 'raw'.
+# Default is 'omit' as 'raw' has security implications.
+BODY_STRATEGY_ENV_VAR = "OTEL_PYTHON_INSTRUMENTATION_ELASTICSEARCH_CAPTURE_SEARCH_QUERY"
+DEFAULT_BODY_STRATEGY = "omit"
+
+
+class OpenTelemetry:
+    def __init__(
+        self,
+        enabled: bool | None = None,
+        tracer: trace.Tracer | None = None,
+        # TODO import Literal at the top-level when dropping Python 3.7
+        body_strategy: 'Literal["omit", "raw"]' | None = None,
+    ):
+        if enabled is None:
+            enabled = os.environ.get(ENABLED_ENV_VAR, "true") == "true"
+        self.tracer = tracer or _tracer
+        self.enabled = enabled and self.tracer is not None
+
+        if body_strategy is not None:
+            self.body_strategy = body_strategy
+        else:
+            self.body_strategy = os.environ.get(
+                BODY_STRATEGY_ENV_VAR, DEFAULT_BODY_STRATEGY
+            )  # type: ignore[assignment]
+            assert self.body_strategy in ("omit", "raw")
+
+    @contextlib.contextmanager
+    def span(
+        self,
+        method: str,
+        *,
+        endpoint_id: str | None,
+        path_parts: Mapping[str, str],
+    ) -> Generator[OpenTelemetrySpan, None, None]:
+        if not self.enabled or self.tracer is None:
+            yield OpenTelemetrySpan(None)
+            return
+
+        span_name = endpoint_id or method
+        with self.tracer.start_as_current_span(span_name) as otel_span:
+            otel_span.set_attribute("http.request.method", method)
+            otel_span.set_attribute("db.system", "elasticsearch")
+            if endpoint_id is not None:
+                otel_span.set_attribute("db.operation", endpoint_id)
+            for key, value in path_parts.items():
+                otel_span.set_attribute(f"db.elasticsearch.path_parts.{key}", value)
+
+            yield OpenTelemetrySpan(
+                otel_span,
+                endpoint_id=endpoint_id,
+                body_strategy=self.body_strategy,
+            )