asana-api-cli 1.2.0__py3-none-any.whl

asana_api_cli/formatter.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import contextlib
+import csv
+import functools
+import io
+import json
+import sys
+from typing import Any
+
+import click
+import jq as jqlib
+from asana.rest import ApiException
+from tabulate import tabulate
+
+
+def formatted(f: Any) -> Any:
+    """Decorator that adds --output / --query and auto-formats the returned dict."""
+
+    @click.option(
+        "--output",
+        "output_format",
+        type=click.Choice(["json", "table", "csv", "text"], case_sensitive=False),
+        default="json",
+        help="Output format (default: json)",
+    )
+    @click.option(
+        "--query",
+        "jq_query",
+        default=None,
+        help="jq expression to filter output",
+    )
+    @functools.wraps(f)
+    def wrapper(*args: Any, output_format: str, jq_query: str | None, **kwargs: Any) -> None:
+        try:
+            data = f(*args, **kwargs)
+            # Collapse the asana SDK PageIterator / generator into a list
+            if not isinstance(data, (dict, list, str, int, float, bool, type(None))):
+                with contextlib.suppress(TypeError):
+                    data = list(data)
+        except ApiException as e:
+            _handle_api_exception(e)
+        _format_output(data, output_format=output_format, jq_query=jq_query)
+
+    return wrapper
+
+
+def _handle_api_exception(e: ApiException) -> None:
+    """Print an Asana API error in human-readable form and exit."""
+    from asana_api_cli.session import runtime
+
+    status = e.status or "error"
+    messages: list[str] = []
+    body = e.body
+    if isinstance(body, bytes):
+        with contextlib.suppress(UnicodeDecodeError):
+            body = body.decode("utf-8")
+    if isinstance(body, str):
+        with contextlib.suppress(json.JSONDecodeError):
+            payload = json.loads(body)
+            if isinstance(payload, dict):
+                for err in payload.get("errors") or []:
+                    if isinstance(err, dict) and "message" in err:
+                        messages.append(str(err["message"]))
+    if not messages:
+        messages.append(e.reason or "Unknown API error")
+    for msg in messages:
+        click.echo(f"Error ({status}): {msg}", err=True)
+    # When the body was not JSON, show a hint and,
+    # in debug mode, dump the raw body so the user can diagnose the issue.
+    if isinstance(body, str) and body and not _is_json(body):
+        click.echo(
+            "The server returned a non-JSON response. "
+            "Re-run with --debug to see the full response body.",
+            err=True,
+        )
+        if runtime.debug:
+            click.echo("--- raw response body ---", err=True)
+            click.echo(body, err=True)
+            click.echo("--- end of response body ---", err=True)
+    sys.exit(1)
+
+
+def _is_json(text: str) -> bool:
+    """Return True if *text* looks like JSON."""
+    try:
+        json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        return False
+    return True
+
+
+def _format_output(data: Any, *, output_format: str, jq_query: str | None) -> None:
+    if jq_query:
+        try:
+            data = jqlib.first(jq_query, data)
+        except ValueError as e:
+            click.echo(f"Invalid jq expression: {e}", err=True)
+            sys.exit(1)
+
+    if output_format == "text":
+        _print_text(data)
+        return
+
+    if output_format == "json":
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    rows = _to_rows(data)
+    if rows is None:
+        click.echo(data)
+        return
+
+    if output_format == "table":
+        click.echo(tabulate(rows, headers="keys", tablefmt="simple"))
+    elif output_format == "csv":
+        _print_csv(rows)
+
+
+def _to_rows(data: Any) -> list[dict[str, Any]] | None:
+    """Convert data into a list of dicts for table/csv. Return None if not possible."""
+    if isinstance(data, list):
+        if not data:
+            return []
+        if isinstance(data[0], dict):
+            return data
+        return [{"value": v} for v in data]
+    if isinstance(data, dict):
+        return [data]
+    return None
+
+
+def _print_text(data: Any) -> None:
+    """Print data in plain text format (like ``aws --output text``)."""
+    if data is None:
+        click.echo("None")
+        return
+    if isinstance(data, (str, int, float, bool)):
+        click.echo(data)
+        return
+    if isinstance(data, dict):
+        click.echo("\t".join(str(v) for v in data.values()))
+        return
+    if isinstance(data, list):
+        for item in data:
+            if isinstance(item, dict):
+                click.echo("\t".join(str(v) for v in item.values()))
+            else:
+                click.echo(item)
+        return
+    click.echo(data)
+
+
+def _print_csv(rows: list[dict[str, Any]]) -> None:
+    if not rows:
+        return
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=list(rows[0].keys()))
+    writer.writeheader()
+    writer.writerows(rows)
+    click.echo(buf.getvalue(), nl=False)

asana_api_cli/session.py

@@ -0,0 +1,173 @@
+"""Asana SDK client construction utilities.
+
+A thin wrapper around the official `asana` SDK ApiClient that handles
+initialization from environment variables, toggling pagination mode, and
+applying the global configuration passed in from the CLI.
+"""
+from __future__ import annotations
+
+import functools
+import json
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import asana
+from urllib3.util.retry import Retry
+
+DEFAULT_TOKEN_ENV = "ASANA_ACCESS_TOKEN"
+DEFAULT_WORKSPACE_ENV = "ASANA_DEFAULT_WORKSPACE"
+
+
+def resolve_body(value: str) -> Any:
+    """Parse a body argument as JSON.
+
+    Supports three input forms:
+    - ``@path`` — read JSON from a file
+    - ``-``     — read JSON from stdin
+    - otherwise — parse the string itself as JSON
+    """
+    if value == "-":
+        raw = sys.stdin.read()
+    elif value.startswith("@"):
+        path = Path(value[1:])
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            print(f"Body file not found: {path}", file=sys.stderr)
+            sys.exit(1)
+        except OSError as exc:
+            print(f"Cannot read body file {path}: {exc}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        raw = value
+
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        print(f"Invalid JSON in body: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+@dataclass
+class _Runtime:
+    """Configuration shared globally during a CLI invocation. Updated by the main group callback."""
+
+    debug: bool = False
+    host: str | None = None
+    proxy: str | None = None
+    verify_ssl: bool = True
+    ssl_ca_cert: str | None = None
+    page_limit: int | None = None
+    retries: int | None = None
+    timeout: float | None = None
+    token_env: str = DEFAULT_TOKEN_ENV
+    temp_dir: str | None = None
+
+
+runtime = _Runtime()
+
+
+class AsanaSession:
+    """Session that holds an ApiClient from the official asana SDK."""
+
+    def __init__(self, token: str, *, paginate: bool = False) -> None:
+        config = asana.Configuration()
+        config.access_token = token
+        # When --paginate is set, the SDK returns a PageIterator that walks every page.
+        config.return_page_iterator = paginate
+
+        # Apply runtime values to Configuration
+        if runtime.host:
+            config.host = runtime.host
+        if runtime.proxy:
+            config.proxy = runtime.proxy
+        if not runtime.verify_ssl:
+            config.verify_ssl = False
+        if runtime.ssl_ca_cert:
+            config.ssl_ca_cert = runtime.ssl_ca_cert
+        if runtime.page_limit is not None:
+            config.page_limit = runtime.page_limit
+        if runtime.temp_dir:
+            config.temp_folder_path = runtime.temp_dir
+        if runtime.retries is not None:
+            # Replace only `total` while keeping the existing backoff/status_forcelist.
+            config.retry_strategy = Retry(
+                total=runtime.retries,
+                backoff_factor=2,
+                status_forcelist=[429, 500, 502, 503, 504],
+            )
+        if runtime.debug:
+            # The SDK debug setter attaches a stderr handler to the urllib3/asana
+            # loggers and enables http.client.HTTPConnection.debuglevel.
+            config.debug = True
+
+        self._config = config
+        self._client = asana.ApiClient(config)
+
+        # Configuration has no --timeout knob, so wrap call_api to inject it.
+        if runtime.timeout is not None:
+            self._install_timeout(runtime.timeout)
+
+    def _install_timeout(self, timeout: float) -> None:
+        """Wrap ApiClient.call_api to inject a default _request_timeout."""
+        original = self._client.call_api
+
+        @functools.wraps(original)
+        def call_api_with_timeout(*args: Any, **kwargs: Any) -> Any:
+            kwargs.setdefault("_request_timeout", timeout)
+            return original(*args, **kwargs)
+
+        self._client.call_api = call_api_with_timeout  # type: ignore[method-assign]
+
+    @property
+    def client(self) -> asana.ApiClient:
+        return self._client
+
+    def api(self, api_class: type) -> object:
+        """Take a <Tag>Api class and return an instance bound to this session."""
+        return api_class(self._client)
+
+    @classmethod
+    def from_env(cls, *, paginate: bool = False) -> "AsanaSession":
+        """Build a session from environment variables (variable name from runtime.token_env)."""
+        var = runtime.token_env or DEFAULT_TOKEN_ENV
+        token = os.environ.get(var, "")
+        if not token:
+            print(f"{var} environment variable is not set", file=sys.stderr)
+            sys.exit(1)
+        return cls(token=token, paginate=paginate)
+
+
+def resolve_workspace(
+    explicit: str | None,
+    *,
+    required: bool = False,
+) -> str | None:
+    """Resolve workspace GID with fallback chain.
+
+    Priority: explicit ``--workspace`` value > ``ASANA_DEFAULT_WORKSPACE``
+    env var (only when *required* is True).
+
+    When workspace is optional (``required=False``), the env-var fallback is
+    **not** used.  This prevents the default workspace from being sent
+    alongside other scope parameters (e.g. ``--project`` on ``get-tasks``)
+    that are mutually exclusive with workspace in the Asana API.
+
+    If *required* is True and no value is found, exits with an error.
+    """
+    if explicit is not None:
+        return explicit
+    if required:
+        ws = os.environ.get(DEFAULT_WORKSPACE_ENV)
+        if ws:
+            return ws
+        print(
+            f"Workspace is required. Specify --workspace or "
+            f"set {DEFAULT_WORKSPACE_ENV}.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return None

asana_api_cli/version.py

@@ -0,0 +1,11 @@
+"""Version information for the CLI."""
+from __future__ import annotations
+
+from importlib.metadata import version
+
+
+def version_string() -> str:
+    """Return a version string including the python-asana SDK version."""
+    cli_ver = version("asana-api-cli")
+    sdk_ver = version("asana")
+    return f"{cli_ver} (python-asana {sdk_ver})"

asana_api_cli-1.2.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: asana-api-cli
+Version: 1.2.0
+Summary: Command-line wrapper around the official Asana Python SDK
+Author-email: Masanao Izumo <asana@masanao.site>
+License-Expression: Apache-2.0
+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
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<9,>=8.1
+Requires-Dist: jq<2,>=1.8
+Requires-Dist: tabulate<1,>=0.9
+Requires-Dist: asana<6,>=5.2.4
+Dynamic: license-file
+
+# asana-api-cli
+
+A CLI tool for the Asana API. It thinly wraps the official
+[python-asana](https://github.com/Asana/python-asana) SDK with click, exposing
+every API endpoint from the command line via `asana-api <group> <command>`.
+
+## Installation
+
+```bash
+pip install asana-api-cli
+
+# or, to install as an isolated CLI tool
+pipx install asana-api-cli
+```
+
+## Environment variables
+
+| Name | Required | Description |
+|------|----------|-------------|
+| `ASANA_ACCESS_TOKEN` | Yes (at runtime only) | Asana Personal Access Token |
+| `ASANA_DEFAULT_WORKSPACE` | No | Default workspace GID for endpoints that require it |
+
+The token can be issued from the
+[Asana Developer Console](https://app.asana.com/0/developer-console).
+No token is needed for `--help` or argument-error output.
+
+```bash
+export ASANA_ACCESS_TOKEN="1/12345..."
+export ASANA_DEFAULT_WORKSPACE="12345678"   # optional
+```
+
+## Usage
+
+```bash
+# Show version
+asana-api --version
+
+# List commands
+asana-api --help
+asana-api tasks --help
+asana-api tasks get-tasks --help
+
+# List workspaces
+asana-api workspaces get-workspaces
+
+# List projects (workspace resolved from ASANA_DEFAULT_WORKSPACE)
+asana-api projects get-projects-for-workspace
+asana-api projects get-projects --workspace <WORKSPACE_GID>
+
+# List tasks (first page)
+asana-api tasks get-tasks --project <PROJECT_GID>
+
+# Auto-fetch all pages
+asana-api tasks get-tasks --project <PROJECT_GID> --paginate
+
+# Single task (--task instead of positional argument)
+asana-api tasks get-task --task <TASK_GID>
+
+# Create a task (body is a JSON string)
+asana-api tasks create-task --body '{"data":{"name":"new task","projects":["<PID>"]}}'
+
+# Output formats
+asana-api tasks get-tasks --project <PID> --output table
+asana-api tasks get-tasks --project <PID> --query '.data' --output csv
+```
+
+### Workspace resolution
+
+Many API endpoints require a workspace. For those endpoints (e.g.
+`get-projects-for-workspace`), the CLI resolves it in this order:
+
+1. `--workspace <GID>` on the command
+2. `ASANA_DEFAULT_WORKSPACE` environment variable
+
+For endpoints where workspace is optional (e.g. `get-tasks`), the env-var
+fallback is **not** used — pass `--workspace` explicitly if needed. This
+prevents conflicts with other scope parameters like `--project` that are
+mutually exclusive with workspace in the Asana API.
+
+## Development
+
+See [docs/development.md](https://github.com/izumo-m/asana-api-cli/blob/main/docs/development.md)
+for building from source, project layout, and library usage.
+
+## License
+
+[Apache License 2.0](https://github.com/izumo-m/asana-api-cli/blob/main/LICENSE)

asana_api_cli-1.2.0.dist-info/RECORD

@@ -0,0 +1,57 @@
+asana_api_cli/__init__.py,sha256=VwCvAdoxu2DuaYGGMVBTXB-DgPagEeKIpop-BaiLL7k,75
+asana_api_cli/formatter.py,sha256=V5-rfMtMwcAbW-P0KPGa05RKUWOjHUkpXsXibmDfVok,4965
+asana_api_cli/session.py,sha256=s3f01vk1LE7U4wO_7rdKgO7XkeoVjeuC0WnQZC6qEg4,5746
+asana_api_cli/version.py,sha256=Hhyl20g8y07oEoBHBhJrNre92HlEkVV_kdDnvKxXsh0,338
+asana_api_cli/cli/__init__.py,sha256=0MjxSiKGnHcWUWuqEucGLBvXPQk7TQUjc9VTtyoFeo0,6711
+asana_api_cli/cli/access_requests.py,sha256=XZxooEyLKjpcWalqvakfcdPx6dZzQypNTZqn_htzVyc,2851
+asana_api_cli/cli/allocations.py,sha256=l6TRGWd9TTi05_Nona5wYorT9bbjgtboUJ3cZbn9jaY,5236
+asana_api_cli/cli/attachments.py,sha256=19kyRq-Bzt4c6ajjJNvoIl-PD1JLpx5C4o7Lg4c2N1M,4603
+asana_api_cli/cli/audit_log_api.py,sha256=OJxWaTqtVySR22k05sgIAD_vH4k0wQVmGErDVl6Qb9c,2960
+asana_api_cli/cli/batch_api.py,sha256=oukiisYeU-eXrVCo808-bW5Ljqinz5GOVvd953IeE70,1178
+asana_api_cli/cli/budgets.py,sha256=aw3WcZgaEqMOYzT4l6yZwyBFe0kVtoLcXO7b3OY03ec,3245
+asana_api_cli/cli/custom_field_settings.py,sha256=73MeEuTIzXmX93rUp7OXJLdT0IkNOW376nKta0e35dI,5709
+asana_api_cli/cli/custom_fields.py,sha256=hxXS7fPNQE0E0OvfS9020_8d7yjJsftROslo1oeb07Q,7132
+asana_api_cli/cli/custom_types.py,sha256=vahRL3JhDm8Q4m96dcSpG2spAySa9jFijVSzhL0iXEU,2639
+asana_api_cli/cli/events.py,sha256=DesmksXsaf2keXF-pJuuZsHGY5TEXkh7snVIw7g5p68,1446
+asana_api_cli/cli/exports.py,sha256=iGYghD6XbLskieJvcdtbzFGujioBPiHJaGltp6qFq64,1442
+asana_api_cli/cli/goal_relationships.py,sha256=67S3g7raB3-Y3w8iBlQC7mikJiRNx1aKp3VOFyMGBRY,5544
+asana_api_cli/cli/goals.py,sha256=6hlmyNFIW2h4Hun96Plun7ypjzcMts5tDO6xet6wW5c,11206
+asana_api_cli/cli/jobs.py,sha256=zhLLxYuUXgVebOjNFTL5KtidoIlTmcoxQZqICLPnjb8,1046
+asana_api_cli/cli/memberships.py,sha256=Xbi2Ax1P6eg8joN7PGgASKiyqOk-1WMXWVpPNvgXRwM,4443
+asana_api_cli/cli/organization_exports.py,sha256=h00T2xWvrJmtA84RNM8D6UuCadhnvxtAAD7B36qJMTk,2087
+asana_api_cli/cli/portfolio_memberships.py,sha256=2gyih0Wt0_Oq7q5Jbi_b3_67pC1r7m2fZxmelWBI3iA,4961
+asana_api_cli/cli/portfolios.py,sha256=jsxR9nwQ3VE1EqGXYVLxPKOulPpUJJpLDLI3WwoloG4,11701
+asana_api_cli/cli/project_briefs.py,sha256=POnb6UUQukVQ-B1_X904s8-HcMeZTVGEp-0gMMX2nBw,3479
+asana_api_cli/cli/project_memberships.py,sha256=0LutTGJA4vkboniOpU6tu97JLKFZD19wWCakhpBfR7M,2885
+asana_api_cli/cli/project_portfolio_settings.py,sha256=TXjv8YGnHxoYHGWx80cHvQZrhj_oEsA0EkxyCvrOURU,5480
+asana_api_cli/cli/project_statuses.py,sha256=11L1RBGLX2v6PBvw1vCbVLwOUxVg7ndzJV8JLSR47ak,4064
+asana_api_cli/cli/project_templates.py,sha256=YwKAsqhmE9ZvynoeM64CCuvFUz5FDRccMSW0pReDAEs,5760
+asana_api_cli/cli/projects.py,sha256=9BTLESTDi5HXc4b0qy5hKokbNXYmd9nYlwXemnAtjpo,21997
+asana_api_cli/cli/rates.py,sha256=lLSDhEiCSIGAEsyMyS_9GN1FhUXanU3VfvrDx8M9B2A,4603
+asana_api_cli/cli/reactions.py,sha256=Gqof-upq3ton7Bi0-3LlJ5c12ibEMXec8VIngwP6Nho,1690
+asana_api_cli/cli/roles.py,sha256=Wk4_RPNqmS9IJjvHXWFDAVWtWlxoEYTPJiM5ibGv4zU,4756
+asana_api_cli/cli/rules.py,sha256=hlbQV97Mma-1wXyUtHmg9K0Z6d20gDhSg_ADnM_mC38,1063
+asana_api_cli/cli/sections.py,sha256=hoqDuzbDb4I9lV41OAFGPbwVyiZYknKltiy020pntz0,5249
+asana_api_cli/cli/status_updates.py,sha256=549jdi_rdTi0tfvpg8KK5I8sv0rO5bmvBIaPplUnGpg,4764
+asana_api_cli/cli/stories.py,sha256=NgeiVl5yZNyKwJXgtOKciqV8rRkZzW41w5PNg-CDfmE,6803
+asana_api_cli/cli/tags.py,sha256=he7LMNsQ2TbGyJOZSHqpIVa7mAJOEoE7CulEkrZctM4,8310
+asana_api_cli/cli/task_templates.py,sha256=ct2H4NcDFaXCMuOnNvioRLanZx83z6PezyUwFnmmMVE,3923
+asana_api_cli/cli/tasks.py,sha256=u-p-E6tWzARDx8npli4NK3hwSFki1I1QtPfYrUrkc50,29615
+asana_api_cli/cli/team_memberships.py,sha256=kmti-zH5Vh3Mr0zDJbIkXt9zkh_V23wQHTmJxhpIXyo,6335
+asana_api_cli/cli/teams.py,sha256=3pEaF2A-AgPPbzoTcWA2ruLfbudW-y-iadBbIkhB1QM,7103
+asana_api_cli/cli/time_periods.py,sha256=E55GFasCeHqV0ycIbsGV3RnZLyrYxY9Og6iZhOuife4,2955
+asana_api_cli/cli/time_tracking_categories.py,sha256=PUUpBzaC5YRj0swh4oB8suBNYL9-4tlaQBMI-lI43pY,7651
+asana_api_cli/cli/time_tracking_entries.py,sha256=AtSgSdwWwEeIOKHz0DROy15jgC7BSwlzX6Q_Zmek148,8543
+asana_api_cli/cli/timesheet_approval_statuses.py,sha256=FV3wGdeVQdLzpL4Fp8tzHs9ryp4L2kq-V8sZfjL85l4,5720
+asana_api_cli/cli/typeahead.py,sha256=0Cw24ttyoTIvQ56omb03_oPxTh7tkAB8md67D3dTEZ4,2300
+asana_api_cli/cli/user_task_lists.py,sha256=FUqnOk_t31cAk7hrXm_9Om-uV6NaUaWhectZa9jPitU,2224
+asana_api_cli/cli/users.py,sha256=E62aDKkBjirx9Xp4bM8-y7NA9FiPC1NCizxGP2qCF-I,10462
+asana_api_cli/cli/webhooks.py,sha256=Wv7M1gTJn1jyyJEorlcItpgRkFfC849hZmDZ41me7L4,4799
+asana_api_cli/cli/workspace_memberships.py,sha256=5JcFCA9KEgxlahQ2NCGLUfMymFAewg_zhGj7KQLNP2E,4580
+asana_api_cli/cli/workspaces.py,sha256=vv5XhNEMQGXP4aNyzql5bZp_tRbybDp2i0RSmX4q3Z4,5982
+asana_api_cli-1.2.0.dist-info/licenses/LICENSE,sha256=0x0LkhzzvBg1yYZvRGGOZ3ZZUVLmP4sK_jyUljmH4Pg,10764
+asana_api_cli-1.2.0.dist-info/METADATA,sha256=0PcCgX_q6LdOOmHyHKzjmpUWP7QsTerCuz_OTDstjAE,3221
+asana_api_cli-1.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+asana_api_cli-1.2.0.dist-info/entry_points.txt,sha256=dcNQUEQQh7ODXPh9TsCsj1jHycMgIJ7uFpz0Wwi1_UU,53
+asana_api_cli-1.2.0.dist-info/top_level.txt,sha256=Hj5dHD-kV-G8pIp46m76N9spxBOwzxQ1Rh1ocdzoXw4,14
+asana_api_cli-1.2.0.dist-info/RECORD,,

asana_api_cli-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

asana_api_cli-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+asana-api = asana_api_cli.cli:main