agualpha 1.0.0__py3-none-any.whl

agualpha/__init__.py

@@ -0,0 +1,22 @@
+"""
+AGuAlpha API Client Library
+A Python library for accessing AGuAlpha investment platform data
+"""
+
+from .client import AGuAlphaClient
+from .async_client import AGuAlphaAsyncClient
+from .models import PositionsResponse, IdeasResponse, Position, Idea
+from .exceptions import APIError, AuthenticationError, RateLimitError
+
+__version__ = "1.0.0"
+__all__ = [
+    "AGuAlphaClient",
+    "AGuAlphaAsyncClient",
+    "PositionsResponse",
+    "IdeasResponse",
+    "Position",
+    "Idea",
+    "APIError",
+    "AuthenticationError",
+    "RateLimitError",
+]

agualpha/async_client.py

@@ -0,0 +1,116 @@
+"""
+Asynchronous API client for AGuAlpha
+"""
+
+import aiohttp
+from typing import Optional
+from .models import PositionsResponse, IdeasResponse
+from .exceptions import APIError, AuthenticationError, ServerError
+
+
+class AGuAlphaAsyncClient:
+    """Asynchronous client for AGuAlpha API"""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.agualpha.com/api"
+    ):
+        """
+        Initialize the AGuAlpha async client
+
+        Args:
+            api_key: Your API key
+            base_url: Base URL for the API (default: https://api.agualpha.com/api)
+        """
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._session = None
+
+    async def __aenter__(self):
+        """Async context manager entry"""
+        self._session = aiohttp.ClientSession(
+            headers={"X-API-Key": self.api_key}
+        )
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit"""
+        if self._session:
+            await self._session.close()
+
+    async def get_positions(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None
+    ) -> PositionsResponse:
+        """
+        Get position data from subscribed analysts
+
+        Args:
+            start_date: Filter by start date (YYYY-MM-DD format)
+            end_date: Filter by end date (YYYY-MM-DD format)
+
+        Returns:
+            PositionsResponse: Response containing position data
+        """
+        if not self._session:
+            raise RuntimeError("Client not initialized. Use 'async with' or call _ensure_session()")
+
+        url = f"{self.base_url}/investor/data/positions"
+        params = {}
+        if start_date:
+            params["startDate"] = start_date
+        if end_date:
+            params["endDate"] = end_date
+
+        try:
+            async with self._session.get(url, params=params) as response:
+                if response.status == 401:
+                    raise AuthenticationError("Invalid API key")
+                response.raise_for_status()
+                data = await response.json()
+                return PositionsResponse.from_dict(data)
+        except aiohttp.ClientError as e:
+            raise APIError(f"Request failed: {e}")
+
+    async def get_ideas(
+        self,
+        status: Optional[str] = None,
+        direction: Optional[str] = None
+    ) -> IdeasResponse:
+        """
+        Get trade ideas from subscribed analysts
+
+        Args:
+            status: Filter by status (active, closed)
+            direction: Filter by direction (long, short)
+
+        Returns:
+            IdeasResponse: Response containing trade ideas data
+        """
+        if not self._session:
+            raise RuntimeError("Client not initialized. Use 'async with' or call _ensure_session()")
+
+        url = f"{self.base_url}/investor/data/ideas"
+        params = {}
+        if status:
+            params["status"] = status
+        if direction:
+            params["direction"] = direction
+
+        try:
+            async with self._session.get(url, params=params) as response:
+                if response.status == 401:
+                    raise AuthenticationError("Invalid API key")
+                response.raise_for_status()
+                data = await response.json()
+                return IdeasResponse.from_dict(data)
+        except aiohttp.ClientError as e:
+            raise APIError(f"Request failed: {e}")
+
+    async def close(self):
+        """Close the session"""
+        if self._session:
+            await self._session.close()
+            self._session = None

agualpha/client.py

@@ -0,0 +1,109 @@
+"""
+Synchronous API client for AGuAlpha
+"""
+
+import requests
+from typing import Optional
+from .models import PositionsResponse, IdeasResponse
+from .exceptions import APIError, AuthenticationError, ServerError
+
+
+class AGuAlphaClient:
+    """Synchronous client for AGuAlpha API"""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.agualpha.com/api"
+    ):
+        """
+        Initialize the AGuAlpha client
+
+        Args:
+            api_key: Your API key
+            base_url: Base URL for the API (default: https://api.agualpha.com/api)
+        """
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.session = requests.Session()
+        self.session.headers.update({"X-API-Key": api_key})
+
+    def get_positions(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None
+    ) -> PositionsResponse:
+        """
+        Get position data from subscribed analysts
+
+        Args:
+            start_date: Filter by start date (YYYY-MM-DD format)
+            end_date: Filter by end date (YYYY-MM-DD format)
+
+        Returns:
+            PositionsResponse: Response containing position data
+        """
+        url = f"{self.base_url}/investor/data/positions"
+        params = {}
+        if start_date:
+            params["startDate"] = start_date
+        if end_date:
+            params["endDate"] = end_date
+
+        try:
+            response = self.session.get(url, params=params)
+            response.raise_for_status()
+            data = response.json()
+            return PositionsResponse.from_dict(data)
+        except requests.HTTPError as e:
+            if e.response.status_code == 401:
+                raise AuthenticationError("Invalid API key")
+            raise ServerError(f"Server error: {e}")
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {e}")
+
+    def get_ideas(
+        self,
+        status: Optional[str] = None,
+        direction: Optional[str] = None
+    ) -> IdeasResponse:
+        """
+        Get trade ideas from subscribed analysts
+
+        Args:
+            status: Filter by status (active, closed)
+            direction: Filter by direction (long, short)
+
+        Returns:
+            IdeasResponse: Response containing trade ideas data
+        """
+        url = f"{self.base_url}/investor/data/ideas"
+        params = {}
+        if status:
+            params["status"] = status
+        if direction:
+            params["direction"] = direction
+
+        try:
+            response = self.session.get(url, params=params)
+            response.raise_for_status()
+            data = response.json()
+            return IdeasResponse.from_dict(data)
+        except requests.HTTPError as e:
+            if e.response.status_code == 401:
+                raise AuthenticationError("Invalid API key")
+            raise ServerError(f"Server error: {e}")
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {e}")
+
+    def close(self):
+        """Close the session"""
+        self.session.close()
+
+    def __enter__(self):
+        """Context manager entry"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit"""
+        self.close()

agualpha/exceptions.py

@@ -0,0 +1,28 @@
+"""
+Custom exceptions for AGuAlpha API client
+"""
+
+
+class APIError(Exception):
+    """Base exception for API errors"""
+    pass
+
+
+class AuthenticationError(APIError):
+    """Raised when API key authentication fails"""
+    pass
+
+
+class RateLimitError(APIError):
+    """Raised when API rate limit is exceeded"""
+    pass
+
+
+class InvalidRequestError(APIError):
+    """Raised when request parameters are invalid"""
+    pass
+
+
+class ServerError(APIError):
+    """Raised when server returns an error"""
+    pass

agualpha/models.py

@@ -0,0 +1,118 @@
+"""
+Data models for AGuAlpha API responses
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Any, Optional
+
+
+@dataclass
+class Position:
+    """Position data model"""
+    date: str
+    time: str
+    price: Optional[float]
+    buy_sell: Optional[int]
+    outstanding: Optional[int]
+    value: Optional[float]
+    af_backward: Optional[float]
+    money_flow: Optional[float]
+    operation_type: Optional[str]
+    execution_status: Optional[str]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Position":
+        return cls(
+            date=data.get("date", ""),
+            time=data.get("time", ""),
+            price=data.get("price"),
+            buy_sell=data.get("buy_sell"),
+            outstanding=data.get("outstanding"),
+            value=data.get("value"),
+            af_backward=data.get("af_backward"),
+            money_flow=data.get("money_flow"),
+            operation_type=data.get("operation_type"),
+            execution_status=data.get("execution_status"),
+        )
+
+
+@dataclass
+class Idea:
+    """Trade idea data model"""
+    ticker_symbol: str
+    company_name: str
+    direction: str
+    hedge_instrument: Optional[str]
+    target_amount: Optional[float]
+    calculated_shares: Optional[int]
+    actual_cost: Optional[float]
+    target_price: Optional[float]
+    stop_loss_price: Optional[float]
+    thesis: Optional[str]
+    catalysts: Optional[str]
+    status: str
+    position_open_date: Optional[str]
+    position_close_date: Optional[str]
+    close_price: Optional[float]
+    close_reason: Optional[str]
+    idea_created_at: Optional[str]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Idea":
+        return cls(
+            ticker_symbol=data.get("ticker_symbol", ""),
+            company_name=data.get("company_name", ""),
+            direction=data.get("direction", ""),
+            hedge_instrument=data.get("hedge_instrument"),
+            target_amount=data.get("target_amount"),
+            calculated_shares=data.get("calculated_shares"),
+            actual_cost=data.get("actual_cost"),
+            target_price=data.get("target_price"),
+            stop_loss_price=data.get("stop_loss_price"),
+            thesis=data.get("thesis"),
+            catalysts=data.get("catalysts"),
+            status=data.get("status", ""),
+            position_open_date=data.get("position_open_date"),
+            position_close_date=data.get("position_close_date"),
+            close_price=data.get("close_price"),
+            close_reason=data.get("close_reason"),
+            idea_created_at=data.get("idea_created_at"),
+        )
+
+
+@dataclass
+class PositionsResponse:
+    """Response model for positions endpoint"""
+    success: bool
+    total: int
+    data: List[Position]
+    error: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PositionsResponse":
+        positions = [Position.from_dict(item) for item in data.get("data", [])]
+        return cls(
+            success=data.get("success", False),
+            total=data.get("total", 0),
+            data=positions,
+            error=data.get("error"),
+        )
+
+
+@dataclass
+class IdeasResponse:
+    """Response model for ideas endpoint"""
+    success: bool
+    total: int
+    data: List[Idea]
+    error: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "IdeasResponse":
+        ideas = [Idea.from_dict(item) for item in data.get("data", [])]
+        return cls(
+            success=data.get("success", False),
+            total=data.get("total", 0),
+            data=ideas,
+            error=data.get("error"),
+        )

agualpha/utils.py

@@ -0,0 +1,89 @@
+"""
+Utility functions for AGuAlpha library
+"""
+
+import pandas as pd
+from typing import List, Union
+from .models import Position, Idea
+
+
+def positions_to_dataframe(positions: List[Position]) -> pd.DataFrame:
+    """
+    Convert list of Position objects to pandas DataFrame
+
+    Args:
+        positions: List of Position objects
+
+    Returns:
+        pd.DataFrame: DataFrame containing position data
+    """
+    data = [
+        {
+            "date": p.date,
+            "time": p.time,
+            "price": p.price,
+            "buy_sell": p.buy_sell,
+            "outstanding": p.outstanding,
+            "value": p.value,
+            "af_backward": p.af_backward,
+            "money_flow": p.money_flow,
+            "operation_type": p.operation_type,
+            "execution_status": p.execution_status,
+        }
+        for p in positions
+    ]
+    return pd.DataFrame(data)
+
+
+def ideas_to_dataframe(ideas: List[Idea]) -> pd.DataFrame:
+    """
+    Convert list of Idea objects to pandas DataFrame
+
+    Args:
+        ideas: List of Idea objects
+
+    Returns:
+        pd.DataFrame: DataFrame containing idea data
+    """
+    data = [
+        {
+            "ticker_symbol": i.ticker_symbol,
+            "company_name": i.company_name,
+            "direction": i.direction,
+            "hedge_instrument": i.hedge_instrument,
+            "target_amount": i.target_amount,
+            "calculated_shares": i.calculated_shares,
+            "actual_cost": i.actual_cost,
+            "target_price": i.target_price,
+            "stop_loss_price": i.stop_loss_price,
+            "thesis": i.thesis,
+            "catalysts": i.catalysts,
+            "status": i.status,
+            "position_open_date": i.position_open_date,
+            "position_close_date": i.position_close_date,
+            "close_price": i.close_price,
+            "close_reason": i.close_reason,
+            "idea_created_at": i.idea_created_at,
+        }
+        for i in ideas
+    ]
+    return pd.DataFrame(data)
+
+
+def export_to_csv(data: Union[List[Position], List[Idea]], filename: str):
+    """
+    Export data to CSV file
+
+    Args:
+        data: List of Position or Idea objects
+        filename: Output CSV filename
+    """
+    if isinstance(data[0], Position):
+        df = positions_to_dataframe(data)
+    elif isinstance(data[0], Idea):
+        df = ideas_to_dataframe(data)
+    else:
+        raise ValueError("Data must be list of Position or Idea objects")
+
+    df.to_csv(filename, index=False)
+    print(f"Data exported to {filename}")

agualpha-1.0.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: agualpha
+Version: 1.0.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

agualpha-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+agualpha/__init__.py,sha256=52mtgz_2V1FkijEhlu8XScAMVOQQI8QqqB6DxRKpM9w,547
+agualpha/async_client.py,sha256=O_7lI7t_8kxL2U-98uAhzSB_mqEvmhqWwvRgeAKUziw,3639
+agualpha/client.py,sha256=EmCPNGc6A0H5TAMmuGB7W9y8yBlMxltBXlNoxtVmZwE,3302
+agualpha/exceptions.py,sha256=tHf56SiKv_ua8o9rKk4X_D-I50RE3-1_AIdCfMOoeI4,506
+agualpha/models.py,sha256=FnvKBX7HqwVj3NHf3EptpuP4OmiZxI3T4nWLVGzR0eY,3597
+agualpha/utils.py,sha256=k6Sp4q-WlUtgEAmh6EHv0mM0UcJhemdV1UBKny9m7Nw,2517
+agualpha-1.0.0.dist-info/licenses/LICENSE,sha256=ovg1h9Q06PLwHn8T7kNzMeVE8ZIKlQb8Ud19SUiT-Tg,1065
+agualpha-1.0.0.dist-info/METADATA,sha256=eossmRDK5Ic8-WL7QBTm1YBj4Q3sdMUfSQ3Ne6aOyv4,5192
+agualpha-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+agualpha-1.0.0.dist-info/entry_points.txt,sha256=BvyMdH68c9hu8vNhNoJtKMgcx723WxPOVk7JEeybxzA,47
+agualpha-1.0.0.dist-info/top_level.txt,sha256=fc_X8-D1wrOZekD_G7u3WOmXaoUEDTRFU_rJiMuJ_mo,9
+agualpha-1.0.0.dist-info/RECORD,,

agualpha-1.0.0.dist-info/WHEEL

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

agualpha-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agualpha = agualpha.cli:main

agualpha-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AGuAlpha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agualpha-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agualpha