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

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

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

{mammoth_cli-2.2.62 → mammoth_cli-2.2.64}/mammoth_cli/app.py

@@ -1343,7 +1343,7 @@ _ROOT_LEAF_HELP: dict[str, str] = {
     ),
     "resolve": (
         "Say what NAME refers to: a dataset, a view or a project, with ids and projects."
-        "\n\nExample: mammoth resolve uqa-w29-ren"
+        "\n\nExample: mammoth resolve uqa-w29-ren\n\nInput fields: all_projects (bool)"
     ),
     "upgrade": (
         "Upgrade the mammoth CLI to the latest (or a specified) version from PyPI."

{mammoth_cli-2.2.62 → mammoth_cli-2.2.64}/mammoth_cli/commands/connector.py

@@ -145,26 +145,23 @@ def connector_get(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
 
 
-#: ``availability`` a premium connector gets when it is not yet added to the
-#: workspace -- distinct from an ordinary connector nobody has added yet.
-_PREMIUM_NOT_ENABLED = "premium_not_enabled"
+#: ``availability`` a connector gets when the server says this workspace's plan
+#: does not include it.
+_NOT_IN_PLAN = "not_in_plan"
 
 
-_PREMIUM_NOT_ENABLED_NOTE = (
-    "Premium connector, not enabled in this workspace: Mammoth sales must enable"
-    " it before it can be connected. Tell the user so and offer to contact sales."
-)
+_NOT_IN_PLAN_NOTE = "Not included in this workspace's plan. Mammoth sales can enable it."
 
 
-def _with_premium_availability(data: Any) -> Any:
-    """Mark each premium, not-yet-added connector with why it cannot be connected.
+def _with_plan_availability(data: Any) -> Any:
+    """Mark each connector the server reports unavailable to this workspace.
 
-    ``is_premium``/``is_added`` alone said a connector could not be connected
-    but never why: a premium connector must be enabled by Mammoth sales
-    before this workspace can use it, unlike an ordinary connector nobody has
-    added yet. Without this, an agent that reads ``connector list`` can route
-    a user to sales but never explain why (T2-WPP-W7). ``ConnectorsAPI.list``
-    returns a list, which stays a list.
+    The server's ``is_available`` is the same plan check that gates creating a
+    connection. ``is_premium``/``is_added`` cannot stand in for it: ``is_added``
+    only says a legacy integration row exists, so a premium connector the plan
+    does include read as "not enabled". A response without ``is_available`` (an
+    older server) is left unmarked. ``ConnectorsAPI.list`` returns a list, which
+    stays a list.
     """
     if not isinstance(data, list):
         return data
@@ -172,10 +169,10 @@ def _with_premium_availability(data: Any) -> Any:
         (
             {
                 **item,
-                "availability": _PREMIUM_NOT_ENABLED,
-                "availability_note": _PREMIUM_NOT_ENABLED_NOTE,
+                "availability": _NOT_IN_PLAN,
+                "availability_note": _NOT_IN_PLAN_NOTE,
             }
-            if isinstance(item, dict) and item.get("is_premium") and not item.get("is_added")
+            if isinstance(item, dict) and item.get("is_available") is False
             else item
         )
         for item in data
@@ -187,7 +184,7 @@ def connector_list(invocation: Invocation) -> HandlerResult:
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation))
     return (
-        _with_premium_availability(data),
+        _with_plan_availability(data),
         _meta(invocation, auth.workspace_id, resolved_project(invocation)),
     )
 

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

@@ -10,14 +10,17 @@ seam to the public SDK method named by the command's reviewed manifest
 
 from __future__ import annotations
 
+from collections.abc import Callable
 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,
 )
@@ -358,6 +361,44 @@ def _tag_scope(matches: list[dict[str, Any]], project_id: int) -> list[dict[str,
     return [{**m, "in_project": m.get("project_id") == project_id} for m in matches]
 
 
+def all_projects_requested(invocation: Invocation) -> bool:
+    """Whether ``--input '{"all_projects": true}'`` asks for matches outside the project."""
+    value = (invocation.load_input() or {}).get("all_projects", False)
+    if not isinstance(value, bool):
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message="all_projects must be true or false.",
+            exit_status=EXIT_USAGE,
+        )
+    return value
+
+
+def narrow_to_project(
+    rows: list[dict[str, Any]], is_exact: Callable[[dict[str, Any]], bool]
+) -> tuple[list[dict[str, Any]], int]:
+    """``(rows, dropped)``: only the project's own rows when one of them is an exact match.
+
+    The name already is in the project the call runs under, so the same name in
+    every other project is noise that reads as an ambiguity to ask the user about.
+    Rows must carry ``in_project``. With no exact match in the project, all rows
+    stay: the name may live elsewhere. ``dropped`` counts the rows left out.
+    """
+    own = [r for r in rows if r.get("in_project")]
+    if not any(is_exact(r) for r in own):
+        return rows, 0
+    return own, len(rows) - len(own)
+
+
+def elsewhere_note(dropped: int) -> str:
+    """Says how many matches in other projects were left out, and how to list them."""
+    if not dropped:
+        return ""
+    return (
+        f"{dropped} more match(es) in other projects are not listed: "
+        """--input '{"all_projects": true}' lists them."""
+    )
+
+
 def _find_scoped(
     service: Any,
     needle: str,
@@ -384,11 +425,14 @@ def dataset_find(invocation: Invocation) -> HandlerResult:
     carrying its ``project_id`` and ``project_name``: the in-product agent runs
     every call under the project the user last opened, which is often not the one
     the named dataset is in, so it states where the name is instead of asking the
-    user to switch. Does not require an active project.
+    user to switch. When the project holds an exact match, only the project's own
+    matches are returned and ``elsewhere`` counts the rest; ``--input
+    '{"all_projects": true}'`` returns them all. Does not require an active project.
     """
     name_substring = _require_string_positional(invocation, "name substring")
     needle = name_substring.lower()
     skipped: list[dict[str, Any]] = []
+    dropped = 0
     with open_service(invocation) as (service, auth):
         visible = _visible_projects(service)
         cut = False
@@ -396,6 +440,10 @@ def dataset_find(invocation: Invocation) -> HandlerResult:
             matches, projects, cut = _find_scoped(
                 service, needle, visible, invocation.project, skipped
             )
+            if not all_projects_requested(invocation):
+                matches, dropped = narrow_to_project(
+                    matches, lambda m: str(m.get("name", "")).lower() == needle
+                )
         else:
             projects = visible
             holding, cut = _projects_holding(service, needle, visible)
@@ -412,6 +460,9 @@ def dataset_find(invocation: Invocation) -> HandlerResult:
     if skipped:
         result["projects_skipped"] = skipped
     notes = [ambiguity_note(len(matches), name_substring)]
+    if dropped:
+        result["elsewhere"] = dropped
+        notes.append(elsewhere_note(dropped))
     if cut:
         result["truncated"] = True
         notes.append(search_cut_note("datasets"))
@@ -828,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,
@@ -878,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.62 → mammoth_cli-2.2.64}/mammoth_cli/commands/resolve.py

@@ -14,6 +14,9 @@ from typing import Any
 from mammoth_cli.commands.dataset import (
     _require_string_positional,
     _visible_projects,
+    all_projects_requested,
+    elsewhere_note,
+    narrow_to_project,
     search_cut_note,
     search_hits,
 )
@@ -99,10 +102,11 @@ def kinds_note(name: str, rows: list[dict[str, Any]]) -> str:
 def resolve(invocation: Invocation) -> HandlerResult:
     """Say what NAME refers to: a dataset, a view or a project, with ids and projects.
 
-    Read-only. NAME is a case-insensitive substring and the only argument; the
-    command has no options besides the global ``--project``, which only marks
-    each match ``in_project`` (matches elsewhere are always returned). Searches
-    every project the credential can see. Does not require an active project.
+    Read-only. NAME is a case-insensitive substring. Searches every project the
+    credential can see and marks each match ``in_project`` under ``--project``.
+    When the project holds an exact match, only the project's own matches are
+    returned and ``elsewhere`` counts the rest; ``--input '{"all_projects": true}'``
+    returns them all. Does not require an active project.
     """
     name = _require_string_positional(invocation, "name")
     cut = False
@@ -118,7 +122,13 @@ def resolve(invocation: Invocation) -> HandlerResult:
             "project_id": invocation.project,
         }
     rows = resolve_matches(name, projects, hits, invocation.project)
+    dropped = 0
+    if invocation.project is not None and not all_projects_requested(invocation):
+        rows, dropped = narrow_to_project(rows, lambda r: r["exact"])
     result: dict[str, Any] = {"name": name, "matches": rows, "note": kinds_note(name, rows)}
+    if dropped:
+        result["elsewhere"] = dropped
+        result["note"] += " " + elsewhere_note(dropped)
     if cut:
         result["truncated"] = True
         result["note"] += " " + search_cut_note("datasets or views")

{mammoth_cli-2.2.62 → mammoth_cli-2.2.64}/mammoth_cli/services/command_contract.py

@@ -250,6 +250,8 @@ _PILOT_ADAPTER_INPUTS: dict[str, frozenset[str]] = {
 _LOCAL_CONTRACT_FIELDS: dict[str, tuple[FieldSpec, ...]] = {
     "project.ensure": (FieldSpec("name", required=False, annotation=str),),
     "doctor": (FieldSpec("wait", required=False, annotation=int, default=0),),
+    "resolve": (FieldSpec("all_projects", required=False, annotation=bool, default=False),),
+    "dataset.find": (FieldSpec("all_projects", required=False, annotation=bool, default=False),),
     "schema.get": (FieldSpec("full", required=False, annotation=bool, default=False),),
     "schema.list": (
         FieldSpec("family", required=False, annotation=str | None, default=None),

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

@@ -1,6 +1,6 @@
 [project]
 name = "mammoth-cli"
-version = "2.2.62"
+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.62 → 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