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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.27
+Version: 2.2.29
 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.29}/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.29"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.27 → mammoth_cli-2.2.29}/mammoth_cli/bundled_skill/mammoth-cli/references/about-mammoth.md

@@ -141,7 +141,12 @@ No command:
 - **Union or append two views.** There is no union task. Upload a file into
   an existing dataset with `append_to_ds_id`, or send a view's rows into an
   existing dataset with `view export dataset` (`target_ds_id` and
-  `save_as_mode` `APPEND_TO_DS`). An append is a standing link: it is stored
+  `save_as_mode` `APPEND_TO_DS`). Omit `column_mapping` and every column is
+  matched by name; a non-empty `column_mapping` is used as-is, so it must map
+  every source column to an existing target column. A partial mapping, or a
+  destination the target lacks, is refused with `append_mapping_incomplete`
+  before anything is written (the backend would append only the mapped columns
+  and add a new column for the unknown name). An append is a standing link: it is stored
   as a pipeline step of the source view, so every later re-run of that view
   appends again into the target dataset, not just the first run. A column
   with the same name but a different type in the source view and the target

{mammoth_cli-2.2.27 → mammoth_cli-2.2.29}/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.29}/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.29}/mammoth_cli/commands/view.py

@@ -3545,6 +3545,7 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
             _reject_export_into_draft(service, dataview_id, dataset_id)
         target_view_before = None
         target_only_columns: list[str] = []
+        mapped_type_warnings: list[str] = []
         if target_ds_id is not None:
             # Each `view export dataset` call creates its own PERSISTENT
             # export trigger on this view, which re-runs on every pipeline
@@ -3578,7 +3579,7 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
             # before the call so a later re-read can never be confused with it.
             target_view_before = _dataset_view_info(service, int(target_ds_id), result_project_id)
             if save_as_mode == "APPEND_TO_DS":
-                target_only_columns = _reject_append_schema_mismatch(
+                target_only_columns, mapped_type_warnings = _reject_append_schema_mismatch(
                     service,
                     dataview_id,
                     dataset_id,
@@ -3640,13 +3641,17 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
                 # An append is expected to grow the target; verify.py treats
                 # a non-increase here as unverified, not just an omitted count.
                 row_check["expected_row_increase"] = True
+            warnings = list(mapped_type_warnings)
             if target_only_columns:
                 # Allowed -- an append never has to cover every target column
                 # -- but worth surfacing rather than leaving silent.
-                row_check["warnings"] = [
+                warnings.insert(
+                    0,
                     "target dataset has column(s) the source view does not (kept "
-                    "as-is): " + ", ".join(target_only_columns)
-                ]
+                    "as-is): " + ", ".join(target_only_columns),
+                )
+            if warnings:
+                row_check["warnings"] = warnings
             data["row_check"] = row_check
             if pipeline_error is not None:
                 data["pipeline_error"] = pipeline_error
@@ -3799,24 +3804,92 @@ def _reject_append_type_mismatch(
     )
 
 
+def _reject_partial_append_mapping(
+    source_names: set[str],
+    target_names: set[str],
+    mapping: dict[str, str],
+    ids: tuple[int, int],
+) -> None:
+    """Refuse a non-empty append ``column_mapping`` that drops or invents columns.
+
+    The backend maps every column by name when the mapping is empty, but uses
+    a non-empty one as-is: unmapped source columns are not appended (their
+    target cells stay NULL) and a destination the target lacks becomes a new
+    column named after the source.
+    """
+    if not mapping:
+        return
+    unknown = {src: dest for src, dest in sorted(mapping.items()) if dest not in target_names}
+    unmapped = sorted(source_names - set(mapping))
+    if not unknown and not unmapped:
+        return
+    view_id, target_ds_id = ids
+    problems = []
+    if unknown:
+        listed = ", ".join(f"{dest!r} (for {src!r})" for src, dest in unknown.items())
+        problems.append(f"destination column(s) not in target dataset {target_ds_id}: {listed}")
+    if unmapped:
+        problems.append(f"source column(s) left unmapped and not appended: {', '.join(unmapped)}")
+    raise CliError(
+        code="append_mapping_incomplete",
+        message=(
+            f"column_mapping for appending view {view_id} into dataset {target_ds_id} would "
+            f"corrupt the append: {'; '.join(problems)}. A non-empty column_mapping is used "
+            "as-is: unmapped columns are not appended and an unknown destination creates a "
+            "new column."
+        ),
+        exit_status=EXIT_USAGE,
+        hint=(
+            "Omit column_mapping to map all columns by name, or map every source column to "
+            f"an existing column of dataset {target_ds_id}."
+        ),
+        details={
+            "unknown_destinations": unknown,
+            "unmapped_source_columns": unmapped,
+            "target_columns": sorted(target_names),
+        },
+    )
+
+
+def _mapped_type_warnings(
+    source_types: Any, target_schema: dict[str, str], mapping: dict[str, str]
+) -> list[str]:
+    """Warn where a mapped source column's type differs from its target column's."""
+    if not isinstance(source_types, dict):
+        return []
+    return [
+        f"mapped column {src!r} is {str(source_types[src]).lower()} but target column "
+        f"{dest!r} is {target_schema[dest].lower()}"
+        for src, dest in sorted(mapping.items())
+        if source_types.get(src)
+        and target_schema.get(dest)
+        and str(source_types[src]).lower() != target_schema[dest].lower()
+    ]
+
+
 def _reject_append_schema_mismatch(
     service: Any,
     dataview_id: int,
     dataset_id: int | None,
     target_ds_id: int,
     column_mapping: Any,
-) -> list[str]:
+) -> tuple[list[str], list[str]]:
     """Refuse an ``APPEND_TO_DS`` export whose source has a column the target
     dataset's schema does not, and ``column_mapping`` does not cover.
 
+    A non-empty ``column_mapping`` is stricter: the backend then copies only
+    the mapped columns and turns an unknown destination into a new column, so
+    every source column must be mapped to a column the target already has
+    (``_reject_partial_append_mapping``).
+
     An append writes into rows the target dataset already has; a source
     column with no home in the target schema and no explicit mapping would
     otherwise reach the backend as a malformed write. Checked here, before
     the call, so the refusal costs nothing and names exactly what to fix.
 
     Returns the target-only column names (present in the target schema, not
-    in the source, not a ``column_mapping`` destination) -- allowed, but
-    worth a warning rather than silence.
+    in the source, not a ``column_mapping`` destination) and the type
+    warnings for mapped pairs -- both allowed, but worth a warning.
     """
     source_columns = service.call_view(dataview_id, "columns", dataset_id=dataset_id)
     if not isinstance(source_columns, dict):
@@ -3833,14 +3906,11 @@ def _reject_append_schema_mismatch(
     # dict keys are display names, matching what the backend's own schema
     # match compares by -- never the internal ids in the dict's values.
     source_names = set(source_columns)
+    _reject_partial_append_mapping(source_names, target_names, mapping, (dataview_id, target_ds_id))
     source_only = sorted(source_names - target_names - set(mapping))
     target_only = sorted(target_names - source_names - set(mapping.values()))
-    _reject_append_type_mismatch(
-        service.call_view(dataview_id, "column_types", dataset_id=dataset_id),
-        target_schema,
-        mapping,
-        (dataview_id, target_ds_id),
-    )
+    source_types = service.call_view(dataview_id, "column_types", dataset_id=dataset_id)
+    _reject_append_type_mismatch(source_types, target_schema, mapping, (dataview_id, target_ds_id))
     if source_only:
         raise CliError(
             code="append_schema_mismatch",
@@ -3855,7 +3925,7 @@ def _reject_append_schema_mismatch(
             ),
             details={"source_only": source_only, "target_only": target_only},
         )
-    return target_only
+    return target_only, _mapped_type_warnings(source_types, target_schema, mapping)
 
 
 def _dataset_view_info(

{mammoth_cli-2.2.27 → mammoth_cli-2.2.29}/mammoth_cli/errors/envelope.py

@@ -77,6 +77,7 @@ ERROR_SUMMARIES: dict[str, str] = {
         "More than one item matched, so the assistant needs to be more specific."
     ),
     "api_error": "Mammoth couldn't complete this step.",
+    "append_mapping_incomplete": "The column mapping would leave columns out or add new ones.",
     "append_schema_mismatch": "The new data doesn't line up with the existing columns.",
     "append_type_mismatch": "A column has a different type than in the existing data.",
     "append_schema_unreadable": "The columns of the existing data couldn't be read.",

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

@@ -1,6 +1,6 @@
 [project]
 name = "mammoth-cli"
-version = "2.2.27"
+version = "2.2.29"
 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.29}/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.29}/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.29}/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.29}/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. Appending into an existing dataset (save_as_mode APPEND_TO_DS with target_ds_id): omit column_mapping and every column is mapped by name; a non-empty column_mapping is used as-is, so it must map every source column to an existing target column, and a partial mapping or an unknown destination is refused (append_mapping_incomplete) before anything is written. A mapped pair of different types is reported in row_check.warnings.'
   reviewed_by: primary
 - command_id: view.export.delete
   command_path: view export delete