valkey-glide 2.0.0rc7__cp310-cp310-macosx_11_0_arm64.whl → 2.1.0rc1__cp310-cp310-macosx_11_0_arm64.whl

glide/async_commands/{server_modules/ft.py → ft.py}

@@ -5,24 +5,24 @@ module for `vector search` commands.
 
 from typing import List, Mapping, Optional, cast
 
-from glide.async_commands.server_modules.ft_options.ft_aggregate_options import (
+from glide_shared.commands.server_modules.ft_options.ft_aggregate_options import (
     FtAggregateOptions,
 )
-from glide.async_commands.server_modules.ft_options.ft_constants import (
+from glide_shared.commands.server_modules.ft_options.ft_constants import (
     CommandNames,
     FtCreateKeywords,
 )
-from glide.async_commands.server_modules.ft_options.ft_create_options import (
+from glide_shared.commands.server_modules.ft_options.ft_create_options import (
     Field,
     FtCreateOptions,
 )
-from glide.async_commands.server_modules.ft_options.ft_profile_options import (
+from glide_shared.commands.server_modules.ft_options.ft_profile_options import (
     FtProfileOptions,
 )
-from glide.async_commands.server_modules.ft_options.ft_search_options import (
+from glide_shared.commands.server_modules.ft_options.ft_search_options import (
     FtSearchOptions,
 )
-from glide.constants import (
+from glide_shared.constants import (
     TOK,
     FtAggregateResponse,
     FtInfoResponse,
@@ -30,7 +30,8 @@ from glide.constants import (
     FtSearchResponse,
     TEncodable,
 )
-from glide.glide_client import TGlideClient
+
+from ..glide_client import TGlideClient
 
 
 async def create(

glide/async_commands/{server_modules/glide_json.py → glide_json.py}

@@ -7,7 +7,7 @@ Examples:
     >>> import json
     >>> value = {'a': 1.0, 'b': 2}
     >>> json_str = json.dumps(value) # Convert Python dictionary to JSON string using json.dumps()
-    >>> await json.set(client, "doc", "$", json_str)
+    >>> await glide_json.set(client, "doc", "$", json_str)
         'OK'  # Indicates successful setting of the value at path '$' in the key stored at `doc`.
     >>> json_get = await glide_json.get(client, "doc", "$") # Returns the value at path '$' in the JSON document stored at
                                                             # `doc` as JSON string.
@@ -19,97 +19,20 @@ Examples:
 """
 from typing import List, Optional, Union, cast
 
-from glide.async_commands.core import ConditionalChange
-from glide.constants import TOK, TEncodable, TJsonResponse, TJsonUniversalResponse
-from glide.glide_client import TGlideClient
-
-
-class JsonGetOptions:
-    """
-    Represents options for formatting JSON data, to be used in  the [JSON.GET](https://valkey.io/commands/json.get/) command.
-
-    Args:
-        indent (Optional[str]): Sets an indentation string for nested levels. Defaults to None.
-        newline (Optional[str]): Sets a string that's printed at the end of each line. Defaults to None.
-        space (Optional[str]): Sets a string that's put between a key and a value. Defaults to None.
-    """
-
-    def __init__(
-        self,
-        indent: Optional[str] = None,
-        newline: Optional[str] = None,
-        space: Optional[str] = None,
-    ):
-        self.indent = indent
-        self.new_line = newline
-        self.space = space
-
-    def get_options(self) -> List[str]:
-        args = []
-        if self.indent:
-            args.extend(["INDENT", self.indent])
-        if self.new_line:
-            args.extend(["NEWLINE", self.new_line])
-        if self.space:
-            args.extend(["SPACE", self.space])
-        return args
-
-
-class JsonArrIndexOptions:
-    """
-    Options for the `JSON.ARRINDEX` command.
-
-    Args:
-        start (int): The inclusive start index from which the search begins. Defaults to None.
-        end (Optional[int]): The exclusive end index where the search stops. Defaults to None.
-
-    Note:
-        - If `start` is greater than `end`, the command returns `-1` to indicate that the value was not found.
-        - Indices that exceed the array bounds are automatically adjusted to the nearest valid position.
-    """
-
-    def __init__(self, start: int, end: Optional[int] = None):
-        self.start = start
-        self.end = end
-
-    def to_args(self) -> List[str]:
-        """
-        Get the options as a list of arguments for the JSON.ARRINDEX command.
-
-        Returns:
-            List[str]: A list containing the start and end indices if specified.
-        """
-        args = [str(self.start)]
-        if self.end is not None:
-            args.append(str(self.end))
-        return args
-
-
-class JsonArrPopOptions:
-    """
-    Options for the JSON.ARRPOP command.
-
-    Args:
-        path (TEncodable): The path within the JSON document.
-        index (Optional[int]): The index of the element to pop. If not specified, will pop the last element.
-            Out of boundary indexes are rounded to their respective array boundaries. Defaults to None.
-    """
-
-    def __init__(self, path: TEncodable, index: Optional[int] = None):
-        self.path = path
-        self.index = index
-
-    def to_args(self) -> List[TEncodable]:
-        """
-        Get the options as a list of arguments for the `JSON.ARRPOP` command.
-
-        Returns:
-            List[TEncodable]: A list containing the path and, if specified, the index.
-        """
-        args = [self.path]
-        if self.index is not None:
-            args.append(str(self.index))
-        return args
+from glide_shared.commands.core_options import ConditionalChange
+from glide_shared.commands.server_modules.json_options import (
+    JsonArrIndexOptions,
+    JsonArrPopOptions,
+    JsonGetOptions,
+)
+from glide_shared.constants import (
+    TOK,
+    TEncodable,
+    TJsonResponse,
+    TJsonUniversalResponse,
+)
+
+from ..glide_client import TGlideClient
 
 
 async def set(

glide/async_commands/standalone_commands.py

@@ -4,24 +4,25 @@ from __future__ import annotations
 
 from typing import Dict, List, Mapping, Optional, Union, cast
 
-from glide.async_commands.batch import Batch
-from glide.async_commands.command_args import ObjectType
-from glide.async_commands.core import (
-    CoreCommands,
+from glide.glide import Script
+from glide_shared.commands.batch import Batch
+from glide_shared.commands.batch_options import BatchOptions
+from glide_shared.commands.command_args import ObjectType
+from glide_shared.commands.core_options import (
     FlushMode,
     FunctionRestorePolicy,
     InfoSection,
 )
-from glide.constants import (
+from glide_shared.constants import (
     TOK,
     TEncodable,
     TFunctionListResponse,
     TFunctionStatsFullResponse,
     TResult,
 )
-from glide.protobuf.command_request_pb2 import RequestType
+from glide_shared.protobuf.command_request_pb2 import RequestType
 
-from ..glide import Script
+from .core import CoreCommands
 
 
 class StandaloneCommands(CoreCommands):
@@ -76,7 +77,7 @@ class StandaloneCommands(CoreCommands):
         self,
         batch: Batch,
         raise_on_error: bool,
-        timeout: Optional[int] = None,
+        options: Optional[BatchOptions] = None,
     ) -> Optional[List[TResult]]:
         """
         Executes a batch by processing the queued commands.
@@ -96,10 +97,7 @@ class StandaloneCommands(CoreCommands):
                 When set to ``False``, errors will be included as part of the batch response array, allowing
                 the caller to process both successful and failed commands together. In this case, error details
                 will be provided as instances of ``RequestError``.
-            timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
-                to complete. This duration encompasses sending the request, awaiting a response from the server, and any
-                required reconnections or retries. If the specified timeout is exceeded for the request,
-                a timeout error will be raised. If not explicitly set, the client's default request timeout will be used.
+            options (Optional[BatchOptions]): A ``BatchOptions`` object containing execution options.
 
         Returns:
             Optional[List[TResult]]: An array of results, where each entry corresponds to a command's execution result.
@@ -125,33 +123,38 @@ class StandaloneCommands(CoreCommands):
             # Expected Output: Pipeline Batch Result: [OK, OK, b'value1', b'value2']
 
         Example (Atomic Batch - Transaction with options):
+            >>> from glide import BatchOptions
             >>> transaction = Batch(is_atomic=True)
             >>> transaction.set("key", "1")
             >>> transaction.incr("key")
             >>> transaction.custom_command(["get", "key"])
+            >>> options = BatchOptions(timeout=1000)  # Set a timeout of 1000 milliseconds
             >>> result = await client.exec(
             ...     transaction,
             ...     raise_on_error=False,  # Do not raise an error on failure
-            ...     timeout=1000  # Set a timeout of 1000 milliseconds
+            ...     options=options
             ... )
             >>> print(f"Transaction Result: {result}")
             # Expected Output: Transaction Result: [OK, 2, b'2']
 
         Example (Non-Atomic Batch - Pipeline with options):
+            >>> from glide import BatchOptions
             >>> pipeline = Batch(is_atomic=False)
             >>> pipeline.custom_command(["set", "key1", "value1"])
             >>> pipeline.custom_command(["set", "key2", "value2"])
             >>> pipeline.custom_command(["get", "key1"])
             >>> pipeline.custom_command(["get", "key2"])
+            >>> options = BatchOptions(timeout=1000)  # Set a timeout of 1000 milliseconds
             >>> result = await client.exec(
             ...     pipeline,
             ...     raise_on_error=False,  # Do not raise an error on failure
-            ...     timeout=1000  # Set a timeout of 1000 milliseconds
+            ...     options=options
             ... )
             >>> print(f"Pipeline Result: {result}")
             # Expected Output: Pipeline Result: [OK, OK, b'value1', b'value2']
         """
         commands = batch.commands[:]
+        timeout = options.timeout if options else None
         return await self._execute_batch(
             commands,
             is_atomic=batch.is_atomic,
@@ -868,8 +871,6 @@ class StandaloneCommands(CoreCommands):
             TOK: A simple "OK" response.
 
         Examples:
-            >>> await client.watch("sampleKey")
-                'OK'
             >>> await client.unwatch()
                 'OK'
         """
@@ -1033,7 +1034,7 @@ class StandaloneCommands(CoreCommands):
 
         Examples:
             >>> lua_script = Script("return { KEYS[1], ARGV[1] }")
-            >>> await client.invoke_script(lua_script, keys=["foo"], args=["bar"] );
+            >>> await client.invoke_script(lua_script, keys=["foo"], args=["bar"])
                 [b"foo", b"bar"]
         """
         return await self._execute_script(script.get_hash(), keys, args)

glide/glide.pyi

@@ -2,7 +2,7 @@ from collections.abc import Callable
 from enum import Enum
 from typing import List, Optional, Union
 
-from glide.constants import TResult
+from glide_shared.constants import TResult
 
 DEFAULT_TIMEOUT_IN_MILLISECONDS: int = ...
 MAX_REQUEST_ARGS_LEN: int = ...
@@ -27,6 +27,28 @@ class ClusterScanCursor:
     def get_cursor(self) -> str: ...
     def is_finished(self) -> bool: ...
 
+class OpenTelemetryConfig:
+    def __init__(
+        self,
+        traces: Optional[OpenTelemetryTracesConfig] = None,
+        metrics: Optional[OpenTelemetryMetricsConfig] = None,
+        flush_interval_ms: Optional[int] = None,
+    ) -> None: ...
+    def get_traces(self) -> Optional[OpenTelemetryTracesConfig]: ...
+    def set_traces(self, traces: OpenTelemetryTracesConfig) -> None: ...
+    def get_metrics(self) -> Optional[OpenTelemetryMetricsConfig]: ...
+
+class OpenTelemetryTracesConfig:
+    def __init__(
+        self, endpoint: str, sample_percentage: Optional[int] = None
+    ) -> None: ...
+    def get_endpoint(self) -> str: ...
+    def get_sample_percentage(self) -> Optional[int]: ...
+
+class OpenTelemetryMetricsConfig:
+    def __init__(self, endpoint: str) -> None: ...
+    def get_endpoint(self) -> str: ...
+
 def start_socket_listener_external(init_callback: Callable) -> None: ...
 def value_from_pointer(pointer: int) -> TResult: ...
 def create_leaked_value(message: str) -> int: ...
@@ -34,3 +56,6 @@ def create_leaked_bytes_vec(args_vec: List[bytes]) -> int: ...
 def get_statistics() -> dict: ...
 def py_init(level: Optional[Level], file_name: Optional[str]) -> Level: ...
 def py_log(log_level: Level, log_identifier: str, message: str) -> None: ...
+def create_otel_span(name: str) -> int: ...
+def drop_otel_span(span_ptr: int) -> None: ...
+def init_opentelemetry(config: OpenTelemetryConfig) -> None: ...

glide/glide_client.py

@@ -11,7 +11,6 @@ from typing import (
     Optional,
     Set,
     Tuple,
-    Type,
     Union,
     cast,
 )
@@ -19,38 +18,49 @@ from typing import (
 import anyio
 import sniffio
 from anyio import to_thread
-
-from glide.async_commands.cluster_commands import ClusterCommands
-from glide.async_commands.command_args import ObjectType
-from glide.async_commands.core import CoreCommands
-from glide.async_commands.standalone_commands import StandaloneCommands
-from glide.config import BaseClientConfiguration, ServerCredentials
-from glide.constants import DEFAULT_READ_BYTES_SIZE, OK, TEncodable, TRequest, TResult
-from glide.exceptions import (
-    ClosingError,
-    ConfigurationError,
-    ConnectionError,
-    ExecAbortError,
-    RequestError,
-    TimeoutError,
-)
-from glide.logger import Level as LogLevel
-from glide.logger import Logger as ClientLogger
-from glide.protobuf.command_request_pb2 import Command, CommandRequest, RequestType
-from glide.protobuf.connection_request_pb2 import ConnectionRequest
-from glide.protobuf.response_pb2 import RequestErrorType, Response
-from glide.protobuf_codec import PartialMessageException, ProtobufCodec
-from glide.routes import Route, set_protobuf_route
-
-from .glide import (
+from glide.glide import (
     DEFAULT_TIMEOUT_IN_MILLISECONDS,
     MAX_REQUEST_ARGS_LEN,
     ClusterScanCursor,
     create_leaked_bytes_vec,
+    create_otel_span,
+    drop_otel_span,
     get_statistics,
     start_socket_listener_external,
     value_from_pointer,
 )
+from glide_shared.commands.command_args import ObjectType
+from glide_shared.commands.core_options import PubSubMsg
+from glide_shared.config import BaseClientConfiguration, ServerCredentials
+from glide_shared.constants import (
+    DEFAULT_READ_BYTES_SIZE,
+    OK,
+    TEncodable,
+    TRequest,
+    TResult,
+)
+from glide_shared.exceptions import (
+    ClosingError,
+    ConfigurationError,
+    ConnectionError,
+    get_request_error_class,
+)
+from glide_shared.protobuf.command_request_pb2 import (
+    Command,
+    CommandRequest,
+    RequestType,
+)
+from glide_shared.protobuf.connection_request_pb2 import ConnectionRequest
+from glide_shared.protobuf.response_pb2 import Response
+from glide_shared.protobuf_codec import PartialMessageException, ProtobufCodec
+from glide_shared.routes import Route, set_protobuf_route
+
+from .async_commands.cluster_commands import ClusterCommands
+from .async_commands.core import CoreCommands
+from .async_commands.standalone_commands import StandaloneCommands
+from .logger import Level as LogLevel
+from .logger import Logger as ClientLogger
+from .opentelemetry import OpenTelemetry
 
 if sys.version_info >= (3, 11):
     from typing import Self
@@ -66,20 +76,6 @@ if TYPE_CHECKING:
     TFuture = Union[asyncio.Future[Any], "_CompatFuture"]
 
 
-def get_request_error_class(
-    error_type: Optional[RequestErrorType.ValueType],
-) -> Type[RequestError]:
-    if error_type == RequestErrorType.Disconnect:
-        return ConnectionError
-    if error_type == RequestErrorType.ExecAbort:
-        return ExecAbortError
-    if error_type == RequestErrorType.Timeout:
-        return TimeoutError
-    if error_type == RequestErrorType.Unspecified:
-        return RequestError
-    return RequestError
-
-
 class _CompatFuture:
     """anyio shim for asyncio.Future-like functionality"""
 
@@ -410,6 +406,13 @@ class BaseClient(CoreCommands):
             raise ClosingError(
                 "Unable to execute requests; the client is closed. Please create a new client."
             )
+
+        # Create span if OpenTelemetry is configured and sampling indicates we should trace
+        span = None
+        if OpenTelemetry.should_sample():
+            command_name = RequestType.Name(request_type)
+            span = create_otel_span(command_name)
+
         request = CommandRequest()
         request.callback_idx = self._get_callback_index()
         request.single_command.request_type = request_type
@@ -424,6 +427,11 @@ class BaseClient(CoreCommands):
             request.single_command.args_vec_pointer = create_leaked_bytes_vec(
                 encoded_args
             )
+
+        # Add span pointer to request if span was created
+        if span:
+            request.root_span_ptr = span
+
         set_protobuf_route(request, route)
         return await self._write_request_await_response(request)
 
@@ -441,6 +449,14 @@ class BaseClient(CoreCommands):
             raise ClosingError(
                 "Unable to execute requests; the client is closed. Please create a new client."
             )
+
+        # Create span if OpenTelemetry is configured and sampling indicates we should trace
+        span = None
+
+        if OpenTelemetry.should_sample():
+            # Use "Batch" as span name for batches
+            span = create_otel_span("Batch")
+
         request = CommandRequest()
         request.callback_idx = self._get_callback_index()
         batch_commands = []
@@ -462,6 +478,11 @@ class BaseClient(CoreCommands):
             request.batch.timeout = timeout
         request.batch.retry_server_error = retry_server_error
         request.batch.retry_connection_error = retry_connection_error
+
+        # Add span pointer to request if span was created
+        if span:
+            request.root_span_ptr = span
+
         set_protobuf_route(request, route)
         return await self._write_request_await_response(request)
 
@@ -496,7 +517,7 @@ class BaseClient(CoreCommands):
         set_protobuf_route(request, route)
         return await self._write_request_await_response(request)
 
-    async def get_pubsub_message(self) -> CoreCommands.PubSubMsg:
+    async def get_pubsub_message(self) -> PubSubMsg:
         if self._is_closed:
             raise ClosingError(
                 "Unable to execute requests; the client is closed. Please create a new client."
@@ -523,7 +544,7 @@ class BaseClient(CoreCommands):
         await response_future
         return response_future.result()
 
-    def try_get_pubsub_message(self) -> Optional[CoreCommands.PubSubMsg]:
+    def try_get_pubsub_message(self) -> Optional[PubSubMsg]:
         if self._is_closed:
             raise ClosingError(
                 "Unable to execute requests; the client is closed. Please create a new client."
@@ -540,7 +561,7 @@ class BaseClient(CoreCommands):
             )
 
         # locking might not be required
-        msg: Optional[CoreCommands.PubSubMsg] = None
+        msg: Optional[PubSubMsg] = None
         try:
             self._pubsub_lock.acquire()
             self._complete_pubsub_futures_safe()
@@ -558,7 +579,7 @@ class BaseClient(CoreCommands):
 
     def _notification_to_pubsub_message_safe(
         self, response: Response
-    ) -> Optional[CoreCommands.PubSubMsg]:
+    ) -> Optional[PubSubMsg]:
         pubsub_message = None
         push_notification = cast(
             Dict[str, Any], value_from_pointer(response.resp_pointer)
@@ -577,11 +598,11 @@ class BaseClient(CoreCommands):
         ):
             values: List = push_notification["values"]
             if message_kind == "PMessage":
-                pubsub_message = BaseClient.PubSubMsg(
+                pubsub_message = PubSubMsg(
                     message=values[2], channel=values[1], pattern=values[0]
                 )
             else:
-                pubsub_message = BaseClient.PubSubMsg(
+                pubsub_message = PubSubMsg(
                     message=values[1], channel=values[0], pattern=None
                 )
         elif (
@@ -656,6 +677,10 @@ class BaseClient(CoreCommands):
             else:
                 res_future.set_result(None)
 
+        # Clean up span if it was created
+        if response.HasField("root_span_ptr"):
+            drop_otel_span(response.root_span_ptr)
+
     async def _process_push(self, response: Response) -> None:
         if response.HasField("closing_error") or not response.HasField("resp_pointer"):
             err_msg = (

glide/logger.py

@@ -2,11 +2,12 @@
 
 from __future__ import annotations
 
+import traceback
 from enum import Enum
 from typing import Optional
 
-from .glide import Level as internalLevel
-from .glide import py_init, py_log
+from glide.glide import Level as internalLevel
+from glide.glide import py_init, py_log
 
 
 class Level(Enum):
@@ -20,13 +21,12 @@ class Level(Enum):
 
 class Logger:
     """
-    A singleton class that allows logging which is consistent with logs from the internal rust core.
+    A singleton class that allows logging which is consistent with logs from the internal GLIDE core.
     The logger can be set up in 2 ways -
     1. By calling Logger.init, which configures the logger only if it wasn't previously configured.
     2. By calling Logger.set_logger_config, which replaces the existing configuration, and means that new logs will not be
     saved with the logs that were sent before the call.
-    If set_logger_config wasn't called, the first log attempt will initialize a new logger with default configuration decided
-    by the Rust core.
+    If none of these functions are called, the first log attempt will initialize a new logger with default configuration.
     """
 
     _instance = None
@@ -38,48 +38,60 @@ class Logger:
 
     @classmethod
     def init(cls, level: Optional[Level] = None, file_name: Optional[str] = None):
-        """_summary_
+        """
         Initialize a logger if it wasn't initialized before - this method is meant to be used when there is no intention to
-        replace an existing logger.
-        The logger will filter all logs with a level lower than the given level,
-        If given a fileName argument, will write the logs to files postfixed with fileName. If fileName isn't provided,
+        replace an existing logger. Otherwise, use `set_logger_config` for overriding the existing logger configs.
+        The logger will filter all logs with a level lower than the given level.
+        If given a file_name argument, will write the logs to files postfixed with file_name. If file_name isn't provided,
         the logs will be written to the console.
+
         Args:
             level (Optional[Level]): Set the logger level to one of [ERROR, WARN, INFO, DEBUG, TRACE, OFF].
-            If log level isn't provided, the logger will be configured with default configuration decided by the Rust core.
-            file_name (Optional[str]):  If provided the target of the logs will be the file mentioned.
-            Otherwise, logs will be printed to the console.
-            To turn off logging completely, set the level to Level.OFF.
+                If log level isn't provided, the logger will be configured with default configuration.
+                To turn off logging completely, set the level to Level.OFF.
+            file_name (Optional[str]): If provided the target of the logs will be the file mentioned.
+                Otherwise, logs will be printed to the console.
         """
         if cls._instance is None:
             cls._instance = cls(level, file_name)
 
     @classmethod
-    def log(cls, log_level: Level, log_identifier: str, message: str):
-        """Logs the provided message if the provided log level is lower then the logger level.
+    def log(
+        cls,
+        log_level: Level,
+        log_identifier: str,
+        message: str,
+        err: Optional[Exception] = None,
+    ):
+        """
+        Logs the provided message if the provided log level is lower then the logger level.
 
         Args:
-            log_level (Level): The log level of the provided message
+            log_level (Level): The log level of the provided message.
             log_identifier (str): The log identifier should give the log a context.
             message (str): The message to log.
+            err (Optional[Exception]): The exception or error to log.
         """
         if not cls._instance:
             cls._instance = cls(None)
         if not log_level.value.is_lower(Logger.logger_level):
             return
+        if err:
+            message = f"{message}: {traceback.format_exception(err)}"
         py_log(log_level.value, log_identifier, message)
 
     @classmethod
     def set_logger_config(
         cls, level: Optional[Level] = None, file_name: Optional[str] = None
     ):
-        """Creates a new logger instance and configure it with the provided log level and file name.
+        """
+        Creates a new logger instance and configure it with the provided log level and file name.
 
         Args:
             level (Optional[Level]): Set the logger level to one of [ERROR, WARN, INFO, DEBUG, TRACE, OFF].
-            If log level isn't provided, the logger will be configured with default configuration decided by the Rust core.
-            file_name (Optional[str]):  If provided the target of the logs will be the file mentioned.
-            Otherwise, logs will be printed to the console.
-            To turn off logging completely, set the level to OFF.
+                If log level isn't provided, the logger will be configured with default configuration.
+                To turn off logging completely, set the level to OFF.
+            file_name (Optional[str]): If provided the target of the logs will be the file mentioned.
+                Otherwise, logs will be printed to the console.
         """
         Logger._instance = Logger(level, file_name)