Metadata-Version: 2.4
Name: axprism
Version: 0.2.0
Summary: AxPrism API client — institutional XBRL data, Shariah compliance screening, SEC/EDGAR, ESEF, Tadawul/Bursa/IDX
Home-page: https://axprism.com
Author: AxPrism
Author-email: AxPrism <dev@axprism.com>
Maintainer: AxPrism
Maintainer-email: AxPrism <dev@axprism.com>
License: MIT
Project-URL: Homepage, https://axprism.com
Project-URL: Documentation, https://axprism.com/api-reference
Project-URL: API Reference, https://axprism.com/api-reference
Project-URL: Bug Reports, https://axprism.com/contact
Keywords: xbrl,financial-data,shariah-compliance,aaoifi,sec-edgar,esef,tadawul
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
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
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: async
Requires-Dist: httpx>=0.24.0; extra == "async"
Provides-Extra: pandas
Requires-Dist: pandas>=1.5.0; extra == "pandas"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: maintainer
Dynamic: requires-python

# axprism

Official Python SDK for the [AxPrism API](https://axprism.com) — institutional
XBRL data, Shariah compliance screening (AAOIFI, MSCI Islamic, DJIM, FTSE, Saudi
CMA), SEC/EDGAR, ESEF, EDINET, and the Tadawul / Bursa Malaysia / IDX exchanges.

## Installation

> **Coming soon to PyPI.** `pip install axprism` will work once the package is
> published. For now, install from a local checkout of this repo:

```bash
# From the repo root:
pip install ./sdk/python
# …or for development (editable install):
pip install -e ./sdk/python
```

Requires Python 3.8+ and [`requests`](https://pypi.org/project/requests/).

## Authentication

AxPrism authenticates with the `X-API-Key` header. Get a key at
[axprism.com/keys](https://axprism.com/keys). A public **read-only demo key** is
available for trying the API: `axmd_demo_try_axprism_2024`.

```python
from axprism import AxPrism

client = AxPrism(api_key="axmd_live_...")
```

## Quick Start

```python
from axprism import AxPrism

client = AxPrism(api_key="axmd_demo_try_axprism_2024")

# Shariah compliance screening
result = client.compliance("AAPL", standard="aaoifi")
print(result.verdict)               # "halal"
print(result.ratios.debt.ratio)     # 0.026
print(result.ratios.debt.passes)    # True

# Screen a full portfolio (with purification)
portfolio = client.portfolio([
    {"ticker": "AAPL", "weight": 35, "shares": 120, "dividend_per_share": 0.96},
    {"ticker": "MSFT", "weight": 25, "shares": 80,  "dividend_per_share": 3.32},
])
print(portfolio.summary.halal_weight)
print(portfolio.purification.total_usd)

# Normalized financial statements (values are display strings; use as_number=True for floats)
fin = client.financials("AAPL", statement="IS", period="annual", currency="USD")
print(fin.get_metric("Revenue"))                  # "$416,161,000,000"
print(f"Revenue: ${fin.get_metric('Revenue', as_number=True):,.0f}")

# Price history
hist = client.prices("AAPL", start="2024-01-01", limit=252)
print(hist.prices[0].close)
```

## Endpoint coverage

The SDK provides typed, ergonomic methods across all key groups. For any of the
API's 165+ operations not given a dedicated method, use the generic
`client.request(method, path, params=..., json=...)` escape hatch.

| Group | Methods |
|-------|---------|
| **Compliance** | `compliance`, `compliance_multi`, `compliance_trend`, `compliance_history`, `compliance_point_in_time`, `compliance_audit`, `sukuk`, `portfolio`, `screen_compliance`, `purification`, `is_halal` |
| **Financials** | `financials`, `ttm`, `batch_metric`, `compare`, `facts`, `segments`, `nongaap`, `restatements`, `restatement_events`, `concept_history`, `concepts_search`, `screener` |
| **Profile / symbols** | `profile`, `market_cap`, `symbols`, `exchanges`, `company_resolve` |
| **Market data** | `prices`, `estimates`, `news`, `insiders`, `holders_13f`, `etf_holdings`, `options_chain`, `corporate_actions`, `esg`, `calendar`, `fx_rates` |
| **Disclosures / text** | `disclosures.search`, `disclosures.recent`, `disclosures.facets`, `text.search`, `text.stats`, `text.index` |
| **International** | `tadawul.*`, `bursa.*`, `idx.*` (`symbols`, `profile`, `financials`, `sectors`, `shariah`) |
| **Filings** | `filing_index`, `filing_as_reported`, `filing_footnote_graph`, `filing_diff`, `filing_textblocks` |
| **Webhooks** | `webhooks.list`, `webhooks.events`, `webhooks.create`, `webhooks.delete` |
| **Bulk / export** | `bulk_financials` (CSV), `excel_workbook` (XLSX bytes) |
| **Coverage** | `coverage_core50`, `coverage_summary`, `benchmark_financials_50` |
| **Account** | `me`, `usage`, `pricing`, `rulesets`, `metrics_catalog`, `keys.*` |

### International exchanges

```python
client.tadawul.symbols(limit=10)        # Saudi Tadawul registry
client.tadawul.financials("2222")       # Saudi Aramco
client.bursa.shariah()                  # Bursa Malaysia SC list
client.idx.profile("BBCA")              # Indonesia Stock Exchange
```

### Disclosure & text search

```python
client.disclosures.search("supply chain risk", ticker="AAPL", forms=["10-K", "10-Q"])
client.disclosures.recent("AAPL", limit=10)
client.text.search("revenue recognition", ticker="MSFT")
```

### Pagination

```python
for hit in client.paginate("/api/v1/disclosures/search",
                           {"q": "climate", "ticker": "AAPL"},
                           items_key="results", max_items=200):
    print(hit)
```

## Error Handling & Retries

The client retries automatically on `429` (honoring `Retry-After`) and transient
`5xx` errors with exponential backoff (configurable via `max_retries` and
`backoff_factor`).

```python
from axprism import AxPrism, AuthError, RateLimitError, TierError, NotFoundError

client = AxPrism(api_key="...", max_retries=3, backoff_factor=0.5)

try:
    result = client.compliance("AAPL")
except AuthError:
    print("Invalid API key (401)")
except TierError as e:                       # 402 / 403
    print(f"Need {e.required_tier}. Upgrade at {e.upgrade_url}")
except RateLimitError as e:                  # 429
    print(f"Quota exceeded: {e.used_today}/{e.daily_limit}")
except NotFoundError:                        # 404
    print("Ticker not found")
```

## Examples & tests

- `examples/quickstart.py` — runnable script using the demo key.
- `tests/test_live.py` — read-only live tests (`pytest`).

## Documentation

- **API Reference**: [axprism.com/api-reference](https://axprism.com/api-reference)
- **Pricing**: [axprism.com/pricing](https://axprism.com/pricing)
- **Support**: support@axprism.com

## License

MIT — see [LICENSE](./LICENSE).
