mammoth-cli 2.2.13__tar.gz → 2.2.14__tar.gz

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.13
+Version: 2.2.14
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -17,7 +17,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.9,>=0.8.13
+Requires-Dist: mammoth-io<0.9,>=0.8.14
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.2.13"
+__version__ = "2.2.14"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/mammoth_cli/commands/browse.py

@@ -86,6 +86,26 @@ def _forward_optional(
             kwargs[field] = document[field]
 
 
+#: The id a dataset or a view is known by elsewhere in the CLI; a hit's ``id`` is its tree id.
+_OBJECT_ID_KEYS = {"datasource": "dataset_id", "dataview": "view_id"}
+
+
+def _with_object_ids(data: Any) -> Any:
+    """Name the id a command takes: ``dataset_id`` / ``view_id`` beside the tree ``id``."""
+    rows = data.get("resources") if isinstance(data, dict) else None
+    if not isinstance(rows, list):
+        return data
+    named = [
+        (
+            {**row, key: row.get("object_id")}
+            if isinstance(row, dict) and (key := _OBJECT_ID_KEYS.get(str(row.get("resource_type"))))
+            else row
+        )
+        for row in rows
+    ]
+    return {**data, "resources": named}
+
+
 def browse_folder(invocation: Invocation) -> HandlerResult:
     """Browse resources inside one folder of the active project.
 
@@ -173,7 +193,7 @@ def browse_resources(invocation: Invocation) -> HandlerResult:
     )
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), **kwargs)
-    return data, _meta(invocation, auth.workspace_id, project_id)
+    return _with_object_ids(data), _meta(invocation, auth.workspace_id, project_id)
 
 
 def browse_resource(invocation: Invocation) -> HandlerResult:
@@ -208,7 +228,11 @@ def browse_ancestors(invocation: Invocation) -> HandlerResult:
 
 
 def browse_search(invocation: Invocation) -> HandlerResult:
-    """Search resources across every project of the workspace (resources v2)."""
+    """Search resources across every project of the workspace (resources v2).
+
+    ``resource_type`` ``dataset`` means the route's ``datasource``. Each dataset hit
+    carries ``dataset_id`` and each view hit ``view_id``: pass those, never the tree ``id``.
+    """
     document = invocation.load_input() or {}
     kwargs: dict[str, Any] = {}
     _forward_optional(
@@ -216,7 +240,7 @@ def browse_search(invocation: Invocation) -> HandlerResult:
     )
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), **kwargs)
-    return data, _meta(invocation, auth.workspace_id, None)
+    return _with_object_ids(data), _meta(invocation, auth.workspace_id, None)
 
 
 def browse_resources_bulk(invocation: Invocation) -> HandlerResult:

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/mammoth_cli/commands/dataset.py

@@ -33,6 +33,7 @@ from mammoth_cli.runtime.session import open_service, require_project
 from mammoth_cli.services.listing import (
     DATASET_ROW_FIELDS,
     ambiguity_note,
+    compact_columns,
     dataset_summary,
     fit_budget,
     name_hit,
@@ -202,7 +203,11 @@ _SEARCH_PAGE_SIZE = 100
 
 
 def search_hits(
-    service: Any, resource_type: str, needle: str, project_id: int | None = None
+    service: Any,
+    resource_type: str,
+    needle: str,
+    project_id: int | None = None,
+    fields: str = "minimal",
 ) -> tuple[list[dict[str, Any]], bool]:
     """Resources of ``resource_type`` whose name contains ``needle``, from the search route.
 
@@ -222,11 +227,11 @@ def search_hits(
     for _ in range(_SEARCH_PAGES):
         page = service.call(
             symbol,
-            search=needle,
+            search=needle or None,
             resource_type=resource_type,
             limit=_SEARCH_PAGE_SIZE,
             cursor=cursor,
-            fields="minimal",
+            fields=fields,
             **scope,
         )
         rows += [r for r in page.get("resources", []) if isinstance(r, dict)]
@@ -274,6 +279,61 @@ def named_project(service: Any, project_id: int, visible: list[dict[str, Any]])
     return {"id": project_id, "name": record.get("name")}
 
 
+def _requested_columns(document: dict[str, Any]) -> list[str]:
+    """The ``columns`` input as a list of names (a comma-separated string is split)."""
+    raw = document.get("columns")
+    if raw is None:
+        return []
+    names = raw.split(",") if isinstance(raw, str) else raw
+    if not isinstance(names, list) or not all(isinstance(n, str) for n in names):
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message="'columns' must be a list of column names (or one comma-separated string).",
+            exit_status=EXIT_USAGE,
+        )
+    return [n.strip() for n in names if n.strip()]
+
+
+def _column_names(hit: dict[str, Any]) -> list[str]:
+    """Display names of the columns a full-field search hit carries."""
+    properties = hit.get("object_properties")
+    metadata = properties.get("metadata") if isinstance(properties, dict) else None
+    return [
+        str(c["display_name"])
+        for c in metadata or []
+        if isinstance(c, dict) and c.get("display_name")
+    ]
+
+
+def _find_by_columns(
+    service: Any,
+    needle: str,
+    columns: list[str],
+    visible: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], bool]:
+    """Datasets (named like ``needle``, when given) that have every one of ``columns``."""
+    hits, cut = search_hits(service, "datasource", needle, fields="full")
+    names = {p.get("id"): p.get("name") for p in visible}
+    wanted = [c.lower() for c in columns]
+    matches: list[dict[str, Any]] = []
+    for hit in hits:
+        have = _column_names(hit)
+        if not set(wanted) <= {c.lower() for c in have}:
+            continue
+        matches.append(
+            {
+                "project_id": hit.get("project_id"),
+                "project_name": names.get(hit.get("project_id")),
+                "id": hit.get("object_id"),
+                "name": hit.get("name"),
+                "rows": hit.get("row_count"),
+                "cols": len(have),
+                "columns": compact_columns([(c, None) for c in have], limit=None),
+            }
+        )
+    return matches, cut
+
+
 def dataset_find(invocation: Invocation) -> HandlerResult:
     """Search dataset names for a substring across every visible project.
 
@@ -326,9 +386,11 @@ def dataset_find(invocation: Invocation) -> HandlerResult:
 def dataset_list(invocation: Invocation) -> HandlerResult:
     """List datasets in the active project, newest first, each with what tells them apart.
 
-    Every item carries its size, created/updated time, how its data arrived, and
-    its column names and types (from the list route's stored ``stats``,
-    ``sources`` and ``data_schema``), cut to fit the agent tool output cap.
+    Every item carries its created/updated time and how its data arrived (from the
+    list route's ``sources``), cut to fit the agent tool output cap. The list asks
+    only the cheap fields, so it holds no row counts or column names: ``view list
+    DATASET_ID`` shows a dataset's columns, and ``dataset find --input '{"columns":
+    [...]}'`` finds the dataset that has given columns.
     ``full: true`` returns the raw ``{id, name}`` list instead. ``name`` keeps only datasets
     whose name contains it (case-insensitive) across every page, as short rows without
     column lists; ``limit``/``offset`` then page over the matches.
@@ -347,7 +409,9 @@ def dataset_list(invocation: Invocation) -> HandlerResult:
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), **kwargs)
     if compact:
-        data = _compact_dataset_list(data, kwargs.get("offset", 0), kwargs.get("sort"))
+        data = _compact_dataset_list(
+            data, kwargs.get("offset", 0), kwargs.get("sort"), kwargs.get("limit", 100)
+        )
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
@@ -388,7 +452,7 @@ def _dataset_name_search(
     return page, _meta(invocation, auth.workspace_id, project_id)
 
 
-def _compact_dataset_list(data: Any, offset: int, sort: str | None) -> Any:
+def _compact_dataset_list(data: Any, offset: int, sort: str | None, limit: int) -> Any:
     """Summarise a dataset-list page and fit it to the tool output cap."""
     datasets = data.get("datasets") if isinstance(data, dict) else None
     if not isinstance(datasets, list):
@@ -404,7 +468,8 @@ def _compact_dataset_list(data: Any, offset: int, sort: str | None) -> Any:
             "stored sample_values per view (all_columns: true lists every column)."
         ),
     }
-    if omitted or data.get("next"):
+    # The list route sends no ``next``: a page of ``limit`` rows may have a successor.
+    if omitted or data.get("next") or len(datasets) >= limit:
         result["more"] = True
         result["next_offset"] = int(offset) + len(kept)
     return result

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/mammoth_cli/commands/registry.py

@@ -718,7 +718,7 @@ HANDLERS: dict[str, Handler] = {
     "view.update": view_cmd.view_update,
     "view.data.get": view_cmd.view_data_get,
     "view.data.query": view_cmd.view_data_query,
-    "view.data.aggregate": view_cmd.view_data_aggregate,
+    "view.data.aggregate": view_cmd.view_data_aggregate_rounded,
     "view.data.compare": view_cmd.view_data_compare,
     "view.data.explore": view_cmd.view_data_explore,
     "view.data.profile": view_profile_cmd.view_data_profile,

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/mammoth_cli/commands/schema.py

@@ -306,7 +306,8 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "view.data.explore": (
         "explore trend trends trending over time per day week month quarter year by date "
         "distribution spread histogram top most common frequent values breakdown share "
-        "percentage profile period year quarter month date range coverage figure"
+        "percentage profile period year quarter month date range coverage figure "
+        "cumulative"
     ),
     # "Give the West team their own copy they can change" / "duplicate this
     # dataset as an independent copy" / "clone it without changing the

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/mammoth_cli/commands/view.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 
 import dataclasses
 import inspect
+import shlex
 from datetime import UTC, datetime
 from decimal import Decimal, InvalidOperation
 from typing import Any
@@ -1690,6 +1691,7 @@ def view_data_aggregate(invocation: Invocation) -> HandlerResult:
     TEXT-date) column groups by the named part of the date -- ``Monday``..``Sunday``,
     ``January``..``December``, ``Q1``..``Q4``, the year -- in calendar order: the
     read-only way to answer by-weekday and by-month questions.
+    Figures are rounded for display (2 decimals; 4 below 1).
     Never use ``view transform pivot`` just to read a number -- it mutates the
     view's pipeline.
     """
@@ -1745,6 +1747,15 @@ def view_data_aggregate(invocation: Invocation) -> HandlerResult:
     return data, meta
 
 
+def view_data_aggregate_rounded(invocation: Invocation) -> HandlerResult:
+    """``view data aggregate`` as the user reads it: floats rounded (2 decimals; 4 below 1).
+
+    ``view data compare`` calls :func:`view_data_aggregate` itself, at full precision.
+    """
+    data, meta = view_data_aggregate(invocation)
+    return read_queries.round_result_rows(data), meta
+
+
 def _compare_key_and_value_columns(document: dict[str, Any]) -> tuple[list[str], list[str]]:
     """Return the (key, value) display-column names an aggregate call over
     ``document`` will produce, without making the call -- mirrors the label
@@ -1930,7 +1941,9 @@ def _explore_text_dates(
         condition=condition,
     )
     page = (document.get("offset"), document.get("limit"))
-    rows = read_queries.apply_explore_order(response["data"], document.get("sort"), page)
+    rows = read_queries.apply_explore_order(
+        response["data"], document.get("sort"), page, bool(document.get("cumulative"))
+    )
     return {**response, "data": rows}
 
 
@@ -1953,7 +1966,13 @@ def view_data_explore(invocation: Invocation) -> HandlerResult:
     An optional ``metric`` ``{"column": ..., "function": ...}`` (SUM, COUNT,
     AVG, MIN, MAX, STDDEV or DISTINCT_COUNT) adds a second aggregate per bucket over another column,
     and an optional ``condition`` filters rows first -- same as ``view data
-    aggregate``, which this command wraps for the raw PIVOT shape. Never use
+    aggregate``, which this command wraps for the raw PIVOT shape. A date range
+    is one ``and`` condition (``>=`` a start, ``<=`` an end); one year is
+    ``{"column": ..., "operator": "=", "value": 2017, "component": "year"}``.
+    ``cumulative: true`` adds a running total of the metric (of ``count`` without
+    one) over the buckets in date order, whatever ``sort`` or ``limit`` shows:
+    the answer to "cumulative / running total through X". Figures are rounded for
+    display (2 decimals; 4 below 1). Never use
     ``view transform pivot`` just to explore a column; it mutates the
     pipeline.
     """
@@ -1989,6 +2008,8 @@ def view_data_explore(invocation: Invocation) -> HandlerResult:
         if isinstance(metric, dict):
             resolved_metric = _resolved_aggregate_item(metric, display_to_internal)
             as_map["agg_1"] = resolved_metric["as_name"]
+        if document.get("cumulative"):
+            as_map["cumulative"] = f"{as_map.get('agg_1', 'count')} (running total)"
         if bucket_dates:
             data = _explore_text_dates(reads, document, internal_column, resolved_metric)
         else:
@@ -2003,7 +2024,7 @@ def view_data_explore(invocation: Invocation) -> HandlerResult:
         data = read_queries.with_assumptions(reads, data)
         if not bucket_dates:
             data = read_queries.with_variant_hint(reads, data, column_arg)
-    return data, meta
+    return read_queries.round_result_rows(data), meta
 
 
 def _explore_on_backend(
@@ -2028,7 +2049,9 @@ def _explore_on_backend(
         kwargs[CONDITION_KWARG] = compile_condition(spec).build(
             reads.display_to_internal or None, reads.column_types or None
         )
-    _forward_optional(document, kwargs, ("level", "sequence", "limit", "offset", "sort"))
+    _forward_optional(
+        document, kwargs, ("level", "sequence", "limit", "offset", "sort", "cumulative")
+    )
     return reads.service.call(_symbol(invocation), **kwargs)
 
 
@@ -3474,7 +3497,14 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
                     int(target_ds_id),
                     kwargs.get("column_mapping"),
                 )
-        data = service.call_view(dataview_id, method, dataset_id=dataset_id, **kwargs)
+        try:
+            data = service.call_view(dataview_id, method, dataset_id=dataset_id, **kwargs)
+        except CliError as error:
+            if not (is_dataset_route and error.details.get("export_pending")):
+                raise
+            return _pending_dataset_export(error, dataview_id, result_project_id), _meta(
+                invocation, auth.workspace_id, project_id
+            )
         if is_dataset_route and isinstance(data, int):
             # The SDK returns the bare id of the dataset written to; name it, and
             # say which project it landed in, so the agent's next read is obvious.
@@ -3535,6 +3565,33 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
+def _pending_dataset_export(error: CliError, view_id: int, project_id: int) -> dict[str, Any]:
+    """A dataset export that was accepted but whose dataset id is not known yet.
+
+    The export was submitted and the server is writing it (or has written it); only
+    the lookup of its id ran out of time. That is not a failure, so say what is known
+    and how to read the dataset when it lands, never an error.
+    """
+    name = error.details.get("dataset_name")
+    pending: dict[str, Any] = {
+        "status": "pending",
+        "source_view_id": view_id,
+        "project_id": project_id,
+        "refreshes_on_pipeline_run": True,
+        "note": (
+            "The export was submitted and is still being written, so its dataset id is not "
+            "known yet. Do not export again: that would create a second dataset. Look it up "
+            f"in a moment with the next command (its source reads 'export of view {view_id}')."
+        ),
+    }
+    if name is not None:
+        pending["dataset_name"] = name
+        pending["next"] = f"mammoth dataset find {shlex.quote(str(name))} --project {project_id}"
+    if error.details.get("dataset_id") is not None:
+        pending["dataset_id"] = error.details["dataset_id"]
+    return pending
+
+
 _EXPORTS_LIST_SYMBOL = "mammoth.api.exports.ExportsAPI.list"
 _INTERNAL_DATASET_HANDLER_TYPE = "internal_dataset"
 

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/mammoth_cli/services/positionals.py

@@ -644,8 +644,9 @@ POSITIONAL_OVERRIDES: dict[str, tuple[PositionalSpec, ...]] = {
         PositionalSpec(
             name="name_substring",
             type=str,
-            required=True,
-            help="Case-insensitive substring to match against dataset names.",
+            required=False,
+            help="Case-insensitive substring to match against dataset names; optional "
+            "when --input gives 'columns'.",
             example_value="sales",
         ),
     ),

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/mammoth_cli/services/read_queries.py

@@ -19,13 +19,18 @@ from dataclasses import dataclass, field
 from datetime import date
 from typing import Any
 
-from mammoth.api.dataviews import _add_explore_percentages, _explore_sort_and_limit
+from mammoth.api.dataviews import (
+    _add_explore_cumulative,
+    _add_explore_percentages,
+    _explore_sort_and_limit,
+)
 
 from mammoth_cli.errors.envelope import (
     CODE_INVALID_ARGUMENTS,
     EXIT_USAGE,
     CliError,
 )
+from mammoth_cli.output.normalize import DataRows
 from mammoth_cli.services import data_profile as dp
 from mammoth_cli.services import text_dates
 from mammoth_cli.services.conditions import CONDITION_KWARG, _resolve_operator
@@ -382,10 +387,15 @@ def pivot_with_text_dates(
 
 
 def apply_explore_order(
-    rows: list[dict[str, Any]], sort: str | None, page: tuple[int | None, int | None]
+    rows: list[dict[str, Any]],
+    sort: str | None,
+    page: tuple[int | None, int | None],
+    cumulative: bool = False,
 ) -> list[dict[str, Any]]:
-    """Percentages, order and paging for a bucketed explore, like the SDK's own."""
+    """Percentages, running total, order and paging for a bucketed explore, like the SDK's own."""
     _add_explore_percentages(rows)
+    if cumulative:
+        _add_explore_cumulative(rows)
     return _explore_sort_and_limit(rows, "DATE", sort, page)
 
 
@@ -628,3 +638,32 @@ def with_assumptions(ctx: ReadContext, data: Any) -> Any:
     if not ctx.assumptions or not isinstance(data, dict):
         return data
     return {**data, "text_dates": list(ctx.assumptions.values())}
+
+
+# ---------------------------------------------------------------------------
+# Display rounding
+# ---------------------------------------------------------------------------
+
+
+def _round_for_display(value: Any) -> Any:
+    """A float rounded to what a person reads: 2 decimals, 4 below 1 so a rate survives."""
+    if isinstance(value, bool) or not isinstance(value, float):
+        return value
+    return round(value, 2 if abs(value) >= 1 else 4)
+
+
+def round_result_rows(data: Any) -> Any:
+    """``data`` with every float in its result rows rounded for display.
+
+    Sums and averages come back with float noise (``428257.2699000002``) that
+    would be quoted to a user as is. Only the answer rows are rounded; a caller
+    that joins or diffs figures reads the unrounded handler instead.
+    """
+    rows = data.get("data") if isinstance(data, dict) else None
+    if not isinstance(rows, list):
+        return data
+    rounded = [
+        {k: _round_for_display(v) for k, v in row.items()} if isinstance(row, dict) else row
+        for row in rows
+    ]
+    return {**data, "data": DataRows(rounded) if isinstance(rows, DataRows) else rounded}

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.2.13"
+version = "2.2.14"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"
 license = "LicenseRef-Proprietary"
 requires-python = ">=3.12,<3.15"
 dependencies = [
-    "mammoth-io (>=0.8.13,<0.9)",
+    "mammoth-io (>=0.8.14,<0.9)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/spec/manifests/commands/dataset.yaml

@@ -524,10 +524,11 @@ commands:
   positionals:
   - name: name_substring
     type: str
-    required: true
+    required: false
     metavar: NAME_SUBSTRING
     falls_back_to_field: null
-    help: Case-insensitive substring to match against dataset names.
+    help: Case-insensitive substring to match against dataset names; optional when --input
+      gives 'columns'.
   options: []
   sdk_symbol: mammoth_cli.commands.dataset.find
   sdk_conversion: Call mammoth_cli.commands.dataset.find with validated request fields.
@@ -543,7 +544,7 @@ commands:
   contract_fixture: null
   required_fixture_guard: null
   secret_fields: []
-  human_example: mammoth dataset find NAME_SUBSTRING --help
+  human_example: mammoth dataset find --help
   agent_example: mammoth dataset find sales
   unit_tests:
   - UT-DATASET-FIND

{mammoth_cli-2.2.13 → mammoth_cli-2.2.14}/spec/manifests/sdk-methods.yaml

@@ -3997,7 +3997,7 @@ methods:
   reviewed_by: primary
 - sdk_symbol: mammoth.api.dataviews.DataviewsAPI.explore
   implementation_origin: mammoth.api.dataviews.DataviewsAPI.explore
-  signature: 'explore(self, dataset_id: ''int'', dataview_id: ''int'', column: ''str'', column_type: ''str | None'' = None, level: ''str | None'' = None, metric: ''dict[str, Any] | None'' = None, condition: ''dict[str, Any] | None'' = None, sequence: ''int | None'' = None, limit: ''int | None'' = None, offset: ''int | None'' = None, sort: ''str | None'' = None, workspace_id: ''int | None'' = None, project_id: ''int | None'' = None, timeout: ''int | None'' = None, poll_interval: ''int'' = 2) -> ''dict[str, Any]'''
+  signature: 'explore(self, dataset_id: ''int'', dataview_id: ''int'', column: ''str'', column_type: ''str | None'' = None, level: ''str | None'' = None, metric: ''dict[str, Any] | None'' = None, condition: ''dict[str, Any] | None'' = None, sequence: ''int | None'' = None, limit: ''int | None'' = None, offset: ''int | None'' = None, sort: ''str | None'' = None, cumulative: ''bool'' = False, workspace_id: ''int | None'' = None, project_id: ''int | None'' = None, timeout: ''int | None'' = None, poll_interval: ''int'' = 2) -> ''dict[str, Any]'''
   openapi_operation_ids: []
   canonical_command: view.data.explore
   alias_of: null