peak-sdk 1.17.0__py3-none-any.whl → 1.18.0__py3-none-any.whl

peak/_version.py

@@ -18,4 +18,4 @@
 # # You should have received a copy of the APACHE LICENSE, VERSION 2.0
 # # along with this program. If not, see <https://apache.org/licenses/LICENSE-2.0>
 #
-__version__: str = "1.17.0"
+__version__: str = "1.18.0"

peak/cli/cli.py

@@ -26,7 +26,7 @@ import typer
 from peak.cli import args, helpers
 from peak.cli.metrics import metrics
 from peak.cli.press import apps, blocks, deployments, specs
-from peak.cli.resources import alerts, artifacts, images, services, tenants, users, webapps, workflows
+from peak.cli.resources import alerts, artifacts, cache, images, services, tenants, users, webapps, workflows
 from peak.constants import Sources
 from peak.output import Writer
 
@@ -38,6 +38,7 @@ typer_app.add_typer(images.app, name="images")
 typer_app.add_typer(metrics.app, name="metrics")
 typer_app.add_typer(alerts.app, name="alerts")
 typer_app.add_typer(artifacts.app, name="artifacts")
+typer_app.add_typer(cache.app, name="cache")
 typer_app.add_typer(workflows.app, name="workflows")
 typer_app.add_typer(webapps.app, name="webapps")
 typer_app.add_typer(services.app, name="services")

peak/cli/helpers.py

@@ -251,6 +251,7 @@ def get_client(command: str) -> base_client.BaseClient:
         "specs": press.specs,
         "deployments": press.deployments,
         "artifacts": resources.artifacts,
+        "cache": resources.cache,
         "images": resources.images,
         "workflows": resources.workflows,
         "services": resources.services,

peak/cli/resources/cache.py

@@ -0,0 +1,452 @@
+#
+# # Copyright © 2025 Peak AI Limited. or its affiliates. All Rights Reserved.
+# #
+# # Licensed under the Apache License, Version 2.0 (the "License"). You
+# # may not use this file except in compliance with the License. A copy of
+# # the License is located at:
+# #
+# # https://github.com/PeakBI/peak-sdk/blob/main/LICENSE
+# #
+# # or in the "license" file accompanying this file. This file 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.
+# #
+# # This file is part of the peak-sdk.
+# # see (https://github.com/PeakBI/peak-sdk)
+# #
+# # You should have received a copy of the APACHE LICENSE, VERSION 2.0
+# # along with this program. If not, see <https://apache.org/licenses/LICENSE-2.0>
+#
+"""Peak Cache commands."""
+import json
+from typing import Any, Dict, Optional
+
+import typer
+from peak.cli.args import OUTPUT_TYPES, PAGING
+from peak.constants import OutputTypes, OutputTypesNoTable
+from peak.output import Writer
+from peak.resources.cache import CacheClient
+
+app = typer.Typer(
+    help="Cache operations for storing and retrieving data.",
+    short_help="Manage Cache Operations.",
+)
+
+_KEY = typer.Option(..., help="The cache key to operate on.")
+_VALUE = typer.Option(..., help="The value to store in the cache.")
+_TTL = typer.Option(None, help="Time to live in seconds for the cache entry.")
+_DEFAULT = typer.Option(None, help="Default value to return if key doesn't exist.")
+_KEYS = typer.Option(..., help="Comma-separated list of keys to operate on.")
+_MAPPING = typer.Option(..., help="JSON mapping of key-value pairs to store.")
+_PATTERN = typer.Option(..., help="Pattern to match keys for deletion.")
+_DEBUG = typer.Option(False, help="Enable debug logging.")
+_PREFIX = typer.Option(None, help="Additional prefix for cache keys.")
+
+
+def _parse_json_mapping(mapping: str) -> Dict[str, Any]:
+    """Parse and validate JSON mapping for mset command.
+
+    Args:
+        mapping: JSON string to parse
+
+    Returns:
+        Parsed dictionary
+
+    Raises:
+        typer.BadParameter: If mapping is invalid
+        TypeError: If mapping is not a JSON object
+    """
+    parsed_mapping = json.loads(mapping)
+    if not isinstance(parsed_mapping, dict):
+        msg = "Mapping must be a JSON object"
+        raise TypeError(msg)
+    return parsed_mapping
+
+
+@app.command("set", short_help="Store a value in the cache.")
+def set_value(
+    ctx: typer.Context,
+    key: str = _KEY,
+    value: str = _VALUE,
+    ttl: Optional[int] = _TTL,
+    _debug: bool = _DEBUG,
+    prefix: Optional[str] = _PREFIX,
+    _paging: Optional[bool] = PAGING,
+    _output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,
+) -> None:
+    """Store a value in the cache with an optional TTL.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak cache set --key "user:123" --value "John Doe"
+    peak cache set --key "config" --value '{"timeout": 30}' --ttl 3600
+    ```
+
+    \b
+    🆗 ***Response:***
+    True if the value was stored successfully, False otherwise.
+    """
+    client: CacheClient = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    if prefix:
+        client.set_additional_prefix(prefix)
+
+    try:
+        parsed_value = json.loads(value)
+    except json.JSONDecodeError:
+        parsed_value = value
+
+    with writer.pager():
+        result = client.set(key, parsed_value, ttl=ttl)
+        writer.write(result, output_type=OutputTypes.json)
+
+
+@app.command(short_help="Retrieve a value from the cache.")
+def get(
+    ctx: typer.Context,
+    key: str = _KEY,
+    default: Optional[str] = _DEFAULT,
+    _debug: bool = _DEBUG,
+    prefix: Optional[str] = _PREFIX,
+    _paging: Optional[bool] = PAGING,
+    _output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,
+) -> None:
+    """Retrieve a value from the cache.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak cache get --key "user:123"
+    peak cache get --key "missing" --default "not found"
+    ```
+
+    \b
+    🆗 ***Response:***
+    The cached value or the default value if the key doesn't exist.
+    """
+    client: CacheClient = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    if prefix:
+        client.set_additional_prefix(prefix)
+
+    parsed_default = None
+    if default is not None:
+        try:
+            parsed_default = json.loads(default)
+        except json.JSONDecodeError:
+            parsed_default = default
+
+    with writer.pager():
+        result = client.get(key, default=parsed_default)
+        writer.write(result, output_type=OutputTypes.json)
+
+
+@app.command(short_help="Retrieve multiple values from the cache.")
+def mget(
+    ctx: typer.Context,
+    keys: str = _KEYS,
+    _debug: bool = _DEBUG,
+    prefix: Optional[str] = _PREFIX,
+    _paging: Optional[bool] = PAGING,
+    _output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,
+) -> None:
+    """Retrieve multiple values from the cache.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak cache mget --keys "user:123,user:456,config"
+    peak cache mget --keys "session:abc,session:def"
+    ```
+
+    \b
+    🆗 ***Response:***
+    List of values corresponding to the keys (null for non-existent keys).
+    """
+    client: CacheClient = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    if prefix:
+        client.set_additional_prefix(prefix)
+
+    key_list = [key.strip() for key in keys.split(",")]
+
+    with writer.pager():
+        result = client.mget(*key_list)
+        writer.write(result, output_type=OutputTypes.json)
+
+
+@app.command(short_help="Store multiple key-value pairs in the cache.")
+def mset(
+    ctx: typer.Context,
+    mapping: str = _MAPPING,
+    ttl: Optional[int] = _TTL,
+    _debug: bool = _DEBUG,
+    prefix: Optional[str] = _PREFIX,
+    _paging: Optional[bool] = PAGING,
+    _output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,
+) -> None:
+    """Store multiple key-value pairs in the cache.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak cache mset --mapping '{"user:123": "John", "user:456": "Jane"}'
+    peak cache mset --mapping '{"config:timeout": 30, "config:retries": 3}' --ttl 3600
+    ```
+
+    \b
+    🆗 ***Response:***
+    True if all values were stored successfully, False otherwise.
+    """
+    client: CacheClient = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    if prefix:
+        client.set_additional_prefix(prefix)
+
+    try:
+        parsed_mapping = _parse_json_mapping(mapping)
+    except (json.JSONDecodeError, ValueError, TypeError) as e:
+        msg = f"Invalid JSON mapping: {e}"
+        raise typer.BadParameter(msg) from e
+
+    with writer.pager():
+        result = client.mset(parsed_mapping, ttl=ttl)
+        writer.write(result, output_type=OutputTypes.json)
+
+
+@app.command(short_help="Delete one or more keys from the cache.")
+def delete(
+    ctx: typer.Context,
+    keys: str = _KEYS,
+    _debug: bool = _DEBUG,
+    prefix: Optional[str] = _PREFIX,
+    _paging: Optional[bool] = PAGING,
+    _output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,
+) -> None:
+    """Delete one or more keys from the cache.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak cache delete --keys "user:123"
+    peak cache delete --keys "user:123,user:456,config"
+    ```
+
+    \b
+    🆗 ***Response:***
+    Number of keys that were deleted.
+    """
+    client: CacheClient = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    if prefix:
+        client.set_additional_prefix(prefix)
+
+    key_list = [key.strip() for key in keys.split(",")]
+
+    with writer.pager():
+        result = client.delete(*key_list)
+        writer.write(result, output_type=OutputTypes.json)
+
+
+@app.command(short_help="Check if one or more keys exist in the cache.")
+def exists(
+    ctx: typer.Context,
+    keys: str = _KEYS,
+    _debug: bool = _DEBUG,
+    prefix: Optional[str] = _PREFIX,
+    _paging: Optional[bool] = PAGING,
+    _output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,
+) -> None:
+    """Check if one or more keys exist in the cache.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak cache exists --keys "user:123"
+    peak cache exists --keys "user:123,user:456"
+    ```
+
+    \b
+    🆗 ***Response:***
+    Number of keys that exist in the cache.
+    """
+    client: CacheClient = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    if prefix:
+        client.set_additional_prefix(prefix)
+
+    key_list = [key.strip() for key in keys.split(",")]
+
+    with writer.pager():
+        result = client.exists(*key_list)
+        writer.write(result, output_type=OutputTypes.json)
+
+
+@app.command(short_help="Set expiration time for a key.")
+def expire(
+    ctx: typer.Context,
+    key: str = _KEY,
+    ttl: int = typer.Option(..., help="Time to live in seconds."),
+    _debug: bool = _DEBUG,
+    prefix: Optional[str] = _PREFIX,
+    _paging: Optional[bool] = PAGING,
+    _output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,
+) -> None:
+    """Set expiration time for a key.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak cache expire --key "user:123" --ttl 3600
+    peak cache expire --key "session:abc" --ttl 1800
+    ```
+
+    \b
+    🆗 ***Response:***
+    True if the expiration was set, False if the key doesn't exist.
+    """
+    client: CacheClient = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    if prefix:
+        client.set_additional_prefix(prefix)
+
+    with writer.pager():
+        result = client.expire(key, ttl)
+        writer.write(result, output_type=OutputTypes.json)
+
+
+@app.command(short_help="Get the remaining time to live for a key.")
+def ttl(
+    ctx: typer.Context,
+    key: str = _KEY,
+    _debug: bool = _DEBUG,
+    prefix: Optional[str] = _PREFIX,
+    _paging: Optional[bool] = PAGING,
+    _output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,
+) -> None:
+    """Get the remaining time to live for a key.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak cache ttl --key "user:123"
+    peak cache ttl --key "session:abc"
+    ```
+
+    \b
+    🆗 ***Response:***
+    Remaining TTL in seconds (-1 if no expiration, -2 if key doesn't exist).
+    """
+    client: CacheClient = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    if prefix:
+        client.set_additional_prefix(prefix)
+
+    with writer.pager():
+        result = client.ttl(key)
+        writer.write(result, output_type=OutputTypes.json)
+
+
+@app.command(short_help="Test cache connection.")
+def ping(
+    ctx: typer.Context,
+    _debug: bool = _DEBUG,
+    prefix: Optional[str] = _PREFIX,
+    _paging: Optional[bool] = PAGING,
+    _output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,
+) -> None:
+    """Test cache connection.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak cache ping
+    ```
+
+    \b
+    🆗 ***Response:***
+    True if the connection is successful, False otherwise.
+    """
+    client: CacheClient = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    if prefix:
+        client.set_additional_prefix(prefix)
+
+    with writer.pager():
+        result = client.ping()
+        writer.write(result, output_type=OutputTypes.json)
+
+
+@app.command(short_help="Delete all keys matching a pattern.")
+def flush_pattern(
+    ctx: typer.Context,
+    pattern: str = _PATTERN,
+    _debug: bool = _DEBUG,
+    prefix: Optional[str] = _PREFIX,
+    _paging: Optional[bool] = PAGING,
+    _output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,
+) -> None:
+    """Delete all keys matching a pattern within the tenant namespace.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak cache flush-pattern --pattern "user:*"
+    peak cache flush-pattern --pattern "session:*"
+    ```
+
+    \b
+    🆗 ***Response:***
+    Number of keys that were deleted.
+    """
+    client: CacheClient = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    if prefix:
+        client.set_additional_prefix(prefix)
+
+    with writer.pager():
+        result = client.flush_by_pattern(pattern)
+        writer.write(result, output_type=OutputTypes.json)
+
+
+@app.command(short_help="Delete all keys for the current tenant.")
+def flush_tenant(
+    ctx: typer.Context,
+    _debug: bool = _DEBUG,
+    prefix: Optional[str] = _PREFIX,
+    _paging: Optional[bool] = PAGING,
+    _output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,
+) -> None:
+    """Delete all keys for the current tenant.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak cache flush-tenant
+    ```
+
+    \b
+    🆗 ***Response:***
+    Number of keys that were deleted.
+    """
+    client: CacheClient = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    if prefix:
+        client.set_additional_prefix(prefix)
+
+    with writer.pager():
+        result = client.flush_tenant()
+        writer.write(result, output_type=OutputTypes.json)

peak/resources/__init__.py

@@ -24,11 +24,12 @@ from __future__ import annotations
 
 from typing import List
 
-from peak.resources import alerts, artifacts, images, services, tenants, users, webapps, workflows
+from peak.resources import alerts, artifacts, cache, images, services, tenants, users, webapps, workflows
 
 __all__: List[str] = [
     "alerts",
     "artifacts",
+    "cache",
     "images",
     "services",
     "tenants",

peak/resources/cache.py

@@ -0,0 +1,650 @@
+#
+# # Copyright © 2025 Peak AI Limited. or its affiliates. All Rights Reserved.
+# #
+# # Licensed under the Apache License, Version 2.0 (the "License"). You
+# # may not use this file except in compliance with the License. A copy of
+# # the License is located at:
+# #
+# # https://github.com/PeakBI/peak-sdk/blob/main/LICENSE
+# #
+# # or in the "license" file accompanying this file. This file 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.
+# #
+# # This file is part of the peak-sdk.
+# # see (https://github.com/PeakBI/peak-sdk)
+# #
+# # You should have received a copy of the APACHE LICENSE, VERSION 2.0
+# # along with this program. If not, see <https://apache.org/licenses/LICENSE-2.0>
+#
+"""Peak Cache Client.
+
+Provides caching functionality with tenant-based key prefixing.
+Supports cache operations with JSON serialization and connection management.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, List, Optional, cast
+from urllib.parse import quote_plus, unquote_plus, urlparse
+
+import valkey
+from valkey.exceptions import ConnectionError, TimeoutError, ValkeyError
+
+from peak.base_client import BaseClient
+from peak.constants import ContentType, HttpMethods
+from peak.session import Session
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_VALKEY_PORT = 6379
+SECURE_VALKEY_PORT = 6380
+
+
+class CacheError(Exception):
+    """Base exception for cache operations."""
+
+
+class CacheConnectionError(CacheError):
+    """Exception for cache connection issues."""
+
+
+def _raise_connection_error(message: str) -> None:
+    """Raise a CacheConnectionError with the given message."""
+    raise CacheConnectionError(message)
+
+
+def _raise_cache_error(message: str) -> None:
+    """Raise a CacheError with the given message."""
+    raise CacheError(message)
+
+
+class CacheClient(BaseClient):
+    """Peak Cache Client for caching operations.
+
+    Provides auto key prefixing based on tenant names to ensure
+    proper isolation and access control patterns.
+
+    Inherits from BaseClient to use the default session pattern.
+    """
+
+    def __init__(
+        self,
+        session: Optional[Session] = None,
+        *,
+        debug_logs: bool = True,
+        additional_prefix: Optional[str] = None,
+        connection_config: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize cache client.
+
+        Args:
+            session: Peak session for authentication (optional)
+            debug_logs: Enable or disable debug logging (default: True)
+            additional_prefix: Additional prefix to add after tenant name (optional)
+            connection_config: Custom connection configuration overrides (optional)
+                Available options:
+                - decode_responses: bool (default: True)
+                - socket_timeout: float (default: 5.0)
+                - socket_connect_timeout: float (default: 5.0)
+                - retry_on_timeout: bool (default: True)
+                - health_check_interval: int (default: 60)
+                - max_connections: int (default: None)
+                - retry_on_error: list (default: None)
+                - socket_keepalive: bool (default: None)
+                - socket_keepalive_options: dict (default: None)
+        """
+        super().__init__(session)
+        self._client: Optional[valkey.Valkey] = None
+        self._connection_config: Optional[Dict[str, Any]] = None
+        self._tenant_name: Optional[str] = None
+        self._debug_logs = debug_logs
+        self._additional_prefix = additional_prefix
+        self._custom_connection_config = connection_config or {}
+
+    def _debug_log(self, message: str) -> None:
+        """Log debug message if debug logging is enabled."""
+        if self._debug_logs:
+            logger.debug(message)
+
+    def _get_connection_config(self) -> Dict[str, Any]:
+        """Get cache connection configuration from credentials endpoint."""
+        if self._connection_config is None:
+            try:
+                self._debug_log("Getting cache credentials...")
+                response = self.session.create_request(
+                    endpoint="connections/api/v1/connections/valkey-credentials",
+                    method=HttpMethods.GET,
+                    content_type=ContentType.APPLICATION_JSON,
+                    subdomain="service",
+                )
+
+                self._tenant_name = response.get("tenant")
+                if not self._tenant_name:
+                    _raise_connection_error("Tenant information not found in cache credentials response")
+
+                engine = response.get("engine", "valkey")
+
+                url = response.get("url")
+                if not url:
+                    host = response.get("host")
+                    port = response.get("port", DEFAULT_VALKEY_PORT)
+                    username = response.get("userId")
+                    password = response.get("password")
+
+                    if not all([host, username, password]):
+                        _raise_connection_error("Missing required cache connection credentials")
+
+                    encoded_username = quote_plus(username)
+                    encoded_password = quote_plus(password)
+                    use_ssl = port == SECURE_VALKEY_PORT or engine == "valkey"
+                    scheme = "rediss" if use_ssl else "redis"
+                    url = f"{scheme}://{encoded_username}:{encoded_password}@{host}:{port}"
+
+                parsed = urlparse(url)
+
+                decoded_username = unquote_plus(parsed.username) if parsed.username else None
+                decoded_password = unquote_plus(parsed.password) if parsed.password else None
+
+                if engine == "valkey":
+                    decoded_username = self._tenant_name
+
+                self._validate_connection_config(
+                    {
+                        "host": parsed.hostname,
+                        "port": parsed.port,
+                        "username": decoded_username,
+                        "password": decoded_password,
+                    },
+                )
+
+                use_ssl = parsed.scheme == "rediss"
+
+                config = {
+                    "host": parsed.hostname,
+                    "port": parsed.port or DEFAULT_VALKEY_PORT,
+                    "password": decoded_password,
+                    "username": decoded_username,
+                    "ssl": use_ssl,
+                    "decode_responses": True,
+                    "socket_timeout": 5.0,
+                    "socket_connect_timeout": 5.0,
+                    "retry_on_timeout": True,
+                    "health_check_interval": 60,
+                }
+
+                # Merge custom configuration (only allow safe overrides)
+                safe_overrides = {
+                    "decode_responses",
+                    "socket_timeout",
+                    "socket_connect_timeout",
+                    "retry_on_timeout",
+                    "health_check_interval",
+                    "max_connections",
+                    "retry_on_error",
+                    "socket_keepalive",
+                    "socket_keepalive_options",
+                }
+
+                for key, value in self._custom_connection_config.items():
+                    if key in safe_overrides:
+                        config[key] = value
+                        self._debug_log(f"Cache config override: {key} = {value}")
+                    else:
+                        logger.warning("Ignoring unsafe connection config override: %s", key)
+
+                self._connection_config = config
+
+                logger.info("Cache configured for tenant: %s", self._tenant_name)
+
+            except Exception as e:
+                logger.exception("Failed to get cache credentials")
+                msg = f"Failed to get cache credentials: {e}"
+                raise CacheConnectionError(msg) from e
+
+        return self._connection_config
+
+    def _validate_connection_config(self, config: Dict[str, Any]) -> None:
+        """Validate connection configuration."""
+        required_fields = ["host", "port", "password", "username"]
+        missing = [field for field in required_fields if not config.get(field)]
+        if missing:
+            _raise_connection_error(f"Missing required connection fields: {missing}")
+
+    def _get_client(self) -> valkey.Valkey:
+        """Get or create cache client."""
+        if self._client is None:
+            try:
+                config = self._get_connection_config()
+                self._client = valkey.Valkey(**config)
+                self._debug_log("Cache client created successfully")
+            except Exception as e:
+                logger.exception("Failed to create cache client")
+                msg = f"Failed to create cache client: {e}"
+                raise CacheConnectionError(msg) from e
+        return self._client
+
+    def _prefix_key(self, key: str) -> str:
+        """Add tenant prefix to key."""
+        if not self._tenant_name:
+            self._get_connection_config()
+        prefix = f"{self._tenant_name}:"
+        if self._additional_prefix:
+            prefix += f"{self._additional_prefix}:"
+        return f"{prefix}{key}"
+
+    def _prefix_keys(self, keys: List[str]) -> List[str]:
+        """Add tenant prefix to multiple keys."""
+        return [self._prefix_key(key) for key in keys]
+
+    def set(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        """Set a key-value pair in the cache.
+
+        Args:
+            key: The key to set
+            value: The value to set (will be JSON serialized if not string)
+            ttl: Time to live in seconds (optional)
+
+        Returns:
+            bool: True if successful, False otherwise
+
+        Raises:
+            CacheError: If the operation fails
+        """
+        try:
+            client = self._get_client()
+            prefixed_key = self._prefix_key(key)
+
+            serialized_value = value if isinstance(value, str) else json.dumps(value)
+
+            result = client.set(prefixed_key, serialized_value, ex=ttl)
+            self._debug_log(f"Set key: {key} (prefixed: {prefixed_key})")
+            return bool(result)
+
+        except (ConnectionError, TimeoutError, ValkeyError) as e:
+            logger.exception("Cache set operation failed for key: %s", key)
+            msg = f"Failed to set cache key: {e}"
+            raise CacheError(msg) from e
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value from the cache.
+
+        Args:
+            key: The key to get
+            default: Default value if key doesn't exist
+
+        Returns:
+            Any: The value (JSON deserialized if applicable) or default
+
+        Raises:
+            CacheError: If the operation fails
+        """
+        try:
+            client = self._get_client()
+            prefixed_key = self._prefix_key(key)
+
+            value = client.get(prefixed_key)
+            if value is None:
+                self._debug_log(f"Key not found: {key}")
+                return default
+
+            if isinstance(value, str):
+                value_str = value
+            else:
+                value_str = value.decode("utf-8") if isinstance(value, bytes) else str(value)
+
+            if value_str.startswith(("{", "[")):
+                try:
+                    result = json.loads(value_str)
+                except json.JSONDecodeError:
+                    pass
+                else:
+                    self._debug_log(f"Got key: {key} (JSON deserialized)")
+                    return result
+
+        except (ConnectionError, TimeoutError, ValkeyError) as e:
+            logger.exception("Cache get operation failed for key: %s", key)
+            msg = f"Failed to get cache key: {e}"
+            raise CacheError(msg) from e
+        else:
+            self._debug_log(f"Got key: {key} (as string)")
+            return value_str
+
+    def delete(self, *keys: str) -> int:
+        """Delete one or more keys from the cache.
+
+        Args:
+            keys: Keys to delete
+
+        Returns:
+            int: Number of keys deleted
+
+        Raises:
+            CacheError: If the operation fails
+        """
+        if not keys:
+            return 0
+
+        try:
+            client = self._get_client()
+            prefixed_keys = self._prefix_keys(list(keys))
+
+            result = client.delete(*prefixed_keys)
+            self._debug_log(f"Deleted {result} keys: {list(keys)}")
+            return int(cast(int, result))
+
+        except (ConnectionError, TimeoutError, ValkeyError) as e:
+            logger.exception("Cache delete operation failed for keys: %s", keys)
+            msg = f"Failed to delete cache keys: {e}"
+            raise CacheError(msg) from e
+
+    def exists(self, *keys: str) -> int:
+        """Check if one or more keys exist in the cache.
+
+        Args:
+            keys: Keys to check
+
+        Returns:
+            int: Number of keys that exist
+
+        Raises:
+            CacheError: If the operation fails
+        """
+        if not keys:
+            return 0
+
+        try:
+            client = self._get_client()
+            prefixed_keys = self._prefix_keys(list(keys))
+
+            result = client.exists(*prefixed_keys)
+            self._debug_log(f"Checked existence of {len(keys)} keys, {result} exist")
+            return int(cast(int, result))
+
+        except (ConnectionError, TimeoutError, ValkeyError) as e:
+            logger.exception("Cache exists operation failed for keys: %s", keys)
+            msg = f"Failed to check cache key existence: {e}"
+            raise CacheError(msg) from e
+
+    def expire(self, key: str, ttl: int) -> bool:
+        """Set expiration time for a key.
+
+        Args:
+            key: The key to set expiration for
+            ttl: Time to live in seconds
+
+        Returns:
+            bool: True if successful, False if key doesn't exist
+
+        Raises:
+            CacheError: If the operation fails
+        """
+        try:
+            client = self._get_client()
+            prefixed_key = self._prefix_key(key)
+
+            result = client.expire(prefixed_key, ttl)
+            self._debug_log(f"Set expiration for key: {key} (TTL: {ttl}s)")
+            return bool(result)
+
+        except (ConnectionError, TimeoutError, ValkeyError) as e:
+            logger.exception("Cache expire operation failed for key: %s", key)
+            msg = f"Failed to set cache key expiration: {e}"
+            raise CacheError(msg) from e
+
+    def ttl(self, key: str) -> int:
+        """Get the time to live for a key.
+
+        Args:
+            key: The key to check
+
+        Returns:
+            int: TTL in seconds (-1 if no expiration, -2 if key doesn't exist)
+
+        Raises:
+            CacheError: If the operation fails
+        """
+        try:
+            client = self._get_client()
+            prefixed_key = self._prefix_key(key)
+
+            result = client.ttl(prefixed_key)
+            self._debug_log(f"Got TTL for key: {key} (TTL: {result}s)")
+            return int(cast(int, result))
+
+        except (ConnectionError, TimeoutError, ValkeyError) as e:
+            logger.exception("Cache TTL operation failed for key: %s", key)
+            msg = f"Failed to get cache key TTL: {e}"
+            raise CacheError(msg) from e
+
+    def mget(self, *keys: str) -> List[Any]:
+        """Get multiple values from the cache.
+
+        Args:
+            keys: Keys to get
+
+        Returns:
+            List[Any]: List of values (None for missing keys)
+
+        Raises:
+            CacheError: If the operation fails
+        """
+        if not keys:
+            return []
+
+        try:
+            client = self._get_client()
+            prefixed_keys = self._prefix_keys(list(keys))
+
+            values = client.mget(prefixed_keys)
+            results: List[Any] = []
+
+            for value in cast(List[Any], values):
+                if value is None:
+                    results.append(None)
+                    continue
+
+                if isinstance(value, str):
+                    value_str = value
+                else:
+                    value_str = value.decode("utf-8") if isinstance(value, bytes) else str(value)
+
+                if value_str.startswith(("{", "[")):
+                    try:
+                        results.append(json.loads(value_str))
+                    except json.JSONDecodeError:
+                        pass
+                    else:
+                        continue
+
+                results.append(value_str)
+
+        except (ConnectionError, TimeoutError, ValkeyError) as e:
+            logger.exception("Cache mget operation failed for keys: %s", keys)
+            msg = f"Failed to get multiple cache keys: {e}"
+            raise CacheError(msg) from e
+        else:
+            self._debug_log(f"Got {len(keys)} keys via mget")
+            return results
+
+    def mset(self, mapping: Dict[str, Any], ttl: Optional[int] = None) -> bool:
+        """Set multiple key-value pairs in the cache.
+
+        Args:
+            mapping: Dictionary of key-value pairs to set
+            ttl: Time to live in seconds (optional, applies to all keys)
+
+        Returns:
+            bool: True if successful
+
+        Raises:
+            CacheError: If the operation fails
+        """
+        if not mapping:
+            return True
+
+        try:
+            client = self._get_client()
+            prefixed_mapping = {}
+
+            for key, value in mapping.items():
+                prefixed_key = self._prefix_key(key)
+                serialized_value = json.dumps(value) if not isinstance(value, str) else value
+                prefixed_mapping[prefixed_key] = serialized_value
+
+            result = client.mset(prefixed_mapping)
+
+            if ttl is not None:
+                for prefixed_key in prefixed_mapping:
+                    client.expire(prefixed_key, ttl)
+
+        except (ConnectionError, TimeoutError, ValkeyError) as e:
+            logger.exception("Cache mset operation failed")
+            msg = f"Failed to set multiple cache keys: {e}"
+            raise CacheError(msg) from e
+        else:
+            self._debug_log(f"Set {len(mapping)} keys via mset")
+            return bool(result)
+
+    def flush_tenant(self) -> int:
+        """Flush all keys for the current tenant.
+
+        Returns:
+            int: Number of keys deleted
+
+        Raises:
+            CacheError: If the operation fails
+        """
+        try:
+            client = self._get_client()
+            if not self._tenant_name:
+                self._get_connection_config()
+
+            pattern = f"{self._tenant_name}:*"
+            keys = list(client.scan_iter(match=pattern))
+
+            if not keys:
+                self._debug_log("No keys found for tenant flush")
+                return 0
+
+            result = client.delete(*keys)
+            self._debug_log(f"Flushed {result} keys for tenant: {self._tenant_name}")
+            return int(cast(int, result))
+
+        except (ConnectionError, TimeoutError, ValkeyError) as e:
+            logger.exception("Cache flush_tenant operation failed")
+            msg = f"Failed to flush tenant cache: {e}"
+            raise CacheError(msg) from e
+
+    def flush_by_pattern(self, pattern: str) -> int:
+        """Flush keys matching a pattern within the tenant namespace.
+
+        Args:
+            pattern: Pattern to match (will be prefixed with tenant name)
+
+        Returns:
+            int: Number of keys deleted
+
+        Raises:
+            CacheError: If the operation fails
+        """
+        try:
+            client = self._get_client()
+            if not self._tenant_name:
+                self._get_connection_config()
+
+            prefixed_pattern = self._prefix_key(pattern)
+            keys = list(client.scan_iter(match=prefixed_pattern))
+
+            if not keys:
+                self._debug_log(f"No keys found for pattern: {pattern}")
+                return 0
+
+            result = client.delete(*keys)
+            self._debug_log(f"Flushed {result} keys for pattern: {pattern}")
+            return int(cast(int, result))
+
+        except (ConnectionError, TimeoutError, ValkeyError) as e:
+            logger.exception("Cache flush_by_pattern operation failed for pattern: %s", pattern)
+            msg = f"Failed to flush cache by pattern: {e}"
+            raise CacheError(msg) from e
+
+    def set_additional_prefix(self, additional_prefix: Optional[str]) -> None:
+        """Set additional prefix for cache keys.
+
+        Args:
+            additional_prefix: Additional prefix to add after tenant name
+        """
+        self._additional_prefix = additional_prefix
+        self._debug_log(f"Set additional prefix: {additional_prefix}")
+
+    def get_additional_prefix(self) -> Optional[str]:
+        """Get current additional prefix.
+
+        Returns:
+            Optional[str]: Current additional prefix
+        """
+        return self._additional_prefix
+
+    def ping(self) -> bool:
+        """Test the connection to the cache.
+
+        Returns:
+            bool: True if connection is successful
+
+        Raises:
+            CacheError: If the connection fails
+        """
+        try:
+            client = self._get_client()
+            result = client.ping()
+            self._debug_log("Cache ping successful")
+            return bool(result)
+
+        except (ConnectionError, TimeoutError, ValkeyError) as e:
+            logger.exception("Cache ping failed")
+            msg = f"Cache connection test failed: {e}"
+            raise CacheError(msg) from e
+
+    def close(self) -> None:
+        """Close the cache connection."""
+        if self._client is not None:
+            try:
+                self._client.close()  # type: ignore[no-untyped-call]
+                self._debug_log("Cache connection closed")
+            except (ConnectionError, TimeoutError, ValkeyError) as e:
+                logger.debug("Error closing cache connection: %s", e)
+            finally:
+                self._client = None
+
+
+def get_client(
+    session: Optional[Session] = None,
+    *,
+    debug_logs: bool = True,
+    additional_prefix: Optional[str] = None,
+    connection_config: Optional[Dict[str, Any]] = None,
+) -> CacheClient:
+    """Get a cache client instance.
+
+    Args:
+        session: Peak session for authentication (optional)
+        debug_logs: Enable or disable debug logging (default: True)
+        additional_prefix: Additional prefix to add after tenant name (optional)
+        connection_config: Custom connection configuration overrides (optional)
+
+    Returns:
+        CacheClient: Cache client instance
+    """
+    return CacheClient(
+        session=session,
+        debug_logs=debug_logs,
+        additional_prefix=additional_prefix,
+        connection_config=connection_config,
+    )
+
+
+__all__: List[str] = ["CacheClient", "CacheError", "CacheConnectionError", "get_client"]

{peak_sdk-1.17.0.dist-info → peak_sdk-1.18.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: peak-sdk
-Version: 1.17.0
+Version: 1.18.0
 Summary: Python SDK for interacting with the Peak platform
 Home-page: https://docs.peak.ai/sdk/latest/
 License: Apache-2.0
@@ -31,6 +31,7 @@ Requires-Dist: shellingham (<1.5.4)
 Requires-Dist: structlog (>=24.2.0,<25.0.0)
 Requires-Dist: typer (>=0.12.4,<0.13.0)
 Requires-Dist: urllib3 (<2)
+Requires-Dist: valkey (>=6.0.0,<7.0.0)
 Project-URL: Documentation, https://docs.peak.ai/sdk/latest/
 Description-Content-Type: text/markdown
 
@@ -106,7 +107,7 @@ Follow these steps to create a virtual environment using Python's built-in `venv
     This should return a response of the following format
 
     ```bash
-    peak-cli==1.17.0
+    peak-cli==1.18.0
     Python==3.12.3
     System==Darwin(23.6.0)
     ```
@@ -122,7 +123,7 @@ Follow these steps to create a virtual environment using Python's built-in `venv
     This should print the version of the SDK
 
     ```
-    1.17.0
+    1.18.0
     ```
 
 ### Using the SDK and CLI

{peak_sdk-1.17.0.dist-info → peak_sdk-1.18.0.dist-info}/RECORD

@@ -1,13 +1,13 @@
 peak/__init__.py,sha256=UaVwsRIPq0Wuti8j2x4ijGRVYywglfjvZGz6ALBA7Oo,1284
 peak/_metadata.py,sha256=8w0pXN03pDvh1toM-divY6HNVF8znTqGGG2T9Q4hEl4,30672
-peak/_version.py,sha256=Hw1o3JR05IC6kt3op9K3WGBGESgn4GVuhnMLvFnZ7fQ,887
+peak/_version.py,sha256=kl78pleYMJmemmlFtE2DoQAdou8KltNLWLbj6m12g5M,887
 peak/auth.py,sha256=A6nM9VGUdPJpFTFmb1zeeHjhKfBIsAyIMmnF9ajZkgs,904
 peak/base_client.py,sha256=UO25ZViCQfKbBEDEfCdKS-eLXaVzb1aGnYDntBZ77ko,1808
 peak/callbacks.py,sha256=WRVxSpg0Ur3uzG1aqxX4dQ5YV_Dr4GBrwYddppztcdM,3775
 peak/cli/__init_.py,sha256=cpyVZFRLvtiZw6X0TEI6xF7bYdWSQL6YDjDmBHsLzO4,859
 peak/cli/args.py,sha256=6vFvxburNhVZ3MOEhGsbXCb2IwURCf_nqcmnEUvsqzg,6166
-peak/cli/cli.py,sha256=ybm87AO0JNTMiIPpaWZRXHwfV76oHOjhDFDlHPo3KI4,2531
-peak/cli/helpers.py,sha256=Jon5yCgXUbRHJddi0Wj0mny3OIWpfaJxV4zW_jLuoFU,8629
+peak/cli/cli.py,sha256=YOt7IS4azxmNsZdEKs1U6P9RUOU-02nyjxUTJPnzOJI,2583
+peak/cli/helpers.py,sha256=VGHLvASMCjlqJV7HoJHE4ZGUHSHdOTbIroc125O3Mu0,8663
 peak/cli/metrics/__init__.py,sha256=O2Nxt8hTbW7E6IdFR5_cuL8WTiEk2Hf9QFNo29bpwfY,894
 peak/cli/metrics/metrics.py,sha256=E_uVPkE0RTKypeMCw9UdNdl2YWiOW-BgXjvPkiXhbHs,29952
 peak/cli/press/__init__.py,sha256=Uiir3EoPCWk_zoEk-RitATS20RxDLqiW8Iz5jybrDts,898
@@ -23,6 +23,7 @@ peak/cli/resources/__init__.py,sha256=bAXS042xP_5_0f8jpRELYFrSg0xXNN6hjsoFhZ74Al
 peak/cli/resources/alerts/__init__.py,sha256=5Ol0XeSwnbQLycnCFr6XLog7B3nAYY4ohS5hC4Sy71g,1197
 peak/cli/resources/alerts/emails.py,sha256=WrhEwy2uSdu7_ysjliOX3_Hb6b4ptIMYO5CW0djauPI,12435
 peak/cli/resources/artifacts.py,sha256=Ik0NlvpRpQj9J_bU-yd5_ujWmU03ugC5q7Fy8Sx85ac,12619
+peak/cli/resources/cache.py,sha256=joWMEQ0GXnR-im_ofsq3uvB6Jkqt9mc4f4nbFiq_vfE,12844
 peak/cli/resources/images.py,sha256=f4SFC34yBBkbzqw4i72RjuLapvczTUIeZHFPIbLW9Hw,43133
 peak/cli/resources/services.py,sha256=ySgpv-7bUsJ4bhRiMU2zvlC5TX_3M-73zsvV84Ki0bw,25666
 peak/cli/resources/tenants.py,sha256=5SkUoW8O_LGqTYVzWYO9m3HjoXWifcmS66LMf5TFjsQ,4066
@@ -47,9 +48,10 @@ peak/press/blocks.py,sha256=9XLt2iiQBFa3ON9BddVZ1vp-kRNjij2JOfn069SAO-g,97610
 peak/press/deployments.py,sha256=ZUcuUMygIEswGXleZAF8wkjzSXSl21jGERvIXJ__dcw,10969
 peak/press/specs.py,sha256=SiSQcXXlPXQQ38AuUqfUmAW8tkuOXlSjwsWDrhNwSmQ,10915
 peak/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-peak/resources/__init__.py,sha256=kOtOXynboPCK844y65BrDQztjoncCr_f-JBuxNXUh1I,1242
+peak/resources/__init__.py,sha256=gB20p9gb_ImrRpOMzj9H5HjoBjRRfdpLLi1e3Y28x0c,1262
 peak/resources/alerts.py,sha256=1H6n_7lsR5rNI6FUfni8ye7KCPPArcm0fTpQOYLB6lg,12792
 peak/resources/artifacts.py,sha256=gKlt9bzb1xkN7meM2r5p7AcWepgFFgxFyP1tvpq57qE,15648
+peak/resources/cache.py,sha256=TmAwKB5qzsj2y4zopV8XJw0BIGqXA7NlKiRXFUscOZc,22929
 peak/resources/images.py,sha256=dgYOlPhwOjbiBIz0xum3PfCT9RAP4GVGxBvr8ItiJEY,46715
 peak/resources/services.py,sha256=MHV4Mxm0GHf5UpQUrnwFBmC9T5qHMI4j7PuD271gV0I,17176
 peak/resources/tenants.py,sha256=_rNLWQxCJeaT0mA8_fipYRjSeZ9PIlTD1u_5STbcN-c,4380
@@ -123,8 +125,8 @@ peak/tools/logging/log_level.py,sha256=FVe94CEtow3nfHhNr5oQk0gEt2_5mpfaiV-xTfagX
 peak/tools/logging/logger.py,sha256=DHe--A2J7RRb5N-u0Gb3bbEApPyoUD060A1IeNvJ87Y,15986
 peak/tools/logging/utils.py,sha256=XRQ0nw_lmV_iiRel-o83EE84UTjvrzLTt4H7BHlPbLg,3330
 peak/validators.py,sha256=mY17UDGKJ879wY3EApqrGVs3hJvRkPhgwftvmvnKAdI,2715
-peak_sdk-1.17.0.dist-info/LICENSE,sha256=W0jszenKx7YdFA7BDnyg8xDKXzCP8AperJb_PHh9paQ,11340
-peak_sdk-1.17.0.dist-info/METADATA,sha256=WeVvPweqWyYP4k6pLKxjStuc5NLAL9_VyHnKwIwOKqU,7935
-peak_sdk-1.17.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-peak_sdk-1.17.0.dist-info/entry_points.txt,sha256=zHCEjuOTjkfmqivgEZQsPGm4zFA4W3Q_vKCjPr7W6lE,47
-peak_sdk-1.17.0.dist-info/RECORD,,
+peak_sdk-1.18.0.dist-info/LICENSE,sha256=W0jszenKx7YdFA7BDnyg8xDKXzCP8AperJb_PHh9paQ,11340
+peak_sdk-1.18.0.dist-info/METADATA,sha256=FzdrCBlmaWgg7AYCd524m_wJzZMQvJzvz8yoeqhfT8A,7974
+peak_sdk-1.18.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+peak_sdk-1.18.0.dist-info/entry_points.txt,sha256=zHCEjuOTjkfmqivgEZQsPGm4zFA4W3Q_vKCjPr7W6lE,47
+peak_sdk-1.18.0.dist-info/RECORD,,