elasticsearch 8.15.1__py3-none-any.whl → 8.17.0__py3-none-any.whl

elasticsearch/_async/client/transform.py

@@ -39,9 +39,9 @@ class TransformClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes a transform.
+        Delete a transform. Deletes a transform.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/delete-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/delete-transform.html>`_
 
         :param transform_id: Identifier for the transform.
         :param delete_dest_index: If this value is true, the destination index is deleted
@@ -99,9 +99,9 @@ class TransformClient(NamespacedClient):
         size: t.Optional[int] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Retrieves configuration information for transforms.
+        Get transforms. Retrieves configuration information for transforms.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/get-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-transform.html>`_
 
         :param transform_id: Identifier for the transform. It can be a transform identifier
             or a wildcard expression. You can get information for all transforms by using
@@ -168,9 +168,9 @@ class TransformClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Retrieves usage information for transforms.
+        Get transform stats. Retrieves usage information for transforms.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/get-transform-stats.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-transform-stats.html>`_
 
         :param transform_id: Identifier for the transform. It can be a transform identifier
             or a wildcard expression. You can get information for all transforms by using
@@ -249,12 +249,14 @@ class TransformClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Previews a transform. It returns a maximum of 100 results. The calculations are
-        based on all the current data in the source index. It also generates a list of
-        mappings and settings for the destination index. These values are determined
-        based on the field types of the source index and the transform aggregations.
+        Preview a transform. Generates a preview of the results that you will get when
+        you create a transform with the same configuration. It returns a maximum of 100
+        results. The calculations are based on all the current data in the source index.
+        It also generates a list of mappings and settings for the destination index.
+        These values are determined based on the field types of the source index and
+        the transform aggregations.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/preview-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/preview-transform.html>`_
 
         :param transform_id: Identifier for the transform to preview. If you specify
             this path parameter, you cannot provide transform configuration details in
@@ -369,28 +371,29 @@ class TransformClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates a transform. A transform copies data from source indices, transforms
-        it, and persists it into an entity-centric destination index. You can also think
-        of the destination index as a two-dimensional tabular data structure (known as
-        a data frame). The ID for each document in the data frame is generated from a
-        hash of the entity, so there is a unique row per entity. You must choose either
-        the latest or pivot method for your transform; you cannot use both in a single
-        transform. If you choose to use the pivot method for your transform, the entities
-        are defined by the set of `group_by` fields in the pivot object. If you choose
-        to use the latest method, the entities are defined by the `unique_key` field
-        values in the latest object. You must have `create_index`, `index`, and `read`
-        privileges on the destination index and `read` and `view_index_metadata` privileges
-        on the source indices. When Elasticsearch security features are enabled, the
-        transform remembers which roles the user that created it had at the time of creation
-        and uses those same roles. If those roles do not have the required privileges
-        on the source and destination indices, the transform fails when it attempts unauthorized
-        operations. NOTE: You must use Kibana or this API to create a transform. Do not
-        add a transform directly into any `.transform-internal*` indices using the Elasticsearch
-        index API. If Elasticsearch security features are enabled, do not give users
-        any privileges on `.transform-internal*` indices. If you used transforms prior
-        to 7.5, also do not give users any privileges on `.data-frame-internal*` indices.
-
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/put-transform.html>`_
+        Create a transform. Creates a transform. A transform copies data from source
+        indices, transforms it, and persists it into an entity-centric destination index.
+        You can also think of the destination index as a two-dimensional tabular data
+        structure (known as a data frame). The ID for each document in the data frame
+        is generated from a hash of the entity, so there is a unique row per entity.
+        You must choose either the latest or pivot method for your transform; you cannot
+        use both in a single transform. If you choose to use the pivot method for your
+        transform, the entities are defined by the set of `group_by` fields in the pivot
+        object. If you choose to use the latest method, the entities are defined by the
+        `unique_key` field values in the latest object. You must have `create_index`,
+        `index`, and `read` privileges on the destination index and `read` and `view_index_metadata`
+        privileges on the source indices. When Elasticsearch security features are enabled,
+        the transform remembers which roles the user that created it had at the time
+        of creation and uses those same roles. If those roles do not have the required
+        privileges on the source and destination indices, the transform fails when it
+        attempts unauthorized operations. NOTE: You must use Kibana or this API to create
+        a transform. Do not add a transform directly into any `.transform-internal*`
+        indices using the Elasticsearch index API. If Elasticsearch security features
+        are enabled, do not give users any privileges on `.transform-internal*` indices.
+        If you used transforms prior to 7.5, also do not give users any privileges on
+        `.data-frame-internal*` indices.
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/put-transform.html>`_
 
         :param transform_id: Identifier for the transform. This identifier can contain
             lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores.
@@ -488,11 +491,11 @@ class TransformClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Resets a transform. Before you can reset it, you must stop it; alternatively,
-        use the `force` query parameter. If the destination index was created by the
-        transform, it is deleted.
+        Reset a transform. Resets a transform. Before you can reset it, you must stop
+        it; alternatively, use the `force` query parameter. If the destination index
+        was created by the transform, it is deleted.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/reset-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/reset-transform.html>`_
 
         :param transform_id: Identifier for the transform. This identifier can contain
             lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores.
@@ -538,12 +541,13 @@ class TransformClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Schedules now a transform. If you _schedule_now a transform, it will process
-        the new data instantly, without waiting for the configured frequency interval.
-        After _schedule_now API is called, the transform will be processed again at now
-        + frequency unless _schedule_now API is called again in the meantime.
+        Schedule a transform to start now. Instantly runs a transform to process data.
+        If you _schedule_now a transform, it will process the new data instantly, without
+        waiting for the configured frequency interval. After _schedule_now API is called,
+        the transform will be processed again at now + frequency unless _schedule_now
+        API is called again in the meantime.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/schedule-now-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/schedule-now-transform.html>`_
 
         :param transform_id: Identifier for the transform.
         :param timeout: Controls the time to wait for the scheduling to take place
@@ -588,25 +592,26 @@ class TransformClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Starts a transform. When you start a transform, it creates the destination index
-        if it does not already exist. The `number_of_shards` is set to `1` and the `auto_expand_replicas`
-        is set to `0-1`. If it is a pivot transform, it deduces the mapping definitions
-        for the destination index from the source indices and the transform aggregations.
-        If fields in the destination index are derived from scripts (as in the case of
-        `scripted_metric` or `bucket_script` aggregations), the transform uses dynamic
-        mappings unless an index template exists. If it is a latest transform, it does
-        not deduce mapping definitions; it uses dynamic mappings. To use explicit mappings,
-        create the destination index before you start the transform. Alternatively, you
-        can create an index template, though it does not affect the deduced mappings
-        in a pivot transform. When the transform starts, a series of validations occur
-        to ensure its success. If you deferred validation when you created the transform,
-        they occur when you start the transform—​with the exception of privilege checks.
-        When Elasticsearch security features are enabled, the transform remembers which
-        roles the user that created it had at the time of creation and uses those same
-        roles. If those roles do not have the required privileges on the source and destination
-        indices, the transform fails when it attempts unauthorized operations.
-
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/start-transform.html>`_
+        Start a transform. Starts a transform. When you start a transform, it creates
+        the destination index if it does not already exist. The `number_of_shards` is
+        set to `1` and the `auto_expand_replicas` is set to `0-1`. If it is a pivot transform,
+        it deduces the mapping definitions for the destination index from the source
+        indices and the transform aggregations. If fields in the destination index are
+        derived from scripts (as in the case of `scripted_metric` or `bucket_script`
+        aggregations), the transform uses dynamic mappings unless an index template exists.
+        If it is a latest transform, it does not deduce mapping definitions; it uses
+        dynamic mappings. To use explicit mappings, create the destination index before
+        you start the transform. Alternatively, you can create an index template, though
+        it does not affect the deduced mappings in a pivot transform. When the transform
+        starts, a series of validations occur to ensure its success. If you deferred
+        validation when you created the transform, they occur when you start the transform—​with
+        the exception of privilege checks. When Elasticsearch security features are enabled,
+        the transform remembers which roles the user that created it had at the time
+        of creation and uses those same roles. If those roles do not have the required
+        privileges on the source and destination indices, the transform fails when it
+        attempts unauthorized operations.
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/start-transform.html>`_
 
         :param transform_id: Identifier for the transform.
         :param from_: Restricts the set of transformed entities to those changed after
@@ -658,9 +663,9 @@ class TransformClient(NamespacedClient):
         wait_for_completion: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Stops one or more transforms.
+        Stop transforms. Stops one or more transforms.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/stop-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/stop-transform.html>`_
 
         :param transform_id: Identifier for the transform. To stop multiple transforms,
             use a comma-separated list or a wildcard expression. To stop all transforms,
@@ -751,15 +756,16 @@ class TransformClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Updates certain properties of a transform. All updated properties except `description`
-        do not take effect until after the transform starts the next checkpoint, thus
-        there is data consistency in each checkpoint. To use this API, you must have
-        `read` and `view_index_metadata` privileges for the source indices. You must
-        also have `index` and `read` privileges for the destination index. When Elasticsearch
-        security features are enabled, the transform remembers which roles the user who
-        updated it had at the time of update and runs with those privileges.
+        Update a transform. Updates certain properties of a transform. All updated properties
+        except `description` do not take effect until after the transform starts the
+        next checkpoint, thus there is data consistency in each checkpoint. To use this
+        API, you must have `read` and `view_index_metadata` privileges for the source
+        indices. You must also have `index` and `read` privileges for the destination
+        index. When Elasticsearch security features are enabled, the transform remembers
+        which roles the user who updated it had at the time of update and runs with those
+        privileges.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/update-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/update-transform.html>`_
 
         :param transform_id: Identifier for the transform.
         :param defer_validation: When true, deferrable validations are not run. This
@@ -846,7 +852,7 @@ class TransformClient(NamespacedClient):
         the role used to read source data and write to the destination index remains
         unchanged.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/upgrade-transforms.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/upgrade-transforms.html>`_
 
         :param dry_run: When true, the request checks for updates but does not run them.
         :param timeout: Period to wait for a response. If no response is received before

elasticsearch/_async/client/utils.py

@@ -20,10 +20,12 @@ from ..._sync.client.utils import (
     _TYPE_HOSTS,
     CLIENT_META_SERVICE,
     SKIP_IN_PATH,
+    Stability,
     _base64_auth_header,
     _quote,
     _quote_query,
     _rewrite_parameters,
+    _stability_warning,
     client_node_configs,
     is_requests_http_auth,
     is_requests_node_class,
@@ -37,8 +39,10 @@ __all__ = [
     "_quote_query",
     "_TYPE_HOSTS",
     "SKIP_IN_PATH",
+    "Stability",
     "client_node_configs",
     "_rewrite_parameters",
+    "_stability_warning",
     "is_requests_http_auth",
     "is_requests_node_class",
 ]

elasticsearch/_async/client/watcher.py

@@ -39,7 +39,7 @@ class WatcherClient(NamespacedClient):
         """
         Acknowledges a watch, manually throttling the execution of the watch's actions.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/watcher-api-ack-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/watcher-api-ack-watch.html>`_
 
         :param watch_id: Watch ID
         :param action_id: A comma-separated list of the action ids to be acked
@@ -90,7 +90,7 @@ class WatcherClient(NamespacedClient):
         """
         Activates a currently inactive watch.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/watcher-api-activate-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/watcher-api-activate-watch.html>`_
 
         :param watch_id: Watch ID
         """
@@ -130,7 +130,7 @@ class WatcherClient(NamespacedClient):
         """
         Deactivates a currently active watch.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/watcher-api-deactivate-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/watcher-api-deactivate-watch.html>`_
 
         :param watch_id: Watch ID
         """
@@ -170,7 +170,7 @@ class WatcherClient(NamespacedClient):
         """
         Removes a watch from Watcher.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/watcher-api-delete-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/watcher-api-delete-watch.html>`_
 
         :param id: Watch ID
         """
@@ -245,7 +245,7 @@ class WatcherClient(NamespacedClient):
         and control whether a watch record would be written to the watch history after
         execution.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/watcher-api-execute-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/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
@@ -328,7 +328,7 @@ class WatcherClient(NamespacedClient):
         """
         Retrieves a watch by its ID.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/watcher-api-get-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/watcher-api-get-watch.html>`_
 
         :param id: Watch ID
         """
@@ -390,7 +390,7 @@ class WatcherClient(NamespacedClient):
         """
         Creates a new watch, or updates an existing one.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/watcher-api-put-watch.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/watcher-api-put-watch.html>`_
 
         :param id: Watch ID
         :param actions:
@@ -487,7 +487,7 @@ class WatcherClient(NamespacedClient):
         """
         Retrieves stored watches.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/watcher-api-query-watches.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/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.
@@ -557,7 +557,7 @@ class WatcherClient(NamespacedClient):
         """
         Starts Watcher if it is not already running.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/watcher-api-start.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/watcher-api-start.html>`_
         """
         __path_parts: t.Dict[str, str] = {}
         __path = "/_watcher/_start"
@@ -614,7 +614,7 @@ class WatcherClient(NamespacedClient):
         """
         Retrieves the current Watcher metrics.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/watcher-api-stats.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/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
@@ -660,7 +660,7 @@ class WatcherClient(NamespacedClient):
         """
         Stops Watcher if it is running.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/watcher-api-stop.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/watcher-api-stop.html>`_
         """
         __path_parts: t.Dict[str, str] = {}
         __path = "/_watcher/_stop"

elasticsearch/_async/client/xpack.py

@@ -34,7 +34,9 @@ class XPackClient(NamespacedClient):
         self,
         *,
         accept_enterprise: t.Optional[bool] = None,
-        categories: t.Optional[t.Sequence[str]] = None,
+        categories: t.Optional[
+            t.Sequence[t.Union[str, t.Literal["build", "features", "license"]]]
+        ] = None,
         error_trace: t.Optional[bool] = None,
         filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
         human: t.Optional[bool] = None,
@@ -43,7 +45,7 @@ class XPackClient(NamespacedClient):
         """
         Provides general information about the installed X-Pack features.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/info-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/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
@@ -88,7 +90,7 @@ class XPackClient(NamespacedClient):
         This API provides information about which features are currently enabled and
         available under the current license and some usage statistics.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/usage-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/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

elasticsearch/_async/helpers.py

@@ -173,6 +173,7 @@ async def async_streaming_bulk(
     max_backoff: float = 600,
     yield_ok: bool = True,
     ignore_status: Union[int, Collection[int]] = (),
+    retry_on_status: Union[int, Collection[int]] = (429,),
     *args: Any,
     **kwargs: Any,
 ) -> AsyncIterable[Tuple[bool, Dict[str, Any]]]:
@@ -184,10 +185,11 @@ async def async_streaming_bulk(
     entire input is consumed and sent.
 
     If you specify ``max_retries`` it will also retry any documents that were
-    rejected with a ``429`` status code. To do this it will wait (**by calling
-    asyncio.sleep**) for ``initial_backoff`` seconds and then,
-    every subsequent rejection for the same chunk, for double the time every
-    time up to ``max_backoff`` seconds.
+    rejected with a ``429`` status code. Use ``retry_on_status`` to
+    configure which status codes will be retried. To do this it will wait
+    (**by calling asyncio.sleep which will block**) for ``initial_backoff`` seconds
+    and then, every subsequent rejection for the same chunk, for double the time
+    every time up to ``max_backoff`` seconds.
 
     :arg client: instance of :class:`~elasticsearch.AsyncElasticsearch` to use
     :arg actions: iterable or async iterable containing the actions to be executed
@@ -200,8 +202,11 @@ async def async_streaming_bulk(
     :arg expand_action_callback: callback executed on each action passed in,
         should return a tuple containing the action line and the data line
         (`None` if data line should be omitted).
+    :arg retry_on_status: HTTP status code that will trigger a retry.
+        (if `None` is specified only status 429 will retry).
     :arg max_retries: maximum number of times a document will be retried when
-        ``429`` is received, set to 0 (default) for no retries on ``429``
+        retry_on_status (defaulting to ``429``) is received,
+        set to 0 (default) for no retries
     :arg initial_backoff: number of seconds we should wait before the first
         retry. Any subsequent retries will be powers of ``initial_backoff *
         2**retry_number``
@@ -213,6 +218,9 @@ async def async_streaming_bulk(
     client = client.options()
     client._client_meta = (("h", "bp"),)
 
+    if isinstance(retry_on_status, int):
+        retry_on_status = (retry_on_status,)
+
     async def map_actions() -> AsyncIterable[_TYPE_BULK_ACTION_HEADER_AND_BODY]:
         async for item in aiter(actions):
             yield expand_action_callback(item)
@@ -264,11 +272,11 @@ async def async_streaming_bulk(
                 ):
                     if not ok:
                         action, info = info.popitem()
-                        # retry if retries enabled, we get 429, and we are not
-                        # in the last attempt
+                        # retry if retries enabled, we are not in the last attempt,
+                        # and status in retry_on_status (defaulting to 429)
                         if (
                             max_retries
-                            and info["status"] == 429
+                            and info["status"] in retry_on_status
                             and (attempt + 1) <= max_retries
                         ):
                             # _process_bulk_chunk expects strings so we need to
@@ -281,8 +289,9 @@ async def async_streaming_bulk(
                         yield ok, info
 
             except ApiError as e:
-                # suppress 429 errors since we will retry them
-                if attempt == max_retries or e.status_code != 429:
+                # suppress any status in retry_on_status (429 by default)
+                # since we will retry them
+                if attempt == max_retries or e.status_code not in retry_on_status:
                     raise
             else:
                 if not to_retry:

elasticsearch/_otel.py

@@ -25,7 +25,7 @@ try:
     from opentelemetry import trace
 
     _tracer: trace.Tracer | None = trace.get_tracer("elasticsearch-api")
-except ModuleNotFoundError:
+except ImportError:
     _tracer = None
 
 from elastic_transport import OpenTelemetrySpan
@@ -102,7 +102,7 @@ class OpenTelemetry:
 
     @contextlib.contextmanager
     def use_span(self, span: OpenTelemetrySpan) -> Generator[None, None, None]:
-        if not self.enabled or self.tracer is None:
+        if not self.enabled or self.tracer is None or span.otel_span is None:
             yield
             return