Metadata-Version: 2.4
Name: stoxim-api
Version: 1.0.0
Summary: Python SDK for the Stoxim API — company master, financials, ratios, shareholding, governance, announcements, and more.
Project-URL: Homepage, https://github.com/imhnzla/stoxim-api-python
Project-URL: Documentation, https://docs.stoxim.com
Project-URL: Bug Tracker, https://github.com/imhnzla/stoxim-api-python/issues
License: MIT
License-File: LICENSE
Keywords: api,bse,financials,india,nse,sdk,stock market,stoxim
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Description-Content-Type: text/markdown

# stoxim-api

Official Python SDK for the [Stoxim](https://stoxim.com) Financial Data API — company master, financials, ratios, shareholding patterns, corporate actions, governance, and announcements for BSE/NSE-listed companies.

## Installation

```bash
pip install stoxim-api
```

Requires Python 3.10+.

## Quick Start

```python
from stoxim import Client

client = Client(api_key="sk_live_your_key_here")

# ── Company lookup ─────────────────────────────────────────────────────────────
company = client.company.get("INE040A01034")
print(company.name, company.sector)
# HDFC Bank  Financial Services

# ── Search ─────────────────────────────────────────────────────────────────────
results = client.company.search("Bajaj Finance", limit=5)
for c in results.items:
    print(c.isin, c.name)

# ── Financial periods ──────────────────────────────────────────────────────────
periods = client.financials.list("INE040A01034", period_type="annual", limit=5)
for p in periods.items:
    print(p.period_label, p.revenue, p.pat)

# ── Ratios ─────────────────────────────────────────────────────────────────────
ratios = client.ratios.get("INE040A01034", period_type="annual")
for r in ratios:
    print(r.period_label, r.roe, r.gross_margin, r.pe_ratio)

# ── Shareholding pattern ───────────────────────────────────────────────────────
patterns = client.shareholding.list("INE040A01034")
for s in patterns.items:
    print(s.period_end, s.promoter_pct, s.fii_pct)

# ── Corporate actions ──────────────────────────────────────────────────────────
actions = client.corporate_actions.list("INE040A01034", action_type="dividend")
for a in actions.items:
    print(a.ex_date, a.dividend_amount)

# ── Board composition (Starter+ plan) ─────────────────────────────────────────
board = client.governance.board("INE040A01034")
for member in board:
    print(member.name, member.designation)

# ── AGM records ────────────────────────────────────────────────────────────────
agm_records = client.governance.agm("INE040A01034")

# ── Related-party transactions ─────────────────────────────────────────────────
rpts = client.governance.related_party_transactions("INE040A01034")

# ── Announcements ──────────────────────────────────────────────────────────────
announcements = client.announcements.list(
    "INE040A01034",
    category="financials",
    from_date="2024-01-01",
)
for ann in announcements.items:
    print(ann.filing_date, ann.subject)
```

## Pagination

```python
# Paginate through all large-cap companies
for page in client.company.paginate(market_cap_category="large"):
    for company in page:
        print(company.isin, company.name)
```

## Context Manager

```python
with Client(api_key="sk_live_...") as client:
    company = client.company.get("INE040A01034")
# Connection is closed automatically
```

## Error Handling

```python
from stoxim import (
    AuthenticationError,
    NotFoundError,
    PlanRestrictionError,
    RateLimitError,
    InvalidParameterError,
    ApiError,
)

try:
    company = client.company.get("INVALID_ISIN")
except NotFoundError as e:
    print(f"Not found: {e.message}")
except PlanRestrictionError:
    print("Upgrade your plan to access this endpoint")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
except ApiError as e:
    print(f"Unexpected error [{e.error_code}]: {e.message}")
```

## Configuration

```python
client = Client(
    api_key="sk_live_...",
    timeout=60,          # seconds (default: 30)
    max_retries=5,       # includes initial attempt (default: 3)
    retry_on_429=True,   # respect Retry-After header on 429 (default: True)
)
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint + format
ruff check src/ tests/
ruff format src/ tests/

# Build
pip install build
python -m build
twine check dist/*
```

## License

MIT — see [LICENSE](LICENSE).
