Metadata-Version: 2.4
Name: algierex
Version: 1.0.0
Summary: Python SDK for the Algierex market data API (the Algerian exchange)
Author-email: Algierex <contact@algierex.com>
License: MIT
Project-URL: Homepage, https://algierex.com/developers
Project-URL: Documentation, https://algierex.com/developers/docs
Keywords: algeria,algiers,stock exchange,market data,finance,api
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == "pandas"
Dynamic: license-file

# algierex (Python)

Python SDK for the [Algierex market data API](https://algierex.com/developers/docs): the Algerian exchange's daily prices back to 1999, sessions, the Dzair index, the OAT yield curve, exchange rates, company events and news.

No dependencies. Python 3.9 or newer.

## Install

```sh
pip install algierex            # or "algierex[pandas]" for to_frame()
```

## Get a key

Create a key and choose a plan at [algierex.com/developers](https://algierex.com/developers). Then:

```sh
export ALGIEREX_API_KEY=alx_...
```

## Example

```python
from algierex import Algierex, PaymentRequiredError, to_frame

client = Algierex()  # reads ALGIEREX_API_KEY

try:
    client.list_tickers()
except PaymentRequiredError as err:
    raise SystemExit(f"{err}")  # no active plan: choose one at algierex.com/developers

# Every daily close of Saidal since 2025, as a pandas DataFrame.
prices = to_frame(client.get_prices("SAI", from_="2025-01-01"))
print(prices["close"].tail())

# The OAT yield curve on a past date.
curve = client.get_yield_curve(date="2026-09-30")
print(curve["asOf"], curve["fit"]["rSquared"] if curve["fit"] else "not enough trades")

# Upcoming company events, in French.
for event in client.get_calendar(from_="2026-11-01", locale="fr"):
    print(event["date"], event["ticker"], event["label"])
```

## Methods

| Method | Route |
|---|---|
| `list_tickers()` | `GET /tickers` |
| `get_prices(ticker, from_=, to=)` | `GET /prices/{ticker}` |
| `list_sessions(market=, from_=, to=)` | `GET /sessions` |
| `get_dzair_index(from_=, to=)` | `GET /index/dzair` |
| `get_yield_curve(date=)` | `GET /yield-curve` |
| `list_fx()` | `GET /fx` |
| `get_fx_history(code, source=, from_=, to=)` | `GET /fx/{code}` |
| `get_calendar(from_=, to=, ticker=, locale=)` | `GET /calendar` |
| `list_news(ticker=, source=, from_=, to=, locale=, include_routine=)` | `GET /news` |

`from` is a Python keyword, so the parameter is `from_`. Every response is plain JSON (dicts and lists), typed with `TypedDict`s.

## Paging

Paging is automatic: list methods return every row. For long histories, the `iter_*` twin yields rows as pages arrive:

```python
for day in client.iter_prices("SAI"):
    ...
```

`page_size` (1 to 1000, default 1000) sets rows per request; the default keeps calls against your plan's limits low.

## Errors

Every error raises a subclass of `AlgierexError`, with `.status` and `.code`:

| Exception | When |
|---|---|
| `BadRequestError` | 400: a parameter is not valid |
| `AuthenticationError` | 401: the key is missing, wrong, or revoked |
| `PaymentRequiredError` | 402: no active plan, or the last payment failed |
| `NotFoundError` | 404: no such security, currency, or date |
| `RateLimitError` | 429: the plan's limit is used up; `.retry_after` in seconds |

On a 429 the client waits `Retry-After` and retries, up to `max_retries` (default 3) and only for waits up to `max_retry_wait` seconds (default 60). `Algierex(max_retries=0)` raises at once. Server errors (5xx), timeouts (`timeout=30` seconds) and network failures raise `AlgierexError` and are not retried.

## Regenerating

This SDK is generated from the API's OpenAPI spec. From the repository root, after `npm install`: `npm run sdk`.
