mammoth-cli 2.2.48__tar.gz → 2.2.49__tar.gz

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.48
+Version: 2.2.49
 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.26
+Requires-Dist: mammoth-io<0.9,>=0.8.27
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/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.48"
+__version__ = "2.2.49"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/bundled_skill/mammoth-cli/references/command-index.md

@@ -1,6 +1,6 @@
 # Published CLI command catalog
 
-This generated catalog is a lookup table for every command in the published CLI manifest, currently 656; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
+This generated catalog is a lookup table for every command in the published CLI manifest, currently 660; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
 
 Load only the applicable domain file:
 
@@ -24,7 +24,7 @@ Load only the applicable domain file:
 - [dashboard-qa](commands/dashboard-qa.md) — 14 published commands
 - [dashboard-template](commands/dashboard-template.md) — 12 published commands
 - [dashboard-style](commands/dashboard-style.md) — 10 published commands
-- [dashboard](commands/dashboard.md) — 98 published commands
+- [dashboard](commands/dashboard.md) — 99 published commands
 - [data-app](commands/data-app.md) — 12 published commands
 - [dataset](commands/dataset.md) — 22 published commands
 - [doctor](commands/doctor.md) — 1 published commands
@@ -51,7 +51,7 @@ Load only the applicable domain file:
 - [user](commands/user.md) — 8 published commands
 - [version](commands/version.md) — 1 published commands
 - [view-transform](commands/view-transform.md) — 32 published commands
-- [view](commands/view.md) — 94 published commands
+- [view](commands/view.md) — 97 published commands
 - [webhook](commands/webhook.md) — 7 published commands
 - [workflow](commands/workflow.md) — 16 published commands
 - [workspace](commands/workspace.md) — 26 published commands

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dashboard.md

@@ -422,6 +422,16 @@ Result: `DashboardFigureIntentResult`; mutation `benign_mutation`, confirmation
 
 Status on release: ran once on CLI 2.0.14 — dashboard re-verification 2026-09-18: exit 0 on release with CLI 2.0.14. CLI defect fixed, confirmed: returned a full matched structured body ({"added":{...},"kind":"bar","spec":{...},"intentApplied":true,...}) instead of raising ValidationError on an unmatch…
 
+### `dashboard.figure.add`
+
+Run: `mammoth dashboard figure add`. Exact input fields: `mammoth schema get dashboard.figure.add`.
+
+Example: `mammoth dashboard figure add 123 --input '{"dataview_id": 1, "figure": {"kind": "hbar", "title": "Revenue by region", "dim": "Region", "measure": "Revenue", "agg": "sum"}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardFigureAddResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `dashboard.filter.add`
 
 Run: `mammoth dashboard filter add`. Exact input fields: `mammoth schema get dashboard.filter.add`.

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -412,6 +412,26 @@ Result: `ViewDraftSubmitResult`; mutation `reversible_pipeline`, confirmation `n
 
 Status on release: untried; no live run recorded.
 
+### `view.explore-panel.get`
+
+Run: `mammoth view explore-panel get`. Exact input fields: `mammoth schema get view.explore-panel.get`.
+
+Example: `mammoth view explore-panel get 123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `ViewExplorePanelGetResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `view.explore-panel.set`
+
+Run: `mammoth view explore-panel set`. Exact input fields: `mammoth schema get view.explore-panel.set`.
+
+Example: `mammoth view explore-panel set 123 --input '{"panel": {"open": true, "items": [{"column": "column_1", "renderType": "chart"}]}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `ViewExplorePanelSetResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `view.export.azure-blob`
 
 Run: `mammoth view export azure-blob`. Exact input fields: `mammoth schema get view.export.azure-blob`.
@@ -914,6 +934,16 @@ Result: `ViewUpdateResult`; mutation `benign_mutation`, confirmation `none`, wai
 
 Status on release: untried; no live run recorded.
 
+### `view.variants.create`
+
+Run: `mammoth view variants create`. Exact input fields: `mammoth schema get view.variants.create`.
+
+Example: `mammoth view variants create 123 --input '{"from_view": 456, "column": "Region", "values": ["East", "West"]}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `ViewVariantsCreateResult`; mutation `benign_mutation`, confirmation `none`, wait policy `always_wait`.
+
+Status on release: untried; no live run recorded.
+
 ### `view.version.apply`
 
 Run: `mammoth view version apply`. Exact input fields: `mammoth schema get view.version.apply`.

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/commands/dashboard.py

@@ -608,6 +608,40 @@ def dashboard_share(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id)
 
 
+def _figure_page_kwargs(page: Any) -> dict[str, Any]:
+    """Map the endpoint's ``page`` ({"id"} or {"new_title"}) onto the SDK's page arguments."""
+    if not isinstance(page, dict) or set(page) not in ({"id"}, {"new_title"}):
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message='The \'page\' input field must be {"id": ...} or {"new_title": ...}.',
+            exit_status=EXIT_USAGE,
+        )
+    if "id" in page:
+        return {"page_id": page["id"]}
+    return {"page_new_title": page["new_title"]}
+
+
+def dashboard_figure_add(invocation: Invocation) -> HandlerResult:
+    """Add one figure to a dashboard. The input is the endpoint's own shape.
+
+    ``dataview_id`` and ``figure`` are required; ``banded`` and ``page`` (``{"id": ...}``
+    or ``{"new_title": ...}``) are optional. The result carries ``bake_job_id``.
+    """
+    dashboard_id = _require_int_positional(invocation, "dashboard id")
+    document = _bound_document(invocation)
+    kwargs: dict[str, Any] = {
+        "dashboard_id": dashboard_id,
+        "dataview_id": _require_field(document, "dataview_id"),
+        "figure": _require_field(document, "figure"),
+    }
+    _forward_optional(document, kwargs, ("banded",))
+    if document.get("page") is not None:
+        kwargs.update(_figure_page_kwargs(document["page"]))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
 def dashboard_cancel_generation(invocation: Invocation) -> HandlerResult:
     """Cancel an in-progress dashboard generation."""
     dashboard_id = _require_int_positional(invocation, "dashboard id")

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/commands/registry.py

@@ -483,6 +483,7 @@ HANDLERS: dict[str, Handler] = {
     "dashboard.tags.merge": dashboard_cmd.dashboard_tags_merge,
     "dashboard.published-data-by-url": dashboard_cmd.dashboard_published_data_by_url,
     "dashboard.restore": dashboard_cmd.dashboard_restore,
+    "dashboard.figure.add": dashboard_cmd.dashboard_figure_add,
     "dashboard.share": dashboard_cmd.dashboard_share,
     "dashboard.source.list": dashboard_cmd.dashboard_source_list,
     "dashboard.trash": dashboard_cmd.dashboard_trash,
@@ -777,6 +778,8 @@ HANDLERS: dict[str, Handler] = {
     "view.optimize": view_cmd.view_optimize,
     "view.compare": view_cmd.view_compare,
     "view.update": view_cmd.view_update,
+    "view.explore-panel.get": view_cmd.view_explore_panel_get,
+    "view.explore-panel.set": view_cmd.view_explore_panel_set,
     "view.data.get": view_cmd.view_data_get,
     "view.data.query": view_cmd.view_data_query,
     "view.data.aggregate": view_cmd.view_data_aggregate_rounded,
@@ -852,6 +855,7 @@ HANDLERS: dict[str, Handler] = {
     "view.export.tableau": view_cmd.view_export_specialized,
     # view family (View-object: create/get/delete, draft, transforms)
     "view.create": view_ops_cmd.view_create,
+    "view.variants.create": view_ops_cmd.view_variants_create,
     "view.get": view_ops_cmd.view_get,
     "view.delete": view_ops_cmd.view_delete,
     "view.draft.enter": view_ops_cmd.view_draft_enter,

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/commands/schema.py

@@ -46,8 +46,17 @@ _PROTECTED_INPUT_PATH = "/private/path/request.json"
 # second id, an optional-but-central input field, or two views to compare.
 _FIXED_EXAMPLES: dict[str, tuple[tuple[str, ...], dict[str, Any]]] = {
     "view.optimize": (("123",), {}),
+    "view.explore-panel.get": (("123",), {}),
+    "view.explore-panel.set": (
+        ("123",),
+        {"panel": {"open": True, "items": [{"column": "column_1", "renderType": "chart"}]}},
+    ),
     "project.check": (("123", "456"), {}),
     "view.data.profile": (("123",), {"target": "Churn"}),
+    "view.variants.create": (
+        ("123",),
+        {"from_view": 456, "column": "Region", "values": ["East", "West"]},
+    ),
     "workflow.canvas": (
         ("12",),
         {
@@ -97,6 +106,11 @@ _GROUP_DISCOVERY_PURPOSES = {
 
 _COMMAND_DISCOVERY_PURPOSES = {
     "view.update": "rename change name to a new name title relabel",
+    "view.explore-panel.get": "explore cards saved panel the data editor explore side panel read",
+    "view.explore-panel.set": "save replace explore cards panel items chart a column in the editor",
+    "dashboard.figure.add": (
+        "append an explore card figure tile to a dashboard from a payload, no chat turn"
+    ),
     "file.upload": (
         "upload import CSV spreadsheet XLSX source data append add rows union stack "
         "a file into an existing dataset excel workbook tabs sheets drop in"

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/commands/view.py

@@ -1115,6 +1115,40 @@ def view_update(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
+def view_explore_panel_get(invocation: Invocation) -> HandlerResult:
+    """Read the Explore panel the caller saved on a view (empty when none is saved)."""
+    project_id = require_project(invocation)
+    dataview_id = _require_int_positional_at(invocation, 0, "view id")
+    document = invocation.load_input() or {}
+    with open_service(invocation) as (service, auth):
+        dataset_id = _resolve_dataset_id(service, invocation, dataview_id, document)
+        data = service.call(
+            _symbol(invocation),
+            dataset_id=dataset_id,
+            dataview_id=dataview_id,
+            project_id=project_id,
+        )
+    return data, _meta(invocation, auth.workspace_id, project_id)
+
+
+def view_explore_panel_set(invocation: Invocation) -> HandlerResult:
+    """Replace the caller's saved Explore panel with the ``panel`` input field."""
+    project_id = require_project(invocation)
+    dataview_id = _require_int_positional_at(invocation, 0, "view id")
+    document = invocation.load_input() or {}
+    panel = _require_field(document, "panel")
+    with open_service(invocation) as (service, auth):
+        dataset_id = _verified_dataset_id(service, invocation, dataview_id, document)
+        data = service.call(
+            _symbol(invocation),
+            dataset_id=dataset_id,
+            dataview_id=dataview_id,
+            panel=panel,
+            project_id=project_id,
+        )
+    return data, _meta(invocation, auth.workspace_id, project_id)
+
+
 def _untyped_patch_error(invocation: Invocation) -> CliError:
     """The refusal for a view patch that is not the typed rename."""
     return CliError(

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/commands/view_ops.py

@@ -32,6 +32,7 @@ from mammoth_cli.commands.view import (
     BRIEF_VIEW_FIELDS,
     UNFINISHED_STATE,
     _dataview_metadata,
+    _display_name_map,
     _require_discovery_allowed,
     apply_column_renames,
     brief_view_record,
@@ -66,6 +67,15 @@ from mammoth_cli.services.command_contract import bind_command_inputs
 from mammoth_cli.services.conditions import CONDITION_KWARG, compile_condition
 from mammoth_cli.services.input_fields import TASK_COUNT_FIELD
 from mammoth_cli.services.sql_check import check_sql_binds
+from mammoth_cli.services.view_variants import (
+    VariantPlan,
+    created_entry,
+    name_template_of,
+    partial_failure,
+    plan_variants,
+    require_known_column,
+    variants_result,
+)
 from mammoth_cli.services.write_impact import (
     ImpactRead,
     Measure,
@@ -772,6 +782,65 @@ def _require_clone_from_same_dataset(service: Any, clone_from: int, dataset_id:
         )
 
 
+_VIEW_CREATE_SYMBOL = "mammoth.client.ViewsResource.create"
+
+
+def view_variants_create(invocation: Invocation) -> HandlerResult:
+    """Create one view per value of a column: each a clone of ``from_view`` filtered to it.
+
+    Composes ``view create`` (``clone_from``) and ``view transform filter``. All
+    checks that need no write run first; the first failing write stops the run
+    and the error names every view already created.
+    """
+    dataset_id = _require_int_positional(invocation, "dataset id")
+    raw = invocation.load_input()
+    for field in ("from_view", "column", "values"):
+        _require_field(raw, field)
+    document = bind_command_inputs(invocation.command_id, raw)
+    from_view = int(document["from_view"])
+    column = str(document["column"])
+    with open_service(invocation) as (service, auth):
+        _require_clone_from_same_dataset(service, from_view, dataset_id)
+        source = service.call(_DATAVIEW_GET_SYMBOL, dataset_id=dataset_id, dataview_id=from_view)
+        names = set(_display_name_map(service, dataset_id, from_view, None).values())
+        require_known_column(from_view, column, names)
+        plans = plan_variants(
+            str(source.get("name", "")) if isinstance(source, dict) else "",
+            column,
+            document["values"],
+            name_template_of(document),
+        )
+        created = _create_variants(service, dataset_id, from_view, plans)
+    result = variants_result(dataset_id, from_view, column, created)
+    return result, _meta(invocation, auth.workspace_id)
+
+
+def _create_variants(
+    service: Any, dataset_id: int, from_view: int, plans: list[VariantPlan]
+) -> list[dict[str, Any]]:
+    """Create and filter each variant in order; the first failure stops with a full report."""
+    created: list[dict[str, Any]] = []
+    for position, plan in enumerate(plans):
+        new_id: int | None = None
+        try:
+            view = _view_payload(
+                service.call(
+                    _VIEW_CREATE_SYMBOL, dataset_id=dataset_id, name=plan.name, clone_from=from_view
+                )
+            )
+            new_id = int(view["id"])
+            data = service.call_view(
+                new_id, "filter_rows", dataset_id=dataset_id, condition=plan.condition
+            )
+            reject_pipeline_reference_errors(service, new_id, dataset_id, data)
+        except CliError as exc:
+            raise partial_failure(
+                plan, exc, created, plans[position + 1 :], new_id, dataset_id
+            ) from exc
+        created.append(created_entry(plan, view))
+    return created
+
+
 _DASHBOARDS_LIST_SYMBOL = "mammoth.api.dashboards.DashboardsAPI.list"
 
 

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/errors/envelope.py

@@ -153,6 +153,7 @@ ERROR_SUMMARIES: dict[str, str] = {
     "missing_field": _S_MISSING_INFO,
     "network_error": "Mammoth couldn't be reached over the network.",
     "no_op": "There is nothing to change, so this step isn't needed.",
+    "variants_partial_failure": "Some of the variant views were created and one failed.",
     "no_output": "This step didn't return anything.",
     "nonfinite_input_number": _S_BAD_INPUT,
     "not_authenticated": _S_SIGN_IN,

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/services/command_contract.py

@@ -350,6 +350,15 @@ _VIEW_DATA_PROFILE_FIELDS = (
     FieldSpec("limit", required=False, annotation=int, default=50),
 )
 
+# view.variants.create is a CLI composite over view create (clone_from) and
+# view transform filter; its document fields are authored here.
+_VIEW_VARIANTS_CREATE_FIELDS = (
+    FieldSpec("from_view", required=True, annotation=int),
+    FieldSpec("column", required=True, annotation=str),
+    FieldSpec("values", required=True, annotation=list[str | int | float]),
+    FieldSpec("name_template", required=False, annotation=str | None, default=None),
+)
+
 # view.conditional-format.create: ``rule`` (raw body) stays accepted; the typed fields build one
 # rule per column (per-cell threshold) or one row rule (see
 # mammoth_cli.services.conditional_format). ``rule`` is therefore optional here -- the handler
@@ -723,6 +732,14 @@ _S7_ADDITIONAL_INPUT_FIELDS: dict[str, tuple[FieldSpec, ...]] = {
     # The typed rename: the handler builds the one ``replace`` on ``name``; the
     # SDK's free-form ``patch_data`` is handler-owned and never offered.
     "view.update": (FieldSpec("name", required=True, annotation=str),),
+    # The endpoint's own params: ``page`` is {"id"} or {"new_title"}; the handler maps
+    # it onto the SDK's page_id / page_new_title.
+    "dashboard.figure.add": (
+        FieldSpec("dataview_id", required=True, annotation=int),
+        FieldSpec("figure", required=True, annotation=dict[str, Any]),
+        FieldSpec("banded", required=False, annotation=dict[str, Any] | None, default=None),
+        FieldSpec("page", required=False, annotation=dict[str, Any] | None, default=None),
+    ),
     "user.preference.update": (
         # PreferencesPatchRequest: replace ops on dotted paths rooted at
         # GLOBAL or WORKSPACE_PREFERENCES.
@@ -795,6 +812,8 @@ def resolve_command_contract(command_id: str) -> ResolvedCommandContract | None:
         special_fields = _VIEW_DATA_COMPARE_FIELDS
     elif command_id == "view.data.profile":
         special_fields = _VIEW_DATA_PROFILE_FIELDS
+    elif command_id == "view.variants.create":
+        special_fields = _VIEW_VARIANTS_CREATE_FIELDS
     elif command_id == "dashboard.filter.add":
         special_fields = _DASHBOARD_FILTER_ADD_FIELDS
     elif command_id == "dashboard.filter.remove":

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/services/input_fields.py

@@ -48,6 +48,8 @@ _HANDLER_OWNED_FIELDS: dict[str, frozenset[str]] = {
     "view.data.aggregate": frozenset({"sort"}),
     # ``view update`` offers only the typed rename; the handler builds the patch.
     "view.update": frozenset({"patch_data"}),
+    # The endpoint names the target page as ``page``; the handler maps it onto these two.
+    "dashboard.figure.add": frozenset({"page_id", "page_new_title"}),
 }
 
 # CLI-only commands whose complete request is carried by positionals/context.
@@ -79,6 +81,16 @@ _EXAMPLE_INPUT_HINTS: dict[str, dict[str, Any]] = {
     # View display settings: real column names read better than sample keys.
     "view.transform.rename-columns": {"renames": {"cust_id": "Customer ID"}},
     "view.update": {"name": "Revenue report"},
+    "dashboard.figure.add": {
+        "dataview_id": 1,
+        "figure": {
+            "kind": "hbar",
+            "title": "Revenue by region",
+            "dim": "Region",
+            "measure": "Revenue",
+            "agg": "sum",
+        },
+    },
     "view.transform.sort": {"order_by": [["Revenue", "DESC"]]},
     # The backend requires integer resource ids ("resource_ids must be
     # comma-separated integers"); the SDK annotation is a plain list[str].

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/mammoth_cli/services/positionals.py

@@ -165,6 +165,10 @@ POSITIONAL_OVERRIDES: dict[str, tuple[PositionalSpec, ...]] = {
             example_value="card.png",
         ),
     ),
+    # The figure's source view is the ``dataview_id`` input field, never a second positional.
+    "dashboard.figure.add": (
+        PositionalSpec(name="dashboard_id", type=int, required=True, help="ID of the dashboard."),
+    ),
     "dashboard.gallery.get": (
         PositionalSpec(name="slug", type=str, required=True, help="Template slug."),
     ),
@@ -810,6 +814,8 @@ POSITIONAL_OVERRIDES: dict[str, tuple[PositionalSpec, ...]] = {
             "view.impact",
             "view.optimize",
             "view.update",
+            "view.explore-panel.get",
+            "view.explore-panel.set",
             "view.conditional-format.create",
             "view.conditional-format.delete-all",
             "view.conditional-format.list",
@@ -1234,6 +1240,10 @@ _EXACT_PARENT_HELP_OVERRIDES: dict[str, str] = {
     "view.optimize": (
         "Optional parent dataset ID. Leave it out and the CLI looks up the view's dataset. A value that is not the view's dataset is refused before the write."
     ),
+    "view.explore-panel.set": (
+        "Optional parent dataset ID. Leave it out and the CLI looks up the view's dataset. "
+        "A value that is not the view's dataset is refused before the write."
+    ),
     "view.export.dataset": (
         "Exact parent dataset ID of the SOURCE view being exported -- not the "
         "destination. Required for this command: pass it here or as the "

mammoth_cli-2.2.49/mammoth_cli/services/view_variants.py

@@ -0,0 +1,164 @@
+"""Plan and report ``view variants create``: one view per value of one column.
+
+The handler composes two existing SDK calls per value (create a view cloned
+from the source view, then filter it to the value). This module owns the parts
+that need no server: the per-value plan and the result, including the loud
+partial-failure error that names every view already created.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from mammoth.models.pipeline import Operator
+
+from mammoth_cli.errors.envelope import (
+    CODE_INVALID_ARGUMENTS,
+    EXIT_API,
+    EXIT_USAGE,
+    CliError,
+)
+
+DEFAULT_NAME_TEMPLATE = "{view} - {value}"
+CODE_VARIANTS_PARTIAL = "variants_partial_failure"
+MAX_VARIANTS = 50
+
+type VariantValue = str | int | float
+
+
+@dataclass(frozen=True)
+class VariantPlan:
+    """One variant to create: its view name and the filter that defines it."""
+
+    value: VariantValue
+    name: str
+    condition: dict[str, Any]
+
+
+def plan_variants(
+    source_name: str, column: str, values: list[VariantValue], name_template: str
+) -> list[VariantPlan]:
+    """Return one plan per value, refusing input that could not make distinct views."""
+    if not values:
+        raise _invalid("values must name at least one value.")
+    if len(values) > MAX_VARIANTS:
+        raise _invalid(f"values holds {len(values)} entries; the limit is {MAX_VARIANTS} per call.")
+    if len({str(value) for value in values}) != len(values):
+        raise _invalid("values must not repeat a value; each value makes one view.")
+    plans = [
+        VariantPlan(
+            value=value,
+            name=_render_name(name_template, source_name, value),
+            condition={"column": column, "operator": Operator.EQ.value, "value": value},
+        )
+        for value in values
+    ]
+    if len({plan.name for plan in plans}) != len(plans):
+        raise _invalid(
+            "name_template gives two variants the same name.",
+            hint="Include {value} in name_template.",
+        )
+    return plans
+
+
+def name_template_of(document: dict[str, Any]) -> str:
+    """The document's name template; absent, null or empty means the default."""
+    return str(document.get("name_template") or DEFAULT_NAME_TEMPLATE)
+
+
+def require_known_column(view_id: int, column: str, names: set[str]) -> None:
+    """Refuse a column the source view lacks; an unreadable column list is an error too."""
+    if not names:
+        raise CliError(
+            code=CODE_INVALID_ARGUMENTS,
+            message=f"Could not read the columns of view {view_id}, so '{column}' was not checked.",
+            exit_status=EXIT_API,
+            hint=f"Run `mammoth view get {view_id}` and retry; no view was created.",
+            details={"view_id": view_id, "column": column},
+        )
+    if column not in names:
+        raise CliError(
+            code=CODE_INVALID_ARGUMENTS,
+            message=f"View {view_id} has no column '{column}'.",
+            exit_status=EXIT_USAGE,
+            hint="Use one of: " + ", ".join(sorted(names)) + ".",
+            details={"view_id": view_id, "column": column, "columns": sorted(names)},
+        )
+
+
+def _render_name(template: str, source_name: str, value: VariantValue) -> str:
+    try:
+        return template.format(view=source_name, value=value)
+    except (KeyError, IndexError, ValueError) as exc:
+        raise _invalid(
+            f"name_template {template!r} is not valid.",
+            hint="Use only {view} and {value}, for example '{view} - {value}'.",
+        ) from exc
+
+
+def _invalid(message: str, hint: str | None = None) -> CliError:
+    return CliError(code=CODE_INVALID_ARGUMENTS, message=message, exit_status=EXIT_USAGE, hint=hint)
+
+
+def created_entry(plan: VariantPlan, view: dict[str, Any]) -> dict[str, Any]:
+    """The result row for a variant that was created and filtered."""
+    return {"value": plan.value, "view_id": view.get("id"), "name": plan.name}
+
+
+def variants_result(
+    dataset_id: int, from_view: int, column: str, created: list[dict[str, Any]]
+) -> dict[str, Any]:
+    """The result of a fully created set."""
+    return {
+        "dataset_id": dataset_id,
+        "from_view": from_view,
+        "column": column,
+        "view_ids": [entry["view_id"] for entry in created],
+        "variants": created,
+    }
+
+
+def partial_failure(
+    failed: VariantPlan,
+    cause: CliError,
+    created: list[dict[str, Any]],
+    not_attempted: list[VariantPlan],
+    orphan_view_id: int | None,
+    dataset_id: int,
+) -> CliError:
+    """The error that stops the run: which variants exist, which failed, which never ran.
+
+    ``orphan_view_id`` is the view that was created for ``failed`` but never got
+    its filter (so it holds the unfiltered source rows); the caller deletes or
+    fixes it, so it is named, never dropped.
+    """
+    made = [entry["view_id"] for entry in created]
+    skipped = [plan.value for plan in not_attempted]
+    recovery = (
+        [f"mammoth view delete {orphan_view_id} {dataset_id}"] if orphan_view_id is not None else []
+    )
+    return CliError(
+        code=CODE_VARIANTS_PARTIAL,
+        message=(
+            f"Variant {failed.value!r} failed ({cause.message}); {len(created)} view(s) were "
+            f"created before it: {made}. Not attempted: {skipped}."
+        ),
+        exit_status=EXIT_API,
+        hint=(
+            "Rerun with only the failed and not-attempted values. "
+            + (
+                f"View {orphan_view_id} was created for {failed.value!r} but is not filtered; "
+                "delete it before the rerun."
+                if orphan_view_id is not None
+                else "No half-made view was left behind."
+            )
+        ),
+        details={
+            "created": created,
+            "failed": {"value": failed.value, "code": cause.code, "message": cause.message},
+            "not_attempted": skipped,
+            "unfiltered_view_id": orphan_view_id,
+        },
+        recovery_commands=recovery,
+    )

{mammoth_cli-2.2.48 → mammoth_cli-2.2.49}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.2.48"
+version = "2.2.49"
 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.26,<0.9)",
+    "mammoth-io (>=0.8.27,<0.9)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",