mammoth-cli 2.2.63__tar.gz → 2.2.64__tar.gz

{mammoth_cli-2.2.63 → mammoth_cli-2.2.64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.63
+Version: 2.2.64
 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.63 → mammoth_cli-2.2.64}/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.63"
+__version__ = "2.2.64"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.63 → mammoth_cli-2.2.64}/mammoth_cli/commands/dataset.py

@@ -15,10 +15,12 @@ from typing import Any, Protocol
 
 from mammoth_cli.errors.envelope import (
     CODE_INVALID_ARGUMENT,
+    CODE_JOB_FAILED,
     CODE_MISSING_ARGUMENT,
     CODE_MISSING_FIELD,
     CODE_SDK_SYMBOL_UNRESOLVED,
     CODE_UNSUPPORTED_CONTRACT,
+    EXIT_API,
     EXIT_USAGE,
     CliError,
 )
@@ -877,6 +879,7 @@ def dataset_create(invocation: Invocation) -> HandlerResult:
     # A clone can land in another project (``dataset_spec.target_project_id``): the
     # name check and the result's scope are that project's, not the active one's.
     landing_project_id = _clone_target_project(ds_creation_type, dataset_spec) or project_id
+    _default_data_pull_file(ds_creation_type, dataset_spec)
     kwargs: dict[str, Any] = {
         "dataset_spec": dataset_spec,
         "ds_creation_type": ds_creation_type,
@@ -927,29 +930,92 @@ def _require_clone_views(ds_creation_type: object, dataset_spec: object) -> None
         )
 
 
+#: The server's ``data_pull_file`` values for a cloud file import; the first is the app default.
+_DATA_PULL_FILE_VALUES = ("Pull same file", "Pull next file based on name pattern")
+
+
+def _default_data_pull_file(ds_creation_type: object, dataset_spec: object) -> None:
+    """Default a cloud file import's ``data_pull_file`` to "Pull same file", as the web app does.
+
+    Raises:
+        CliError: ``invalid_argument`` listing the allowed values when it is not one of them.
+    """
+    if ds_creation_type != "cloud" or not isinstance(dataset_spec, dict):
+        return
+    properties = dataset_spec.get("query_properties")
+    if not isinstance(properties, dict) or not properties.get("file_path"):
+        return
+    pull = properties.setdefault("data_pull_file", _DATA_PULL_FILE_VALUES[0])
+    if pull not in _DATA_PULL_FILE_VALUES:
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message="query_properties.data_pull_file must be one of "
+            f"{list(_DATA_PULL_FILE_VALUES)}, got {pull!r}.",
+            exit_status=EXIT_USAGE,
+        )
+
+
 def _created_dataset(handle: Any, settled: Any) -> dict[str, Any]:
     """Shape a create job (handle + settled result) into a labeled result.
 
-    ``wait_if_job`` returns the completed job's inner response, where the new
-    dataset id lives under ``ds_id``. Falls back to the raw job handle when the
-    server returned something unrecognized, so no information is lost.
+    What each creation type settles with: weburl, clone and a single cloud file or
+    database import carry the new dataset id (``ds_id``, ``dataset_id`` or
+    ``datasource_id``); a cloud import deferred to a later start carries
+    ``datasource_config_id`` and reports ``scheduled``; a bulk cloud file import
+    carries ``files_found``/``created``/``failed`` and is returned as the server
+    sent it; a sketch is not a job and answers with the dataset itself. A job that
+    settled with none of these made nothing, so it raises with the server's reason
+    rather than report success.
+
+    Raises:
+        CliError: ``job_failed`` when the settled job made no dataset.
     """
-    job_id = handle.get("job_id") if isinstance(handle, dict) else None
+    if not isinstance(handle, dict) or "job_id" not in handle:
+        return settled if isinstance(settled, dict) else {"job_id": None}
+    job_id = handle["job_id"]
     ds_id = None
+    config_id = None
     if isinstance(settled, dict):
-        ds_id = settled.get("ds_id") or settled.get("dataset_id")
-        nested = settled.get("response")
-        if ds_id is None and isinstance(nested, dict):
-            ds_id = nested.get("ds_id") or nested.get("dataset_id")
+        for source in (settled, settled.get("response")):
+            if not isinstance(source, dict):
+                continue
+            ds_id = ds_id or _first_id(source, _DATASET_ID_KEYS)
+            config_id = config_id or source.get("datasource_config_id")
         job_id = settled.get("job_id", job_id)
+    if ds_id is None and config_id is not None:
+        return {"status": "scheduled", "datasource_config_id": config_id, "job_id": job_id}
+    if ds_id is None and isinstance(settled, dict) and "files_found" in settled:
+        return settled
     if ds_id is None:
-        # No recognizable dataset id: surface the settled payload untouched
-        # rather than claim a readiness we cannot confirm.
-        return settled if isinstance(settled, dict) else {"job_id": job_id}
-    result: dict[str, Any] = {"status": "ready", "dataset_id": ds_id}
-    if job_id is not None:
-        result["job_id"] = job_id
-    return result
+        reason = _job_reason(settled)
+        raise CliError(
+            code=CODE_JOB_FAILED,
+            message="The dataset was not created"
+            + (f": {reason}" if reason else f" (job {job_id} finished without a dataset id)."),
+            exit_status=EXIT_API,
+        )
+    return {"status": "ready", "dataset_id": ds_id, "job_id": job_id}
+
+
+#: Keys a settled create job may carry its dataset id under.
+_DATASET_ID_KEYS = ("ds_id", "dataset_id", "datasource_id")
+
+
+def _first_id(source: dict[str, Any], keys: tuple[str, ...]) -> Any:
+    """The first non-empty value of ``keys`` in ``source``, or None."""
+    return next((source[key] for key in keys if source.get(key)), None)
+
+
+def _job_reason(settled: Any) -> str | None:
+    """The failure reason a settled job carries (``failure_reason``, ``message``, ``error``)."""
+    if not isinstance(settled, dict):
+        return None
+    nested = settled.get("response")
+    for source in (settled, nested if isinstance(nested, dict) else {}):
+        for key in ("failure_reason", "message", "error"):
+            if source.get(key):
+                return str(source[key])
+    return None
 
 
 #: Pages (of 100) read to predict a final name; past it the answer is "a suffix may be added".

{mammoth_cli-2.2.63 → mammoth_cli-2.2.64}/pyproject.toml

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

{mammoth_cli-2.2.63 → mammoth_cli-2.2.64}/spec/manifests/commands/dataset.yaml

@@ -247,7 +247,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. 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. To import a file from an SFTP server (or another file connector) as a new dataset: connector connection create sftp, then {"ds_creation_type": "cloud", "dataset_spec": {"connector_key": "sftp", "connection_key": KEY, "query_properties": {"ds_name": NAME, "file_path": PATH_ON_SERVER}}}; the recipe is recipes/file-import.md.'
+  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. To import a file from an SFTP server (or another file connector) as a new dataset: connector connection create sftp, then {"ds_creation_type": "cloud", "dataset_spec": {"connector_key": "sftp", "connection_key": KEY, "query_properties": {"ds_name": NAME, "file_path": PATH_ON_SERVER, "data_pull_file": "Pull same file"}}}. data_pull_file is a string and may be left out, which means "Pull same file" (what the web app does); its only other value is "Pull next file based on name pattern", which also needs folder_path and name_pattern. A pull that finds no file at the path fails the create with the server''s reason; the recipe is recipes/file-import.md.'
   reviewed_by: primary
 - command_id: dataset.create-from-pdf
   command_path: dataset create-from-pdf