Metadata-Version: 2.5
Name: composio-client
Version: 2.0.0rc1
Summary: The official Python library for the Composio API, generated from the v3.1 OpenAPI spec with hey-api
Project-URL: Homepage, https://github.com/ComposioHQ/composio-client
Project-URL: Repository, https://github.com/ComposioHQ/composio-client
Author: Composio
License-Expression: Apache-2.0
Keywords: api,client,composio,tool_router
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic<3,>=2.9
Requires-Dist: typing-extensions>=4.12
Description-Content-Type: text/markdown

# composio-client for Python

`composio-client` replaces the Stainless-generated package without requiring you to rewrite existing
`1.43.x` calls.

```python
from composio_client import Composio

client = Composio(api_key="ak_...")

session = client.tool_router.session.create(user_id="user@example.com")
result = client.tool_router.session.execute(
    session.session_id,
    tool_slug="GITHUB_CREATE_ISSUE",
    arguments={"owner": "composiohq", "repo": "composio", "title": "Example"},
)
```

The owned client preserves the public Python contract from `composio-client==1.43.0` and adds the
rest of the v3.1 API. You get all 104 released operations, including the 64 operations published by
Stainless and 40 additive operations generated from the checked-in OpenAPI document.

## Install the client

```bash
pip install composio-client
```

With `uv`:

```bash
uv add composio-client
```

Set `COMPOSIO_API_KEY` or pass `api_key` when you construct the client.

## Use the async client

```python
import asyncio

from composio_client import AsyncComposio


async def main() -> None:
    async with AsyncComposio(api_key="ak_...") as client:
        session = await client.tool_router.session.create(user_id="user@example.com")
        print(session.session_id)


asyncio.run(main())
```

## Read raw response metadata

Every released resource keeps the Stainless raw and streaming accessors:

```python
from composio_client import Composio

client = Composio(api_key="ak_...")

response = client.tool_router.session.with_raw_response.retrieve("sess_123")
print(response.status_code)
session = response.parse()

with client.tool_router.session.with_streaming_response.retrieve("sess_123") as response:
    print(response.headers)
```

The async resource exposes the corresponding async response objects and context managers.

## Handle API errors

The exception hierarchy matches the Stainless package. Existing `except` blocks keep working:

```python
from composio_client import Composio, NotFoundError

client = Composio(api_key="ak_...")

try:
    client.tool_router.session.retrieve("missing")
except NotFoundError as error:
    print(error.status_code)
```

## Migrate pre-release owned-client calls

Earlier owned-client builds accepted aggregate `body`, `query`, and `headers` values. Those calls
remain valid during the transition:

```python
client.tool_router.session.create({"user_id": "user@example.com"})
client.tool_router.session.config_history("sess_123", query={"limit": 25})
```

Prefer the flat Stainless form in new code:

```python
client.tool_router.session.create(user_id="user@example.com")
client.tool_router.session.config_history("sess_123", limit=25)
```

See [the Python migration guide](./MIGRATION.md) for compatibility details and the stricter credential
transport rules.

## Develop the Python package

Generate from the repository root:

```bash
pnpm generate:python
pnpm codegen:check
```

Run Python checks from `python/`:

```bash
uv run ruff check
uv run ruff format --check
uv run mypy src scripts
uv run pytest
uv run python scripts/check_stainless_compatibility.py
uv build
uv run python scripts/check_stainless_compatibility.py --wheel dist/*.whl
```

The normal compatibility check is offline. It reads the committed `1.43.0` fixture and does not
install or call the Stainless client.
