xoople-cli 0.7.0__tar.gz → 0.9.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 (39) hide show
  1. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/PKG-INFO +65 -6
  2. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/README.md +63 -4
  3. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/pyproject.toml +7 -2
  4. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/pyproject.toml.orig +12 -2
  5. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/_context.py +2 -0
  6. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/_errors.py +38 -3
  7. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/_output.py +27 -5
  8. xoople_cli-0.9.0/src/xoople/cli/_skills/manifest.json +14 -0
  9. xoople_cli-0.9.0/src/xoople/cli/_skills/xoople-cli/SKILL.md +461 -0
  10. xoople_cli-0.9.0/src/xoople/cli/_skills/xoople-cli/references/commands.md +201 -0
  11. xoople_cli-0.9.0/src/xoople/cli/_skills/xoople-cli/references/exit-codes.md +36 -0
  12. xoople_cli-0.9.0/src/xoople/cli/_skills/xoople-cli/references/spec-files.md +169 -0
  13. xoople_cli-0.9.0/src/xoople/cli/_skills/xoople-sdk/SKILL.md +427 -0
  14. xoople_cli-0.9.0/src/xoople/cli/_skills/xoople-sdk/references/client.md +301 -0
  15. xoople_cli-0.9.0/src/xoople/cli/_skills/xoople-sdk/references/errors.md +103 -0
  16. xoople_cli-0.9.0/src/xoople/cli/_skills/xoople-sdk/references/reading-results.md +192 -0
  17. xoople_cli-0.9.0/src/xoople/cli/_skills/xoople-sdk/references/requests.md +171 -0
  18. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/_spec.py +24 -0
  19. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/analyses.py +4 -1
  20. xoople_cli-0.9.0/src/xoople/cli/aoi_uploads.py +422 -0
  21. xoople_cli-0.9.0/src/xoople/cli/aois.py +225 -0
  22. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/main.py +30 -3
  23. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/packages.py +2 -2
  24. xoople_cli-0.9.0/src/xoople/cli/skills.py +645 -0
  25. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/LICENSE +0 -0
  26. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/__init__.py +0 -0
  27. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/__main__.py +0 -0
  28. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/_ciam.py +0 -0
  29. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/_version.py +0 -0
  30. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/access.py +0 -0
  31. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/auth.py +0 -0
  32. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/catalog.py +0 -0
  33. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/events.py +0 -0
  34. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/outputs.py +0 -0
  35. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/projects.py +0 -0
  36. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/questions.py +0 -0
  37. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/runs.py +0 -0
  38. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/schedules.py +0 -0
  39. {xoople_cli-0.7.0 → xoople_cli-0.9.0}/src/xoople/cli/usage.py +0 -0
@@ -1,12 +1,12 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: xoople-cli
3
- Version: 0.7.0
3
+ Version: 0.9.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.10.0
9
+ Requires-Dist: xoople-sdk>=0.12.0
10
10
  Requires-Dist: cyclopts>=4.18,<5
11
11
  Requires-Dist: rich>=13.7
12
12
  Requires-Python: >=3.12
@@ -19,7 +19,7 @@ Command-line interface for the Xoople Products API, over [`xoople-sdk`](../xoopl
19
19
 
20
20
  ```console
21
21
  $ uv tool install xoople-cli
22
- $ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_TOKEN=...
22
+ $ export XOOPLE_API_URL=https://api.xoople.com/products XOOPLE_TOKEN=...
23
23
  $ xoople analyses list
24
24
  ```
25
25
 
@@ -39,12 +39,15 @@ the API sends but this SDK version does not declare is dropped.
39
39
  | `outputs` | `list` `get` `access-url` `summary` `preview` `refresh-summary` |
40
40
  | `packages` | `create` `list` `get` `access-url` `delete` |
41
41
  | `schedules` | `list` `get` `create` `pause` `resume` `cancel` `run` `estimate-run` |
42
+ | `aois` | `list` `get` `geometry` `create` `update` `delete` `duplicate` |
43
+ | `aoi-uploads` | `create` `lookup` `get` `rows` `delete` |
42
44
  | `events` | `list` `get` |
43
45
  | `usage` | `history` `limits` |
44
46
  | `catalog` | `products` `measures` `projections` `cloud-mask-presets` `designs` |
45
47
  | `questions` | `list` `show` `ask` |
46
48
  | `access` | `me` `token` `rotate-token` `features` |
47
49
  | `auth` | `login` `logout` `status` |
50
+ | `skills` | `install` `update` `uninstall` `status` |
48
51
 
49
52
  `outputs access-url` works only for a product that declares the
50
53
  `outputs.download` capability, which is Imagery Time Series today. On a tabular
@@ -61,7 +64,7 @@ no `--token` is given, and refreshes it when the
61
64
  access token is close to expiry.
62
65
 
63
66
  ```console
64
- $ export XOOPLE_API_URL=https://api.xoople.com
67
+ $ export XOOPLE_API_URL=https://api.xoople.com/products
65
68
  $ xoople auth login
66
69
  $ xoople analyses list
67
70
  ```
@@ -85,7 +88,7 @@ To work in a different organization, create a key there.
85
88
  Pass the key as the token. It takes precedence over a stored session:
86
89
 
87
90
  ```console
88
- $ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_TOKEN=sk_...
91
+ $ export XOOPLE_API_URL=https://api.xoople.com/products XOOPLE_TOKEN=sk_...
89
92
  $ xoople access me
90
93
  ```
91
94
 
@@ -111,6 +114,61 @@ The file holds either the bare spec or a whole create request (anything with a
111
114
  `spec` key). `-f -` reads stdin. `--wait` polls the initial run and exits
112
115
  non-zero if it does not reach `COMPLETE`.
113
116
 
117
+ ## Saving an area from a file
118
+
119
+ `aoi-uploads create` checks a CSV, xlsx, GeoJSON or zipped Shapefile of at most
120
+ 50 MiB row by row and prints the counts, the first rows that failed or warned,
121
+ and how to fix each reason. The API reads the file after the upload, so the
122
+ command waits for it, up to `--wait-timeout` seconds (default 1200, then exit
123
+ `13`). Nothing is saved yet. `aois create --from-upload`
124
+ saves the accepted rows:
125
+
126
+ ```console
127
+ $ xoople aoi-uploads create orchards.csv --radius 250
128
+ $ xoople aoi-uploads rows <upload-id> --status fail --status warn
129
+ $ xoople aois create --from-upload <upload-id> --name "Orchards"
130
+ ```
131
+
132
+ `aoi-uploads rows --output` saves the rows as a CSV file instead of printing them,
133
+ and prints its path and the number of rows. It takes the rows with status `fail`
134
+ unless you pass `--status`, and refuses `--limit`. Fix the cells in the file and upload
135
+ it again. If the upload is deleted during the download, the file can end early and
136
+ look complete, so download again after any delete or expiry:
137
+
138
+ ```console
139
+ $ xoople aoi-uploads rows <upload-id> --output rejected.csv
140
+ ```
141
+
142
+ A file of addresses (`id,address` and an optional `country`) waits for its lookup.
143
+ `aoi-uploads create` asks on a terminal before it looks them up, because an upload
144
+ counts its unique addresses once on the stored address lookup limit, on the first
145
+ lookup that sends them. Say no and it
146
+ prints how to look them up later and how to delete the upload. With no terminal,
147
+ or with `--json`, it prints the upload and exits `18` unless `--confirm-lookup`
148
+ is set. `aoi-uploads lookup` runs the lookup for an upload that waits:
149
+
150
+ ```console
151
+ $ xoople aoi-uploads create sites.csv --radius 100 --confirm-lookup
152
+ $ xoople aoi-uploads lookup <upload-id>
153
+ ```
154
+
155
+ A 429 or 503 on a lookup prints `retry in N s`. Run `lookup` again after that
156
+ wait. It sends only the addresses with no result, and a retry counts none again,
157
+ except after a 503 `AOI_LOOKUP_NOT_STORED` that came before any address was sent.
158
+ After a timeout the server may still run the lookup. Wait, then run
159
+ `xoople aoi-uploads get <upload-id>`. If the status is no longer `needs_lookup`,
160
+ the lookup finished. An immediate retry answers 409 `AOI_LOOKUP_IN_PROGRESS`. A
161
+ 502 or 504 from a gateway is handled like a timeout. Ctrl-C during a lookup
162
+ prints the same advice and exits `130`.
163
+
164
+ An upload is deleted 24 hours after it is created. `aoi-uploads create` exits `0`
165
+ for an upload with status `failed` (no row accepted, nothing to save), so a script
166
+ reads `status` from `--json` or `aoi-uploads get`. A file the API refuses as a whole
167
+ prints its reason and hint and exits `6`. A 429 or 503 prints
168
+ `retry in N s` when the API sent a `Retry-After`. `aois create -f aoi.json`
169
+ saves an area from a JSON body instead. A file over 50 MiB exits `6` before
170
+ anything is sent.
171
+
114
172
  ## Exit codes
115
173
 
116
174
  `0` success · `1` unexpected CLI error · `2` usage error ·
@@ -120,4 +178,5 @@ non-zero if it does not reach `COMPLETE`.
120
178
  `12` run finished in a non-`COMPLETE` state · `13` `--wait` timed out ·
121
179
  `14` the analysis was deleted · `15` the view a question reads is still
122
180
  being built, ask again shortly · `16` that view's last build failed, refresh
123
- it explicitly; `17` the project was deleted.
181
+ it explicitly; `17` the project was deleted · `18` an upload of addresses waits
182
+ for its lookup · `130` Ctrl-C stopped an address lookup.
@@ -4,7 +4,7 @@ Command-line interface for the Xoople Products API, over [`xoople-sdk`](../xoopl
4
4
 
5
5
  ```console
6
6
  $ uv tool install xoople-cli
7
- $ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_TOKEN=...
7
+ $ export XOOPLE_API_URL=https://api.xoople.com/products XOOPLE_TOKEN=...
8
8
  $ xoople analyses list
9
9
  ```
10
10
 
@@ -24,12 +24,15 @@ the API sends but this SDK version does not declare is dropped.
24
24
  | `outputs` | `list` `get` `access-url` `summary` `preview` `refresh-summary` |
25
25
  | `packages` | `create` `list` `get` `access-url` `delete` |
26
26
  | `schedules` | `list` `get` `create` `pause` `resume` `cancel` `run` `estimate-run` |
27
+ | `aois` | `list` `get` `geometry` `create` `update` `delete` `duplicate` |
28
+ | `aoi-uploads` | `create` `lookup` `get` `rows` `delete` |
27
29
  | `events` | `list` `get` |
28
30
  | `usage` | `history` `limits` |
29
31
  | `catalog` | `products` `measures` `projections` `cloud-mask-presets` `designs` |
30
32
  | `questions` | `list` `show` `ask` |
31
33
  | `access` | `me` `token` `rotate-token` `features` |
32
34
  | `auth` | `login` `logout` `status` |
35
+ | `skills` | `install` `update` `uninstall` `status` |
33
36
 
34
37
  `outputs access-url` works only for a product that declares the
35
38
  `outputs.download` capability, which is Imagery Time Series today. On a tabular
@@ -46,7 +49,7 @@ no `--token` is given, and refreshes it when the
46
49
  access token is close to expiry.
47
50
 
48
51
  ```console
49
- $ export XOOPLE_API_URL=https://api.xoople.com
52
+ $ export XOOPLE_API_URL=https://api.xoople.com/products
50
53
  $ xoople auth login
51
54
  $ xoople analyses list
52
55
  ```
@@ -70,7 +73,7 @@ To work in a different organization, create a key there.
70
73
  Pass the key as the token. It takes precedence over a stored session:
71
74
 
72
75
  ```console
73
- $ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_TOKEN=sk_...
76
+ $ export XOOPLE_API_URL=https://api.xoople.com/products XOOPLE_TOKEN=sk_...
74
77
  $ xoople access me
75
78
  ```
76
79
 
@@ -96,6 +99,61 @@ The file holds either the bare spec or a whole create request (anything with a
96
99
  `spec` key). `-f -` reads stdin. `--wait` polls the initial run and exits
97
100
  non-zero if it does not reach `COMPLETE`.
98
101
 
102
+ ## Saving an area from a file
103
+
104
+ `aoi-uploads create` checks a CSV, xlsx, GeoJSON or zipped Shapefile of at most
105
+ 50 MiB row by row and prints the counts, the first rows that failed or warned,
106
+ and how to fix each reason. The API reads the file after the upload, so the
107
+ command waits for it, up to `--wait-timeout` seconds (default 1200, then exit
108
+ `13`). Nothing is saved yet. `aois create --from-upload`
109
+ saves the accepted rows:
110
+
111
+ ```console
112
+ $ xoople aoi-uploads create orchards.csv --radius 250
113
+ $ xoople aoi-uploads rows <upload-id> --status fail --status warn
114
+ $ xoople aois create --from-upload <upload-id> --name "Orchards"
115
+ ```
116
+
117
+ `aoi-uploads rows --output` saves the rows as a CSV file instead of printing them,
118
+ and prints its path and the number of rows. It takes the rows with status `fail`
119
+ unless you pass `--status`, and refuses `--limit`. Fix the cells in the file and upload
120
+ it again. If the upload is deleted during the download, the file can end early and
121
+ look complete, so download again after any delete or expiry:
122
+
123
+ ```console
124
+ $ xoople aoi-uploads rows <upload-id> --output rejected.csv
125
+ ```
126
+
127
+ A file of addresses (`id,address` and an optional `country`) waits for its lookup.
128
+ `aoi-uploads create` asks on a terminal before it looks them up, because an upload
129
+ counts its unique addresses once on the stored address lookup limit, on the first
130
+ lookup that sends them. Say no and it
131
+ prints how to look them up later and how to delete the upload. With no terminal,
132
+ or with `--json`, it prints the upload and exits `18` unless `--confirm-lookup`
133
+ is set. `aoi-uploads lookup` runs the lookup for an upload that waits:
134
+
135
+ ```console
136
+ $ xoople aoi-uploads create sites.csv --radius 100 --confirm-lookup
137
+ $ xoople aoi-uploads lookup <upload-id>
138
+ ```
139
+
140
+ A 429 or 503 on a lookup prints `retry in N s`. Run `lookup` again after that
141
+ wait. It sends only the addresses with no result, and a retry counts none again,
142
+ except after a 503 `AOI_LOOKUP_NOT_STORED` that came before any address was sent.
143
+ After a timeout the server may still run the lookup. Wait, then run
144
+ `xoople aoi-uploads get <upload-id>`. If the status is no longer `needs_lookup`,
145
+ the lookup finished. An immediate retry answers 409 `AOI_LOOKUP_IN_PROGRESS`. A
146
+ 502 or 504 from a gateway is handled like a timeout. Ctrl-C during a lookup
147
+ prints the same advice and exits `130`.
148
+
149
+ An upload is deleted 24 hours after it is created. `aoi-uploads create` exits `0`
150
+ for an upload with status `failed` (no row accepted, nothing to save), so a script
151
+ reads `status` from `--json` or `aoi-uploads get`. A file the API refuses as a whole
152
+ prints its reason and hint and exits `6`. A 429 or 503 prints
153
+ `retry in N s` when the API sent a `Retry-After`. `aois create -f aoi.json`
154
+ saves an area from a JSON body instead. A file over 50 MiB exits `6` before
155
+ anything is sent.
156
+
99
157
  ## Exit codes
100
158
 
101
159
  `0` success · `1` unexpected CLI error · `2` usage error ·
@@ -105,4 +163,5 @@ non-zero if it does not reach `COMPLETE`.
105
163
  `12` run finished in a non-`COMPLETE` state · `13` `--wait` timed out ·
106
164
  `14` the analysis was deleted · `15` the view a question reads is still
107
165
  being built, ask again shortly · `16` that view's last build failed, refresh
108
- it explicitly; `17` the project was deleted.
166
+ it explicitly; `17` the project was deleted · `18` an upload of addresses waits
167
+ for its lookup · `130` Ctrl-C stopped an address lookup.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "xoople-cli"
3
- version = "0.7.0"
3
+ version = "0.9.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.10.0",
14
+ "xoople-sdk>=0.12.0",
15
15
  "cyclopts>=4.18,<5",
16
16
  "rich>=13.7",
17
17
  ]
@@ -32,6 +32,11 @@ module-name = "xoople.cli"
32
32
  [tool.uv.sources.xoople-sdk]
33
33
  workspace = true
34
34
 
35
+ [tool.ruff]
36
+ extend = "../../pyproject.toml"
37
+ src = ["../.."]
38
+ extend-exclude = ["src/xoople/cli/_skills"]
39
+
35
40
  [dependency-groups]
36
41
  dev = [
37
42
  "ruff>=0.15.7",
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "xoople-cli"
3
- version = "0.7.0"
3
+ version = "0.9.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.10.0",
16
+ "xoople-sdk>=0.12.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
@@ -38,6 +38,16 @@ module-name = "xoople.cli"
38
38
  [tool.uv.sources]
39
39
  xoople-sdk = { workspace = true }
40
40
 
41
+ [tool.ruff]
42
+ extend = "../../pyproject.toml"
43
+ # Resolve imports from the repo root, as the root config does, so `xoople.cli`
44
+ # and `xoople.sdk` sort as one block here and in `tests/`.
45
+ src = ["../.."]
46
+ # `_skills/` is a verbatim copy of `docs/agent-skills/`, checked byte for byte by
47
+ # `test_the_bundled_skills_match_docs_agent_skills`. ruff formats the Python blocks
48
+ # inside its Markdown, which would make `fmt` drift the copy from its source.
49
+ extend-exclude = ["src/xoople/cli/_skills"]
50
+
41
51
  [dependency-groups]
42
52
  dev = [
43
53
  "ruff>=0.15.7",
@@ -5,6 +5,7 @@ from typing import Annotated, Protocol
5
5
  from cyclopts import Parameter
6
6
  from xoople.cli import _ciam
7
7
  from xoople.cli._errors import NotSignedIn, UsageError
8
+ from xoople.cli._output import at_terminal
8
9
  from xoople.cli._version import version as cli_version
9
10
  from xoople.sdk import Config, CredentialProvider, XoopleClient
10
11
  from xoople.sdk import session as session_file
@@ -66,6 +67,7 @@ class Settings:
66
67
  login: LoginRunner = _ciam.login
67
68
  discover: _ciam.ClientIdLookup = ciam_discover_client_id
68
69
  as_json: bool = False
70
+ can_prompt: Callable[[], bool] = at_terminal
69
71
  _client: XoopleClient | None = field(default=None, repr=False)
70
72
 
71
73
  def client(self) -> XoopleClient:
@@ -1,7 +1,10 @@
1
+ import math
2
+
1
3
  from rich.markup import escape
2
4
  from xoople.cli._output import note
3
- from xoople.sdk import errors
5
+ from xoople.sdk import errors, models
4
6
 
7
+ WAIT_TIMEOUT_EXIT = 13
5
8
  EXIT_CODES: dict[type[errors.XoopleError], int] = {
6
9
  errors.AuthenticationError: 3,
7
10
  errors.PermissionDeniedError: 4,
@@ -11,19 +14,24 @@ EXIT_CODES: dict[type[errors.XoopleError], int] = {
11
14
  errors.NotFoundError: 5,
12
15
  errors.BadRequestError: 6,
13
16
  errors.ValidationError: 6,
17
+ errors.UploadTooLargeError: 6,
14
18
  errors.ConflictError: 7,
15
19
  errors.RateLimitError: 8,
16
20
  errors.ServerError: 9,
21
+ errors.UploadParseTimeoutError: WAIT_TIMEOUT_EXIT,
17
22
  errors.XoopleConnectionError: 10,
18
23
  errors.XoopleResponseError: 11,
19
24
  }
25
+ _RETRY_AFTER_STATUSES = frozenset({429, 503})
20
26
  _FALLBACK_EXIT = 1
21
27
  # Generic CLI errors fall back to 1; CLI-only outcomes use the codes below.
22
28
  USAGE_EXIT = 2
23
29
  FAILED_RUN_EXIT = 12
24
- WAIT_TIMEOUT_EXIT = 13
25
30
  QUESTION_COMPUTING_EXIT = 15
26
31
  QUESTION_FAILED_EXIT = 16
32
+ LOOKUP_PENDING_EXIT = 18
33
+ # The shell's convention for a command stopped by Ctrl-C (128 + SIGINT).
34
+ INTERRUPT_EXIT = 130
27
35
 
28
36
 
29
37
  class CliError(Exception):
@@ -82,6 +90,25 @@ class QuestionFailed(CliError):
82
90
  exit_code = QUESTION_FAILED_EXIT
83
91
 
84
92
 
93
+ class LookupPending(CliError):
94
+ """An upload waits for its address lookup, and nothing confirmed it."""
95
+
96
+ exit_code = LOOKUP_PENDING_EXIT
97
+
98
+
99
+ class UploadRefused(CliError):
100
+ """The API read an AOI file and refused it as a whole.
101
+
102
+ Takes the code of the 422 that create answers for a file it refuses before
103
+ it reads it, so a script tests one number for a refused file.
104
+ """
105
+
106
+ exit_code = EXIT_CODES[errors.ValidationError]
107
+
108
+ def __init__(self, issue: models.AoiUploadIssue) -> None:
109
+ super().__init__(f"{issue.code}: {issue.detail} {issue.hint}".strip())
110
+
111
+
85
112
  def exit_code(exc: errors.XoopleError) -> int:
86
113
  for cls, code in EXIT_CODES.items():
87
114
  if isinstance(exc, cls):
@@ -93,7 +120,15 @@ def _describe(exc: errors.XoopleError) -> str:
93
120
  # The API text is data, not markup: a detail that echoes a cell can read like `[red]`.
94
121
  if isinstance(exc, errors.XoopleAPIError):
95
122
  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}"
123
+ wait = (
124
+ f" [dim](retry in {math.ceil(exc.retry_after)} s)[/dim]"
125
+ if exc.retry_after is not None and exc.status in _RETRY_AFTER_STATUSES
126
+ else ""
127
+ )
128
+ return (
129
+ f"[red]error[/red] {exc.status} {escape(str(exc.code))}: "
130
+ f"{escape(str(exc.message))}{wait}{trace}"
131
+ )
97
132
  return f"[red]error[/red] {escape(str(exc))}"
98
133
 
99
134
 
@@ -1,5 +1,6 @@
1
1
  import json
2
- from collections.abc import Iterable, Sequence
2
+ import sys
3
+ from collections.abc import Iterable, Mapping, Sequence
3
4
 
4
5
  from pydantic import BaseModel
5
6
  from rich.console import Console
@@ -100,7 +101,8 @@ def emit_one(model: BaseModel, fields: Sequence[Column], *, as_json: bool) -> No
100
101
  table.add_column(style="bold")
101
102
  table.add_column(overflow="fold")
102
103
  for field in fields:
103
- table.add_row(field[0], _cell(model, field))
104
+ # Literal text: a value can be customer data, such as a file name.
105
+ table.add_row(field[0], Text(_cell(model, field)))
104
106
  _console.print(table)
105
107
 
106
108
 
@@ -153,9 +155,10 @@ def emit_rows(headers: Sequence[str], rows: Iterable[Sequence[object]]) -> None:
153
155
  """
154
156
  table = Table(box=None, pad_edge=False, header_style="bold")
155
157
  for header in headers:
156
- table.add_column(header, overflow="ellipsis", no_wrap=True)
158
+ table.add_column(Text(header), overflow="ellipsis", no_wrap=True)
157
159
  for row in rows:
158
- table.add_row(*(_scalar(cell) for cell in row))
160
+ # Literal text: a cell can be customer data, such as a matched address.
161
+ table.add_row(*(Text(_scalar(cell)) for cell in row))
159
162
  _console.print(table)
160
163
 
161
164
 
@@ -165,10 +168,19 @@ def emit_pairs(pairs: Iterable[tuple[str, object]]) -> None:
165
168
  table.add_column(style="bold")
166
169
  table.add_column(overflow="fold")
167
170
  for name, value in pairs:
168
- table.add_row(name, _scalar(value))
171
+ # Literal text: a value can be a path or a hint with brackets in it.
172
+ table.add_row(name, Text(_scalar(value)))
169
173
  _console.print(table)
170
174
 
171
175
 
176
+ def emit_dict(values: Mapping[str, object], *, as_json: bool) -> None:
177
+ """Render a few named values: a raw JSON object, or name/value lines."""
178
+ if as_json:
179
+ _raw_json(dict(values))
180
+ return
181
+ emit_pairs((name.replace("_", " ").capitalize(), value) for name, value in values.items())
182
+
183
+
172
184
  def heading(text: str) -> None:
173
185
  """A section label for a command that prints more than one table."""
174
186
  _console.print(f"\n[bold]{text}[/bold]")
@@ -184,6 +196,16 @@ def _raw_json(payload: object) -> None:
184
196
  print(json.dumps(payload, indent=2, default=str))
185
197
 
186
198
 
199
+ def interactive() -> bool:
200
+ """Whether stderr is a terminal a person reads, as opposed to a pipe or a log."""
201
+ return _stderr.is_terminal
202
+
203
+
204
+ def at_terminal() -> bool:
205
+ """Whether a person can answer a question: stdin and stdout are both terminals."""
206
+ return sys.stdin.isatty() and _console.is_terminal
207
+
208
+
187
209
  def note(message: str) -> None:
188
210
  """Progress and confirmation text — stderr, so ``--json`` stdout stays parseable."""
189
211
  _stderr.print(message)
@@ -0,0 +1,14 @@
1
+ {
2
+ "version": "0.4.0",
3
+ "files": {
4
+ "xoople-cli/SKILL.md": "cc9610174dc7a66cbde6e153845f1c43099f2c7bc52caf183f4fdb8f5280b201",
5
+ "xoople-cli/references/commands.md": "762f96a0eb4f6bc81722b7b6417d1c650552cdf10449136ceed4610e4e9287e5",
6
+ "xoople-cli/references/exit-codes.md": "97d2958b01edd3c1e6d942fa48845b051bc4e995c5ba0c2b821da02804a99667",
7
+ "xoople-cli/references/spec-files.md": "b7b4281f7e358ca522bf6e3c21ef495738213740b077fe9da68fd0d4d03d4c12",
8
+ "xoople-sdk/SKILL.md": "9eac4fd8d568755f01a31690ceb4e849df6ba7ad0eca9e1d84306cbf27dc84c4",
9
+ "xoople-sdk/references/client.md": "6572f828f13379c16e720a0d47500a789375571e1e76bd76c4fcca1e485631b6",
10
+ "xoople-sdk/references/errors.md": "2ec7ad8aa43438f19228a538fdfc34a92442f1a01fa1349441142d6ca3344a66",
11
+ "xoople-sdk/references/reading-results.md": "79fa6f53748986c61259876564cb0fef1e2ab61bba9e1de041a51b7773d24d24",
12
+ "xoople-sdk/references/requests.md": "4d853ac2477187834ffbcb775b51e533db882050b0e3dc5a32f7170160b05dd4"
13
+ }
14
+ }