Metadata-Version: 2.4
Name: agualpha
Version: 1.1.0
Summary: Python client for AGuAlpha Investment Platform API
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.28.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

Official Python library for accessing AGuAlpha Investment Platform data.

## Installation

```bash
pip install agualpha
```

For async support:
```bash
pip install agualpha[async]
```

For pandas integration:
```bash
pip install agualpha[pandas]
```

## Quick Start

### Synchronous Usage

```python
from agualpha import AGuAlphaClient

# Initialize client
client = AGuAlphaClient(api_key="sk-your-api-key-here")

# Get positions data
positions = client.get_positions()
print(f"Total positions: {positions.total}")

for position in positions.data:
    print(f"Date: {position.date}, Outstanding: {position.outstanding}")

# Get ideas data
ideas = client.get_ideas(status="active")
print(f"Total active ideas: {ideas.total}")

for idea in ideas.data:
    print(f"Symbol: {idea.ticker_symbol}, Status: {idea.status}")

# Close the connection
client.close()
```

### Using Context Manager

```python
from agualpha import AGuAlphaClient

with AGuAlphaClient(api_key="sk-your-api-key-here") as client:
    positions = client.get_positions(
        start_date="2024-01-01",
        end_date="2024-12-31"
    )
    print(f"Found {positions.total} positions")
```

### Asynchronous Usage

```python
import asyncio
from agualpha import AGuAlphaAsyncClient

async def main():
    async with AGuAlphaAsyncClient(api_key="sk-your-api-key-here") as client:
        # Fetch data concurrently
        positions, ideas = await asyncio.gather(
            client.get_positions(),
            client.get_ideas(status="active")
        )

        print(f"Positions: {positions.total}, Ideas: {ideas.total}")

asyncio.run(main())
```

### Pandas Integration

```python
from agualpha import AGuAlphaClient
from agualpha.utils import positions_to_dataframe, export_to_csv

client = AGuAlphaClient(api_key="sk-your-api-key-here")

# Get positions and convert to DataFrame
positions_response = client.get_positions()
df = positions_to_dataframe(positions_response.data)

# Export to CSV
export_to_csv(positions_response.data, "positions.csv")
```

## API Reference

### AGuAlphaClient

#### `__init__(api_key: str, base_url: str = "https://api.agualpha.com/api")`
Initialize the client with your API key.

#### `get_positions(start_date: Optional[str] = None, end_date: Optional[str] = None) -> PositionsResponse`
Get position data from subscribed analysts.

**Parameters:**
- `start_date` (str): Filter by start date (YYYY-MM-DD format)
- `end_date` (str): Filter by end date (YYYY-MM-DD format)

**Returns:** `PositionsResponse`

#### `get_ideas(status: Optional[str] = None, direction: Optional[str] = None) -> IdeasResponse`
Get trade ideas from subscribed analysts.

**Parameters:**
- `status` (str): Filter by status ("active", "closed")
- `direction` (str): Filter by direction ("long", "short")

**Returns:** `IdeasResponse`

### Response Models

#### `PositionsResponse`
- `success` (bool): Request success status
- `total` (int): Total number of records
- `data` (List[Position]): List of position objects
- `error` (str, optional): Error message if failed

#### `IdeasResponse`
- `success` (bool): Request success status
- `total` (int): Total number of records
- `data` (List[Idea]): List of idea objects
- `error` (str, optional): Error message if failed

## Error Handling

```python
from agualpha import AGuAlphaClient
from agualpha.exceptions import APIError, AuthenticationError

try:
    client = AGuAlphaClient(api_key="invalid-key")
    positions = client.get_positions()
except AuthenticationError:
    print("Invalid API key")
except APIError as e:
    print(f"API error: {e}")
```

## Requirements

- Python 3.8+
- requests 2.28.0+

## License

MIT License
