From 590c086af822204e3fe2dac05b58d19a1948eb2d Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Wed, 18 Jun 2025 10:26:05 +0300 Subject: [PATCH 1/6] refactor(types): add generic type parameters to collection schemas - Add `_CreateFieldT` and `_UpdateFieldT` type variables for field type constraints - Make `CollectionCreateSchema` generic with `_CreateFieldT` parameter - Make `CollectionSchema` inherit generic parameter from `CollectionCreateSchema` - Make `CollectionUpdateSchema` generic with `_UpdateFieldT` parameter - Add `CollectionSchemaCompat` and `CollectionUpdateSchemaCompat` type aliases for backward compatibility - Replace hardcoded union types with generic type parameters in field definitions --- src/typesense/types/collection.py | 56 +++++++++++++++++++++---------- 1 file changed, 39 insertions(+), 17 deletions(-) diff --git a/src/typesense/types/collection.py b/src/typesense/types/collection.py index 9e8a397..44ba8e4 100644 --- a/src/typesense/types/collection.py +++ b/src/typesense/types/collection.py @@ -10,6 +10,22 @@ _TType = typing.TypeVar("_TType") +_CreateFieldT = typing.TypeVar( + "_CreateFieldT", + bound=typing.Union[ + "RegularCollectionFieldSchema", "ReferenceCollectionFieldSchema" + ], +) + +_UpdateFieldT = typing.TypeVar( + "_UpdateFieldT", + bound=typing.Union[ + "RegularCollectionFieldSchema", + "ReferenceCollectionFieldSchema", + "DropCollectionFieldSchema", + ], +) + _FieldType = typing.Literal[ "string", "int32", @@ -150,15 +166,14 @@ class VoiceQueryModelSchema(typing.TypedDict): model_name: str -class CollectionCreateSchema(typing.TypedDict): +class CollectionCreateSchema(typing.Generic[_CreateFieldT], typing.TypedDict): """ The schema for the request of the Collections.create method. Attributes: name (str): The name of the collection. - fields (list[RegularCollectionFieldSchema | ReferenceCollectionFieldSchema]): The fields - of the collection. + fields (list[_CreateFieldT]): The fields of the collection. default_sorting_field (str): The default sorting field of the collection. @@ -172,9 +187,7 @@ class CollectionCreateSchema(typing.TypedDict): """ name: str - fields: typing.List[ - typing.Union[RegularCollectionFieldSchema, ReferenceCollectionFieldSchema] - ] + fields: typing.List[_CreateFieldT] default_sorting_field: typing.NotRequired[str] symbols_to_index: typing.NotRequired[typing.List[str]] token_separators: typing.NotRequired[typing.List[str]] @@ -182,7 +195,7 @@ class CollectionCreateSchema(typing.TypedDict): voice_query_model: typing.NotRequired[VoiceQueryModelSchema] -class CollectionSchema(CollectionCreateSchema): +class CollectionSchema(CollectionCreateSchema[_CreateFieldT]): """ The schema for the response of the Collections.create method. @@ -195,8 +208,7 @@ class CollectionSchema(CollectionCreateSchema): name (str): The name of the collection. - fields (list[RegularCollectionFieldSchema | ReferenceCollectionFieldSchema]): The fields - of the collection. + fields (list[_CreateFieldT]): The fields of the collection. default_sorting_field (str): The default sorting field of the collection. @@ -214,19 +226,29 @@ class CollectionSchema(CollectionCreateSchema): num_memory_shards: int -class CollectionUpdateSchema(typing.TypedDict): +# Type alias for backward compatibility +CollectionSchemaCompat = CollectionSchema[ + typing.Union[RegularCollectionFieldSchema, ReferenceCollectionFieldSchema] +] + + +class CollectionUpdateSchema(typing.Generic[_UpdateFieldT], typing.TypedDict): """ The schema for the request of the Collection.update method. Attributes: - fields (list): The fields of the collection. + fields (list[_UpdateFieldT]): The fields of the collection. """ - fields: typing.List[ - typing.Union[ - RegularCollectionFieldSchema, - ReferenceCollectionFieldSchema, - DropCollectionFieldSchema, - ] + fields: typing.List[_UpdateFieldT] + + +# Type alias for backward compatibility +CollectionUpdateSchemaCompat = CollectionUpdateSchema[ + typing.Union[ + RegularCollectionFieldSchema, + ReferenceCollectionFieldSchema, + DropCollectionFieldSchema, ] +] From f4d690868f55c17c8c31c6f141c1ba3baf0b429f Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Wed, 18 Jun 2025 10:26:52 +0300 Subject: [PATCH 2/6] refactor(types): add generic type variables for document operations - Add `_DocumentImportParamsT` type variable for document import parameter constraints - Add `_ImportResponseT` type variable for import response type constraints - Add `_StringOrListT` type variable for string or list type constraints - Add `DocumentImportParametersGeneric` type variable for document import parameters - Define bounded type variables to improve type safety and flexibility --- src/typesense/types/document.py | 37 +++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/src/typesense/types/document.py b/src/typesense/types/document.py index 416ca7e..a2b29c0 100644 --- a/src/typesense/types/document.py +++ b/src/typesense/types/document.py @@ -187,6 +187,33 @@ class ImportResponseFail(typing.Generic[TDoc], typing.TypedDict): document: TDoc +_DocumentImportParamsT = typing.TypeVar( + "_DocumentImportParamsT", + bound=typing.Union[ + "DocumentWriteParameters", + "DocumentImportParametersReturnId", + "DocumentImportParametersReturnDoc", + "DocumentImportParametersReturnDocAndId", + ], +) + +_ImportResponseT = typing.TypeVar( + "_ImportResponseT", + bound=typing.Union[ + "ImportResponseSuccess", + "ImportResponseWithDoc[typing.Any]", + "ImportResponseWithId", + "ImportResponseWithDocAndId[typing.Any]", + "ImportResponseFail[typing.Any]", + ], +) + +_StringOrListT = typing.TypeVar( + "_StringOrListT", + bound=typing.Union[str, typing.List[str]], +) + + ImportResponse: typing.TypeAlias = typing.Union[ typing.List[typing.Union[ImportResponseWithDoc[TDoc], ImportResponseFail[TDoc]]], typing.List[typing.Union[ImportResponseWithId, ImportResponseFail[TDoc]]], @@ -299,6 +326,16 @@ class DocumentImportParametersReturnDocAndId(DocumentWriteParameters): return_id: typing.Literal[True] +DocumentImportParametersGeneric = typing.TypeVar( + "DocumentImportParametersGeneric", + bound=typing.Union[ + DocumentWriteParameters, + DocumentImportParametersReturnId, + DocumentImportParametersReturnDoc, + DocumentImportParametersReturnDocAndId, + ], +) + DocumentImportParameters: typing.TypeAlias = typing.Union[ DocumentWriteParameters, DocumentImportParametersReturnId, From 8b1cbd04f120db110819104e67a73625b1d40f8f Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Wed, 18 Jun 2025 10:27:27 +0300 Subject: [PATCH 3/6] refactor(types): add generic type parameters to api key schemas - Add `_ActionT` type variable for api key action type constraints - Make `ApiKeyCreateSchema` generic with `_ActionT` parameter - Make `ApiKeyCreateResponseSchema` inherit generic parameter from `ApiKeyCreateSchema` - Make `ApiKeySchema` and `ApiKeyRetrieveSchema` generic with `_ActionT` parameter - Add compatibility type aliases for backward compatibility - Replace hardcoded `_Actions` union type with generic `_ActionT` parameter --- src/typesense/types/key.py | 46 +++++++++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 10 deletions(-) diff --git a/src/typesense/types/key.py b/src/typesense/types/key.py index 51cb2a0..d9ad10f 100644 --- a/src/typesense/types/key.py +++ b/src/typesense/types/key.py @@ -8,6 +8,20 @@ import typing_extensions as typing +_ActionT = typing.TypeVar( + "_ActionT", + bound=typing.Union[ + "_CollectionActions", + "_DocumentActions", + "_AliasActions", + "_SynonymActions", + "_OverrideActions", + "_StopwordActions", + "_KeyActions", + "_MiscActions", + ], +) + _CollectionActions = typing.Literal[ "collections:list", "collections:get", @@ -87,12 +101,12 @@ ] -class ApiKeyCreateSchema(typing.TypedDict): +class ApiKeyCreateSchema(typing.Generic[_ActionT], typing.TypedDict): """ Schema for creating a [new API key](https://typesense.org/docs/26.0/api/api-keys.html#create-an-api-key). Attributes: - actions (list[str]): The actions allowed for this key. + actions (list[_ActionT]): The actions allowed for this key. collections (list[str]): The collections this key has access to. description (str): The description for this key. value (str): The value of the key. @@ -100,7 +114,7 @@ class ApiKeyCreateSchema(typing.TypedDict): autodelete (bool): Whether the key should be deleted after it expires. """ - actions: typing.List[_Actions] + actions: typing.List[_ActionT] collections: typing.List[str] description: str value: typing.NotRequired[str] @@ -108,7 +122,10 @@ class ApiKeyCreateSchema(typing.TypedDict): autodelete: typing.NotRequired[bool] -class ApiKeyCreateResponseSchema(ApiKeyCreateSchema): +ApiKeyCreateSchemaCompat = ApiKeyCreateSchema[_Actions] + + +class ApiKeyCreateResponseSchema(ApiKeyCreateSchema[_ActionT]): """ Response schema for creating a [new API key](https://typesense.org/docs/26.0/api/api-keys.html#create-an-api-key). @@ -121,12 +138,15 @@ class ApiKeyCreateResponseSchema(ApiKeyCreateSchema): id: int -class ApiKeySchema(typing.TypedDict): +ApiKeyCreateResponseSchemaCompat = ApiKeyCreateResponseSchema[_Actions] + + +class ApiKeySchema(typing.Generic[_ActionT], typing.TypedDict): """ Response schema for an [API key](https://typesense.org/docs/26.0/api/api-keys.html#retrieve-an-api-key). Attributes: - actions (list[str]): The actions allowed for this key. + actions (list[_ActionT]): The actions allowed for this key. collections (list[str]): The collections this key has access to. description (str): The description for this key. id (int): The ID of the key. @@ -134,7 +154,7 @@ class ApiKeySchema(typing.TypedDict): expires_at (int): The time in UNIX timestamp format when the key """ - actions: typing.List[_Actions] + actions: typing.List[_ActionT] collections: typing.List[str] description: str id: int @@ -142,15 +162,21 @@ class ApiKeySchema(typing.TypedDict): expires_at: int -class ApiKeyRetrieveSchema(typing.TypedDict): +ApiKeySchemaCompat = ApiKeySchema[_Actions] + + +class ApiKeyRetrieveSchema(typing.Generic[_ActionT], typing.TypedDict): """ Response schema for retrieving [API keys](https://typesense.org/docs/26.0/api/api-keys.html#list-all-keys). Attributes: - keys (list[ApiKeySchema]): The list of keys. + keys (list[ApiKeySchema[_ActionT]]): The list of keys. """ - keys: typing.List[ApiKeySchema] + keys: typing.List[ApiKeySchema[_ActionT]] + + +ApiKeyRetrieveSchemaCompat = ApiKeyRetrieveSchema[_Actions] class ApiKeyDeleteSchema(typing.TypedDict): From d7338d0399b9465955e1153c49927f83a43d3090 Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Wed, 18 Jun 2025 10:27:59 +0300 Subject: [PATCH 4/6] refactor(types): add generic type parameters to override schemas - Add `_OverrideRuleT` type variable for override rule type constraints - Make `OverrideCreateSchema` generic with `_OverrideRuleT` parameter - Make `OverrideSchema` inherit generic parameter from `OverrideCreateSchema` - Add `OverrideCreateSchemaCompat` and `OverrideSchemaCompat` type aliases for backward compatibility - Replace hardcoded union type with generic `_OverrideRuleT` parameter in rule field --- src/typesense/types/override.py | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/src/typesense/types/override.py b/src/typesense/types/override.py index 134716c..9752613 100644 --- a/src/typesense/types/override.py +++ b/src/typesense/types/override.py @@ -8,6 +8,12 @@ import typing_extensions as typing +_OverrideRuleT = typing.TypeVar( + "_OverrideRuleT", + bound=typing.Union["OverrideQueryRuleSchema", "OverrideFilterSchema"], +) + + class OverrideQueryRuleSchema(typing.TypedDict): """ The schema for the rule field in the Overrides.upsert method. @@ -51,12 +57,12 @@ class IncludesSchema(typing.TypedDict): position: int -class OverrideCreateSchema(typing.TypedDict): +class OverrideCreateSchema(typing.Generic[_OverrideRuleT], typing.TypedDict): """ The schema for the request of the Overrides.upsert method. Attributes: - rule (OverrideQueryRuleSchema | OverrideFilterSchema): The rule. + rule (_OverrideRuleT): The rule. sort_by (str): The sort by string. filter_by (str): The filter by string. excludes (list[str]): The excludes list. @@ -69,7 +75,7 @@ class OverrideCreateSchema(typing.TypedDict): stop_processing (bool): Whether to stop processing. """ - rule: typing.Union[OverrideQueryRuleSchema, OverrideFilterSchema] + rule: _OverrideRuleT sort_by: typing.NotRequired[str] filter_by: typing.NotRequired[str] excludes: typing.NotRequired[typing.List[str]] @@ -82,12 +88,22 @@ class OverrideCreateSchema(typing.TypedDict): stop_processing: typing.NotRequired[bool] -class OverrideSchema(OverrideCreateSchema): +OverrideCreateSchemaCompat = OverrideCreateSchema[ + typing.Union[OverrideQueryRuleSchema, OverrideFilterSchema] +] + + +class OverrideSchema(OverrideCreateSchema[_OverrideRuleT]): """The schema for the response of the Overrides.upsert method.""" id: str +OverrideSchemaCompat = OverrideSchema[ + typing.Union[OverrideQueryRuleSchema, OverrideFilterSchema] +] + + class OverrideDeleteSchema(typing.TypedDict): """The schema for the response of the Overrides.delete method.""" From 60af1e869e1374b38dd67b5da61faa8982e3f902 Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Wed, 18 Jun 2025 10:28:22 +0300 Subject: [PATCH 5/6] chore: bump ver --- src/typesense/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/typesense/__init__.py b/src/typesense/__init__.py index 5f7f548..5fc48c1 100644 --- a/src/typesense/__init__.py +++ b/src/typesense/__init__.py @@ -1,4 +1,4 @@ from .client import Client # NOQA -__version__ = "1.2.0" +__version__ = "1.2.1" From 8853e3f352a67c730bde4fefea23c2a3e31e1122 Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Wed, 18 Jun 2025 14:29:19 +0300 Subject: [PATCH 6/6] fix(types): fix override generic type parameter for retrieve schema --- src/typesense/types/override.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/typesense/types/override.py b/src/typesense/types/override.py index 9752613..bd80f43 100644 --- a/src/typesense/types/override.py +++ b/src/typesense/types/override.py @@ -113,4 +113,4 @@ class OverrideDeleteSchema(typing.TypedDict): class OverrideRetrieveSchema(typing.TypedDict): """The schema for the response of the Overrides.retrieve method.""" - overrides: typing.List[OverrideSchema] + overrides: typing.List[OverrideSchema[typing.Union[OverrideQueryRuleSchema, OverrideFilterSchema]]]