xoople-cli 0.5.0__tar.gz → 0.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/PKG-INFO +26 -11
  2. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/README.md +24 -9
  3. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/pyproject.toml +2 -2
  4. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/pyproject.toml.orig +2 -2
  5. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/_context.py +4 -2
  6. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/_errors.py +31 -4
  7. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/_output.py +55 -0
  8. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/access.py +3 -3
  9. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/analyses.py +16 -1
  10. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/auth.py +2 -2
  11. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/catalog.py +2 -2
  12. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/main.py +4 -1
  13. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/outputs.py +45 -1
  14. xoople_cli-0.7.0/src/xoople/cli/questions.py +209 -0
  15. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/usage.py +15 -1
  16. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/LICENSE +0 -0
  17. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/__init__.py +0 -0
  18. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/__main__.py +0 -0
  19. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/_ciam.py +0 -0
  20. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/_spec.py +0 -0
  21. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/_version.py +0 -0
  22. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/events.py +0 -0
  23. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/packages.py +0 -0
  24. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/projects.py +0 -0
  25. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/runs.py +0 -0
  26. {xoople_cli-0.5.0 → xoople_cli-0.7.0}/src/xoople/cli/schedules.py +0 -0
@@ -1,12 +1,12 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: xoople-cli
3
- Version: 0.5.0
3
+ Version: 0.7.0
4
4
  Summary: Command-line interface for the Xoople Products API.
5
5
  License-Expression: LicenseRef-Xoople-Proprietary
6
6
  License-File: LICENSE
7
7
  Classifier: Development Status :: 3 - Alpha
8
8
  Classifier: Programming Language :: Python :: 3.12
9
- Requires-Dist: xoople-sdk>=0.7.0
9
+ Requires-Dist: xoople-sdk>=0.10.0
10
10
  Requires-Dist: cyclopts>=4.18,<5
11
11
  Requires-Dist: rich>=13.7
12
12
  Requires-Python: >=3.12
@@ -24,23 +24,34 @@ $ xoople analyses list
24
24
  ```
25
25
 
26
26
  Every command reads `--api-url` and `--token` from `XOOPLE_API_URL` and
27
- `XOOPLE_TOKEN`. `--json` prints the API response verbatim instead of a table, so
28
- output pipes into `jq`.
27
+ `XOOPLE_TOKEN`. `--json` prints the response as the SDK parses it instead of a
28
+ table, so output pipes into `jq`. Every field the SDK model declares appears, and
29
+ one the API leaves out uses the SDK model's default, which may be `null`. A field
30
+ the API sends but this SDK version does not declare is dropped.
29
31
 
30
32
  ## Commands
31
33
 
32
34
  | Group | Commands |
33
35
  | --- | --- |
34
- | `analyses` | `list` `get` `create` `update` `cancel` `estimate` |
36
+ | `analyses` | `list` `get` `status` `create` `update` `cancel` `delete` `run-again` `estimate-run-again` `estimate` |
37
+ | `projects` | `list` `create` `get` `update` `members` `add-member` `remove-member` `move` `archive` `delete` `record-access` `recent` |
35
38
  | `runs` | `list` `get` |
36
- | `outputs` | `list` `get` `access-url` |
39
+ | `outputs` | `list` `get` `access-url` `summary` `preview` `refresh-summary` |
40
+ | `packages` | `create` `list` `get` `access-url` `delete` |
37
41
  | `schedules` | `list` `get` `create` `pause` `resume` `cancel` `run` `estimate-run` |
38
42
  | `events` | `list` `get` |
39
43
  | `usage` | `history` `limits` |
40
- | `catalog` | `products` `measures` `designs` |
41
- | `access` | `me` `token` `features` |
44
+ | `catalog` | `products` `measures` `projections` `cloud-mask-presets` `designs` |
45
+ | `questions` | `list` `show` `ask` |
46
+ | `access` | `me` `token` `rotate-token` `features` |
42
47
  | `auth` | `login` `logout` `status` |
43
48
 
49
+ `outputs access-url` works only for a product that declares the
50
+ `outputs.download` capability, which is Imagery Time Series today. On a tabular
51
+ output the API answers 422 `unsupported_operation` and the CLI exits `6`. Read
52
+ tabular rows over Delta Sharing (`access token`), or export a Tabular Time Series
53
+ analysis with `packages create`.
54
+
44
55
  ## Signing in
45
56
 
46
57
  `auth login` signs in through the browser with PKCE and stores the session at
@@ -89,11 +100,13 @@ The product spec is deeply nested and differs per product, so `create` and
89
100
  `estimate` take it as JSON rather than as flags:
90
101
 
91
102
  ```console
92
- $ xoople catalog designs --json | jq '.[0].spec_fragment' > spec.json
93
- $ # fill in period and aoi, then:
103
+ $ xoople catalog designs --product tabular_time_series --json | jq '.[0].spec_fragment | {product: "tabular_time_series", period: {start: "2024-01-01", end: "2024-06-30"}, aoi: [-1.5, 52.0, -1.0, 52.5], spatial_partition: {type: "h3", target_cells: 5000}, measures}' > spec.json
94
104
  $ xoople analyses create -f spec.json --display-name "South Wales NDVI" --wait
95
105
  ```
96
106
 
107
+ A design's `spec_fragment` holds only what to measure, so the `jq` filter adds the
108
+ product, period, area and grid around its `measures`. The cadence defaults to monthly.
109
+
97
110
  The file holds either the bare spec or a whole create request (anything with a
98
111
  `spec` key). `-f -` reads stdin. `--wait` polls the initial run and exits
99
112
  non-zero if it does not reach `COMPLETE`.
@@ -105,4 +118,6 @@ non-zero if it does not reach `COMPLETE`.
105
118
  `5` not found · `6` bad request or validation · `7` conflict · `8` rate limited ·
106
119
  `9` server error · `10` connection failure · `11` unreadable response ·
107
120
  `12` run finished in a non-`COMPLETE` state · `13` `--wait` timed out ·
108
- `14` the analysis was deleted.
121
+ `14` the analysis was deleted · `15` the view a question reads is still
122
+ being built, ask again shortly · `16` that view's last build failed, refresh
123
+ it explicitly; `17` the project was deleted.
@@ -9,23 +9,34 @@ $ xoople analyses list
9
9
  ```
10
10
 
11
11
  Every command reads `--api-url` and `--token` from `XOOPLE_API_URL` and
12
- `XOOPLE_TOKEN`. `--json` prints the API response verbatim instead of a table, so
13
- output pipes into `jq`.
12
+ `XOOPLE_TOKEN`. `--json` prints the response as the SDK parses it instead of a
13
+ table, so output pipes into `jq`. Every field the SDK model declares appears, and
14
+ one the API leaves out uses the SDK model's default, which may be `null`. A field
15
+ the API sends but this SDK version does not declare is dropped.
14
16
 
15
17
  ## Commands
16
18
 
17
19
  | Group | Commands |
18
20
  | --- | --- |
19
- | `analyses` | `list` `get` `create` `update` `cancel` `estimate` |
21
+ | `analyses` | `list` `get` `status` `create` `update` `cancel` `delete` `run-again` `estimate-run-again` `estimate` |
22
+ | `projects` | `list` `create` `get` `update` `members` `add-member` `remove-member` `move` `archive` `delete` `record-access` `recent` |
20
23
  | `runs` | `list` `get` |
21
- | `outputs` | `list` `get` `access-url` |
24
+ | `outputs` | `list` `get` `access-url` `summary` `preview` `refresh-summary` |
25
+ | `packages` | `create` `list` `get` `access-url` `delete` |
22
26
  | `schedules` | `list` `get` `create` `pause` `resume` `cancel` `run` `estimate-run` |
23
27
  | `events` | `list` `get` |
24
28
  | `usage` | `history` `limits` |
25
- | `catalog` | `products` `measures` `designs` |
26
- | `access` | `me` `token` `features` |
29
+ | `catalog` | `products` `measures` `projections` `cloud-mask-presets` `designs` |
30
+ | `questions` | `list` `show` `ask` |
31
+ | `access` | `me` `token` `rotate-token` `features` |
27
32
  | `auth` | `login` `logout` `status` |
28
33
 
34
+ `outputs access-url` works only for a product that declares the
35
+ `outputs.download` capability, which is Imagery Time Series today. On a tabular
36
+ output the API answers 422 `unsupported_operation` and the CLI exits `6`. Read
37
+ tabular rows over Delta Sharing (`access token`), or export a Tabular Time Series
38
+ analysis with `packages create`.
39
+
29
40
  ## Signing in
30
41
 
31
42
  `auth login` signs in through the browser with PKCE and stores the session at
@@ -74,11 +85,13 @@ The product spec is deeply nested and differs per product, so `create` and
74
85
  `estimate` take it as JSON rather than as flags:
75
86
 
76
87
  ```console
77
- $ xoople catalog designs --json | jq '.[0].spec_fragment' > spec.json
78
- $ # fill in period and aoi, then:
88
+ $ xoople catalog designs --product tabular_time_series --json | jq '.[0].spec_fragment | {product: "tabular_time_series", period: {start: "2024-01-01", end: "2024-06-30"}, aoi: [-1.5, 52.0, -1.0, 52.5], spatial_partition: {type: "h3", target_cells: 5000}, measures}' > spec.json
79
89
  $ xoople analyses create -f spec.json --display-name "South Wales NDVI" --wait
80
90
  ```
81
91
 
92
+ A design's `spec_fragment` holds only what to measure, so the `jq` filter adds the
93
+ product, period, area and grid around its `measures`. The cadence defaults to monthly.
94
+
82
95
  The file holds either the bare spec or a whole create request (anything with a
83
96
  `spec` key). `-f -` reads stdin. `--wait` polls the initial run and exits
84
97
  non-zero if it does not reach `COMPLETE`.
@@ -90,4 +103,6 @@ non-zero if it does not reach `COMPLETE`.
90
103
  `5` not found · `6` bad request or validation · `7` conflict · `8` rate limited ·
91
104
  `9` server error · `10` connection failure · `11` unreadable response ·
92
105
  `12` run finished in a non-`COMPLETE` state · `13` `--wait` timed out ·
93
- `14` the analysis was deleted.
106
+ `14` the analysis was deleted · `15` the view a question reads is still
107
+ being built, ask again shortly · `16` that view's last build failed, refresh
108
+ it explicitly; `17` the project was deleted.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "xoople-cli"
3
- version = "0.5.0"
3
+ version = "0.7.0"
4
4
  description = "Command-line interface for the Xoople Products API."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -11,7 +11,7 @@ classifiers = [
11
11
  "Programming Language :: Python :: 3.12",
12
12
  ]
13
13
  dependencies = [
14
- "xoople-sdk>=0.7.0",
14
+ "xoople-sdk>=0.10.0",
15
15
  "cyclopts>=4.18,<5",
16
16
  "rich>=13.7",
17
17
  ]
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "xoople-cli"
3
- version = "0.5.0"
3
+ version = "0.7.0"
4
4
  description = "Command-line interface for the Xoople Products API."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -13,7 +13,7 @@ classifiers = [
13
13
  "Programming Language :: Python :: 3.12",
14
14
  ]
15
15
  dependencies = [
16
- "xoople-sdk>=0.7.0",
16
+ "xoople-sdk>=0.10.0",
17
17
  # Cyclopts parses docstrings for parameter help so signatures stay plain,
18
18
  # supports union types and Pydantic models natively, and owns its parser.
19
19
  # Global options + dependency injection go through the meta-app launcher
@@ -4,7 +4,8 @@ from typing import Annotated, Protocol
4
4
 
5
5
  from cyclopts import Parameter
6
6
  from xoople.cli import _ciam
7
- from xoople.cli._errors import UsageError
7
+ from xoople.cli._errors import NotSignedIn, UsageError
8
+ from xoople.cli._version import version as cli_version
8
9
  from xoople.sdk import Config, CredentialProvider, XoopleClient
9
10
  from xoople.sdk import session as session_file
10
11
  from xoople.sdk.auth import (
@@ -90,7 +91,7 @@ def _credential_provider(credentials: Credentials) -> CredentialProvider:
90
91
  # The credential refreshes a user token itself. Store what it mints, so
91
92
  # the next run does not spend another refresh token.
92
93
  return CiamUserCredentials(session, on_refresh=_persist_session)
93
- raise UsageError("no credentials: run `xoople auth login`, pass --token, or set XOOPLE_TOKEN")
94
+ raise NotSignedIn("no credentials: run `xoople auth login`, pass --token, or set XOOPLE_TOKEN")
94
95
 
95
96
 
96
97
  def build_client(credentials: Credentials) -> XoopleClient:
@@ -108,5 +109,6 @@ def build_client(credentials: Credentials) -> XoopleClient:
108
109
  credentials=_credential_provider(credentials),
109
110
  timeout=credentials.timeout,
110
111
  max_retries=credentials.max_retries,
112
+ user_agent_prefix=f"xoople-cli/{cli_version()}",
111
113
  )
112
114
  )
@@ -1,3 +1,4 @@
1
+ from rich.markup import escape
1
2
  from xoople.cli._output import note
2
3
  from xoople.sdk import errors
3
4
 
@@ -6,6 +7,7 @@ EXIT_CODES: dict[type[errors.XoopleError], int] = {
6
7
  errors.PermissionDeniedError: 4,
7
8
  # Before its parent: `exit_code` takes the first class the error is an instance of.
8
9
  errors.AnalysisDeletedError: 14,
10
+ errors.ProjectDeletedError: 17,
9
11
  errors.NotFoundError: 5,
10
12
  errors.BadRequestError: 6,
11
13
  errors.ValidationError: 6,
@@ -20,6 +22,8 @@ _FALLBACK_EXIT = 1
20
22
  USAGE_EXIT = 2
21
23
  FAILED_RUN_EXIT = 12
22
24
  WAIT_TIMEOUT_EXIT = 13
25
+ QUESTION_COMPUTING_EXIT = 15
26
+ QUESTION_FAILED_EXIT = 16
23
27
 
24
28
 
25
29
  class CliError(Exception):
@@ -44,6 +48,16 @@ class LoginFailed(CliError):
44
48
  exit_code = EXIT_CODES[errors.AuthenticationError]
45
49
 
46
50
 
51
+ class NotSignedIn(CliError):
52
+ """A command needs a credential and there is none to send.
53
+
54
+ Takes the API's unauthenticated code, like `LoginFailed`, so a script tests
55
+ one number for "sign in first".
56
+ """
57
+
58
+ exit_code = EXIT_CODES[errors.AuthenticationError]
59
+
60
+
47
61
  class RunFailed(CliError):
48
62
  """``--wait`` finished, but the run ended in a non-``COMPLETE`` state."""
49
63
 
@@ -56,6 +70,18 @@ class WaitTimeout(CliError):
56
70
  exit_code = WAIT_TIMEOUT_EXIT
57
71
 
58
72
 
73
+ class QuestionComputing(CliError):
74
+ """The view a question reads is still being built; ask again shortly."""
75
+
76
+ exit_code = QUESTION_COMPUTING_EXIT
77
+
78
+
79
+ class QuestionFailed(CliError):
80
+ """The last build of the view a question reads failed; refresh it explicitly."""
81
+
82
+ exit_code = QUESTION_FAILED_EXIT
83
+
84
+
59
85
  def exit_code(exc: errors.XoopleError) -> int:
60
86
  for cls, code in EXIT_CODES.items():
61
87
  if isinstance(exc, cls):
@@ -64,10 +90,11 @@ def exit_code(exc: errors.XoopleError) -> int:
64
90
 
65
91
 
66
92
  def _describe(exc: errors.XoopleError) -> str:
93
+ # The API text is data, not markup: a detail that echoes a cell can read like `[red]`.
67
94
  if isinstance(exc, errors.XoopleAPIError):
68
- trace = f" [dim](trace {exc.trace_id})[/dim]" if exc.trace_id else ""
69
- return f"[red]error[/red] {exc.status} {exc.code}: {exc.message}{trace}"
70
- return f"[red]error[/red] {exc}"
95
+ trace = f" [dim](trace {escape(str(exc.trace_id))})[/dim]" if exc.trace_id else ""
96
+ return f"[red]error[/red] {exc.status} {escape(str(exc.code))}: {escape(str(exc.message))}{trace}"
97
+ return f"[red]error[/red] {escape(str(exc))}"
71
98
 
72
99
 
73
100
  def report(exc: errors.XoopleError | CliError) -> int:
@@ -80,5 +107,5 @@ def report(exc: errors.XoopleError | CliError) -> int:
80
107
  if isinstance(exc, errors.XoopleError):
81
108
  note(_describe(exc))
82
109
  return exit_code(exc)
83
- note(f"[red]error[/red] {exc}")
110
+ note(f"[red]error[/red] {escape(str(exc))}")
84
111
  return exc.exit_code
@@ -4,6 +4,7 @@ from collections.abc import Iterable, Sequence
4
4
  from pydantic import BaseModel
5
5
  from rich.console import Console
6
6
  from rich.table import Table
7
+ from rich.text import Text
7
8
 
8
9
  type Column = tuple[str, str]
9
10
 
@@ -103,6 +104,36 @@ def emit_one(model: BaseModel, fields: Sequence[Column], *, as_json: bool) -> No
103
104
  _console.print(table)
104
105
 
105
106
 
107
+ def emit_grid(
108
+ model: BaseModel,
109
+ headers: Sequence[str],
110
+ rows: Iterable[Sequence[object]],
111
+ *,
112
+ as_json: bool,
113
+ ) -> None:
114
+ """Render positional rows under their headers: raw JSON of the whole
115
+ response, or a table whose columns come from the data, not a declared list."""
116
+ if as_json:
117
+ _raw_json(model.model_dump(mode="json", by_alias=True))
118
+ return
119
+ items = [list(row) for row in rows]
120
+ if not items:
121
+ _stderr.print("[dim]no rows[/dim]")
122
+ return
123
+ # Literal text throughout: a cell is customer data (a feature id can read
124
+ # like rich markup) and a measure keeps its full precision.
125
+ table = Table(box=None, pad_edge=False, header_style="bold")
126
+ for header in headers:
127
+ table.add_column(Text(header), overflow="ellipsis", no_wrap=True)
128
+ for row in items:
129
+ table.add_row(*(Text(_grid_cell(value)) for value in row))
130
+ _console.print(table)
131
+
132
+
133
+ def _grid_cell(value: object) -> str:
134
+ return repr(value) if isinstance(value, float) else _scalar(value)
135
+
136
+
106
137
  def emit_model(model: BaseModel, *, as_json: bool) -> None:
107
138
  """Render every declared field of a single resource.
108
139
 
@@ -114,6 +145,30 @@ def emit_model(model: BaseModel, *, as_json: bool) -> None:
114
145
  emit_one(model, fields, as_json=as_json)
115
146
 
116
147
 
148
+ def emit_rows(headers: Sequence[str], rows: Iterable[Sequence[object]]) -> None:
149
+ """Render rows that are already positional — a question's answer, say.
150
+
151
+ Goes through the same console as `emit`, so piped output does not depend
152
+ on the width of the terminal that launched it.
153
+ """
154
+ table = Table(box=None, pad_edge=False, header_style="bold")
155
+ for header in headers:
156
+ table.add_column(header, overflow="ellipsis", no_wrap=True)
157
+ for row in rows:
158
+ table.add_row(*(_scalar(cell) for cell in row))
159
+ _console.print(table)
160
+
161
+
162
+ def emit_pairs(pairs: Iterable[tuple[str, object]]) -> None:
163
+ """Render name/value lines for values that are not a model's fields."""
164
+ table = Table(box=None, pad_edge=False, show_header=False)
165
+ table.add_column(style="bold")
166
+ table.add_column(overflow="fold")
167
+ for name, value in pairs:
168
+ table.add_row(name, _scalar(value))
169
+ _console.print(table)
170
+
171
+
117
172
  def heading(text: str) -> None:
118
173
  """A section label for a command that prints more than one table."""
119
174
  _console.print(f"\n[bold]{text}[/bold]")
@@ -8,7 +8,7 @@ from xoople.cli._output import emit, emit_model
8
8
 
9
9
  app = App(
10
10
  name="access",
11
- help="Delta Sharing credentials and feature flags for your account.",
11
+ help="Delta Sharing credentials and preview features for your account.",
12
12
  )
13
13
 
14
14
 
@@ -67,7 +67,7 @@ def rotate_token(
67
67
 
68
68
  @app.command(name="features")
69
69
  def features(*, settings: SettingsParam) -> None:
70
- """Show which feature flags are on for you, and why."""
70
+ """Show which preview features are on for you, and why."""
71
71
  result = settings.client().features.get()
72
72
  if settings.as_json:
73
73
  emit_model(result, as_json=True)
@@ -78,6 +78,6 @@ def features(*, settings: SettingsParam) -> None:
78
78
  ]
79
79
  emit(
80
80
  flags,
81
- [("FLAG", "flag"), ("ON", "value"), ("REASON", "reason")],
81
+ [("PREVIEW FEATURE", "flag"), ("ON", "value"), ("REASON", "reason")],
82
82
  as_json=False,
83
83
  )
@@ -29,7 +29,7 @@ FIELDS = [
29
29
  ("UID", "uid"),
30
30
  ("Display name", "display_name"),
31
31
  ("Product", "product"),
32
- ("Product version", "product_version"),
32
+ ("Schema version", "schema_version"),
33
33
  ("Output schema outdated", "output_schema_outdated"),
34
34
  ("State", "state"),
35
35
  ("State message", "state_message"),
@@ -179,6 +179,21 @@ def cancel(analysis: str, *, settings: SettingsParam) -> None:
179
179
  emit_one(settings.client().analyses.cancel(analysis), FIELDS, as_json=settings.as_json)
180
180
 
181
181
 
182
+ @app.command(name="delete")
183
+ def delete(analysis: str, *, settings: SettingsParam) -> None:
184
+ """Delete a settled analysis and its outputs.
185
+
186
+ Removal runs in the background, so the analysis shows as DELETING. Once it
187
+ finishes, `analyses get` exits with the deleted-analysis code.
188
+
189
+ Parameters
190
+ ----------
191
+ analysis:
192
+ The analysis to delete. Needs its owner; cancel a running analysis first.
193
+ """
194
+ emit_one(settings.client().analyses.delete(analysis), FIELDS, as_json=settings.as_json)
195
+
196
+
182
197
  @app.command(name="run-again")
183
198
  def run_again(
184
199
  analysis: str,
@@ -2,7 +2,7 @@ from cyclopts import App
2
2
  from pydantic import BaseModel
3
3
  from xoople.cli import _ciam
4
4
  from xoople.cli._context import SettingsParam
5
- from xoople.cli._errors import LoginFailed
5
+ from xoople.cli._errors import LoginFailed, NotSignedIn
6
6
  from xoople.cli._output import emit_one, note
7
7
  from xoople.sdk import session as session_file
8
8
  from xoople.sdk.auth import normalize_api_url
@@ -65,6 +65,6 @@ def status(*, settings: SettingsParam) -> None:
65
65
  """Show who the stored session belongs to, and when it expires."""
66
66
  session = session_file.read_session()
67
67
  if session is None:
68
- raise LoginFailed("no stored session: run `xoople auth login`")
68
+ raise NotSignedIn("no stored session: run `xoople auth login`")
69
69
  row = _StatusRow(email=session.email, org_id=session.org_id, expires_at=session.expires_at)
70
70
  emit_one(row, FIELDS, as_json=settings.as_json)
@@ -17,7 +17,7 @@ def products(*, settings: SettingsParam) -> None:
17
17
  [
18
18
  ("ID", "product_id"),
19
19
  ("NAME", "display_name"),
20
- ("VERSION", "version"),
20
+ ("SCHEMA VERSION", "schema_version"),
21
21
  ("LIFECYCLE", "lifecycle"),
22
22
  ("OUTPUTS", "output_kinds"),
23
23
  ],
@@ -121,7 +121,7 @@ def cloud_mask_presets(*, settings: SettingsParam) -> None:
121
121
 
122
122
  @app.command(name="designs")
123
123
  def designs(*, settings: SettingsParam, product: str | None = None) -> None:
124
- """List the starting-point analysis designs. Their `spec_fragment` seeds a spec file.
124
+ """List the starting-point analysis designs. Their `spec_fragment` seeds measures or bands only.
125
125
 
126
126
  Parameters
127
127
  ----------
@@ -10,6 +10,7 @@ from xoople.cli import (
10
10
  outputs,
11
11
  packages,
12
12
  projects,
13
+ questions,
13
14
  runs,
14
15
  schedules,
15
16
  usage,
@@ -56,6 +57,7 @@ def create_app(
56
57
  app.command(events.app)
57
58
  app.command(usage.app)
58
59
  app.command(catalog.app)
60
+ app.command(questions.app)
59
61
  app.command(access.app)
60
62
  app.command(auth.app)
61
63
 
@@ -91,7 +93,8 @@ def create_app(
91
93
  max_retries:
92
94
  Retries for replay-safe requests on 429 and 5xx.
93
95
  json_output:
94
- Print the raw API response instead of a table.
96
+ Print the response as the SDK parses it instead of a table.
97
+ Missing fields use the SDK model's default, which may be null.
95
98
  """
96
99
  if not tokens:
97
100
  # Bare invocation prints help rather than erroring — a deliberate
@@ -2,7 +2,7 @@ from typing import Annotated
2
2
 
3
3
  from cyclopts import App, Parameter
4
4
  from xoople.cli._context import SettingsParam, at_least_one
5
- from xoople.cli._output import emit, emit_model
5
+ from xoople.cli._output import emit, emit_grid, emit_model, note
6
6
 
7
7
  app = App(
8
8
  name="outputs",
@@ -62,6 +62,11 @@ def access_url(
62
62
  ) -> None:
63
63
  """Mint a time-limited download URL for an output.
64
64
 
65
+ Only products that declare the `outputs.download` capability support this,
66
+ which is Imagery Time Series today. A tabular output answers 422
67
+ `unsupported_operation` (exit 6); read it over Delta Sharing (`access token`)
68
+ or export a Tabular Time Series one with `packages create`.
69
+
65
70
  Parameters
66
71
  ----------
67
72
  analysis:
@@ -94,6 +99,45 @@ def summary(analysis: str, output: str, *, settings: SettingsParam) -> None:
94
99
  )
95
100
 
96
101
 
102
+ @app.command(name="preview")
103
+ def preview(
104
+ analysis: str,
105
+ output: str,
106
+ *,
107
+ settings: SettingsParam,
108
+ limit: Annotated[int | None, Parameter(validator=at_least_one)] = None,
109
+ columns: str | None = None,
110
+ ) -> None:
111
+ """Show the first rows of an output's table, in no particular order.
112
+
113
+ Parameters
114
+ ----------
115
+ analysis:
116
+ The analysis the output belongs to.
117
+ output:
118
+ The output whose rows to show.
119
+ limit:
120
+ Rows to show, up to 100 (also the default). For every row, read the
121
+ table instead.
122
+ columns:
123
+ Comma-separated column names to show, in this order; omit for every column.
124
+ """
125
+ result = settings.client().analyses.outputs.get_preview(
126
+ analysis,
127
+ output,
128
+ limit=limit,
129
+ columns=[name.strip() for name in columns.split(",")] if columns is not None else None,
130
+ )
131
+ emit_grid(
132
+ result,
133
+ [column.name for column in result.columns],
134
+ result.rows,
135
+ as_json=settings.as_json,
136
+ )
137
+ if result.truncated and not settings.as_json:
138
+ note(f"[dim]showing the first {len(result.rows)} rows; the table holds more[/dim]")
139
+
140
+
97
141
  @app.command(name="refresh-summary")
98
142
  def refresh_summary(analysis: str, output: str, *, settings: SettingsParam) -> None:
99
143
  """Start (or join) an asynchronous recomputation of an output's summary.
@@ -0,0 +1,209 @@
1
+ """Browse the question catalogue and ask one of a completed output."""
2
+
3
+ from typing import Annotated
4
+
5
+ from cyclopts import App, Parameter
6
+ from xoople.cli._context import SettingsParam
7
+ from xoople.cli._errors import CliError, QuestionComputing, QuestionFailed, UsageError
8
+ from xoople.cli._output import emit, emit_model, emit_pairs, emit_rows, heading, note
9
+ from xoople.sdk import XoopleClient
10
+ from xoople.sdk.answers import QuestionAnswer
11
+
12
+ app = App(
13
+ name="questions",
14
+ help="Browse the questions an output can answer, and ask one.",
15
+ )
16
+
17
+ _CATALOG_COLUMNS = [
18
+ ("ID", "id"),
19
+ ("QUESTION", "question"),
20
+ ("CATEGORY", "category"),
21
+ ("RESULT", "result_kind"),
22
+ ("MEASURE", "requires_measure"),
23
+ ]
24
+
25
+
26
+ @app.command(name="list")
27
+ def list_questions(
28
+ *,
29
+ settings: SettingsParam,
30
+ analysis: str | None = None,
31
+ output: str | None = None,
32
+ category: list[str] | None = None,
33
+ available: bool = False,
34
+ ) -> None:
35
+ """List the questions that can be asked.
36
+
37
+ Without an analysis this is the product catalogue, which answers before
38
+ anything has run. With one, each entry says whether that output can
39
+ answer it and what to do when it cannot.
40
+
41
+ Parameters
42
+ ----------
43
+ analysis:
44
+ Narrow the catalogue to one analysis's output.
45
+ output:
46
+ Which output of that analysis; defaults to its primary table.
47
+ category:
48
+ Only these categories. Repeat to pass several.
49
+ available:
50
+ With an analysis, hide the questions this output cannot answer.
51
+ """
52
+ client = settings.client()
53
+ if analysis is None:
54
+ result = client.questions.list(category=category)
55
+ emit(result.questions, _CATALOG_COLUMNS, as_json=settings.as_json)
56
+ return
57
+
58
+ bound = client.analyses.outputs.list_questions(
59
+ analysis, _resolve_output(client, analysis, output)
60
+ )
61
+ entries = [
62
+ entry
63
+ for entry in bound.questions or []
64
+ if (not available or entry.available)
65
+ and (not category or entry.question.category in category)
66
+ ]
67
+ if settings.as_json:
68
+ emit_model(bound.model_copy(update={"questions": entries}), as_json=True)
69
+ return
70
+ note(
71
+ f"measures: {', '.join(bound.measures or [])} · "
72
+ f"grid: {bound.grid or '-'} · summary: {bound.summary_status} · "
73
+ f"grid build: {bound.sampler_status}"
74
+ )
75
+ if not entries:
76
+ note("no matching questions")
77
+ return
78
+ emit_rows(
79
+ ("ID", "QUESTION", "ASKABLE", "WHY NOT"),
80
+ [
81
+ (
82
+ entry.question.id,
83
+ entry.question.question,
84
+ entry.available,
85
+ entry.unavailable_reason,
86
+ )
87
+ for entry in entries
88
+ ],
89
+ )
90
+
91
+
92
+ @app.command(name="show")
93
+ def show(question: str, *, settings: SettingsParam) -> None:
94
+ """Show one question's parameters and what it needs an output to carry.
95
+
96
+ Parameters
97
+ ----------
98
+ question:
99
+ The question id, as `questions list` prints it.
100
+ """
101
+ result = settings.client().questions.list()
102
+ entry = next((item for item in result.questions or [] if item.id == question), None)
103
+ if entry is None:
104
+ raise CliError(f"unknown question: {question}")
105
+ if settings.as_json:
106
+ emit_model(entry, as_json=True)
107
+ return
108
+ emit_model(entry, as_json=False)
109
+ heading("parameters")
110
+ emit(
111
+ entry.parameters or [],
112
+ [
113
+ ("NAME", "name"),
114
+ ("TYPE", "type"),
115
+ ("REQUIRED", "required"),
116
+ ("DEFAULT", "default"),
117
+ ("DESCRIPTION", "description"),
118
+ ],
119
+ as_json=False,
120
+ )
121
+
122
+
123
+ @app.command(name="ask")
124
+ def ask(
125
+ analysis: str,
126
+ question: str,
127
+ *,
128
+ settings: SettingsParam,
129
+ output: str | None = None,
130
+ param: Annotated[list[str] | None, Parameter(name="--param")] = None,
131
+ ) -> None:
132
+ """Ask one question of an analysis's output.
133
+
134
+ Parameters
135
+ ----------
136
+ analysis:
137
+ The analysis whose output to ask about.
138
+ question:
139
+ The question id, as `questions list` prints it.
140
+ output:
141
+ Which output to ask about; defaults to the analysis's primary table.
142
+ param:
143
+ A `name=value` parameter. Repeat for several; `questions show` lists
144
+ what each question accepts.
145
+ """
146
+ client = settings.client()
147
+ answer = client.analyses.outputs.ask(
148
+ analysis,
149
+ _resolve_output(client, analysis, output),
150
+ question,
151
+ **_parameters(param or []),
152
+ )
153
+ if settings.as_json:
154
+ emit_model(answer.response, as_json=True)
155
+ else:
156
+ _print_answer(answer)
157
+ # The payload is out either way; the exit code says it is not an answer yet.
158
+ if answer.computing:
159
+ raise QuestionComputing(answer.response.answer)
160
+ if answer.failed:
161
+ raise QuestionFailed(answer.response.answer)
162
+
163
+
164
+ def _print_answer(answer: QuestionAnswer) -> None:
165
+ response = answer.response
166
+ if response.status != "ANSWERED":
167
+ return
168
+ note(response.answer)
169
+ if response.rows:
170
+ emit_rows(
171
+ [
172
+ f"{column.name} ({column.unit})" if column.unit else column.name
173
+ for column in response.columns or []
174
+ ],
175
+ response.rows,
176
+ )
177
+ if response.totals:
178
+ heading("totals")
179
+ emit_pairs(response.totals.items())
180
+ for caveat in response.caveats or []:
181
+ note(f"[yellow]note[/yellow] {caveat}")
182
+
183
+
184
+ def _parameters(values: list[str]) -> dict[str, bool | int | float | str | None]:
185
+ """`name=value` pairs, sent as typed.
186
+
187
+ The question's schema converts and validates server-side, so a number
188
+ travels as the text it was typed as and `period=2024` stays a string.
189
+ Only a boolean needs reading here, because the schema takes no text for one.
190
+ """
191
+ parsed: dict[str, bool | int | float | str | None] = {}
192
+ for item in values:
193
+ name, separator, raw = item.partition("=")
194
+ if not separator or not name:
195
+ raise UsageError(f"--param expects name=value, got {item!r}")
196
+ parsed[name] = raw.lower() == "true" if raw.lower() in ("true", "false") else raw
197
+ return parsed
198
+
199
+
200
+ def _resolve_output(client: XoopleClient, analysis: str, output: str | None) -> str:
201
+ """The named output, or the analysis's only table output."""
202
+ if output is not None:
203
+ return output
204
+ outputs = [
205
+ item for item in client.analyses.outputs.list(analysis) if item.kind == "delta_table"
206
+ ]
207
+ if not outputs:
208
+ raise CliError(f"analysis {analysis} has no table output to ask about")
209
+ return str(outputs[0].uid)
@@ -27,6 +27,13 @@ PRODUCT_COLUMNS = [
27
27
  ("LABEL", "unit_label"),
28
28
  ]
29
29
 
30
+ METER_LIMIT_COLUMNS = [
31
+ ("METER", "meter"),
32
+ ("COUNTS", "label"),
33
+ ("USED", "used"),
34
+ ("MONTHLY LIMIT", "cap"),
35
+ ]
36
+
30
37
  WINDOW_COLUMNS = [
31
38
  ("DIMENSION", "dimension"),
32
39
  ("LIMIT", "limit"),
@@ -84,7 +91,11 @@ def history(
84
91
 
85
92
  @app.command(name="limits")
86
93
  def limits(*, settings: SettingsParam) -> None:
87
- """Show current-period consumption, and the quota windows in force for each product."""
94
+ """Show current-period consumption, quota windows and monthly limits.
95
+
96
+ Quota windows are the ones in force for each product. The monthly limits are the
97
+ caps on costly routes, such as place search, and appear for an organization read only.
98
+ """
88
99
  result = settings.client().usage.limits()
89
100
  if settings.as_json:
90
101
  emit_model(result, as_json=True)
@@ -97,3 +108,6 @@ def limits(*, settings: SettingsParam) -> None:
97
108
  continue
98
109
  heading(f"{summary.product} quota")
99
110
  emit(summary.quota_status.windows, WINDOW_COLUMNS, as_json=False)
111
+ if result.meter_limits:
112
+ heading("monthly limits")
113
+ emit(result.meter_limits, METER_LIMIT_COLUMNS, as_json=False)
File without changes