elasticsearch 8.17.2__py3-none-any.whl → 9.0.0__py3-none-any.whl

elasticsearch/dsl/function.py

@@ -0,0 +1,180 @@
+#  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.
+
+import collections.abc
+from copy import deepcopy
+from typing import (
+    Any,
+    ClassVar,
+    Dict,
+    Literal,
+    MutableMapping,
+    Optional,
+    Union,
+    overload,
+)
+
+from elastic_transport.client_utils import DEFAULT, DefaultType
+
+from .utils import AttrDict, DslBase
+
+
+@overload
+def SF(name_or_sf: MutableMapping[str, Any]) -> "ScoreFunction": ...
+
+
+@overload
+def SF(name_or_sf: "ScoreFunction") -> "ScoreFunction": ...
+
+
+@overload
+def SF(name_or_sf: str, **params: Any) -> "ScoreFunction": ...
+
+
+def SF(
+    name_or_sf: Union[str, "ScoreFunction", MutableMapping[str, Any]],
+    **params: Any,
+) -> "ScoreFunction":
+    # {"script_score": {"script": "_score"}, "filter": {}}
+    if isinstance(name_or_sf, collections.abc.MutableMapping):
+        if params:
+            raise ValueError("SF() cannot accept parameters when passing in a dict.")
+
+        kwargs: Dict[str, Any] = {}
+        sf = deepcopy(name_or_sf)
+        for k in ScoreFunction._param_defs:
+            if k in name_or_sf:
+                kwargs[k] = sf.pop(k)
+
+        # not sf, so just filter+weight, which used to be boost factor
+        sf_params = params
+        if not sf:
+            name = "boost_factor"
+        # {'FUNCTION': {...}}
+        elif len(sf) == 1:
+            name, sf_params = sf.popitem()
+        else:
+            raise ValueError(f"SF() got an unexpected fields in the dictionary: {sf!r}")
+
+        # boost factor special case, see elasticsearch #6343
+        if not isinstance(sf_params, collections.abc.Mapping):
+            sf_params = {"value": sf_params}
+
+        # mix known params (from _param_defs) and from inside the function
+        kwargs.update(sf_params)
+        return ScoreFunction.get_dsl_class(name)(**kwargs)
+
+    # ScriptScore(script="_score", filter=Q())
+    if isinstance(name_or_sf, ScoreFunction):
+        if params:
+            raise ValueError(
+                "SF() cannot accept parameters when passing in a ScoreFunction object."
+            )
+        return name_or_sf
+
+    # "script_score", script="_score", filter=Q()
+    return ScoreFunction.get_dsl_class(name_or_sf)(**params)
+
+
+class ScoreFunction(DslBase):
+    _type_name = "score_function"
+    _type_shortcut = staticmethod(SF)
+    _param_defs = {
+        "query": {"type": "query"},
+        "filter": {"type": "query"},
+        "weight": {},
+    }
+    name: ClassVar[Optional[str]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = super().to_dict()
+        # filter and query dicts should be at the same level as us
+        for k in self._param_defs:
+            if self.name is not None:
+                val = d[self.name]
+                if isinstance(val, dict) and k in val:
+                    d[k] = val.pop(k)
+        return d
+
+
+class ScriptScore(ScoreFunction):
+    name = "script_score"
+
+
+class BoostFactor(ScoreFunction):
+    name = "boost_factor"
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = super().to_dict()
+        if self.name is not None:
+            val = d[self.name]
+            if isinstance(val, dict):
+                if "value" in val:
+                    d[self.name] = val.pop("value")
+                else:
+                    del d[self.name]
+        return d
+
+
+class RandomScore(ScoreFunction):
+    name = "random_score"
+
+
+class FieldValueFactorScore(ScoreFunction):
+    name = "field_value_factor"
+
+
+class FieldValueFactor(FieldValueFactorScore):  # alias of the above
+    pass
+
+
+class Linear(ScoreFunction):
+    name = "linear"
+
+
+class Gauss(ScoreFunction):
+    name = "gauss"
+
+
+class Exp(ScoreFunction):
+    name = "exp"
+
+
+class DecayFunction(AttrDict[Any]):
+    def __init__(
+        self,
+        *,
+        decay: Union[float, "DefaultType"] = DEFAULT,
+        offset: Any = DEFAULT,
+        scale: Any = DEFAULT,
+        origin: Any = DEFAULT,
+        multi_value_mode: Union[
+            Literal["min", "max", "avg", "sum"], "DefaultType"
+        ] = DEFAULT,
+        **kwargs: Any,
+    ):
+        if decay != DEFAULT:
+            kwargs["decay"] = decay
+        if offset != DEFAULT:
+            kwargs["offset"] = offset
+        if scale != DEFAULT:
+            kwargs["scale"] = scale
+        if origin != DEFAULT:
+            kwargs["origin"] = origin
+        if multi_value_mode != DEFAULT:
+            kwargs["multi_value_mode"] = multi_value_mode
+        super().__init__(kwargs)

elasticsearch/dsl/index.py

@@ -0,0 +1,23 @@
+#  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 ._async.index import (  # noqa: F401
+    AsyncComposableIndexTemplate,
+    AsyncIndex,
+    AsyncIndexTemplate,
+)
+from ._sync.index import ComposableIndexTemplate, Index, IndexTemplate  # noqa: F401

elasticsearch/dsl/index_base.py

@@ -0,0 +1,178 @@
+#  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 typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
+
+from typing_extensions import Self
+
+from . import analysis
+from .utils import AnyUsingType, merge
+
+if TYPE_CHECKING:
+    from .document_base import DocumentMeta
+    from .field import Field
+    from .mapping_base import MappingBase
+
+
+class IndexBase:
+    def __init__(self, name: str, mapping_class: type, using: AnyUsingType = "default"):
+        """
+        :arg name: name of the index
+        :arg using: connection alias to use, defaults to ``'default'``
+        """
+        self._name = name
+        self._doc_types: List["DocumentMeta"] = []
+        self._using = using
+        self._settings: Dict[str, Any] = {}
+        self._aliases: Dict[str, Any] = {}
+        self._analysis: Dict[str, Any] = {}
+        self._mapping_class = mapping_class
+        self._mapping: Optional["MappingBase"] = None
+
+    def resolve_nested(
+        self, field_path: str
+    ) -> Tuple[List[str], Optional["MappingBase"]]:
+        for doc in self._doc_types:
+            nested, field = doc._doc_type.mapping.resolve_nested(field_path)
+            if field is not None:
+                return nested, field
+        if self._mapping:
+            return self._mapping.resolve_nested(field_path)
+        return [], None
+
+    def resolve_field(self, field_path: str) -> Optional["Field"]:
+        for doc in self._doc_types:
+            field = doc._doc_type.mapping.resolve_field(field_path)
+            if field is not None:
+                return field
+        if self._mapping:
+            return self._mapping.resolve_field(field_path)
+        return None
+
+    def get_or_create_mapping(self) -> "MappingBase":
+        if self._mapping is None:
+            self._mapping = self._mapping_class()
+        return self._mapping
+
+    def mapping(self, mapping: "MappingBase") -> None:
+        """
+        Associate a mapping (an instance of
+        :class:`~elasticsearch.dsl.Mapping`) with this index.
+        This means that, when this index is created, it will contain the
+        mappings for the document type defined by those mappings.
+        """
+        self.get_or_create_mapping().update(mapping)
+
+    def document(self, document: "DocumentMeta") -> "DocumentMeta":
+        """
+        Associate a :class:`~elasticsearch.dsl.Document` subclass with an index.
+        This means that, when this index is created, it will contain the
+        mappings for the ``Document``. If the ``Document`` class doesn't have a
+        default index yet (by defining ``class Index``), this instance will be
+        used. Can be used as a decorator::
+
+            i = Index('blog')
+
+            @i.document
+            class Post(Document):
+                title = Text()
+
+            # create the index, including Post mappings
+            i.create()
+
+            # .search() will now return a Search object that will return
+            # properly deserialized Post instances
+            s = i.search()
+        """
+        self._doc_types.append(document)
+
+        # If the document index does not have any name, that means the user
+        # did not set any index already to the document.
+        # So set this index as document index
+        if document._index._name is None:
+            document._index = self
+
+        return document
+
+    def settings(self, **kwargs: Any) -> Self:
+        """
+        Add settings to the index::
+
+            i = Index('i')
+            i.settings(number_of_shards=1, number_of_replicas=0)
+
+        Multiple calls to ``settings`` will merge the keys, later overriding
+        the earlier.
+        """
+        self._settings.update(kwargs)
+        return self
+
+    def aliases(self, **kwargs: Any) -> Self:
+        """
+        Add aliases to the index definition::
+
+            i = Index('blog-v2')
+            i.aliases(blog={}, published={'filter': Q('term', published=True)})
+        """
+        self._aliases.update(kwargs)
+        return self
+
+    def analyzer(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Explicitly add an analyzer to an index. Note that all custom analyzers
+        defined in mappings will also be created. This is useful for search analyzers.
+
+        Example::
+
+            from elasticsearch.dsl import analyzer, tokenizer
+
+            my_analyzer = analyzer('my_analyzer',
+                tokenizer=tokenizer('trigram', 'nGram', min_gram=3, max_gram=3),
+                filter=['lowercase']
+            )
+
+            i = Index('blog')
+            i.analyzer(my_analyzer)
+
+        """
+        analyzer = analysis.analyzer(*args, **kwargs)
+        d = analyzer.get_analysis_definition()
+        # empty custom analyzer, probably already defined out of our control
+        if not d:
+            return
+
+        # merge the definition
+        merge(self._analysis, d, True)
+
+    def to_dict(self) -> Dict[str, Any]:
+        out = {}
+        if self._settings:
+            out["settings"] = self._settings
+        if self._aliases:
+            out["aliases"] = self._aliases
+        mappings = self._mapping.to_dict() if self._mapping else {}
+        analysis = self._mapping._collect_analysis() if self._mapping else {}
+        for d in self._doc_types:
+            mapping = d._doc_type.mapping
+            merge(mappings, mapping.to_dict(), True)
+            merge(analysis, mapping._collect_analysis(), True)
+        if mappings:
+            out["mappings"] = mappings
+        if analysis or self._analysis:
+            merge(analysis, self._analysis)
+            out.setdefault("settings", {})["analysis"] = analysis
+        return out

elasticsearch/dsl/mapping.py

@@ -0,0 +1,19 @@
+#  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 ._async.mapping import AsyncMapping  # noqa: F401
+from ._sync.mapping import Mapping  # noqa: F401

elasticsearch/dsl/mapping_base.py

@@ -0,0 +1,219 @@
+#  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.
+
+import collections.abc
+from itertools import chain
+from typing import Any, Dict, Iterator, List, Optional, Tuple, cast
+
+from typing_extensions import Self
+
+from .field import Field, Nested, Text, construct_field
+from .utils import DslBase
+
+META_FIELDS = frozenset(
+    (
+        "dynamic",
+        "transform",
+        "dynamic_date_formats",
+        "date_detection",
+        "numeric_detection",
+        "dynamic_templates",
+        "enabled",
+    )
+)
+
+
+class Properties(DslBase):
+    name = "properties"
+    _param_defs = {"properties": {"type": "field", "hash": True}}
+
+    properties: Dict[str, Field]
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    def __repr__(self) -> str:
+        return "Properties()"
+
+    def __getitem__(self, name: str) -> Field:
+        return self.properties[name]
+
+    def __contains__(self, name: str) -> bool:
+        return name in self.properties
+
+    def to_dict(self) -> Dict[str, Any]:
+        return cast(Dict[str, Field], super().to_dict()["properties"])
+
+    def field(self, name: str, *args: Any, **kwargs: Any) -> Self:
+        self.properties[name] = construct_field(*args, **kwargs)
+        return self
+
+    def _collect_fields(self) -> Iterator[Field]:
+        """Iterate over all Field objects within, including multi fields."""
+        fields = cast(Dict[str, Field], self.properties.to_dict())  # type: ignore[attr-defined]
+        for f in fields.values():
+            yield f
+            # multi fields
+            if hasattr(f, "fields"):
+                yield from f.fields.to_dict().values()
+            # nested and inner objects
+            if hasattr(f, "_collect_fields"):
+                yield from f._collect_fields()
+
+    def update(self, other_object: Any) -> None:
+        if not hasattr(other_object, "properties"):
+            # not an inner/nested object, no merge possible
+            return
+
+        our, other = self.properties, other_object.properties
+        for name in other:
+            if name in our:
+                if hasattr(our[name], "update"):
+                    our[name].update(other[name])
+                continue
+            our[name] = other[name]
+
+
+class MappingBase:
+    def __init__(self) -> None:
+        self.properties = Properties()
+        self._meta: Dict[str, Any] = {}
+
+    def __repr__(self) -> str:
+        return "Mapping()"
+
+    def _clone(self) -> Self:
+        m = self.__class__()
+        m.properties._params = self.properties._params.copy()
+        return m
+
+    def resolve_nested(
+        self, field_path: str
+    ) -> Tuple[List[str], Optional["MappingBase"]]:
+        field = self
+        nested = []
+        parts = field_path.split(".")
+        for i, step in enumerate(parts):
+            try:
+                field = field[step]  # type: ignore[assignment]
+            except KeyError:
+                return [], None
+            if isinstance(field, Nested):
+                nested.append(".".join(parts[: i + 1]))
+        return nested, field
+
+    def resolve_field(self, field_path: str) -> Optional[Field]:
+        field = self
+        for step in field_path.split("."):
+            try:
+                field = field[step]  # type: ignore[assignment]
+            except KeyError:
+                return None
+        return cast(Field, field)
+
+    def _collect_analysis(self) -> Dict[str, Any]:
+        analysis: Dict[str, Any] = {}
+        fields = []
+        if "_all" in self._meta:
+            fields.append(Text(**self._meta["_all"]))
+
+        for f in chain(fields, self.properties._collect_fields()):
+            for analyzer_name in (
+                "analyzer",
+                "normalizer",
+                "search_analyzer",
+                "search_quote_analyzer",
+            ):
+                if not hasattr(f, analyzer_name):
+                    continue
+                analyzer = getattr(f, analyzer_name)
+                d = analyzer.get_analysis_definition()
+                # empty custom analyzer, probably already defined out of our control
+                if not d:
+                    continue
+
+                # merge the definition
+                # TODO: conflict detection/resolution
+                for key in d:
+                    analysis.setdefault(key, {}).update(d[key])
+
+        return analysis
+
+    def _update_from_dict(self, raw: Dict[str, Any]) -> None:
+        for name, definition in raw.get("properties", {}).items():
+            self.field(name, definition)
+
+        # metadata like _all etc
+        for name, value in raw.items():
+            if name != "properties":
+                if isinstance(value, collections.abc.Mapping):
+                    self.meta(name, **value)
+                else:
+                    self.meta(name, value)
+
+    def update(self, mapping: "MappingBase", update_only: bool = False) -> None:
+        for name in mapping:
+            if update_only and name in self:
+                # nested and inner objects, merge recursively
+                if hasattr(self[name], "update"):
+                    # FIXME only merge subfields, not the settings
+                    self[name].update(mapping[name], update_only)
+                continue
+            self.field(name, mapping[name])
+
+        if update_only:
+            for name in mapping._meta:
+                if name not in self._meta:
+                    self._meta[name] = mapping._meta[name]
+        else:
+            self._meta.update(mapping._meta)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self.properties.properties
+
+    def __getitem__(self, name: str) -> Field:
+        return self.properties.properties[name]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.properties.properties)
+
+    def field(self, *args: Any, **kwargs: Any) -> Self:
+        self.properties.field(*args, **kwargs)
+        return self
+
+    def meta(self, name: str, params: Any = None, **kwargs: Any) -> Self:
+        if not name.startswith("_") and name not in META_FIELDS:
+            name = "_" + name
+
+        if params and kwargs:
+            raise ValueError("Meta configs cannot have both value and a dictionary.")
+
+        self._meta[name] = kwargs if params is None else params
+        return self
+
+    def to_dict(self) -> Dict[str, Any]:
+        meta = self._meta
+
+        # hard coded serialization of analyzers in _all
+        if "_all" in meta:
+            meta = meta.copy()
+            _all = meta["_all"] = meta["_all"].copy()
+            for f in ("analyzer", "search_analyzer", "search_quote_analyzer"):
+                if hasattr(_all.get(f, None), "to_dict"):
+                    _all[f] = _all[f].to_dict()
+        meta.update(self.properties.to_dict())
+        return meta