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

{asana_api_cli-2.1.0/src/asana_api_cli.egg-info → asana_api_cli-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asana-api-cli
-Version: 2.1.0
+Version: 2.1.1
 Summary: Command-line wrapper around the official Asana Python SDK
 Author-email: Masanao Izumo <asana@masanao.site>
 License-Expression: MIT

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

@@ -1,6 +1,6 @@
 [project]
 name = "asana-api-cli"
-version = "2.1.0"
+version = "2.1.1"
 description = "Command-line wrapper around the official Asana Python SDK"
 authors = [{name = "Masanao Izumo", email = "asana@masanao.site"}]
 readme = "README.md"

{asana_api_cli-2.1.0 → asana_api_cli-2.1.1}/src/asana_api_cli/cli.py

@@ -276,23 +276,6 @@ def _operations_for(api_cls: type) -> list[_Operation]:
 # ---------------------------------------------------------------------------
 
 
-def _resolve_effective_page_size(page_size: int | None, max_items: int | None) -> int | None:
-    """Return the per-page size to request when ``--max-items`` caps the total.
-
-    Only shrink below the natural per-page size (100, Asana's max) when
-    ``--max-items`` is *smaller* than what we would otherwise request — that
-    way a single trailing page is not wasted. When ``--max-items`` is larger,
-    keep the user's explicit ``--page-size`` (or fall back to the SDK default
-    of 100); shrinking to ``--max-items`` would push the per-request ``limit``
-    above the Asana API cap of 100 and produce a 400 response.
-    """
-    if max_items is None:
-        return page_size
-    if max_items < (page_size or 100):
-        return max_items
-    return page_size
-
-
 def _make_command(api_cls: type, op: _Operation) -> click.Command:
     """Build a :class:`CommandWithGlobalOptions` for a single SDK method."""
     # If the SDK method has no ``opts`` parameter, docstring-derived named
@@ -327,6 +310,9 @@ def _make_command(api_cls: type, op: _Operation) -> click.Command:
         flag = f"--{opt_name.replace('_', '-')}"
         dp = op.params.get(name)
         help_text = _escape_help(dp.description) if dp else ""
+        if name != opt_name:
+            suffix = f"(SDK kwarg: {name})"
+            help_text = f"{help_text} {suffix}".strip() if help_text else suffix
         options.append(click.Option([flag], required=True, help=help_text))
 
     # Unified --workspace option. The env-var fallback only applies when the
@@ -420,18 +406,10 @@ def _make_command(api_cls: type, op: _Operation) -> click.Command:
         if all_items and max_items is not None:
             raise click.UsageError("--max-items cannot be combined with --all-items")
 
-        # --max-items 0 makes no API call; skip session creation so we don't
-        # briefly set Configuration.page_limit = 0 (derived from max_items)
-        # on a session we immediately discard.
-        if max_items == 0:
-            return []
-
-        effective_page_size = _resolve_effective_page_size(page_size, max_items)
+        want_iter = paginatable and (all_items or max_items is not None)
 
         if paginatable:
-            session_ctx = AsanaSession.from_env(
-                use_page_iterator=all_items, page_size=effective_page_size
-            )
+            session_ctx = AsanaSession.from_env(use_page_iterator=want_iter, page_size=page_size)
         else:
             session_ctx = AsanaSession.from_env()
 
@@ -459,17 +437,24 @@ def _make_command(api_cls: type, op: _Operation) -> click.Command:
                     call_args.append(kwargs.pop(_option_name(name)))
 
             method = getattr(api, op.method_name)
+            # ``--max-items N`` maps to the SDK's native ``item_limit`` kwarg
+            # on paginated methods: PageIterator caps the per-call ``limit``
+            # to ``min(page_limit, item_limit - count)`` and stops at exactly
+            # N items.
+            method_kwargs: dict[str, Any] = {}
             if paginatable and max_items is not None:
-                return session.fetch_capped(method, *call_args, opts=opts, max_items=max_items)
-            result = method(*call_args, opts) if op.has_opts else method(*call_args)
-            # When --all-items is active the SDK returns a PageIterator
-            # that lazily issues an HTTP request per page on iteration.
-            # The formatter would otherwise iterate it after this ``with``
-            # block exits — that is, after the debug redactor has been
-            # uninstalled — leaking Authorization headers on every page
-            # past the first. Consume it here so every page request lands
-            # while the session (and its redactor) is still live.
-            if paginatable and all_items:
+                method_kwargs["item_limit"] = max_items
+            result = (
+                method(*call_args, opts, **method_kwargs) if op.has_opts else method(*call_args)
+            )
+            # When the SDK returns a PageIterator it lazily issues an HTTP
+            # request per page on iteration. The formatter would otherwise
+            # iterate it after this ``with`` block exits — that is, after
+            # the debug redactor has been uninstalled — leaking Authorization
+            # headers on every page past the first. Consume it here so every
+            # page request lands while the session (and its redactor) is
+            # still live.
+            if want_iter:
                 result = list(result)
             return result
 

{asana_api_cli-2.1.0 → asana_api_cli-2.1.1}/src/asana_api_cli/session.py

@@ -286,7 +286,6 @@ class AsanaSession:
         # When --page-size is set, override the SDK default per-page size (100).
         if page_size is not None:
             config.page_limit = page_size
-        self._page_size = page_size
 
         # Apply runtime values to Configuration
         if runtime.host:
@@ -382,54 +381,6 @@ class AsanaSession:
             sys.exit(1)
         return cls(token=token, use_page_iterator=use_page_iterator, page_size=page_size)
 
-    def fetch_capped(
-        self,
-        api_method: Callable[..., Any],
-        *args: Any,
-        opts: dict[str, Any],
-        max_items: int,
-    ) -> list[Any]:
-        """Fetch up to *max_items* items by manually walking ``next_page.offset``.
-
-        The last request is automatically capped to the remaining count so we
-        do not overfetch. Returns a flat list of items, matching the shape
-        produced by ``--all-items``.
-        """
-        # Disable the SDK's PageIterator path for the duration of these calls.
-        config = self._client.configuration
-        original = config.return_page_iterator
-        config.return_page_iterator = False
-        try:
-            page_size_default = self._page_size if self._page_size is not None else 100
-            items: list[Any] = []
-            opts = dict(opts)  # don't mutate the caller's dict
-            while len(items) < max_items:
-                remaining = max_items - len(items)
-                opts["limit"] = min(remaining, page_size_default)
-                response = api_method(*args, opts)
-                page_data = _extract(response, "data") or []
-                items.extend(page_data)
-                # Empty page with a non-empty offset would loop forever with zero progress.
-                if not page_data:
-                    break
-                next_page = _extract(response, "next_page")
-                offset = _extract(next_page, "offset") if next_page else None
-                if not offset:
-                    break
-                opts["offset"] = offset
-            return items[:max_items]
-        finally:
-            config.return_page_iterator = original
-
-
-def _extract(obj: Any, key: str) -> Any:
-    """Read *key* from a SDK response that may be a dict or a typed model."""
-    if obj is None:
-        return None
-    if isinstance(obj, dict):
-        return obj.get(key)
-    return getattr(obj, key, None)
-
 
 def resolve_workspace(
     explicit: str | None,

{asana_api_cli-2.1.0 → asana_api_cli-2.1.1/src/asana_api_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asana-api-cli
-Version: 2.1.0
+Version: 2.1.1
 Summary: Command-line wrapper around the official Asana Python SDK
 Author-email: Masanao Izumo <asana@masanao.site>
 License-Expression: MIT

{asana_api_cli-2.1.0 → asana_api_cli-2.1.1}/tests/test_cli.py

@@ -20,7 +20,6 @@ from asana_api_cli.cli import (
     _operations_for,
     _parse_params,
     _parse_summary,
-    _resolve_effective_page_size,
     _snake,
     main,
 )
@@ -178,6 +177,13 @@ class TestBuiltCommands:
         # Path positional ``task_gid`` becomes ``--task`` (gid suffix stripped).
         assert "--task" in _option_flags(get_task_cmd)
 
+    def test_renamed_positional_help_shows_sdk_kwarg(self, get_task_cmd: click.Command) -> None:
+        # When ``task_gid`` is exposed as ``--task``, the original SDK kwarg
+        # name must appear in the help text so users can map the CLI flag back
+        # to the python-asana API.
+        task_param = next(p for p in get_task_cmd.params if "--task" in p.opts)
+        assert "task_gid" in (task_param.help or "")
+
     def test_get_tasks_pagination_options(self, get_tasks_cmd: click.Command) -> None:
         flags = _option_flags(get_tasks_cmd)
         assert "--all-items" in flags
@@ -212,45 +218,6 @@ class TestBuiltCommands:
         assert "--query" in flags
 
 
-# ---------------------------------------------------------------------------
-# Pagination size resolution
-# ---------------------------------------------------------------------------
-
-
-class TestEffectivePageSize:
-    """``_resolve_effective_page_size`` decides the per-page ``limit`` value.
-
-    The Asana API caps ``limit`` at 100, so we must never request more than
-    100 per page even when ``--max-items`` is larger.
-    """
-
-    def test_no_max_items_returns_page_size(self) -> None:
-        assert _resolve_effective_page_size(None, None) is None
-        assert _resolve_effective_page_size(50, None) == 50
-
-    def test_max_items_below_default_shrinks(self) -> None:
-        # max_items=5, page_size unset → request a single page of 5.
-        assert _resolve_effective_page_size(None, 5) == 5
-
-    def test_max_items_above_api_cap_keeps_default(self) -> None:
-        # max_items=250, page_size unset → keep page_size None so fetch_capped
-        # falls back to the 100-per-page default. Returning 250 would push the
-        # API's limit parameter above its 100 ceiling and produce a 400.
-        assert _resolve_effective_page_size(None, 250) is None
-
-    def test_max_items_equal_to_cap_keeps_default(self) -> None:
-        # 100 < 100 is False — no shrink, leave page_size None.
-        assert _resolve_effective_page_size(None, 100) is None
-
-    def test_explicit_page_size_smaller_than_max_items_kept(self) -> None:
-        # User explicitly requested 50/page; auto-page through it.
-        assert _resolve_effective_page_size(50, 250) == 50
-
-    def test_explicit_page_size_larger_than_max_items_shrinks(self) -> None:
-        # No point fetching 50 items just to throw 30 away.
-        assert _resolve_effective_page_size(50, 20) == 20
-
-
 # ---------------------------------------------------------------------------
 # Root group integration
 # ---------------------------------------------------------------------------

{asana_api_cli-2.1.0 → asana_api_cli-2.1.1}/tests/test_cli_invocation.py

@@ -3,11 +3,11 @@
 Each test builds a real command via ``_make_command`` against a real
 ``*Api`` class, replaces the underlying SDK method with a ``MagicMock``,
 drives the command through ``CliRunner``, and asserts on what reached the
-SDK (positional args, opts dict, call count).
+SDK (positional args, opts dict, kwargs, call count).
 
 This catches bugs in the argument-plumbing layer that structural tests
-miss -- for example the ``--max-items > 100`` regression where the CLI
-forwarded ``limit=N`` to the SDK even though Asana caps ``limit`` at 100.
+miss -- for example forgetting to forward ``--max-items`` as the SDK's
+``item_limit`` kwarg.
 """
 
 from __future__ import annotations
@@ -91,9 +91,8 @@ def _patch(
 
     ``MagicMock.call_args_list[i].args`` reflects the arguments the CLI
     passed in (without ``self``, since the stub strips it). Mutable args
-    (the ``opts`` dict) are deep-copied before being recorded so that
-    ``fetch_capped``'s in-place mutation across iterations does not collapse
-    every recorded call into the dict's final state.
+    (the ``opts`` dict) are deep-copied before being recorded so each
+    call's snapshot survives any later in-place mutation.
     """
     api_cls = getattr(asana, api_cls_name)
     mock = MagicMock(
@@ -110,140 +109,103 @@ def _patch(
 
 
 # ---------------------------------------------------------------------------
-# Pagination: --max-items size handling (regression area)
+# Pagination: --max-items forwards to the SDK's ``item_limit`` kwarg
 # ---------------------------------------------------------------------------
 
 
-class TestMaxItemsLimitArg:
-    """``--max-items`` must never push ``opts["limit"]`` above the API cap (100)."""
+class TestMaxItemsKwarg:
+    """``--max-items N`` is forwarded as ``item_limit=N`` to the SDK method.
 
-    def test_max_items_250_walks_100_100_50(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        """Regression: previously this forwarded ``limit=250`` and got a 400."""
-        cmd = _build_command("TasksApi", "get_tasks")
-        responses = [
-            _page([{"gid": str(i)} for i in range(0, 100)], offset="off1"),
-            _page([{"gid": str(i)} for i in range(100, 200)], offset="off2"),
-            _page([{"gid": str(i)} for i in range(200, 250)]),
-        ]
-        mock = _patch(monkeypatch, "TasksApi", "get_tasks", side_effect=responses)
-
-        result = CliRunner().invoke(cmd, ["--max-items", "250"])
+    The SDK's ``PageIterator`` then caps each per-request ``limit`` to
+    ``min(page_limit, item_limit - count)`` and stops at exactly N items,
+    so the CLI does not need to walk pages itself.
+    """
 
-        assert result.exit_code == 0, result.output
-        assert mock.call_count == 3
-        limits = [c.args[0]["limit"] for c in mock.call_args_list]
-        assert limits == [100, 100, 50]
-        # ``offset`` is threaded from each response into the next request.
-        assert "offset" not in mock.call_args_list[0].args[0]
-        assert mock.call_args_list[1].args[0]["offset"] == "off1"
-        assert mock.call_args_list[2].args[0]["offset"] == "off2"
-
-    def test_max_items_exactly_at_cap(self, monkeypatch: pytest.MonkeyPatch) -> None:
+    def test_max_items_passes_item_limit_kwarg(self, monkeypatch: pytest.MonkeyPatch) -> None:
         cmd = _build_command("TasksApi", "get_tasks")
         mock = _patch(
             monkeypatch,
             "TasksApi",
             "get_tasks",
-            side_effect=[_page([{"gid": str(i)} for i in range(100)])],
+            return_value=iter([{"gid": str(i)} for i in range(250)]),
         )
-        result = CliRunner().invoke(cmd, ["--max-items", "100"])
+        result = CliRunner().invoke(cmd, ["--max-items", "250"])
         assert result.exit_code == 0, result.output
         assert mock.call_count == 1
-        assert mock.call_args_list[0].args[0]["limit"] == 100
+        assert mock.call_args_list[0].kwargs == {"item_limit": 250}
+        # CLI does not push ``limit`` into opts; that's the SDK's job.
+        assert "limit" not in mock.call_args_list[0].args[0]
+        assert len(json.loads(result.output)) == 250
 
-    def test_max_items_below_cap_one_request(self, monkeypatch: pytest.MonkeyPatch) -> None:
+    def test_max_items_zero_passes_item_limit_zero(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """``--max-items 0`` still constructs a session and calls the SDK; the
+        SDK's PageIterator short-circuits and makes no HTTP request."""
         cmd = _build_command("TasksApi", "get_tasks")
         mock = _patch(
             monkeypatch,
             "TasksApi",
             "get_tasks",
-            side_effect=[_page([{"gid": str(i)} for i in range(5)])],
+            return_value=iter([]),
         )
-        result = CliRunner().invoke(cmd, ["--max-items", "5"])
-        assert result.exit_code == 0, result.output
-        assert mock.call_count == 1
-        assert mock.call_args_list[0].args[0]["limit"] == 5
-
-    def test_max_items_zero_makes_no_api_call(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        """``--max-items 0`` returns ``[]`` without ever calling the SDK."""
-        cmd = _build_command("TasksApi", "get_tasks")
-        mock = _patch(monkeypatch, "TasksApi", "get_tasks", return_value=_page([]))
         result = CliRunner().invoke(cmd, ["--max-items", "0"])
         assert result.exit_code == 0, result.output
-        assert mock.call_count == 0
-        assert json.loads(result.output) == []
-
-
-# ---------------------------------------------------------------------------
-# Pagination: termination conditions
-# ---------------------------------------------------------------------------
-
-
-class TestMaxItemsTermination:
-    """``fetch_capped`` must terminate even when the server cuts pagination short."""
-
-    def test_stops_when_offset_missing(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        """No ``next_page.offset`` -> stop, even if ``--max-items`` was larger."""
-        cmd = _build_command("TasksApi", "get_tasks")
-        mock = _patch(
-            monkeypatch,
-            "TasksApi",
-            "get_tasks",
-            side_effect=[_page([{"gid": "1"}], offset=None)],
-        )
-        result = CliRunner().invoke(cmd, ["--max-items", "500"])
-        assert result.exit_code == 0, result.output
         assert mock.call_count == 1
-        assert json.loads(result.output) == [{"gid": "1"}]
+        assert mock.call_args_list[0].kwargs == {"item_limit": 0}
+        assert json.loads(result.output) == []
 
-    def test_stops_on_empty_page_with_phantom_offset(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        """Empty page with a non-empty offset must not loop forever (zero-progress guard)."""
+    def test_max_items_5_passes_item_limit_5(self, monkeypatch: pytest.MonkeyPatch) -> None:
         cmd = _build_command("TasksApi", "get_tasks")
         mock = _patch(
             monkeypatch,
             "TasksApi",
             "get_tasks",
-            side_effect=[_page([], offset="phantom")],
+            return_value=iter([{"gid": str(i)} for i in range(5)]),
         )
-        result = CliRunner().invoke(cmd, ["--max-items", "500"])
+        result = CliRunner().invoke(cmd, ["--max-items", "5"])
         assert result.exit_code == 0, result.output
-        assert mock.call_count == 1
+        assert mock.call_args_list[0].kwargs == {"item_limit": 5}
 
 
 # ---------------------------------------------------------------------------
-# Pagination: --page-size interaction with --max-items
+# Pagination: --page-size feeds Configuration.page_limit
 # ---------------------------------------------------------------------------
 
 
-class TestPageSizeWithMaxItems:
-    """``--page-size`` controls per-request size; ``--max-items`` caps the total."""
+class TestPageSizeKwarg:
+    """``--page-size N`` sets ``Configuration.page_limit = N`` for the SDK.
 
-    def test_page_size_smaller_than_max_items_used_as_limit(
-        self, monkeypatch: pytest.MonkeyPatch
-    ) -> None:
+    The SDK reads ``page_limit`` to populate ``query_params['limit']`` when
+    the caller did not. We assert by snapshotting the configuration at the
+    moment the SDK method is invoked.
+    """
+
+    def _capture_page_limit_on_call(
+        self, monkeypatch: pytest.MonkeyPatch, return_value: Any
+    ) -> list[int]:
+        captured: list[int] = []
+
+        def patched_get_tasks(self_api: Any, opts: Any, **kwargs: Any) -> Any:
+            captured.append(self_api.api_client.configuration.page_limit)
+            return return_value
+
+        monkeypatch.setattr(asana.TasksApi, "get_tasks", patched_get_tasks)
+        return captured
+
+    def test_page_size_sets_page_limit(self, monkeypatch: pytest.MonkeyPatch) -> None:
         cmd = _build_command("TasksApi", "get_tasks")
-        responses = [
-            _page([{"gid": str(i)} for i in range(0, 50)], offset="o1"),
-            _page([{"gid": str(i)} for i in range(50, 100)], offset="o2"),
-            _page([{"gid": str(i)} for i in range(100, 120)]),
-        ]
-        mock = _patch(monkeypatch, "TasksApi", "get_tasks", side_effect=responses)
-        result = CliRunner().invoke(cmd, ["--page-size", "50", "--max-items", "120"])
+        captured = self._capture_page_limit_on_call(monkeypatch, return_value=iter([{"gid": "1"}]))
+        result = CliRunner().invoke(cmd, ["--page-size", "50", "--max-items", "10"])
         assert result.exit_code == 0, result.output
-        assert [c.args[0]["limit"] for c in mock.call_args_list] == [50, 50, 20]
+        assert captured == [50]
 
-    def test_page_size_larger_than_max_items_shrinks(self, monkeypatch: pytest.MonkeyPatch) -> None:
+    def test_no_page_size_keeps_sdk_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Default ``page_limit`` is 100 (the SDK default) when ``--page-size``
+        is not passed."""
         cmd = _build_command("TasksApi", "get_tasks")
-        mock = _patch(
-            monkeypatch,
-            "TasksApi",
-            "get_tasks",
-            side_effect=[_page([{"gid": str(i)} for i in range(20)])],
-        )
-        result = CliRunner().invoke(cmd, ["--page-size", "50", "--max-items", "20"])
+        captured = self._capture_page_limit_on_call(monkeypatch, return_value=_page([]))
+        result = CliRunner().invoke(cmd, [])
         assert result.exit_code == 0, result.output
-        assert mock.call_count == 1
-        assert mock.call_args_list[0].args[0]["limit"] == 20
+        assert captured == [100]
 
 
 # ---------------------------------------------------------------------------