mammoth-cli 2.2.27__tar.gz → 2.2.28__tar.gz

{mammoth_cli-2.2.27 → mammoth_cli-2.2.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.27
+Version: 2.2.28
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk

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

{mammoth_cli-2.2.27 → mammoth_cli-2.2.28}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities.md

@@ -1,7 +1,7 @@
 # What is proven on release
 
 Generated from `docs/release-capability-matrix.json`; do not edit by hand.
-The CLI publishes 645 commands. 516 of them bind one of the 545 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (`view transform *` commands submit through `view.task.add`, except `rename-columns` and `sort`, which set view display properties through `view.update`). 262 bound commands ran once successfully on release, 1 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer. Use an untried command normally: confirm a write with the user first, check its result with a read afterwards, and never refuse a command only because it is untried.
+The CLI publishes 646 commands. 516 of them bind one of the 545 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (`view transform *` commands submit through `view.task.add`, except `rename-columns` and `sort`, which set view display properties through `view.update`). 262 bound commands ran once successfully on release, 1 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer. Use an untried command normally: confirm a write with the user first, check its result with a read afterwards, and never refuse a command only because it is untried.
 
 Status meanings:
 

{mammoth_cli-2.2.27 → mammoth_cli-2.2.28}/mammoth_cli/commands/dataset.py

@@ -526,7 +526,8 @@ def _compact_dataset_list(data: Any, offset: int, sort: str | None, limit: int)
         "order": sort or "newest first (created_at desc)",
         "note": (
             "A dataset record holds no sample values; 'view list DATASET_ID' shows "
-            "a sample of the stored profile per view as sample_values (all_columns: true lists every column)."
+            "a sample of the stored profile per view as sample_values "
+            "(all_columns: true lists every column)."
         ),
     }
     # The list route sends no ``next``: a page of ``limit`` rows may have a successor.
@@ -802,6 +803,7 @@ def dataset_create(invocation: Invocation) -> HandlerResult:
     document = invocation.load_input()
     dataset_spec = _require_field(document, "dataset_spec")
     ds_creation_type = _require_field(document, "ds_creation_type")
+    _require_clone_views(ds_creation_type, dataset_spec)
     kwargs: dict[str, Any] = {
         "dataset_spec": dataset_spec,
         "ds_creation_type": ds_creation_type,
@@ -822,6 +824,20 @@ def dataset_create(invocation: Invocation) -> HandlerResult:
     return result, _meta(invocation, auth.workspace_id, project_id)
 
 
+def _require_clone_views(ds_creation_type: object, dataset_spec: object) -> None:
+    """Refuse a clone with no ``clone_dataview_ids``: the server would make a blank view."""
+    if ds_creation_type != "clone" or not isinstance(dataset_spec, dict):
+        return
+    if dataset_spec.get("clone_dataview_ids") == []:
+        raise CliError(
+            code=CODE_MISSING_ARGUMENT,
+            message="A clone needs at least one view in dataset_spec.clone_dataview_ids",
+            exit_status=EXIT_USAGE,
+            hint="Pass the source dataset's default_view id from 'mammoth view list "
+            "DATASET_ID' (other views only when asked); an empty list makes a blank view.",
+        )
+
+
 def _created_dataset(handle: Any, settled: Any) -> dict[str, Any]:
     """Shape a create job (handle + settled result) into a labeled result.
 

{mammoth_cli-2.2.27 → mammoth_cli-2.2.28}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mammoth-cli"
-version = "2.2.27"
+version = "2.2.28"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"

{mammoth_cli-2.2.27 → mammoth_cli-2.2.28}/spec/manifests/commands/browse.yaml

@@ -303,7 +303,7 @@ commands:
   - CT-BROWSE-SEARCH-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: 'Searches resources across every project you can open in the workspace (resources v2), a cursor page at a time: pass next_cursor back as cursor while has_more is true. search matches names; resource_type (comma-separated), sort and fields narrow the page. Needs no active project.'
+  known_restrictions: 'Searches resources across every project you can open in the workspace (resources v2), a cursor page at a time: pass next_cursor back as cursor while has_more is true. search matches names; resource_type (comma-separated), sort and fields narrow the page. Needs no active project. Each dataset hit carries dataset_id (its object_id) and each view hit view_id: pass those, never the tree id.'
   reviewed_by: primary
   readback:
     command: browse.search

{mammoth_cli-2.2.27 → mammoth_cli-2.2.28}/spec/manifests/commands/dashboard.yaml

@@ -389,7 +389,7 @@ commands:
   - CT-DASHBOARD-CANVAS-GET-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: 'A board''s data is the view in the canvas dataset.dataview_id: read it with view data get VIEW_ID. After a board''s bake job, read the canvas and quote one number from it, such as a KPI total.'
   reviewed_by: primary
 - command_id: dashboard.canvas.restore
   command_path: dashboard canvas restore

{mammoth_cli-2.2.27 → mammoth_cli-2.2.28}/spec/manifests/commands/dataset.yaml

@@ -246,14 +246,7 @@ commands:
   - CT-DATASET-CREATE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: ds_creation_type is freeform and dataset_spec is arbitrary, so variants beyond the
-    documented path are not qualified. Retained live evidence supports ds_creation_type=weburl with dataset_spec.url;
-    the CLI command waits for the raw SDK job and returned ready for five OWID URL imports. Re-read returned
-    dataset/view IDs and delete only IDs created by this task. A weburl dataset is a one-time copy that
-    keeps no source details to refresh from, so automation's run_data_retrieval task cannot refresh it
-    (only a cloud-connected dataset can be refreshed); say so rather than scheduling a refresh for it.
-    The result's name is the dataset's real name; when the requested name was taken the server adds a suffix,
-    and requested_name and note say so. Use name, not the name you asked for.
+  known_restrictions: 'ds_creation_type is freeform and dataset_spec is arbitrary, so variants beyond the documented path are not qualified. Retained live evidence supports ds_creation_type=weburl with dataset_spec.url; the CLI command waits for the raw SDK job and returned ready for five OWID URL imports. Re-read returned dataset/view IDs and delete only IDs created by this task. A weburl dataset is a one-time copy that keeps no source details to refresh from, so automation''s run_data_retrieval task cannot refresh it (only a cloud-connected dataset can be refreshed); say so rather than scheduling a refresh for it. The result''s name is the dataset''s real name; when the requested name was taken the server adds a suffix, and requested_name and note say so. Use name, not the name you asked for. To copy a dataset as a new independent one: {"ds_creation_type": "clone", "dataset_spec": {"ds_name": NEW_NAME, "source_ds_id": ID, "clone_dataview_ids": [DEFAULT_VIEW_ID], "exclude_data": false}}, DEFAULT_VIEW_ID being the id in dataset''s `default_view` from view list (other views only when asked); an empty clone_dataview_ids is refused here because it makes a blank view. A clone waits and returns the new dataset_id; never use view export dataset for a plain copy, which leaves a live export on the source. A weburl import names the dataset after the downloaded file: follow it with dataset rename to the name the user picked.'
   reviewed_by: primary
 - command_id: dataset.create-from-pdf
   command_path: dataset create-from-pdf

{mammoth_cli-2.2.27 → mammoth_cli-2.2.28}/spec/manifests/commands/view.yaml

@@ -807,7 +807,7 @@ commands:
   - CT-VIEW-CREATE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: 'To work on a dataset''s changes without touching its own views, create a working view; clone_from (a view id of the same dataset) carries that view''s steps. A dataset''s own view is the default_view of view list, never the newest or an agent-made view: read it, or clone it with clone_from when steps are needed; edit it in place only when asked to change that view.'
   reviewed_by: primary
 - command_id: view.data-check.create
   command_path: view data-check create
@@ -1347,26 +1347,7 @@ commands:
   - CT-VIEW-DATA-EXPLORE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: 'Read-only: explore one column the way the web app''s column Explore card does --
-    trend, distribution, histogram, or top values -- without adding a task to the view''s pipeline (never
-    use ''view transform pivot'' just to explore). DATE column: counts per ''level'' bucket (AUTO default;
-    SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR, DECADE, CENTURY, MILLENNIUM) for "what''s trending",
-    "over time", "by month", "by year". NUMERIC column: counts per ''level'' resolution (AUTO default;
-    a power of 10) for a distribution or histogram. TEXT column: top values by count, ''limit'' default
-    20 -- "what''s in this column". Every bucket has ''count'' and ''percentage'' of the total. Options
-    (--input): ''metric'' {"column","function"} adds a per-bucket SUM, COUNT, AVG, MIN, MAX, STDDEV or
-    DISTINCT_COUNT over another column (the custom card); ''condition'' filters rows first -- include/exclude
-    values, blanks, a date or number range, text contains -- and several cards'' selections combine as
-    one AND condition (cross-filter); drill down by re-running at a finer ''level'' with a ''condition''
-    on the chosen bucket''s range; ''sort'' count_desc, count_asc, value_asc or value_desc; ''limit''
-    and ''offset'' page the buckets ("load more"); ''sequence'' explores at a pipeline step. Related:
-    distinct raw values of a DATE/NUMERIC column, a summary (min/max/sum/avg) or a matching-row count
-    -> ''view data aggregate''; keep the filter as a pipeline step -> ''view transform filter''; save
-    it as a new view -> ''view create'' then ''view transform filter'' on it; download all rows -> ''view
-    export csv''. A TEXT column of dates takes a level (or column_type DATE): the format is detected from the data and
-    stated in text_dates; ambiguous or unreadable dates fail loud. A column_type that disagrees with the
-    stored type is refused, never dropped. Example: --input ''{"level": "MONTH", "condition": {"column": "Results", "operator":
-    "EQ", "value": "Fail"}}''.'
+  known_restrictions: 'Read-only: explore one column the way the web app''s column Explore card does -- trend, distribution, histogram, or top values -- without adding a task to the view''s pipeline (never use ''view transform pivot'' just to explore). DATE column: counts per ''level'' bucket (AUTO default; SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR, DECADE, CENTURY, MILLENNIUM) for "what''s trending", "over time", "by month", "by year". NUMERIC column: counts per ''level'' resolution (AUTO default; a power of 10) for a distribution or histogram. TEXT column: top values by count, ''limit'' default 20 -- "what''s in this column". Every bucket has ''count'' and ''percentage'' of the total. Options (--input): ''metric'' {"column","function"} adds a per-bucket SUM, COUNT, AVG, MIN, MAX, STDDEV or DISTINCT_COUNT over another column (the custom card); ''condition'' filters rows first -- include/exclude values, blanks, a date or number range, text contains -- and several cards'' selections combine as one AND condition (cross-filter); drill down by re-running at a finer ''level'' with a ''condition'' on the chosen bucket''s range; ''sort'' count_desc, count_asc, value_asc or value_desc; ''limit'' and ''offset'' page the buckets ("load more"); ''sequence'' explores at a pipeline step. Related: distinct raw values of a DATE/NUMERIC column, a summary (min/max/sum/avg) or a matching-row count -> ''view data aggregate''; keep the filter as a pipeline step -> ''view transform filter''; save it as a new view -> ''view create'' then ''view transform filter'' on it; download all rows -> ''view export csv''. A TEXT column of dates takes a level (or column_type DATE): the format is detected from the data and stated in text_dates; ambiguous or unreadable dates fail loud. A column_type that disagrees with the stored type is refused, never dropped. Example: --input ''{"level": "MONTH", "condition": {"column": "Results", "operator": "EQ", "value": "Fail"}}''. A figure for a period (year, quarter, month) is one explore of the DATE column with level YEAR, QUARTER or MONTH and a metric {"column": AMOUNT, "function": "SUM"}: it returns one figure per period and the date range the data covers, so no rows need paging. cumulative true adds a running total; keep one year or range with condition, for a year {"column": DATE_COLUMN, "operator": "=", "value": 2017, "component": "year"}. Figures come back rounded to two decimals: quote them as returned.'
   reviewed_by: primary
 - command_id: view.data.profile
   command_path: view data profile
@@ -2280,10 +2261,7 @@ commands:
   - CT-VIEW-EXPORT-DATASET-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: 'Mutation class dynamic: benign_mutation for a new target, destructive when replacing
-    an existing target. The export is appended to the source pipeline (end_of_pipeline) and re-runs with
-    it; target_project_id sends the dataset into another project (cross-project branch-out, proven on
-    release). Result: {dataset_id, project_id, source_view_id, next}.'
+  known_restrictions: 'Mutation class dynamic: benign_mutation for a new target, destructive when replacing an existing target. The export is appended to the source pipeline (end_of_pipeline) and re-runs with it; target_project_id sends the dataset into another project (cross-project branch-out, proven on release). Result: {dataset_id, project_id, source_view_id, next}. Not a plain copy: this leaves a live export on the source and the new dataset refreshes from the source view, so keep that working view and name it as the new dataset''s source. For an independent copy of a dataset use dataset create with ds_creation_type clone.'
   reviewed_by: primary
 - command_id: view.export.delete
   command_path: view export delete