[SYNPY-1869] Review fixes for SearchIndex entity and supporting functionality

docs/reference/experimental/async/search_index.md

@@ -0,0 +1,30 @@
+# SearchIndex
+
+## API reference
+
+::: synapseclient.models.SearchIndex
+    options:
+        inherited_members: true
+        members:
+            - store_async
+            - get_async
+            - delete_async
+            - query_async
+            - autocomplete_async
+            - get_permissions_async
+            - get_acl_async
+            - set_permissions_async
+            - delete_permissions_async
+            - list_acl_async
+
+## Supporting types
+
+::: synapseclient.models.SearchQuery
+::: synapseclient.models.SearchQueryPart
+::: synapseclient.models.SearchIndexQuery
+::: synapseclient.models.SearchAutocompleteRequest
+::: synapseclient.models.SearchHit
+::: synapseclient.models.SearchFieldValue
+::: synapseclient.models.SearchHighlight
+::: synapseclient.models.SearchIndexState
+::: synapseclient.models.SearchIndexStatus

docs/reference/experimental/async/search_management.md

@@ -0,0 +1,46 @@
+# Search Configuration
+
+Analyzer, synonym, and configuration resources that control how a
+[SearchIndex](search_index.md) builds its OpenSearch index.
+
+## API reference
+
+::: synapseclient.models.SearchConfiguration
+    options:
+        inherited_members: true
+        members:
+            - store_async
+            - get_async
+            - list_async
+
+::: synapseclient.models.TextAnalyzer
+    options:
+        inherited_members: true
+        members:
+            - store_async
+            - get_async
+            - list_async
+
+::: synapseclient.models.SynonymSet
+    options:
+        inherited_members: true
+        members:
+            - store_async
+            - get_async
+            - list_async
+
+::: synapseclient.models.ColumnAnalyzerOverride
+    options:
+        inherited_members: true
+        members:
+            - store_async
+            - get_async
+            - list_async
+
+::: synapseclient.models.SearchConfigBinding
+    options:
+        inherited_members: true
+        members:
+            - store_async
+            - get_async
+            - delete_async

docs/reference/experimental/sync/search_index.md

@@ -0,0 +1,39 @@
+[](){ #searchindex-reference-sync }
+# SearchIndex
+
+## API reference
+
+::: synapseclient.models.SearchIndex
+    options:
+        inherited_members: true
+        members:
+            - store
+            - get
+            - delete
+            - query
+            - autocomplete
+            - get_permissions
+            - get_acl
+            - set_permissions
+            - delete_permissions
+            - list_acl
+
+## Supporting types
+
+::: synapseclient.models.SearchQuery
+::: synapseclient.models.SearchQueryPart
+::: synapseclient.models.SearchIndexQuery
+::: synapseclient.models.SearchAutocompleteRequest
+::: synapseclient.models.SearchHit
+::: synapseclient.models.SearchFieldValue
+::: synapseclient.models.SearchHighlight
+::: synapseclient.models.SearchIndexState
+::: synapseclient.models.SearchIndexStatus
+
+## OpenSearch query DSL
+
+::: synapseclient.models.search_dsl
+    options:
+        show_root_heading: false
+        show_if_no_docstring: true
+        members_order: source

docs/reference/experimental/sync/search_management.md

@@ -0,0 +1,51 @@
+[](){ #search-management-reference-sync }
+# Search Configuration
+
+Analyzer, synonym, and configuration resources that control how a
+[SearchIndex][searchindex-reference-sync] builds its OpenSearch index.
+
+## API reference
+
+::: synapseclient.models.SearchConfiguration
+    options:
+        inherited_members: true
+        members:
+            - store
+            - get
+            - list
+
+::: synapseclient.models.TextAnalyzer
+    options:
+        inherited_members: true
+        members:
+            - store
+            - get
+            - list
+
+::: synapseclient.models.SynonymSet
+    options:
+        inherited_members: true
+        members:
+            - store
+            - get
+            - list
+
+::: synapseclient.models.ColumnAnalyzerOverride
+    options:
+        inherited_members: true
+        members:
+            - store
+            - get
+            - list
+
+::: synapseclient.models.SearchConfigBinding
+    options:
+        inherited_members: true
+        members:
+            - store
+            - get
+            - delete
+
+## Supporting types
+
+::: synapseclient.models.ColumnAnalyzerOverrideEntry

mkdocs.yml

@@ -86,6 +86,8 @@ nav:
       - Dataset Collection: reference/experimental/sync/dataset_collection.md
       - EntityView: reference/experimental/sync/entityview.md
       - MaterializedView: reference/experimental/sync/materializedview.md
+      - SearchIndex: reference/experimental/sync/search_index.md
+      - Search Configuration: reference/experimental/sync/search_management.md
       - SubmissionView: reference/experimental/sync/submissionview.md
       - Activity: reference/experimental/sync/activity.md
       - Team: reference/experimental/sync/team.md
@@ -117,6 +119,8 @@ nav:
           - Dataset Collection: reference/experimental/async/dataset_collection.md
           - EntityView: reference/experimental/async/entityview.md
           - MaterializedView: reference/experimental/async/materializedview.md
+          - SearchIndex: reference/experimental/async/search_index.md
+          - Search Configuration: reference/experimental/async/search_management.md
           - SubmissionView: reference/experimental/async/submissionview.md
           - Activity: reference/experimental/async/activity.md
           - Team: reference/experimental/async/team.md

synapseclient/models/mixins/__init__.py

@@ -2,7 +2,10 @@
 
 from synapseclient.models.mixins.access_control import AccessControllable
 from synapseclient.models.mixins.asynchronous_job import AsynchronousCommunicator
-from synapseclient.models.mixins.enum_coercion import EnumCoercionMixin
+from synapseclient.models.mixins.enum_coercion import (
+    EnumCoercionMixin,
+    ForwardCompatibleStrEnum,
+)
 from synapseclient.models.mixins.form import (
     FormChangeRequest,
     FormData,
@@ -30,6 +33,7 @@
 __all__ = [
     "AccessControllable",
     "EnumCoercionMixin",
+    "ForwardCompatibleStrEnum",
     "ProjectSettingsMixin",
     "StorableContainer",
     "StorageLocationConfigurable",

synapseclient/models/mixins/enum_coercion.py

@@ -1,6 +1,7 @@
-"""Mixin for automatic enum coercion in dataclasses."""
+"""Mixins and base classes for enum handling in dataclasses."""
 
-from typing import Any, ClassVar, Dict
+from enum import Enum
+from typing import Any, ClassVar, Dict, Optional
 
 
 class EnumCoercionMixin:
@@ -31,3 +32,31 @@ def __setattr__(self, name: str, value: Any) -> None:
         ):
             value = enum_cls(value)
         super().__setattr__(name, value)
+
+
+class ForwardCompatibleStrEnum(str, Enum):
+    """A string enum that accepts values it does not declare.
+
+    Use this for enums whose values are chosen by the Synapse backend. An
+    undeclared value is kept as a new member rather than raising ``ValueError``,
+    so a backend that gains a value cannot break deserialization. Comparisons
+    against the raw string and against declared members both work, and repeated
+    lookups of the same undeclared value return the same member.
+
+    Example::
+
+        class MyState(ForwardCompatibleStrEnum):
+            ACTIVE = "ACTIVE"
+
+        MyState("ACTIVE") is MyState.ACTIVE     # True
+        MyState("BRAND_NEW") == "BRAND_NEW"     # True, no exception
+    """
+
+    @classmethod
+    def _missing_(cls, value: object) -> Optional["ForwardCompatibleStrEnum"]:
+        if not isinstance(value, str):
+            return None
+        pseudo_member = str.__new__(cls, value)
+        pseudo_member._name_ = value
+        pseudo_member._value_ = value
+        return cls._value2member_map_.setdefault(value, pseudo_member)

synapseclient/models/mixins/table_components.py

@@ -85,7 +85,7 @@
     "DatasetCollection",
     "SubmissionView",
 ]
-CLASSES_WITH_READ_ONLY_SCHEMA = ["MaterializedView", "VirtualTable", "SearchIndex"]
+CLASSES_WITH_READ_ONLY_SCHEMA = ["MaterializedView", "VirtualTable"]
 
 PANDAS_TABLE_TYPE = {
     "floating": "DOUBLE",

synapseclient/models/organization.py

@@ -574,7 +574,7 @@ def fill_from_dict(self, response: dict[str, Any]) -> "Organization":
 
 
 @deprecated(
-    version="5.0.0",
+    version="4.14.0",
     reason="SchemaOrganization has been renamed to Organization. "
     "This alias will be removed in a future release; use Organization instead.",
 )
@@ -1439,7 +1439,7 @@ def list_organizations(
 
 
 @deprecated(
-    version="5.0.0",
+    version="4.14.0",
     reason="Renamed to list_organizations. "
     "This alias will be removed in a future release; use list_organizations instead.",
 )