stocksim-sdk 0.1.0__tar.gz

stocksim_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

stocksim_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

stocksim_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: stocksim-sdk
+Version: 0.1.0
+Summary: Official async Python SDK for StockSim Pro API
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# stocksim-sdk
+
+Official async Python SDK for [StockSim Pro](https://stocksim.pro).
+
+- Python 3.13+
+- Async-first (`asyncio` / `httpx`)
+- Typed responses via `dataclasses`
+- Zero heavy dependencies
+
+## Installation
+
+```bash
+pip install stocksim-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from stocksim import StockSimClient
+
+async def main():
+    async with StockSimClient(api_key="your-api-key") as client:
+        price = await client.get_price("AAPL")
+        print(price.ticker, price.price)
+
+asyncio.run(main())
+```
+
+## Usage
+
+### Get price
+
+```python
+async with StockSimClient(api_key="your-api-key") as client:
+    price = await client.get_price("TSLA")
+    # PriceResponse(ticker='TSLA', price=182.5, timestamp='2026-06-16T10:00:00Z')
+    print(f"{price.ticker}: ${price.price}")
+```
+
+### Get portfolio
+
+```python
+async with StockSimClient(api_key="your-api-key") as client:
+    portfolio = await client.get_portfolio()
+    print(f"Balance: ${portfolio.balance:.2f}")
+    for pos in portfolio.positions:
+        print(f"  {pos.ticker}  qty={pos.quantity}  avg=${pos.avg_price}")
+```
+
+### Place an order
+
+```python
+async with StockSimClient(api_key="your-api-key") as client:
+    order = await client.place_order(ticker="AAPL", action="buy", quantity=5)
+    print(f"Order {order.order_id} — {order.status}")
+```
+
+## Error Handling
+
+```python
+from stocksim import (
+    StockSimClient,
+    StockSimAuthError,
+    StockSimRateLimitError,
+    StockSimValidationError,
+    StockSimError,
+)
+
+async with StockSimClient(api_key="your-api-key") as client:
+    try:
+        price = await client.get_price("AAPL")
+    except StockSimAuthError:
+        print("Invalid or missing API key")
+    except StockSimRateLimitError as e:
+        retry = e.retry_after
+        print(f"Rate limit hit — retry after {retry}s")
+    except StockSimValidationError as e:
+        for err in e.errors:
+            print(f"Validation: {err['msg']} at {err['loc']}")
+    except StockSimError as e:
+        print(f"API error {e.status_code}: {e}")
+```
+
+## Manual session management
+
+If you prefer not to use `async with`, call `close()` explicitly:
+
+```python
+client = StockSimClient(api_key="your-api-key")
+try:
+    price = await client.get_price("AAPL")
+finally:
+    await client.close()
+```
+
+## License
+
+MIT

stocksim_sdk-0.1.0/README.md

@@ -0,0 +1,99 @@
+# stocksim-sdk
+
+Official async Python SDK for [StockSim Pro](https://stocksim.pro).
+
+- Python 3.13+
+- Async-first (`asyncio` / `httpx`)
+- Typed responses via `dataclasses`
+- Zero heavy dependencies
+
+## Installation
+
+```bash
+pip install stocksim-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from stocksim import StockSimClient
+
+async def main():
+    async with StockSimClient(api_key="your-api-key") as client:
+        price = await client.get_price("AAPL")
+        print(price.ticker, price.price)
+
+asyncio.run(main())
+```
+
+## Usage
+
+### Get price
+
+```python
+async with StockSimClient(api_key="your-api-key") as client:
+    price = await client.get_price("TSLA")
+    # PriceResponse(ticker='TSLA', price=182.5, timestamp='2026-06-16T10:00:00Z')
+    print(f"{price.ticker}: ${price.price}")
+```
+
+### Get portfolio
+
+```python
+async with StockSimClient(api_key="your-api-key") as client:
+    portfolio = await client.get_portfolio()
+    print(f"Balance: ${portfolio.balance:.2f}")
+    for pos in portfolio.positions:
+        print(f"  {pos.ticker}  qty={pos.quantity}  avg=${pos.avg_price}")
+```
+
+### Place an order
+
+```python
+async with StockSimClient(api_key="your-api-key") as client:
+    order = await client.place_order(ticker="AAPL", action="buy", quantity=5)
+    print(f"Order {order.order_id} — {order.status}")
+```
+
+## Error Handling
+
+```python
+from stocksim import (
+    StockSimClient,
+    StockSimAuthError,
+    StockSimRateLimitError,
+    StockSimValidationError,
+    StockSimError,
+)
+
+async with StockSimClient(api_key="your-api-key") as client:
+    try:
+        price = await client.get_price("AAPL")
+    except StockSimAuthError:
+        print("Invalid or missing API key")
+    except StockSimRateLimitError as e:
+        retry = e.retry_after
+        print(f"Rate limit hit — retry after {retry}s")
+    except StockSimValidationError as e:
+        for err in e.errors:
+            print(f"Validation: {err['msg']} at {err['loc']}")
+    except StockSimError as e:
+        print(f"API error {e.status_code}: {e}")
+```
+
+## Manual session management
+
+If you prefer not to use `async with`, call `close()` explicitly:
+
+```python
+client = StockSimClient(api_key="your-api-key")
+try:
+    price = await client.get_price("AAPL")
+finally:
+    await client.close()
+```
+
+## License
+
+MIT

stocksim_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "stocksim-sdk"
+version = "0.1.0"
+description = "Official async Python SDK for StockSim Pro API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+]
+
+[tool.uv.workspace]
+members = [
+    "stocksim-sdk",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

stocksim_sdk-0.1.0/src/stocksim_sdk/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from stocksim-sdk!"

stocksim_sdk-0.1.0/src/stocksim_sdk/client.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from stocksim.exceptions import _raise_for_status
+from stocksim.models import OrderResponse, PortfolioResponse, PriceResponse
+
+_DEFAULT_BASE_URL = "https://api.stocksim.pro"
+
+
+class StockSimClient:
+    """Async HTTP client for the StockSim Pro API."""
+
+    def __init__(self, api_key: str, base_url: str = _DEFAULT_BASE_URL) -> None:
+        self._http = httpx.AsyncClient(
+            base_url=base_url,
+            headers={"X-API-Key": api_key},
+            timeout=30.0,
+        )
+
+    async def __aenter__(self) -> StockSimClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP session."""
+        await self._http.aclose()
+
+    async def _request(self, method: str, endpoint: str, **kwargs: Any) -> Any:
+        response = await self._http.request(method, endpoint, **kwargs)
+        _raise_for_status(response)
+        return response.json()
+
+    async def get_price(self, ticker: str) -> PriceResponse:
+        """Fetch the current price for *ticker*."""
+        data = await self._request("GET", f"/prices/{ticker}")
+        return PriceResponse.from_dict(data)
+
+    async def get_portfolio(self) -> PortfolioResponse:
+        """Fetch the authenticated user's portfolio."""
+        data = await self._request("GET", "/portfolio")
+        return PortfolioResponse.from_dict(data)
+
+    async def place_order(self, ticker: str, action: str, quantity: int) -> OrderResponse:
+        """Place a buy/sell order.
+
+        Args:
+            ticker: Stock symbol, e.g. ``"AAPL"``.
+            action: ``"buy"`` or ``"sell"``.
+            quantity: Number of shares.
+        """
+        data = await self._request(
+            "POST",
+            "/orders",
+            json={"ticker": ticker, "action": action, "quantity": quantity},
+        )
+        return OrderResponse.from_dict(data)

stocksim_sdk-0.1.0/src/stocksim_sdk/exceptions.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class StockSimError(Exception):
+    """Base exception for all StockSim SDK errors."""
+
+    def __init__(self, message: str, *, status_code: int | None = None, detail: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.args[0]!r}, status_code={self.status_code})"
+
+
+class StockSimAuthError(StockSimError):
+    """Raised on 401 Unauthorized or 403 Forbidden responses."""
+
+
+class StockSimRateLimitError(StockSimError):
+    """Raised on 429 Too Many Requests responses."""
+
+    def __init__(self, message: str, *, status_code: int = 429, detail: Any = None, retry_after: int | None = None) -> None:
+        super().__init__(message, status_code=status_code, detail=detail)
+        self.retry_after = retry_after
+
+
+class StockSimValidationError(StockSimError):
+    """Raised on 422 Unprocessable Entity responses (FastAPI validation errors)."""
+
+    def __init__(self, message: str, *, status_code: int = 422, detail: Any = None) -> None:
+        super().__init__(message, status_code=status_code, detail=detail)
+        self.errors: list[dict[str, Any]] = detail if isinstance(detail, list) else []
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Parse an error response from the StockSim API and raise the appropriate exception."""
+    if response.is_success:
+        return
+
+    status_code = response.status_code
+    detail: Any = None
+    message = f"HTTP {status_code}"
+
+    try:
+        body = response.json()
+        detail = body.get("detail", body)
+        if isinstance(detail, str):
+            message = detail
+        elif isinstance(detail, list) and detail:
+            first = detail[0]
+            if isinstance(first, dict):
+                message = first.get("msg", message)
+    except Exception:
+        message = response.text or message
+
+    if status_code in (401, 403):
+        raise StockSimAuthError(message, status_code=status_code, detail=detail)
+    if status_code == 422:
+        raise StockSimValidationError(message, status_code=status_code, detail=detail)
+    if status_code == 429:
+        retry_after: int | None = None
+        raw = response.headers.get("Retry-After")
+        if raw is not None:
+            try:
+                retry_after = int(raw)
+            except ValueError:
+                pass
+        raise StockSimRateLimitError(message, status_code=status_code, detail=detail, retry_after=retry_after)
+
+    raise StockSimError(message, status_code=status_code, detail=detail)

stocksim_sdk-0.1.0/src/stocksim_sdk/models.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Self
+
+
+@dataclass(frozen=True)
+class PriceResponse:
+    ticker: str
+    price: float
+    timestamp: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        return cls(
+            ticker=data["ticker"],
+            price=float(data["price"]),
+            timestamp=data["timestamp"],
+        )
+
+
+@dataclass(frozen=True)
+class PortfolioPosition:
+    ticker: str
+    quantity: int
+    avg_price: float
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        return cls(
+            ticker=data["ticker"],
+            quantity=int(data["quantity"]),
+            avg_price=float(data["avg_price"]),
+        )
+
+
+@dataclass(frozen=True)
+class PortfolioResponse:
+    balance: float
+    positions: list[PortfolioPosition]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        return cls(
+            balance=float(data["balance"]),
+            positions=[PortfolioPosition.from_dict(p) for p in data.get("positions", [])],
+        )
+
+
+@dataclass(frozen=True)
+class OrderResponse:
+    order_id: str
+    ticker: str
+    action: str
+    quantity: int
+    status: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        return cls(
+            order_id=data["order_id"],
+            ticker=data["ticker"],
+            action=data["action"],
+            quantity=int(data["quantity"]),
+            status=data["status"],
+        )

stocksim_sdk-0.1.0/src/tests/test_client.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import pytest
+import respx
+from httpx import Response
+
+from stocksim import (
+    StockSimAuthError,
+    StockSimClient,
+    StockSimRateLimitError,
+    StockSimValidationError,
+)
+from stocksim.models import OrderResponse, PortfolioResponse, PriceResponse
+
+BASE = "https://api.stocksim.pro"
+
+
+@pytest.fixture
+def client() -> StockSimClient:
+    return StockSimClient(api_key="test-key", base_url=BASE)
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_get_price_success(client: StockSimClient) -> None:
+    respx.get(f"{BASE}/prices/AAPL").mock(
+        return_value=Response(200, json={"ticker": "AAPL", "price": 182.5, "timestamp": "2026-06-16T10:00:00Z"})
+    )
+
+    result = await client.get_price("AAPL")
+
+    assert isinstance(result, PriceResponse)
+    assert result.ticker == "AAPL"
+    assert result.price == 182.5
+    assert result.timestamp == "2026-06-16T10:00:00Z"
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_get_portfolio_success(client: StockSimClient) -> None:
+    respx.get(f"{BASE}/portfolio").mock(
+        return_value=Response(
+            200,
+            json={
+                "balance": 10000.0,
+                "positions": [{"ticker": "AAPL", "quantity": 5, "avg_price": 175.0}],
+            },
+        )
+    )
+
+    result = await client.get_portfolio()
+
+    assert isinstance(result, PortfolioResponse)
+    assert result.balance == 10000.0
+    assert len(result.positions) == 1
+    assert result.positions[0].ticker == "AAPL"
+    assert result.positions[0].quantity == 5
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_place_order_success(client: StockSimClient) -> None:
+    respx.post(f"{BASE}/orders").mock(
+        return_value=Response(
+            201,
+            json={"order_id": "ord-123", "ticker": "TSLA", "action": "buy", "quantity": 10, "status": "filled"},
+        )
+    )
+
+    result = await client.place_order("TSLA", "buy", 10)
+
+    assert isinstance(result, OrderResponse)
+    assert result.order_id == "ord-123"
+    assert result.action == "buy"
+    assert result.status == "filled"
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_auth_error_raises_StockSimAuthError(client: StockSimClient) -> None:
+    respx.get(f"{BASE}/portfolio").mock(
+        return_value=Response(401, json={"detail": "Invalid API key"})
+    )
+
+    with pytest.raises(StockSimAuthError) as exc_info:
+        await client.get_portfolio()
+
+    assert exc_info.value.status_code == 401
+    assert "Invalid API key" in str(exc_info.value)
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_forbidden_raises_StockSimAuthError(client: StockSimClient) -> None:
+    respx.get(f"{BASE}/portfolio").mock(
+        return_value=Response(403, json={"detail": "Forbidden"})
+    )
+
+    with pytest.raises(StockSimAuthError) as exc_info:
+        await client.get_portfolio()
+
+    assert exc_info.value.status_code == 403
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_rate_limit_raises_StockSimRateLimitError(client: StockSimClient) -> None:
+    respx.get(f"{BASE}/prices/AAPL").mock(
+        return_value=Response(
+            429,
+            json={"detail": "Rate limit exceeded"},
+            headers={"Retry-After": "30"},
+        )
+    )
+
+    with pytest.raises(StockSimRateLimitError) as exc_info:
+        await client.get_price("AAPL")
+
+    assert exc_info.value.status_code == 429
+    assert exc_info.value.retry_after == 30
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_validation_error_raises_StockSimValidationError(client: StockSimClient) -> None:
+    respx.post(f"{BASE}/orders").mock(
+        return_value=Response(
+            422,
+            json={
+                "detail": [
+                    {"loc": ["body", "quantity"], "msg": "value is not a valid integer", "type": "type_error.integer"}
+                ]
+            },
+        )
+    )
+
+    with pytest.raises(StockSimValidationError) as exc_info:
+        await client.place_order("AAPL", "buy", -1)
+
+    assert exc_info.value.status_code == 422
+    assert len(exc_info.value.errors) == 1