peak-sdk 1.16.1__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.16.1"
+__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/metrics/metrics.py

@@ -50,6 +50,16 @@ _NAMESPACE = typer.Option(
     None,
     help="The namespace associated with the metrics. If not provided, the default namespace is used.",
 )
+
+_NAMESPACE_DESCRIPTION = typer.Option(
+    None,
+    help="A description of the namespace.",
+)
+
+_NAMESPACE_METADATA = typer.Option(
+    None,
+    help="Key-value metadata associated with the namespace. Provide them in stringified JSON format.",
+)
 _GENERATE_SQL = typer.Option(
     None,
     help="Indicates whether to return the SQL query instead of data. If `true`, the response will include the SQL query used to retrieve the metrics. Default is `false`.",
@@ -70,6 +80,10 @@ _TIME_DIMENSIONS = typer.Option(
     None,
     help="An array of time dimensions to include in the query. Time dimensions allow querying over specific time ranges with optional granularity (e.g., day, month, year). Provide them in stringified JSON format.",
 )
+_SEARCH_TERM = typer.Option(
+    None,
+    help="A search term to filter the metrics. This can be used to search for specific metrics by name.",
+)
 _SEGMENTS = typer.Option(
     None,
     help="An array of segments to include in the query. Segments represent pre-defined filters that can be applied to metrics. Provide them in stringified JSON format.",
@@ -145,6 +159,7 @@ def publish(
     params_file: str = args.TEMPLATE_PARAMS_FILE,
     params: List[str] = args.TEMPLATE_PARAMS,
     namespace: Optional[str] = _PUBLISH_NAMESPACE,
+    namespace_description: Optional[str] = _NAMESPACE_DESCRIPTION,
     artifact_path: Optional[str] = _ARTIFACT_PATH,
     collection_id: Optional[str] = _COLLECTION_ID,
     dry_run: Optional[bool] = DRY_RUN,  # noqa: ARG001
@@ -156,6 +171,7 @@ def publish(
     The metrics can be published either by passing artifact and namespace,
     or by passing collection_id and namespace. If both artifact and collection_id
     are provided, artifact takes priority. If the namespace is not provided, the 'default' namespace is used.
+    Namespace metadata and Namespace description are optional.
 
     \b
     🧩 ***Input file schema(yaml):***<br/>
@@ -164,6 +180,9 @@ def publish(
     ```yaml
       body (map):
         namespace (str): The namespace associated with the metrics.
+        namespaceMetadata (map | required: false): Key-value metadata associated with the namespace.
+        namespaceDescription (str | required: false): A description of the namespace.
+
       artifact (map):
         path (str): Path to the artifact.
     ```
@@ -171,6 +190,9 @@ def publish(
     ```yaml
       body (map):
         namespace (str): The namespace associated with the metrics.
+        namespaceMetadata (map | required: false): Key-value metadata associated with the namespace.
+        namespaceDescription (str | required: false): A description of the namespace.
+
       collectionId (str): The ID of the collection to publish the metrics.
     ```
 
@@ -186,9 +208,10 @@ def publish(
     📝 ***Example usage without yaml:***
     ```bash
     # Publish metrics using artifact and namespace
-    peak metrics publish --artifact-path <path> --namespace <namespace>
+    peak metrics publish --artifact-path <path> --namespace <namespace> --namespace-description "Metrics for pricing"
+
     # Publish metrics using collection id and namespace
-    peak metrics publish --collection-id <collection-id> --namespace <namespace>
+    peak metrics publish --collection-id <collection-id> --namespace <namespace> --namespace-description "Metrics for pricing"
     ```
 
     \b
@@ -208,6 +231,7 @@ def publish(
 
     user_options: Dict[str, Any] = variables_to_dict(
         namespace,
+        namespace_description,
     )
 
     body: Dict[str, Any] = {}
@@ -358,7 +382,9 @@ def list_metrics(
     ctx: typer.Context,
     page_size: Optional[int] = args.PAGE_SIZE,
     page_number: Optional[int] = args.PAGE_NUMBER,
+    publication_id: Optional[str] = _PUBLICATION_ID,
     namespace: Optional[str] = _NAMESPACE,
+    search_term: Optional[str] = _SEARCH_TERM,
     type: Optional[str] = _METRIC_TYPES,  # noqa: A002
     paging: Optional[bool] = PAGING,  # noqa: ARG001
     output_type: Optional[OutputTypes] = OUTPUT_TYPES,  # noqa: ARG001
@@ -368,7 +394,7 @@ def list_metrics(
     \b
     📝 ***Example usage:***<br/>
     ```bash
-    peak metrics list --page-size 25 --page-number 1 --namespace <namespace> --type <type>
+    peak metrics list --page-size 25 --page-number 1 --namespace <namespace> --type <type> --search-term <search_term> --publication-id <publication_id>
     ```
 
     \b
@@ -429,11 +455,12 @@ def list_metrics(
         response = metric_client.list(
             page_size=page_size,
             page_number=page_number,
+            publication_id=publication_id,
             namespace=namespace,
+            search_term=search_term,
             type=type,
             return_iterator=False,
         )
-
         writer.write(response)
 
 
@@ -676,6 +703,11 @@ def list_namespaces(
     {
         "namespaces": [
             {
+                "description": "Default namespace",
+                "metadata": {
+                    "owner": "abc",
+                    "environment": "development"
+                },
                 "name": "default",
                 "models": [
                     {
@@ -705,3 +737,71 @@ def list_namespaces(
             return_iterator=False,
         )
         writer.write(response)
+
+
+@app.command(short_help="Update a namespace.")
+def update_namespace(
+    ctx: typer.Context,
+    file: Annotated[
+        Optional[str],
+        typer.Argument(
+            ...,
+            help="Path to the file that defines the body for this operation, supports both `yaml` file or a `jinja` template.",
+        ),
+    ] = None,
+    params_file: Optional[str] = args.TEMPLATE_PARAMS_FILE,
+    params: Optional[List[str]] = args.TEMPLATE_PARAMS,
+    namespace: Optional[str] = typer.Option(None, help="The name of the namespace to update."),
+    description: Optional[str] = _NAMESPACE_DESCRIPTION,
+    dry_run: Optional[bool] = DRY_RUN,  # noqa: ARG001
+    output_type: Optional[OutputTypesNoTable] = OUTPUT_TYPES,  # noqa: ARG001
+) -> None:
+    """***Update*** a namespace with a new description and metadata.
+
+    \b
+    📝 ***Example usage:***
+    ```bash
+    peak metrics update-namespace update-namespace.yaml --namespace new_namespace --description "Updated description"
+    ```
+
+    \b
+    🆗 ***Response:***
+    ```json
+    {
+        "namespace": "new_namespace",
+        "description": "Updated description",
+        "message": "Updated namespace new_namespace",
+        "metadata": {
+            "key": "value"
+        }
+    }
+    ```
+    """
+    metrics_client: Metric = ctx.obj["client"]
+    writer: Writer = ctx.obj["writer"]
+
+    body: Dict[str, Any] = {}
+    if file:
+        body = helpers.template_handler(file=file, params_file=params_file, params=params)
+
+    cli_options: Dict[str, Any] = variables_to_dict(
+        namespace,
+        description,
+    )
+
+    updated_body = combine_dictionaries(body or {}, cli_options)
+
+    if not updated_body.get("namespace") and not namespace:
+        error_message = "Namespace must be provided either through file or CLI option."
+        raise typer.BadParameter(error_message)
+
+    final_namespace = updated_body.pop("namespace", namespace)
+    metadata = updated_body.get("metadata")
+
+    with writer.pager():
+        response = metrics_client.update_namespace(
+            namespace=final_namespace,
+            description=updated_body.get("description"),
+            metadata=metadata,
+        )
+        writer.write(response)

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)