asana-api-cli 2.1.1__tar.gz → 3.0.0__tar.gz

{asana_api_cli-2.1.1 → asana_api_cli-3.0.0}/PKG-INFO

@@ -1,20 +1,29 @@
 Metadata-Version: 2.4
 Name: asana-api-cli
-Version: 2.1.1
+Version: 3.0.0
 Summary: Command-line wrapper around the official Asana Python SDK
-Author-email: Masanao Izumo <asana@masanao.site>
+Author: Masanao Izumo
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/izumo-m/asana-api-cli
 Project-URL: Repository, https://github.com/izumo-m/asana-api-cli
 Project-URL: Issues, https://github.com/izumo-m/asana-api-cli/issues
 Project-URL: Changelog, https://github.com/izumo-m/asana-api-cli/blob/main/CHANGELOG.md
+Keywords: asana,cli,python-asana
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Groupware
+Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.0
 Requires-Dist: jq>=1.6
 Requires-Dist: tabulate>=0.9
-Requires-Dist: asana<6,>=5.2
+Requires-Dist: asana<6,>=5.0.2
 Dynamic: license-file
 
 # asana-api-cli
@@ -159,14 +168,14 @@ asana-api workspaces get-workspaces
 asana-api projects get-projects-for-workspace
 asana-api projects get-projects --workspace <WORKSPACE_GID>
 
-# List tasks (first page only by default)
+# List every task in a project (walks every page by default)
 asana-api tasks get-tasks --project <PROJECT_GID>
 
 # Preview the first few items
-asana-api tasks get-tasks --project <PROJECT_GID> --max-items 5
+asana-api tasks get-tasks --project <PROJECT_GID> --item-limit 5
 
-# Fetch every item across pages
-asana-api tasks get-tasks --project <PROJECT_GID> --all-items
+# One HTTP call: return the first page + the next_page cursor
+asana-api tasks get-tasks --project <PROJECT_GID> --limit 100 --full-payload
 
 # Single task
 asana-api tasks get-task --task <TASK_GID>
@@ -203,33 +212,50 @@ the Asana API accepts in place of workspace.
 
 ## Pagination
 
-List commands (e.g. `tasks get-tasks`) return paginated results. The CLI
-provides four ways to control how much is fetched:
-
-| Option | Behavior |
-|--------|----------|
-| (none) | Fetch a single page (Asana default: 100 items) |
-| `--max-items N` | Fetch up to N items, auto-paginating across pages. The last request is automatically capped to the remaining count. |
-| `--all-items` | Fetch every page until the server reports no more |
-| `--offset <TOKEN>` | Manual pagination: pass the `next_page.offset` token from the previous response |
-
-`--max-items` and `--all-items` are mutually exclusive.
-
-`--page-size N` tunes the per-page request size (Asana API requires 1-100,
-default 100). Rarely needed — combine with `--all-items` or `--max-items` only
-when the default doesn't suit (e.g. very large response items).
+Paginatable commands like `tasks get-tasks` expose every pagination input
+of the `python-asana` SDK as a CLI flag. Each flag maps 1:1 to an SDK
+`Configuration` property, `opts` key, or method kwarg, so you can probe
+SDK behavior from the shell before writing any Python.
+
+| CLI flag | SDK input | Effect |
+|----------|-----------|--------|
+| (none) | — | SDK default: walks every page automatically and outputs a flat JSON list of items |
+| `--limit N` | `opts["limit"]` | Per-page size sent to the server (Asana API requires 1-100) |
+| `--offset <TOKEN>` | `opts["offset"]` | Pagination cursor (the `next_page.offset` from a previous response) |
+| `--page-limit N` | `Configuration.page_limit` | Same as `--limit` via Configuration (default: 100). Silently ignored when `--no-return-page-iterator` or `--full-payload` is set |
+| `--item-limit N` | kwarg `item_limit=N` | Stop after N items have been collected. Silently ignored when `--no-return-page-iterator` or `--full-payload` is set |
+| `--return-page-iterator` / `--no-return-page-iterator` | `Configuration.return_page_iterator` | Toggle the SDK page iterator (default: enabled). `--no-return-page-iterator` disables auto-pagination — the command runs one HTTP request and outputs the raw `{data, next_page}` dict |
+| `--full-payload` | kwarg `full_payload=True` | Same effect as `--no-return-page-iterator` (per-call kwarg form) |
 
 ```bash
-# Auto-paginate up to 250 items
-asana-api tasks get-tasks --project <PID> --max-items 250
+# Default: walk every page, return a flat list of items
+asana-api tasks get-tasks --project <PID>
 
-# Fetch everything
-asana-api tasks get-tasks --project <PID> --all-items
+# Cap the result to the first 250 items
+asana-api tasks get-tasks --project <PID> --item-limit 250
 
-# Manual pagination using the offset token
+# Single HTTP call: one page + next_page cursor
+asana-api tasks get-tasks --project <PID> --limit 100 --no-return-page-iterator
+
+# Resume from a cursor
 asana-api tasks get-tasks --project <PID> --offset <TOKEN>
 ```
 
+### Deprecated flags (v2.x → v3.0)
+
+The following v2 flags are retained as deprecation aliases. Each emits a
+stderr warning and forwards to the corresponding v3 flag; they will be
+removed in a future release.
+
+| Deprecated | Replacement |
+|------------|-------------|
+| `--all-items` | (no-op; walking every page is now the default) |
+| `--page-size N` | `--limit N` |
+| `--max-items N` | `--item-limit N` |
+
+Combining a deprecated alias with its v3 counterpart (e.g. `--page-size`
+together with `--limit`) is rejected with a usage error.
+
 ## Global options
 
 These options work at any level of the command tree, so the following are
@@ -242,17 +268,35 @@ asana-api tasks get-tasks --project <PID> --debug
 
 When the same option is given at multiple levels, the later one wins.
 
+Every non-extension flag below maps 1:1 to a property of
+`asana.Configuration` (or a per-call SDK kwarg) — see
+[`docs/cli-sdk-mapping.md`](https://github.com/izumo-m/asana-api-cli/blob/main/docs/cli-sdk-mapping.md)
+for the exact destination of each.
+
 | Option | Description |
 |--------|-------------|
 | `--access-token TOKEN` | Asana personal access token (default: `$ASANA_ACCESS_TOKEN`) |
 | `--host URL` | Override API base URL (default: `https://app.asana.com/api/1.0`) |
 | `--proxy URL` | HTTP/HTTPS proxy URL |
-| `--no-verify-ssl` | Disable TLS certificate verification (insecure) |
-| `--ca-cert PATH` | Path to a PEM bundle of trusted CA certificates |
-| `--retries N` | Number of retries on 429/5xx responses (default: 5) |
-| `--timeout SECONDS` | Per-request timeout in seconds |
-| `--temp-dir PATH` | Directory for temporary downloads |
-| `--debug` | Print HTTP request/response traces for troubleshooting (Authorization values are masked). |
+| `--verify-ssl / --no-verify-ssl` | Toggle TLS certificate verification (default: True) |
+| `--ssl-ca-cert PATH` | Path to a PEM bundle of trusted CA certificates |
+| `--cert-file PATH` | Client TLS certificate for mTLS |
+| `--key-file PATH` | Client TLS private key for mTLS |
+| `--assert-hostname / --no-assert-hostname` | Toggle urllib3 hostname assertion (tri-state: unspecified → urllib3 default) |
+| `--retry-strategy VALUE` | Override `Configuration.retry_strategy` fields. `VALUE` accepts shorthand (`total=5,backoff_factor=1.5,raise_on_status=false`), a JSON object (`'{"total":5,"status_forcelist":[429,500]}'`), or `@path` to a JSON file. List-typed fields require the JSON form. See [`docs/cli-sdk-mapping.md`](https://github.com/izumo-m/asana-api-cli/blob/main/docs/cli-sdk-mapping.md#structured-value-format-api-key-api-key-prefix-retry-strategy) for the field list |
+| `--request-timeout SECONDS` | Per-request timeout in seconds |
+| `--connection-pool-maxsize N` | Max urllib3 connections cached per host (default: cpu_count × 5) |
+| `--temp-folder-path PATH` | Directory for temporary downloads |
+| `--safe-chars-for-path-param S` | Extra characters treated as safe when percent-encoding path parameters |
+| `--logger-format FMT` | Python logging format string for the SDK loggers |
+| `--logger-file PATH` | Path the SDK loggers write to when set |
+| `--multibyte-filenames` | Emit RFC 5987 `filename*=UTF-8''<percent-encoded>` on multipart uploads so Asana decodes non-ASCII attachment filenames correctly |
+| `--debug` | Print HTTP request/response traces to stderr for troubleshooting (`Authorization` values are masked) |
+
+Asana only accepts Bearer-token authentication, so `--username`,
+`--password`, `--api-key`, and `--api-key-prefix` are also exposed for
+1:1 parity with `Configuration` but are inert as of python-asana 5.2.4
+— see the disclosure in [`docs/cli-sdk-mapping.md`](https://github.com/izumo-m/asana-api-cli/blob/main/docs/cli-sdk-mapping.md#no-op-auth-properties).
 
 ## Development
 

asana_api_cli-2.1.1/src/asana_api_cli.egg-info/PKG-INFO → asana_api_cli-3.0.0/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.4
-Name: asana-api-cli
-Version: 2.1.1
-Summary: Command-line wrapper around the official Asana Python SDK
-Author-email: Masanao Izumo <asana@masanao.site>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/izumo-m/asana-api-cli
-Project-URL: Repository, https://github.com/izumo-m/asana-api-cli
-Project-URL: Issues, https://github.com/izumo-m/asana-api-cli/issues
-Project-URL: Changelog, https://github.com/izumo-m/asana-api-cli/blob/main/CHANGELOG.md
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: click>=8.0
-Requires-Dist: jq>=1.6
-Requires-Dist: tabulate>=0.9
-Requires-Dist: asana<6,>=5.2
-Dynamic: license-file
-
 # asana-api-cli
 
 A CLI that exposes **every method of the official
@@ -159,14 +140,14 @@ asana-api workspaces get-workspaces
 asana-api projects get-projects-for-workspace
 asana-api projects get-projects --workspace <WORKSPACE_GID>
 
-# List tasks (first page only by default)
+# List every task in a project (walks every page by default)
 asana-api tasks get-tasks --project <PROJECT_GID>
 
 # Preview the first few items
-asana-api tasks get-tasks --project <PROJECT_GID> --max-items 5
+asana-api tasks get-tasks --project <PROJECT_GID> --item-limit 5
 
-# Fetch every item across pages
-asana-api tasks get-tasks --project <PROJECT_GID> --all-items
+# One HTTP call: return the first page + the next_page cursor
+asana-api tasks get-tasks --project <PROJECT_GID> --limit 100 --full-payload
 
 # Single task
 asana-api tasks get-task --task <TASK_GID>
@@ -203,33 +184,50 @@ the Asana API accepts in place of workspace.
 
 ## Pagination
 
-List commands (e.g. `tasks get-tasks`) return paginated results. The CLI
-provides four ways to control how much is fetched:
-
-| Option | Behavior |
-|--------|----------|
-| (none) | Fetch a single page (Asana default: 100 items) |
-| `--max-items N` | Fetch up to N items, auto-paginating across pages. The last request is automatically capped to the remaining count. |
-| `--all-items` | Fetch every page until the server reports no more |
-| `--offset <TOKEN>` | Manual pagination: pass the `next_page.offset` token from the previous response |
-
-`--max-items` and `--all-items` are mutually exclusive.
-
-`--page-size N` tunes the per-page request size (Asana API requires 1-100,
-default 100). Rarely needed — combine with `--all-items` or `--max-items` only
-when the default doesn't suit (e.g. very large response items).
+Paginatable commands like `tasks get-tasks` expose every pagination input
+of the `python-asana` SDK as a CLI flag. Each flag maps 1:1 to an SDK
+`Configuration` property, `opts` key, or method kwarg, so you can probe
+SDK behavior from the shell before writing any Python.
+
+| CLI flag | SDK input | Effect |
+|----------|-----------|--------|
+| (none) | — | SDK default: walks every page automatically and outputs a flat JSON list of items |
+| `--limit N` | `opts["limit"]` | Per-page size sent to the server (Asana API requires 1-100) |
+| `--offset <TOKEN>` | `opts["offset"]` | Pagination cursor (the `next_page.offset` from a previous response) |
+| `--page-limit N` | `Configuration.page_limit` | Same as `--limit` via Configuration (default: 100). Silently ignored when `--no-return-page-iterator` or `--full-payload` is set |
+| `--item-limit N` | kwarg `item_limit=N` | Stop after N items have been collected. Silently ignored when `--no-return-page-iterator` or `--full-payload` is set |
+| `--return-page-iterator` / `--no-return-page-iterator` | `Configuration.return_page_iterator` | Toggle the SDK page iterator (default: enabled). `--no-return-page-iterator` disables auto-pagination — the command runs one HTTP request and outputs the raw `{data, next_page}` dict |
+| `--full-payload` | kwarg `full_payload=True` | Same effect as `--no-return-page-iterator` (per-call kwarg form) |
 
 ```bash
-# Auto-paginate up to 250 items
-asana-api tasks get-tasks --project <PID> --max-items 250
+# Default: walk every page, return a flat list of items
+asana-api tasks get-tasks --project <PID>
+
+# Cap the result to the first 250 items
+asana-api tasks get-tasks --project <PID> --item-limit 250
 
-# Fetch everything
-asana-api tasks get-tasks --project <PID> --all-items
+# Single HTTP call: one page + next_page cursor
+asana-api tasks get-tasks --project <PID> --limit 100 --no-return-page-iterator
 
-# Manual pagination using the offset token
+# Resume from a cursor
 asana-api tasks get-tasks --project <PID> --offset <TOKEN>
 ```
 
+### Deprecated flags (v2.x → v3.0)
+
+The following v2 flags are retained as deprecation aliases. Each emits a
+stderr warning and forwards to the corresponding v3 flag; they will be
+removed in a future release.
+
+| Deprecated | Replacement |
+|------------|-------------|
+| `--all-items` | (no-op; walking every page is now the default) |
+| `--page-size N` | `--limit N` |
+| `--max-items N` | `--item-limit N` |
+
+Combining a deprecated alias with its v3 counterpart (e.g. `--page-size`
+together with `--limit`) is rejected with a usage error.
+
 ## Global options
 
 These options work at any level of the command tree, so the following are
@@ -242,17 +240,35 @@ asana-api tasks get-tasks --project <PID> --debug
 
 When the same option is given at multiple levels, the later one wins.
 
+Every non-extension flag below maps 1:1 to a property of
+`asana.Configuration` (or a per-call SDK kwarg) — see
+[`docs/cli-sdk-mapping.md`](https://github.com/izumo-m/asana-api-cli/blob/main/docs/cli-sdk-mapping.md)
+for the exact destination of each.
+
 | Option | Description |
 |--------|-------------|
 | `--access-token TOKEN` | Asana personal access token (default: `$ASANA_ACCESS_TOKEN`) |
 | `--host URL` | Override API base URL (default: `https://app.asana.com/api/1.0`) |
 | `--proxy URL` | HTTP/HTTPS proxy URL |
-| `--no-verify-ssl` | Disable TLS certificate verification (insecure) |
-| `--ca-cert PATH` | Path to a PEM bundle of trusted CA certificates |
-| `--retries N` | Number of retries on 429/5xx responses (default: 5) |
-| `--timeout SECONDS` | Per-request timeout in seconds |
-| `--temp-dir PATH` | Directory for temporary downloads |
-| `--debug` | Print HTTP request/response traces for troubleshooting (Authorization values are masked). |
+| `--verify-ssl / --no-verify-ssl` | Toggle TLS certificate verification (default: True) |
+| `--ssl-ca-cert PATH` | Path to a PEM bundle of trusted CA certificates |
+| `--cert-file PATH` | Client TLS certificate for mTLS |
+| `--key-file PATH` | Client TLS private key for mTLS |
+| `--assert-hostname / --no-assert-hostname` | Toggle urllib3 hostname assertion (tri-state: unspecified → urllib3 default) |
+| `--retry-strategy VALUE` | Override `Configuration.retry_strategy` fields. `VALUE` accepts shorthand (`total=5,backoff_factor=1.5,raise_on_status=false`), a JSON object (`'{"total":5,"status_forcelist":[429,500]}'`), or `@path` to a JSON file. List-typed fields require the JSON form. See [`docs/cli-sdk-mapping.md`](https://github.com/izumo-m/asana-api-cli/blob/main/docs/cli-sdk-mapping.md#structured-value-format-api-key-api-key-prefix-retry-strategy) for the field list |
+| `--request-timeout SECONDS` | Per-request timeout in seconds |
+| `--connection-pool-maxsize N` | Max urllib3 connections cached per host (default: cpu_count × 5) |
+| `--temp-folder-path PATH` | Directory for temporary downloads |
+| `--safe-chars-for-path-param S` | Extra characters treated as safe when percent-encoding path parameters |
+| `--logger-format FMT` | Python logging format string for the SDK loggers |
+| `--logger-file PATH` | Path the SDK loggers write to when set |
+| `--multibyte-filenames` | Emit RFC 5987 `filename*=UTF-8''<percent-encoded>` on multipart uploads so Asana decodes non-ASCII attachment filenames correctly |
+| `--debug` | Print HTTP request/response traces to stderr for troubleshooting (`Authorization` values are masked) |
+
+Asana only accepts Bearer-token authentication, so `--username`,
+`--password`, `--api-key`, and `--api-key-prefix` are also exposed for
+1:1 parity with `Configuration` but are inert as of python-asana 5.2.4
+— see the disclosure in [`docs/cli-sdk-mapping.md`](https://github.com/izumo-m/asana-api-cli/blob/main/docs/cli-sdk-mapping.md#no-op-auth-properties).
 
 ## Development
 

{asana_api_cli-2.1.1 → asana_api_cli-3.0.0}/pyproject.toml

@@ -1,16 +1,27 @@
 [project]
 name = "asana-api-cli"
-version = "2.1.1"
+version = "3.0.0"
 description = "Command-line wrapper around the official Asana Python SDK"
-authors = [{name = "Masanao Izumo", email = "asana@masanao.site"}]
+authors = [{name = "Masanao Izumo"}]
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
+keywords = ["asana", "cli", "python-asana"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Office/Business :: Groupware",
+    "Topic :: Utilities",
+]
 dependencies = [
     "click>=8.0",
     "jq>=1.6",
     "tabulate>=0.9",
-    "asana>=5.2,<6",
+    "asana>=5.0.2,<6",
 ]
 
 [project.urls]
@@ -30,6 +41,8 @@ dev = [
     "build>=1,<2",
     "twine>=6,<7",
     "vermin>=1.6,<2",
+    "vcrpy>=6",
+    "pytest-recording>=0.13",
 ]
 
 [build-system]
@@ -80,5 +93,6 @@ no_parse_comments = true
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["tests"]
 addopts = ""
 disable_test_id_escaping_and_forfeit_all_rights_to_community_support = true