Metadata-Version: 2.4
Name: agualpha
Version: 0.3.0
Summary: Overseas HTTP client for AGuAlpha Investment Platform (UK deployment)
Home-page: https://github.com/agualpha/agualpha-python
Author: AGuAlpha
Author-email: contact@agualpha.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Office/Business :: Financial
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Provides-Extra: async
Requires-Dist: aiohttp>=3.8.0; extra == "async"
Provides-Extra: pandas
Requires-Dist: pandas>=1.5.0; extra == "pandas"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AGuAlpha Python Client (Overseas)

A Python library for accessing the AGuAlpha Investment Platform via the
**UK (eu-west-1) deployment** at `https://agualpha.com/api/`.

> **Which package should I use?**
>
> - `agualpha` (this one) — points to `https://agualpha.com/api`. Use this
>   if you or your customers cannot reach the `.cn` domain (e.g. clients
>   outside mainland China).
> - `agualphacn` — points to `https://www.agualpha.cn/api`. Use this for
>   domestic (mainland China) deployments.
>
> Both packages expose the same public API (`AGuAlphaClient`,
> `AGuAlphaAsyncClient`, identical method signatures). Only the default
> `base_url` differs.

## Installation

```bash
pip install agualpha
```

For async support:

```bash
pip install agualpha[async]
```

For pandas integration:

```bash
pip install agualpha[pandas]
```

## Configuration

Set your API key as an environment variable (recommended over passing it
in code):

```bash
export AGUALPHA_API_KEY="sk-your-api-key-here"
```

Optional overrides:

```bash
# Point the client at a non-default gateway (e.g. staging).
export AGUALPHA_BASE_URL="https://agualpha.com/api"
```

No credentials other than the API key are required — the gateway handles
database access on its side.

## Quick Start

### Synchronous Usage

```python
from agualpha import AGuAlphaClient

with AGuAlphaClient(api_key="sk-your-api-key-here") as client:
    positions = client.get_positions(start_date="2025-01-01")
    for p in positions.data:
        print(p.date, p.outstanding, p.value)
```

### Asynchronous Usage

```python
import asyncio
from agualpha import AGuAlphaAsyncClient

async def main():
    async with AGuAlphaAsyncClient(api_key="sk-...") as client:
        rows = await client.get_adj_close(
            membership="csi300",
            start_date="2025-01-01",
            end_date="2025-12-31",
        )
        print(f"{len(rows)} rows")

asyncio.run(main())
```

## API Surface

All methods mirror `agualphacn` exactly. List-returning methods
auto-paginate when `page=None` (the default); pass `page=int` for a
single page.

| Method | Returns | Tier | Notes |
|---|---|---|---|
| `get_positions(...)` | `PositionsResponse` | standard | date filter optional |
| `get_ideas(...)` | `IdeasResponse` | standard | status / direction optional |
| `get_csi_weights(index=..., ...)` | `list[dict]` | VIP | `index` required |
| `get_revision_fy2(...)` | `list[dict]` | VIP | date filter required |
| `get_adj_close(membership=..., ...)` | `list[dict]` | VIP | membership + date required, supports cursor |
| `get_p_cies(zone=...)` | `list[dict]` | VIP | `zone` required (`"hk"` or `"cn"`) |
| `get_sp_rolling_index(...)` | `list[dict]` | VIP | at least one filter required |
| `get_sp_rolling_index_products()` | `list[str]` | VIP | no params |
| `get_limit_evts(...)` | `list[dict]` | VIP | date filter required |

Each list method has a `_dataframe` variant (`get_csi_weights_dataframe`,
etc.) that returns a `pandas.DataFrame`.

## CLI

A `agualpha` console-script is provided for quick one-off queries:

```bash
agualpha --api-key sk-... positions --start-date 2025-01-01
agualpha adj-close --membership csi300 --start-date 2025-01-01 --end-date 2025-12-31
```

## License

MIT
