pushmetrics-cli 0.1.0__py3-none-any.whl

pm/commands/db.py

@@ -0,0 +1,291 @@
+"""Database commands."""
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.commands._helpers import json_option, limit_option, name_filter_option, select_rows
+from pm.output import emit
+
+
+@click.group(name="db", cls=AliasedGroup, aliases={"ls": "list"})
+def db() -> None:
+    """Databases, their schemas and tables.
+
+    DB_REF is the database uid or name.
+    """
+
+
+@db.command(name="list")
+@name_filter_option
+@limit_option
+@json_option
+@click.pass_context
+def ls(ctx: click.Context, name_filter: Optional[str], limit: Optional[int]) -> None:
+    """List databases configured in the current workspace."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    items = select_rows(
+        client.databases.list(), name=name_filter, fields=("database_name",), limit=limit
+    )
+    client.persist()
+
+    emit(
+        items,
+        json_output=json_output,
+        columns=[
+            ("UID", "uid"),
+            ("NAME", "database_name"),
+            ("BACKEND", "backend"),
+        ],
+    )
+
+
+@db.command(name="schemas")
+@click.argument("db_ref")
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Bypass the cached schema list and refresh from the source.",
+)
+@json_option
+@click.pass_context
+def schemas(ctx: click.Context, db_ref: str, force: bool) -> None:
+    """List the schemas in a database."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    names = client.databases.schemas(db_ref, force=force)
+    client.persist()
+
+    if json_output:
+        emit(names, json_output=True)
+        return
+
+    emit(
+        [{"name": s} for s in names],
+        json_output=False,
+        columns=[("SCHEMA", "name")],
+    )
+
+
+@db.command(name="tables")
+@click.argument("db_ref")
+@click.argument("schema")
+@json_option
+@click.pass_context
+def tables(ctx: click.Context, db_ref: str, schema: str) -> None:
+    """List the tables and views in a schema."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    items = client.databases.tables(db_ref, schema)
+    client.persist()
+
+    emit(
+        items,
+        json_output=json_output,
+        columns=[
+            ("NAME", "name"),
+            ("TYPE", "type"),
+        ],
+    )
+
+
+@db.command(name="describe")
+@click.argument("db_ref")
+@click.argument("schema")
+@click.argument("table")
+@json_option
+@click.pass_context
+def describe(ctx: click.Context, db_ref: str, schema: str, table: str) -> None:
+    """Show a table's columns, keys and indexes."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    meta = client.databases.table_metadata(db_ref, table, schema)
+    client.persist()
+
+    if json_output:
+        emit(meta, json_output=True)
+        return
+
+    click.echo(f"Table: {schema}.{table}")
+    if meta.get("comment"):
+        click.echo(f"Comment: {meta['comment']}")
+
+    cols = meta.get("columns") or []
+    if cols:
+        click.echo("")
+        emit(
+            cols,
+            json_output=False,
+            columns=[
+                ("NAME", "name"),
+                ("TYPE", "longType"),
+                ("KEYS", lambda r: ",".join(
+                    k.get("type", "") for k in (r.get("keys") or [])
+                )),
+                ("COMMENT", lambda r: r.get("comment") or ""),
+            ],
+        )
+
+    fks = meta.get("foreignKeys") or []
+    if fks:
+        click.echo("")
+        click.echo("Foreign keys:")
+        for fk in fks:
+            src = ", ".join(fk.get("column_names") or [])
+            ref_table = fk.get("referred_table") or "?"
+            ref_cols = ", ".join(fk.get("referred_columns") or [])
+            ref_schema = fk.get("referred_schema") or ""
+            ref_full = f"{ref_schema}.{ref_table}" if ref_schema else ref_table
+            click.echo(f"  ({src}) -> {ref_full}({ref_cols})")
+
+
+@db.command(name="select-star")
+@click.argument("db_ref")
+@click.argument("schema")
+@click.argument("table")
+@click.option(
+    "--limit",
+    type=int,
+    default=100,
+    show_default=True,
+    help="Row limit written into the generated SQL (max 10000).",
+)
+@json_option
+@click.pass_context
+def select_star(
+    ctx: click.Context, db_ref: str, schema: str, table: str, limit: int
+) -> None:
+    """Print a SELECT * statement for a table (not run)."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    sql = client.databases.select_star_sql(db_ref, table, schema, limit=limit)
+    client.persist()
+
+    if json_output:
+        emit({"sql": sql}, json_output=True)
+        return
+    click.echo(sql)
+
+
+@db.command(name="exists")
+@click.argument("db_ref")
+@click.argument("schema")
+@click.argument("table")
+@json_option
+@click.pass_context
+def exists(ctx: click.Context, db_ref: str, schema: str, table: str) -> None:
+    """Check whether a table or view exists.
+
+    Exits 0 if it exists and 1 if not, so it works in shell conditions:
+    if pm database exists ...; then ...; fi. With --json the exit code is
+    always 0 and the "exists" field carries the answer.
+    """
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    info = client.databases.table_exists(db_ref, table, schema)
+    client.persist()
+
+    if json_output:
+        emit(info, json_output=True)
+        # In --json mode (agent / programmatic), exit cleanly — the JSON
+        # carries the boolean. Exit-code signalling is reserved for shell
+        # use of the human-readable mode below.
+        return
+    kind = info.get("type") or "-"
+    resolved = info.get("resolved_name") or "-"
+    click.echo(f"exists={info.get('exists')} type={kind} resolved={resolved}")
+    if not info.get("exists"):
+        ctx.exit(1)
+
+
+@db.command(name="functions")
+@click.argument("db_ref")
+@click.option(
+    "--filter",
+    "filter_",
+    default="",
+    help="Keep only names containing this text (case-insensitive).",
+)
+@click.option(
+    "--limit",
+    type=int,
+    default=100,
+    show_default=True,
+    help="Maximum number of names to return (max 500).",
+)
+@json_option
+@click.pass_context
+def functions(ctx: click.Context, db_ref: str, filter_: str, limit: int) -> None:
+    """List the SQL functions the database supports."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    result = client.databases.function_names(db_ref, filter=filter_, limit=limit)
+    client.persist()
+
+    if json_output:
+        emit(result, json_output=True)
+        return
+
+    note = result.get("note")
+    if note:
+        click.echo(f"Note: {note}")
+        return
+
+    for name in result.get("functions") or []:
+        click.echo(name)
+    total = result.get("total", 0)
+    count = result.get("count", 0)
+    if total and count < total:
+        click.echo(f"-- truncated: {count} of {total} (pass --limit to widen).")
+
+
+@db.command(name="search")
+@click.argument("db_ref")
+@click.argument("pattern")
+@click.option(
+    "--schema",
+    default="",
+    help="Search one schema only (default: every non-system schema).",
+)
+@json_option
+@click.pass_context
+def search(ctx: click.Context, db_ref: str, pattern: str, schema: str) -> None:
+    """Find tables and views whose name contains PATTERN."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    result = client.databases.search_tables(db_ref, pattern, schema=schema)
+    client.persist()
+
+    if json_output:
+        emit(result, json_output=True)
+        return
+
+    emit(
+        result.get("results") or [],
+        json_output=False,
+        columns=[
+            ("SCHEMA", "schema"),
+            ("NAME", "name"),
+            ("TYPE", "type"),
+        ],
+    )

pm/commands/email.py

@@ -0,0 +1,13 @@
+"""`pm email` — create + send email blocks."""
+from __future__ import annotations
+
+from pm.commands._block_factory import make_block_group
+
+
+email = make_block_group(
+    "email",
+    "email",
+    help_text="Email blocks.\n\nBlock type: email.",
+    crud_verbs=("create", "list", "get"),
+    execute_verb="send",
+)

pm/commands/explore.py

@@ -0,0 +1,20 @@
+"""`pm explore` — create explore (saved-view) blocks.
+
+No execute verb today — explore blocks are saved-view definitions that
+the UI renders; there's no server-side "run" path that produces a
+deliverable artifact. ``list`` and ``get`` are exposed for parity with
+the other typed-block groups so an agent that guesses ``pm explore
+list`` lands on a working command instead of an error envelope (prod
+session Gn6eNEko2y, 2026-06-09).
+"""
+from __future__ import annotations
+
+from pm.commands._block_factory import make_block_group
+
+
+explore = make_block_group(
+    "explore",
+    "explore",
+    help_text="Explore blocks (saved data views).\n\nBlock type: explore.",
+    crud_verbs=("create", "list", "get", "update"),
+)

pm/commands/favorites.py

@@ -0,0 +1,77 @@
+"""Favorite commands (ls/create/delete only — backend supports more but FE doesn't)."""
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.commands._helpers import (
+    confirm_delete,
+    json_option,
+    merge_fields,
+    parse_data,
+    report_deleted,
+    yes_option,
+    limit_option,
+    select_rows,
+)
+from pm.output import emit
+
+
+@click.group(name="favorites", cls=AliasedGroup, aliases={"ls": "list"})
+def favorites() -> None:
+    """Your favorite reports and other objects."""
+
+
+@favorites.command(name="list")
+@limit_option
+@json_option
+@click.pass_context
+def ls(ctx: click.Context, limit: Optional[int]) -> None:
+    """List your favorites."""
+    client = PMClient.from_profile(ctx.obj["profile"])
+    items = select_rows(client.favorites.list(), limit=limit)
+    client.persist()
+    emit(
+        items,
+        json_output=ctx.obj["json"],
+        columns=[
+            ("UID", "uid"),
+            ("CLASS", "class_name"),
+            ("OBJ_ID", "obj_id"),
+        ],
+    )
+
+
+@favorites.command(name="create")
+@click.option("--class-name", required=True,
+              help="Kind of object to favorite, e.g. Report.")
+@click.option("--obj-id", type=int, required=True,
+              help="Numeric id of the object (from pm report get --json).")
+@click.option("--data", default=None, help="Extra fields as a JSON object.")
+@json_option
+@click.pass_context
+def create(ctx: click.Context, class_name: str, obj_id: int, data: Optional[str]) -> None:
+    """Add an object to your favorites."""
+    payload = merge_fields(parse_data(data), {"class_name": class_name, "obj_id": obj_id})
+    client = PMClient.from_profile(ctx.obj["profile"])
+    fav = client.favorites.create(payload)
+    client.persist()
+    emit(fav, json_output=ctx.obj["json"])
+
+
+@favorites.command(name="delete")
+@click.argument("uid")
+@yes_option
+@json_option
+@click.pass_context
+def delete(ctx: click.Context, uid: str, yes: bool) -> None:
+    """Remove a favorite."""
+    if not yes:
+        confirm_delete("favorite", uid)
+    client = PMClient.from_profile(ctx.obj["profile"])
+    client.favorites.delete(uid)
+    client.persist()
+    report_deleted(ctx, "favorite", uid)

pm/commands/folders.py

@@ -0,0 +1,113 @@
+"""Folder commands (full CRUD)."""
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.commands._helpers import (
+    confirm_delete,
+    json_option,
+    merge_fields,
+    parse_data,
+    peek_name,
+    report_deleted,
+    yes_option,
+    limit_option,
+    name_filter_option,
+    select_rows,
+)
+from pm.output import emit
+
+
+@click.group(name="folders", cls=AliasedGroup, aliases={"ls": "list"})
+def folders() -> None:
+    """Folders that organize reports."""
+
+
+@folders.command(name="list")
+@name_filter_option
+@limit_option
+@json_option
+@click.pass_context
+def ls(ctx: click.Context, name_filter: Optional[str], limit: Optional[int]) -> None:
+    """List folders in the current workspace."""
+    client = PMClient.from_profile(ctx.obj["profile"])
+    items = select_rows(client.folders.list(), name=name_filter, limit=limit)
+    client.persist()
+    emit(
+        items,
+        json_output=ctx.obj["json"],
+        columns=[("UID", "uid"), ("NAME", "name"), ("PARENT_ID", "parent_id"), ("ID", "id")],
+    )
+
+
+@folders.command(name="get")
+@click.argument("uid")
+@json_option
+@click.pass_context
+def get(ctx: click.Context, uid: str) -> None:
+    """Show one folder."""
+    client = PMClient.from_profile(ctx.obj["profile"])
+    folder = client.folders.get(uid)
+    client.persist()
+    emit(folder, json_output=ctx.obj["json"])
+
+
+@folders.command(name="create")
+@click.option("--name", required=True, help="Folder name.")
+@click.option("--parent-id", type=int, default=None,
+              help="Numeric id of the parent folder (from pm folder list). Default: top level.")
+@click.option("--data", default=None, help="Extra fields as a JSON object.")
+@json_option
+@click.pass_context
+def create(ctx: click.Context, name: str, parent_id: Optional[int], data: Optional[str]) -> None:
+    """Create a folder."""
+    payload = merge_fields(parse_data(data), {"name": name, "parent_id": parent_id})
+    client = PMClient.from_profile(ctx.obj["profile"])
+    folder = client.folders.create(payload)
+    client.persist()
+    emit(folder, json_output=ctx.obj["json"])
+
+
+@folders.command(name="update")
+@click.argument("uid")
+@click.option("--name", default=None, help="Rename the folder.")
+@click.option("--parent-id", type=int, default=None,
+              help="Move under this parent folder (numeric id from pm folder list).")
+@click.option("--data", default=None, help="Extra fields as a JSON object.")
+@json_option
+@click.pass_context
+def update(
+    ctx: click.Context,
+    uid: str,
+    name: Optional[str],
+    parent_id: Optional[int],
+    data: Optional[str],
+) -> None:
+    """Update a folder."""
+    payload = merge_fields(parse_data(data), {"name": name, "parent_id": parent_id})
+    if not payload:
+        raise click.UsageError("Nothing to update; pass --name, --parent-id, or --data.")
+    client = PMClient.from_profile(ctx.obj["profile"])
+    folder = client.folders.update(uid, payload)
+    client.persist()
+    emit(folder, json_output=ctx.obj["json"])
+
+
+@folders.command(name="delete")
+@click.argument("uid")
+@yes_option
+@json_option
+@click.pass_context
+def delete(ctx: click.Context, uid: str, yes: bool) -> None:
+    """Delete a folder."""
+    if not yes:
+        name = peek_name(lambda: PMClient.from_profile(ctx.obj["profile"]).folders.get(uid), "name")
+        confirm_delete("folder", uid, name)
+    client = PMClient.from_profile(ctx.obj["profile"])
+    client.folders.delete(uid)
+    client.persist()
+    report_deleted(ctx, "folder", uid)