elasticsearch 8.18.0__py3-none-any.whl → 8.19.0__py3-none-any.whl

elasticsearch/_sync/client/watcher.py

@@ -48,7 +48,7 @@ class WatcherClient(NamespacedClient):
           This happens when the condition of the watch is not met (the condition evaluates to false).</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-ack-watch.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-ack-watch>`_
 
         :param watch_id: The watch identifier.
         :param action_id: A comma-separated list of the action identifiers to acknowledge.
@@ -104,7 +104,7 @@ class WatcherClient(NamespacedClient):
           A watch can be either active or inactive.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-activate-watch.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-activate-watch>`_
 
         :param watch_id: The watch identifier.
         """
@@ -148,7 +148,7 @@ class WatcherClient(NamespacedClient):
           A watch can be either active or inactive.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-deactivate-watch.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-deactivate-watch>`_
 
         :param watch_id: The watch identifier.
         """
@@ -196,7 +196,7 @@ class WatcherClient(NamespacedClient):
           When Elasticsearch security features are enabled, make sure no write privileges are granted to anyone for the <code>.watches</code> index.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-delete-watch.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-delete-watch>`_
 
         :param id: The watch identifier.
         """
@@ -277,7 +277,7 @@ class WatcherClient(NamespacedClient):
           <p>When using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-execute-watch.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-execute-watch>`_
 
         :param id: The watch identifier.
         :param action_modes: Determines how to handle the watch actions as part of the
@@ -365,7 +365,7 @@ class WatcherClient(NamespacedClient):
           Only a subset of settings are shown, for example <code>index.auto_expand_replicas</code> and <code>index.number_of_replicas</code>.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-get-settings.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-get-settings>`_
 
         :param master_timeout: The period to wait for a connection to the master node.
             If no response is received before the timeout expires, the request fails
@@ -410,7 +410,7 @@ class WatcherClient(NamespacedClient):
           <p>Get a watch.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-get-watch.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-get-watch>`_
 
         :param id: The watch identifier.
         """
@@ -485,7 +485,7 @@ class WatcherClient(NamespacedClient):
           If the user is able to read index <code>a</code>, but not index <code>b</code>, the same will apply when the watch runs.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-put-watch.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-put-watch>`_
 
         :param id: The identifier for the watch.
         :param actions: The list of actions that will be run if the condition matches.
@@ -598,7 +598,7 @@ class WatcherClient(NamespacedClient):
           <p>Note that only the <code>_id</code> and <code>metadata.*</code> fields are queryable or sortable.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-query-watches.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-query-watches>`_
 
         :param from_: The offset from the first result to fetch. It must be non-negative.
         :param query: A query that filters the watches to be returned.
@@ -673,7 +673,7 @@ class WatcherClient(NamespacedClient):
           Start the Watcher service if it is not already running.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-start.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-start>`_
 
         :param master_timeout: Period to wait for a connection to the master node.
         """
@@ -739,7 +739,7 @@ class WatcherClient(NamespacedClient):
           You retrieve more metrics by using the metric parameter.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-stats.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-stats>`_
 
         :param metric: Defines which additional metrics are included in the response.
         :param emit_stacktraces: Defines whether stack traces are generated for each
@@ -790,7 +790,7 @@ class WatcherClient(NamespacedClient):
           Stop the Watcher service if it is running.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-stop.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-stop>`_
 
         :param master_timeout: The period to wait for the master node. If the master
             node is not available before the timeout expires, the request fails and returns
@@ -851,7 +851,7 @@ class WatcherClient(NamespacedClient):
           Watcher shards must always be in the <code>data_content</code> tier.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-update-settings.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-watcher-update-settings>`_
 
         :param index_auto_expand_replicas:
         :param index_number_of_replicas:

elasticsearch/_sync/client/xpack.py

@@ -54,7 +54,7 @@ class XPackClient(NamespacedClient):
           </ul>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/info-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/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
@@ -103,7 +103,7 @@ class XPackClient(NamespacedClient):
           The API also provides some usage statistics.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/usage-api.html>`_
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/v8/group/endpoint-xpack>`_
 
         :param master_timeout: The period to wait for a connection to the master node.
             If no response is received before the timeout expires, the request fails

elasticsearch/_version.py

@@ -15,4 +15,4 @@
 #  specific language governing permissions and limitations
 #  under the License.
 
-__versionstr__ = "8.18.0"
+__versionstr__ = "8.19.0"

elasticsearch/compat.py

@@ -16,12 +16,15 @@
 #  under the License.
 
 import inspect
+import os
 import sys
 from pathlib import Path
 from typing import Tuple, Type, Union
 
 string_types: Tuple[Type[str], Type[bytes]] = (str, bytes)
 
+DISABLE_WARN_STACKLEVEL_ENV_VAR = "DISABLE_WARN_STACKLEVEL"
+
 
 def to_str(x: Union[str, bytes], encoding: str = "ascii") -> str:
     if not isinstance(x, str):
@@ -37,6 +40,8 @@ def to_bytes(x: Union[str, bytes], encoding: str = "ascii") -> bytes:
 
 def warn_stacklevel() -> int:
     """Dynamically determine warning stacklevel for warnings based on the call stack"""
+    if os.environ.get(DISABLE_WARN_STACKLEVEL_ENV_VAR) in ["1", "true", "True"]:
+        return 0
     try:
         # Grab the root module from the current module '__name__'
         module_name = __name__.partition(".")[0]

elasticsearch/dsl/__init__.py

@@ -19,7 +19,7 @@ from . import async_connections, connections
 from .aggs import A, Agg
 from .analysis import analyzer, char_filter, normalizer, token_filter, tokenizer
 from .document import AsyncDocument, Document
-from .document_base import InnerDoc, M, MetaField, mapped_field
+from .document_base import E, InnerDoc, M, MetaField, mapped_field
 from .exceptions import (
     ElasticsearchDslException,
     IllegalOperation,
@@ -135,6 +135,7 @@ __all__ = [
     "Double",
     "DoubleRange",
     "DslBase",
+    "E",
     "ElasticsearchDslException",
     "EmptySearch",
     "Facet",

elasticsearch/dsl/_async/document.py

@@ -96,7 +96,7 @@ class AsyncDocument(DocumentBase, metaclass=AsyncIndexMeta):
 
     @classmethod
     def _get_using(cls, using: Optional[AsyncUsingType] = None) -> AsyncUsingType:
-        return cast(AsyncUsingType, using or cls._index._using)
+        return using or cls._index._using
 
     @classmethod
     def _get_connection(

elasticsearch/dsl/_sync/document.py

@@ -92,7 +92,7 @@ class Document(DocumentBase, metaclass=IndexMeta):
 
     @classmethod
     def _get_using(cls, using: Optional[UsingType] = None) -> UsingType:
-        return cast(UsingType, using or cls._index._using)
+        return using or cls._index._using
 
     @classmethod
     def _get_connection(cls, using: Optional[UsingType] = None) -> "Elasticsearch":

elasticsearch/dsl/aggs.py

@@ -678,9 +678,8 @@ class CategorizeText(Bucket[_R]):
     :arg categorization_analyzer: The categorization analyzer specifies
         how the text is analyzed and tokenized before being categorized.
         The syntax is very similar to that used to define the analyzer in
-        the [Analyze endpoint](https://www.elastic.co/guide/en/elasticsear
-        ch/reference/8.0/indices-analyze.html). This property cannot be
-        used at the same time as categorization_filters.
+        the `_analyze` endpoint. This property cannot be used at the same
+        time as categorization_filters.
     :arg shard_size: The number of categorization buckets to return from
         each shard before merging all the results.
     :arg size: The number of buckets to return. Defaults to `10` if

elasticsearch/dsl/document_base.py

@@ -15,6 +15,7 @@
 #  specific language governing permissions and limitations
 #  under the License.
 
+import json
 from datetime import date, datetime
 from fnmatch import fnmatch
 from typing import (
@@ -56,7 +57,163 @@ class MetaField:
         self.args, self.kwargs = args, kwargs
 
 
-class InstrumentedField:
+class InstrumentedExpression:
+    """Proxy object for a ES|QL expression."""
+
+    def __init__(self, expr: str):
+        self._expr = expr
+
+    def _render_value(self, value: Any) -> str:
+        if isinstance(value, InstrumentedExpression):
+            return str(value)
+        return json.dumps(value)
+
+    def __str__(self) -> str:
+        return self._expr
+
+    def __repr__(self) -> str:
+        return f"InstrumentedExpression[{self._expr}]"
+
+    def __pos__(self) -> "InstrumentedExpression":
+        return self
+
+    def __neg__(self) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"-({self._expr})")
+
+    def __eq__(self, value: Any) -> "InstrumentedExpression":  # type: ignore[override]
+        return InstrumentedExpression(f"{self._expr} == {self._render_value(value)}")
+
+    def __ne__(self, value: Any) -> "InstrumentedExpression":  # type: ignore[override]
+        return InstrumentedExpression(f"{self._expr} != {self._render_value(value)}")
+
+    def __lt__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._expr} < {self._render_value(value)}")
+
+    def __gt__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._expr} > {self._render_value(value)}")
+
+    def __le__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._expr} <= {self._render_value(value)}")
+
+    def __ge__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._expr} >= {self._render_value(value)}")
+
+    def __add__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._expr} + {self._render_value(value)}")
+
+    def __radd__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._render_value(value)} + {self._expr}")
+
+    def __sub__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._expr} - {self._render_value(value)}")
+
+    def __rsub__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._render_value(value)} - {self._expr}")
+
+    def __mul__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._expr} * {self._render_value(value)}")
+
+    def __rmul__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._render_value(value)} * {self._expr}")
+
+    def __truediv__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._expr} / {self._render_value(value)}")
+
+    def __rtruediv__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._render_value(value)} / {self._expr}")
+
+    def __mod__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._expr} % {self._render_value(value)}")
+
+    def __rmod__(self, value: Any) -> "InstrumentedExpression":
+        return InstrumentedExpression(f"{self._render_value(value)} % {self._expr}")
+
+    def is_null(self) -> "InstrumentedExpression":
+        """Compare the expression against NULL."""
+        return InstrumentedExpression(f"{self._expr} IS NULL")
+
+    def is_not_null(self) -> "InstrumentedExpression":
+        """Compare the expression against NOT NULL."""
+        return InstrumentedExpression(f"{self._expr} IS NOT NULL")
+
+    def in_(self, *values: Any) -> "InstrumentedExpression":
+        """Test if the expression equals one of the given values."""
+        rendered_values = ", ".join([f"{value}" for value in values])
+        return InstrumentedExpression(f"{self._expr} IN ({rendered_values})")
+
+    def like(self, *patterns: str) -> "InstrumentedExpression":
+        """Filter the expression using a string pattern."""
+        if len(patterns) == 1:
+            return InstrumentedExpression(
+                f"{self._expr} LIKE {self._render_value(patterns[0])}"
+            )
+        else:
+            return InstrumentedExpression(
+                f'{self._expr} LIKE ({", ".join([self._render_value(p) for p in patterns])})'
+            )
+
+    def rlike(self, *patterns: str) -> "InstrumentedExpression":
+        """Filter the expression using a regular expression."""
+        if len(patterns) == 1:
+            return InstrumentedExpression(
+                f"{self._expr} RLIKE {self._render_value(patterns[0])}"
+            )
+        else:
+            return InstrumentedExpression(
+                f'{self._expr} RLIKE ({", ".join([self._render_value(p) for p in patterns])})'
+            )
+
+    def match(self, query: str) -> "InstrumentedExpression":
+        """Perform a match query on the field."""
+        return InstrumentedExpression(f"{self._expr}:{self._render_value(query)}")
+
+    def asc(self) -> "InstrumentedExpression":
+        """Return the field name representation for ascending sort order.
+
+        For use in ES|QL queries only.
+        """
+        return InstrumentedExpression(f"{self._expr} ASC")
+
+    def desc(self) -> "InstrumentedExpression":
+        """Return the field name representation for descending sort order.
+
+        For use in ES|QL queries only.
+        """
+        return InstrumentedExpression(f"{self._expr} DESC")
+
+    def nulls_first(self) -> "InstrumentedExpression":
+        """Return the field name representation for nulls first sort order.
+
+        For use in ES|QL queries only.
+        """
+        return InstrumentedExpression(f"{self._expr} NULLS FIRST")
+
+    def nulls_last(self) -> "InstrumentedExpression":
+        """Return the field name representation for nulls last sort order.
+
+        For use in ES|QL queries only.
+        """
+        return InstrumentedExpression(f"{self._expr} NULLS LAST")
+
+    def where(
+        self, *expressions: Union[str, "InstrumentedExpression"]
+    ) -> "InstrumentedExpression":
+        """Add a condition to be met for the row to be included.
+
+        Use only in expressions given in the ``STATS`` command.
+        """
+        if len(expressions) == 1:
+            return InstrumentedExpression(f"{self._expr} WHERE {expressions[0]}")
+        else:
+            return InstrumentedExpression(
+                f'{self._expr} WHERE {" AND ".join([f"({expr})" for expr in expressions])}'
+            )
+
+
+E = InstrumentedExpression
+
+
+class InstrumentedField(InstrumentedExpression):
     """Proxy object for a mapped document field.
 
     An object of this instance is returned when a field is accessed as a class
@@ -71,8 +228,8 @@ class InstrumentedField:
         s = s.sort(-MyDocument.name)  # sort by name in descending order
     """
 
-    def __init__(self, name: str, field: Field):
-        self._name = name
+    def __init__(self, name: str, field: Optional[Field]):
+        super().__init__(name)
         self._field = field
 
     # note that the return value type here assumes classes will only be used to
@@ -83,26 +240,29 @@ class InstrumentedField:
             # first let's see if this is an attribute of this object
             return super().__getattribute__(attr)  # type: ignore[no-any-return]
         except AttributeError:
-            try:
-                # next we see if we have a sub-field with this name
-                return InstrumentedField(f"{self._name}.{attr}", self._field[attr])
-            except KeyError:
-                # lastly we let the wrapped field resolve this attribute
-                return getattr(self._field, attr)  # type: ignore[no-any-return]
-
-    def __pos__(self) -> str:
+            if self._field:
+                try:
+                    # next we see if we have a sub-field with this name
+                    return InstrumentedField(f"{self._expr}.{attr}", self._field[attr])
+                except KeyError:
+                    # lastly we let the wrapped field resolve this attribute
+                    return getattr(self._field, attr)  # type: ignore[no-any-return]
+            else:
+                raise
+
+    def __pos__(self) -> str:  # type: ignore[override]
         """Return the field name representation for ascending sort order"""
-        return f"{self._name}"
+        return f"{self._expr}"
 
-    def __neg__(self) -> str:
+    def __neg__(self) -> str:  # type: ignore[override]
         """Return the field name representation for descending sort order"""
-        return f"-{self._name}"
+        return f"-{self._expr}"
 
     def __str__(self) -> str:
-        return self._name
+        return self._expr
 
     def __repr__(self) -> str:
-        return f"InstrumentedField[{self._name}]"
+        return f"InstrumentedField[{self._expr}]"
 
 
 class DocumentMeta(type):