grind-t-moex 0.1.0__tar.gz

grind_t_moex-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.3
+Name: grind-t-moex
+Version: 0.1.0
+Summary: Async Python client for the Moscow Exchange ISS API
+Author: grind-t
+Author-email: grind-t <grindt.gd@gmail.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.5
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# grind-t-moex
+
+Async Python client for the [Moscow Exchange ISS API](https://iss.moex.com/iss/reference/).
+Python port of [`@grind-t/moex`](https://github.com/grind-t/moex).
+
+## Installation
+
+```sh
+uv add grind-t-moex
+```
+
+## Usage
+
+```python
+import asyncio
+
+import httpx
+import moex
+
+
+async def main():
+    bonds = await moex.get_moex_bonds(primary_board=1)
+    print(bonds[0]["SECID"], bonds[0]["COUPONPERCENT"])
+
+    # Reuse one connection pool for several requests
+    async with httpx.AsyncClient() as client:
+        description = await moex.get_moex_security_description("SU26238RMFS4", client=client)
+        amortizations = await moex.get_moex_bond_amortizations("SU26238RMFS4", client=client)
+
+
+asyncio.run(main())
+```
+
+## Functions
+
+| Function | ISS resource |
+| --- | --- |
+| `get_moex_bonds(primary_board=)` | `engines/stock/markets/bonds/securities` → `securities` |
+| `get_moex_bonds_market_data()` | `engines/stock/markets/bonds/securities` → `marketdata` |
+| `get_moex_bonds_market_yield()` | `engines/stock/markets/bonds/securities` → `marketdata_yields` |
+| `get_moex_bond_coupons(...)` | `statistics/engines/stock/markets/bonds/bondization` → `coupons` |
+| `get_moex_bond_amortizations(id, ...)` | `securities/{id}/bondization` → `amortizations` |
+| `get_moex_bond_securities()` | all traded bonds from `securities`, paginated |
+| `get_moex_securities(...)` | `securities` → `securities` |
+| `get_moex_security_description(id)` | `securities/{id}` → `description` |
+| `get_moex_daily_table()` | `engines/stock` → `dailytable` |
+
+Low-level helpers: `moex_fetch(path, block, params)`, `get_moex_resource`, `parse_moex_block`.
+
+All functions accept an optional `client: httpx.AsyncClient`. The `from` query
+parameter is passed as `from_`.

grind_t_moex-0.1.0/README.md

@@ -0,0 +1,51 @@
+# grind-t-moex
+
+Async Python client for the [Moscow Exchange ISS API](https://iss.moex.com/iss/reference/).
+Python port of [`@grind-t/moex`](https://github.com/grind-t/moex).
+
+## Installation
+
+```sh
+uv add grind-t-moex
+```
+
+## Usage
+
+```python
+import asyncio
+
+import httpx
+import moex
+
+
+async def main():
+    bonds = await moex.get_moex_bonds(primary_board=1)
+    print(bonds[0]["SECID"], bonds[0]["COUPONPERCENT"])
+
+    # Reuse one connection pool for several requests
+    async with httpx.AsyncClient() as client:
+        description = await moex.get_moex_security_description("SU26238RMFS4", client=client)
+        amortizations = await moex.get_moex_bond_amortizations("SU26238RMFS4", client=client)
+
+
+asyncio.run(main())
+```
+
+## Functions
+
+| Function | ISS resource |
+| --- | --- |
+| `get_moex_bonds(primary_board=)` | `engines/stock/markets/bonds/securities` → `securities` |
+| `get_moex_bonds_market_data()` | `engines/stock/markets/bonds/securities` → `marketdata` |
+| `get_moex_bonds_market_yield()` | `engines/stock/markets/bonds/securities` → `marketdata_yields` |
+| `get_moex_bond_coupons(...)` | `statistics/engines/stock/markets/bonds/bondization` → `coupons` |
+| `get_moex_bond_amortizations(id, ...)` | `securities/{id}/bondization` → `amortizations` |
+| `get_moex_bond_securities()` | all traded bonds from `securities`, paginated |
+| `get_moex_securities(...)` | `securities` → `securities` |
+| `get_moex_security_description(id)` | `securities/{id}` → `description` |
+| `get_moex_daily_table()` | `engines/stock` → `dailytable` |
+
+Low-level helpers: `moex_fetch(path, block, params)`, `get_moex_resource`, `parse_moex_block`.
+
+All functions accept an optional `client: httpx.AsyncClient`. The `from` query
+parameter is passed as `from_`.

grind_t_moex-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "grind-t-moex"
+version = "0.1.0"
+description = "Async Python client for the Moscow Exchange ISS API"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.5",
+]
+
+[[project.authors]]
+name = "grind-t"
+email = "grindt.gd@gmail.com"
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "moex"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["e2e: hits the live MOEX ISS API"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+]

grind_t_moex-0.1.0/pyproject.toml.orig

@@ -0,0 +1,30 @@
+[project]
+name = "grind-t-moex"
+version = "0.1.0"
+description = "Async Python client for the Moscow Exchange ISS API"
+readme = "README.md"
+authors = [
+    { name = "grind-t", email = "grindt.gd@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.5",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "moex"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["e2e: hits the live MOEX ISS API"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+]

grind_t_moex-0.1.0/src/moex/__init__.py

@@ -0,0 +1,42 @@
+from .bond_amortizations import MoexBondAmortization, get_moex_bond_amortizations
+from .bond_coupons import MoexBondCoupon, get_moex_bond_coupons
+from .bond_securities import get_moex_bond_securities
+from .bonds import MoexBond, get_moex_bonds
+from .bonds_market_data import MoexBondMarketData, get_moex_bonds_market_data
+from .bonds_market_yield import MoexBondMarketYield, get_moex_bonds_market_yield
+from .core.fetch import moex_fetch, moex_get_json
+from .core.parse_block import parse_moex_block
+from .core.resource import get_moex_resource
+from .core.types import Engine, Market
+from .daily_table import MoexDailyTableRow, get_moex_daily_table
+from .securities import MoexSecurity, get_moex_securities
+from .security_description import (
+    MoexSecurityDescription,
+    get_moex_security_description,
+)
+
+__all__ = [
+    "Engine",
+    "Market",
+    "MoexBond",
+    "MoexBondAmortization",
+    "MoexBondCoupon",
+    "MoexBondMarketData",
+    "MoexBondMarketYield",
+    "MoexDailyTableRow",
+    "MoexSecurity",
+    "MoexSecurityDescription",
+    "get_moex_bond_amortizations",
+    "get_moex_bond_coupons",
+    "get_moex_bond_securities",
+    "get_moex_bonds",
+    "get_moex_bonds_market_data",
+    "get_moex_bonds_market_yield",
+    "get_moex_daily_table",
+    "get_moex_resource",
+    "get_moex_securities",
+    "get_moex_security_description",
+    "moex_fetch",
+    "moex_get_json",
+    "parse_moex_block",
+]

grind_t_moex-0.1.0/src/moex/bond_amortizations.py

@@ -0,0 +1,51 @@
+from datetime import date
+from typing import Literal
+
+import httpx
+from pydantic import BaseModel, Field
+
+from .core.fetch import moex_fetch
+
+
+class MoexBondAmortization(BaseModel):
+    isin: str = Field(pattern=r"^[A-Z]{2}[A-Z0-9]{9}[0-9]$")
+    name: str = Field(min_length=1)
+    # Not always whole: e.g. gold-linked bonds have a fractional issue volume.
+    issuevalue: float = Field(gt=0)
+    amortdate: date
+    facevalue: float = Field(gt=0)
+    initialfacevalue: float = Field(gt=0)
+    faceunit: str = Field(pattern=r"^[A-Z]{3}$")
+    # May exceed 100 for indexed bonds; 0 for future payments not yet known.
+    valueprc: float = Field(ge=0)
+    value: float = Field(ge=0)
+    # None when the payment amount is not known yet.
+    value_rub: float | None = Field(gt=0)
+    data_source: Literal["amortization", "maturity"]
+    secid: str = Field(min_length=1)
+    primary_boardid: str = Field(pattern=r"^[A-Z0-9]{4}$")
+
+
+async def get_moex_bond_amortizations(
+    id: str,
+    *,
+    lang: Literal["ru", "en"] | None = None,
+    from_: str | None = None,
+    till: str | None = None,
+    limit: int | None = None,
+    start: int | None = None,
+    client: httpx.AsyncClient | None = None,
+) -> list[MoexBondAmortization]:
+    rows = await moex_fetch(
+        f"securities/{id}/bondization.json",
+        "amortizations",
+        {
+            "lang": lang,
+            "from": from_,
+            "till": till,
+            "limit": "unlimited" if limit is None else limit,
+            "start": start,
+        },
+        client,
+    )
+    return [MoexBondAmortization.model_validate(row) for row in rows]

grind_t_moex-0.1.0/src/moex/bond_coupons.py

@@ -0,0 +1,47 @@
+from datetime import date
+from typing import Literal
+
+import httpx
+from pydantic import BaseModel, Field
+
+from .core.fetch import moex_fetch
+
+
+class MoexBondCoupon(BaseModel):
+    # None for some old (1990s) bonds.
+    isin: str | None = Field(pattern=r"^[A-Z]{2}[A-Z0-9]{9}[0-9]$")
+    name: str = Field(min_length=1)
+    # Not always whole (e.g. gold-linked bonds); 0 for some structured bonds.
+    issuevalue: float | None = Field(ge=0)
+    coupondate: date
+    recorddate: date | None
+    startdate: date | None
+    initialfacevalue: float | None = Field(gt=0)
+    # 0 for some fully amortized bonds.
+    facevalue: float = Field(ge=0)
+    faceunit: str = Field(pattern=r"^[A-Z]{3}$")
+    # None when the payment amount is not known yet.
+    value: float | None = Field(gt=0)
+    # Annualized, so may exceed 100 for short-period structured bonds.
+    valueprc: float | None = Field(gt=0)
+    value_rub: float | None = Field(gt=0)
+    secid: str = Field(min_length=1)
+    primary_boardid: str | None = Field(pattern=r"^[A-Z0-9]{4}$")
+
+
+async def get_moex_bond_coupons(
+    *,
+    lang: Literal["ru", "en"] | None = None,
+    from_: str | None = None,
+    till: str | None = None,
+    limit: Literal[5, 10, 20, 100] | None = None,
+    start: int | None = None,
+    client: httpx.AsyncClient | None = None,
+) -> list[MoexBondCoupon]:
+    rows = await moex_fetch(
+        "statistics/engines/stock/markets/bonds/bondization.json",
+        "coupons",
+        {"lang": lang, "from": from_, "till": till, "limit": limit, "start": start},
+        client,
+    )
+    return [MoexBondCoupon.model_validate(row) for row in rows]

grind_t_moex-0.1.0/src/moex/bond_securities.py

@@ -0,0 +1,30 @@
+import httpx
+
+from .securities import MoexSecurity, get_moex_securities
+
+
+async def get_moex_bond_securities(
+    *, client: httpx.AsyncClient | None = None
+) -> list[MoexSecurity]:
+    if client is None:
+        async with httpx.AsyncClient() as own_client:
+            return await get_moex_bond_securities(client=own_client)
+
+    securities: list[MoexSecurity] = []
+    start = 0
+
+    while True:
+        chunk = await get_moex_securities(
+            engine="stock",
+            market="bonds",
+            is_trading=1,
+            start=start,
+            limit=100,
+            client=client,
+        )
+
+        securities.extend(chunk)
+        start += len(chunk)
+
+        if len(chunk) < 100:
+            return securities

grind_t_moex-0.1.0/src/moex/bonds.py

@@ -0,0 +1,87 @@
+from datetime import date
+from typing import Annotated, Literal
+
+import httpx
+from pydantic import BaseModel, BeforeValidator, Field
+
+from .core.fetch import moex_fetch
+
+# ISS sends "0000-00-00" instead of null for a missing date.
+MaybeDate = Annotated[
+    date | None, BeforeValidator(lambda v: None if v == "0000-00-00" else v)
+]
+
+
+class MoexBond(BaseModel):
+    SECID: str = Field(min_length=1)
+    BOARDID: str = Field(pattern=r"^[A-Z0-9]{4}$")
+    SHORTNAME: str = Field(min_length=1)
+    # None when the bond has not traded yet (or for a while).
+    PREVWAPRICE: float | None = Field(gt=0)
+    # No bounds: ranges from -100 to six-figure values for distressed bonds.
+    YIELDATPREVWAPRICE: float | None
+    COUPONVALUE: float = Field(ge=0)
+    # None for bonds without a coupon schedule (mostly structured bonds).
+    NEXTCOUPON: MaybeDate
+    ACCRUEDINT: float = Field(ge=0)
+    PREVPRICE: float | None = Field(gt=0)
+    LOTSIZE: int = Field(gt=0)
+    # Not always whole: amortized or indexed bonds have fractional face values.
+    FACEVALUE: float = Field(gt=0)
+    BOARDNAME: str = Field(min_length=1)
+    STATUS: Literal["A", "N"]
+    # None for perpetual bonds and some bonds with a call option.
+    MATDATE: MaybeDate
+    DECIMALS: int = Field(ge=0)
+    # 0 for bonds without periodic coupons.
+    COUPONPERIOD: int = Field(ge=0)
+    ISSUESIZE: int = Field(gt=0)
+    PREVLEGALCLOSEPRICE: float | None = Field(gt=0)
+    # None when the bond has no previous trading day.
+    PREVDATE: MaybeDate
+    SECNAME: str = Field(min_length=1)
+    REMARKS: str | None = Field(pattern=r"^[A-Z]+$")
+    MARKETCODE: str = Field(pattern=r"^[A-Z]{3,4}$")
+    INSTRID: str = Field(pattern=r"^[A-Z]{4}$")
+    # Always null in live data.
+    SECTORID: None
+    MINSTEP: float = Field(gt=0)
+    FACEUNIT: str = Field(pattern=r"^[A-Z]{3}$")
+    BUYBACKPRICE: float | None = Field(gt=0)
+    BUYBACKDATE: MaybeDate
+    ISIN: str = Field(pattern=r"^[A-Z]{2}[A-Z0-9]{9}[0-9]$")
+    LATNAME: str = Field(min_length=1)
+    REGNUMBER: str | None = Field(min_length=1)
+    CURRENCYID: str = Field(pattern=r"^[A-Z]{3}$")
+    ISSUESIZEPLACED: int | None = Field(gt=0)
+    LISTLEVEL: Literal[1, 2, 3]
+    SECTYPE: str = Field(pattern=r"^[0-9A-Z]$")
+    # None when the rate is not known yet (e.g. floaters, structured bonds).
+    COUPONPERCENT: float | None = Field(gt=0)
+    OFFERDATE: date | None
+    SETTLEDATE: date
+    LOTVALUE: float = Field(gt=0)
+    FACEVALUEONSETTLEDATE: float | None = Field(gt=0)
+    CALLOPTIONDATE: date | None
+    PUTOPTIONDATE: date | None
+    DATEYIELDFROMISSUER: date | None
+    BONDTYPE: str | None = Field(min_length=1)
+    BONDSUBTYPE: Literal[
+        "До погашения", "До оферты (put)", "До оферты (call)", "Бессрочные"
+    ]
+    COUPON_DETAILS: str | None = Field(min_length=1)
+    FACEVALUE_TYPE: Literal["Фиксированный", "Индексированный"]
+
+
+async def get_moex_bonds(
+    *,
+    primary_board: Literal[1, 0] | None = None,
+    client: httpx.AsyncClient | None = None,
+) -> list[MoexBond]:
+    rows = await moex_fetch(
+        "engines/stock/markets/bonds/securities.json",
+        "securities",
+        {"primary_board": primary_board},
+        client,
+    )
+    return [MoexBond.model_validate(row) for row in rows]

grind_t_moex-0.1.0/src/moex/bonds_market_data.py

@@ -0,0 +1,97 @@
+from datetime import datetime, time
+
+import httpx
+from pydantic import BaseModel, Field
+
+from .core.fetch import moex_fetch
+
+
+class MoexBondMarketData(BaseModel):
+    # Not unique: a bond may trade on several boards.
+    SECID: str = Field(min_length=1)
+    # None when there are no quotes (e.g. outside trading hours).
+    BID: float | None = Field(gt=0)
+    # Always null in live data.
+    BIDDEPTH: None
+    OFFER: float | None = Field(gt=0)
+    # Always null in live data.
+    OFFERDEPTH: None
+    # No bounds: quotes may cross during auctions. ISS sends 0 rather than null
+    # for this and the other non-nullable numeric fields below when there is no
+    # data, even for bonds that did not trade.
+    SPREAD: float
+    BIDDEPTHT: int | None = Field(ge=0)
+    OFFERDEPTHT: int | None = Field(ge=0)
+    # None when the bond has not traded today.
+    OPEN: float | None = Field(gt=0)
+    LOW: float | None = Field(gt=0)
+    HIGH: float | None = Field(gt=0)
+    LAST: float | None = Field(gt=0)
+    LASTCHANGE: float
+    LASTCHANGEPRCNT: float
+    QTY: int = Field(ge=0)
+    # None on boards without regular trading stats (e.g. TQOD).
+    VALUE: float | None = Field(ge=0)
+    # No bounds: ranges from -100 to five-figure values for distressed bonds.
+    YIELD: float | None
+    VALUE_USD: float | None = Field(ge=0)
+    WAPRICE: float | None = Field(gt=0)
+    LASTCNGTOLASTWAPRICE: float
+    WAPTOPREVWAPRICEPRCNT: float
+    WAPTOPREVWAPRICE: float
+    YIELDATWAPRICE: float | None
+    YIELDTOPREVYIELD: float
+    CLOSEYIELD: float
+    CLOSEPRICE: float | None = Field(gt=0)
+    MARKETPRICETODAY: float | None = Field(gt=0)
+    MARKETPRICE: float | None = Field(gt=0)
+    LASTTOPREVPRICE: float
+    NUMTRADES: int | None = Field(ge=0)
+    VOLTODAY: int | None = Field(ge=0)
+    VALTODAY: int | None = Field(ge=0)
+    VALTODAY_USD: int | None = Field(ge=0)
+    BOARDID: str = Field(pattern=r"^[A-Z0-9]{4}$")
+    # Open set of one-letter codes (N, T, B, C, a seen so far).
+    TRADINGSTATUS: str = Field(pattern=r"^[A-Za-z]$")
+    UPDATETIME: time
+    # In days; 0 when not computed.
+    DURATION: int = Field(ge=0)
+    # Always null in live data.
+    NUMBIDS: None
+    NUMOFFERS: None
+    CHANGE: float | None
+    TIME: time
+    # Always null in live data.
+    HIGHBID: None
+    LOWOFFER: None
+    PRICEMINUSPREVWAPRICE: float | None
+    # Always null in live data.
+    LASTBID: None
+    LASTOFFER: None
+    LCURRENTPRICE: float | None = Field(gt=0)
+    LCLOSEPRICE: float | None = Field(gt=0)
+    MARKETPRICE2: float | None = Field(gt=0)
+    OPENPERIODPRICE: float | None = Field(gt=0)
+    SEQNUM: int = Field(gt=0)
+    SYSTIME: datetime
+    VALTODAY_RUR: int | None = Field(ge=0)
+    # Implied rates, set only for floaters and linkers; no bounds.
+    IRICPICLOSE: float | None
+    BEICLOSE: float | None
+    CBRCLOSE: float | None
+    YIELDTOOFFER: float | None
+    YIELDLASTCOUPON: float | None
+    TRADINGSESSION: str | None = Field(min_length=1)
+    CALLOPTIONYIELD: float | None
+    CALLOPTIONDURATION: float | None = Field(ge=0)
+    ZSPREAD: float | None
+    ZSPREADATWAPRICE: float | None
+
+
+async def get_moex_bonds_market_data(
+    *, client: httpx.AsyncClient | None = None
+) -> list[MoexBondMarketData]:
+    rows = await moex_fetch(
+        "engines/stock/markets/bonds/securities.json", "marketdata", client=client
+    )
+    return [MoexBondMarketData.model_validate(row) for row in rows]

grind_t_moex-0.1.0/src/moex/bonds_market_yield.py

@@ -0,0 +1,58 @@
+from datetime import date, datetime
+from typing import Literal
+
+import httpx
+from pydantic import BaseModel, Field
+
+from .core.fetch import moex_fetch
+
+
+class MoexBondMarketYield(BaseModel):
+    # Not unique: a bond may trade on several boards.
+    SECID: str = Field(min_length=1)
+    BOARDID: str = Field(pattern=r"^[A-Z0-9]{4}$")
+    # Price the yields below are computed from; set even for bonds that did not
+    # trade today.
+    PRICE: float = Field(gt=0)
+    # None for bonds without a maturity date (perpetuals).
+    YIELDDATE: date | None
+    # Timestamp of the zero-coupon yield curve used in the calculation.
+    ZCYCMOMENT: datetime
+    YIELDDATETYPE: Literal["MATDATE", "OFFER", "MBS"]
+    # No bounds: ranges from -100s to eight-figure values for distressed bonds.
+    # None when the yield cannot be computed (e.g. perpetuals).
+    EFFECTIVEYIELD: float | None
+    # In days.
+    DURATION: int | None = Field(ge=0)
+    # In basis points; no bounds.
+    ZSPREADBP: int | None
+    GSPREADBP: int | None
+    # None when the bond has not traded today.
+    WAPRICE: float | None = Field(gt=0)
+    EFFECTIVEYIELDWAPRICE: float | None
+    DURATIONWAPRICE: int | None = Field(ge=0)
+    # Implied rates, set only for floaters and linkers; no bounds.
+    IR: float | None
+    ICPI: float | None
+    BEI: float | None
+    # Always null in live data.
+    CBR: None
+    # Set only when YIELDDATETYPE is OFFER.
+    YIELDTOOFFER: float | None
+    YIELDLASTCOUPON: float | None
+    # Last trade time; 23:59:59 of the last trading day when the bond has not
+    # traded today.
+    TRADEMOMENT: datetime
+    SEQNUM: int = Field(gt=0)
+    SYSTIME: datetime
+
+
+async def get_moex_bonds_market_yield(
+    *, client: httpx.AsyncClient | None = None
+) -> list[MoexBondMarketYield]:
+    rows = await moex_fetch(
+        "engines/stock/markets/bonds/securities.json",
+        "marketdata_yields",
+        client=client,
+    )
+    return [MoexBondMarketYield.model_validate(row) for row in rows]

grind_t_moex-0.1.0/src/moex/core/fetch.py

@@ -0,0 +1,34 @@
+from typing import Any
+
+import httpx
+
+from .parse_block import parse_moex_block
+from .resource import Params, get_moex_resource
+
+
+async def moex_get_json(
+    path: str,
+    block: str,
+    params: Params | None = None,
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    url = get_moex_resource(path, block, params)
+
+    if client is None:
+        async with httpx.AsyncClient() as own_client:
+            response = await own_client.get(url)
+    else:
+        response = await client.get(url)
+
+    response.raise_for_status()
+    return response.json()
+
+
+async def moex_fetch(
+    path: str,
+    block: str,
+    params: Params | None = None,
+    client: httpx.AsyncClient | None = None,
+) -> list[Any]:
+    data = await moex_get_json(path, block, params, client)
+    return parse_moex_block(data[block])

grind_t_moex-0.1.0/src/moex/core/parse_block.py

@@ -0,0 +1,14 @@
+from collections.abc import Mapping, Sequence
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def parse_moex_block(block: Mapping[str, Sequence[Any]]) -> list[T]:
+    columns = block["columns"]
+    records = []
+    for row in block["data"]:
+        records.append(
+            {column: row[i] if i < len(row) else None for i, column in enumerate(columns)}
+        )
+    return records  # type: ignore[return-value]

grind_t_moex-0.1.0/src/moex/core/resource.py

@@ -0,0 +1,17 @@
+from collections.abc import Mapping
+
+import httpx
+
+BASE_URL = "https://iss.moex.com/iss/"
+
+Params = Mapping[str, str | int | None]
+
+
+def get_moex_resource(path: str, block: str, params: Params | None = None) -> httpx.URL:
+    query = {
+        key: str(value) for key, value in (params or {}).items() if value is not None
+    }
+    query["iss.meta"] = "off"
+    query["iss.only"] = block
+
+    return httpx.URL(BASE_URL + path.lstrip("/"), params=query)

grind_t_moex-0.1.0/src/moex/core/types.py

@@ -0,0 +1,54 @@
+from typing import Literal
+
+# https://iss.moex.com/iss/index.json?iss.only=engines
+Engine = Literal[
+    "stock",
+    "state",
+    "currency",
+    "futures",
+    "commodity",
+    "interventions",
+    "offboard",
+    "agro",
+    "otc",
+    "quotes",
+    "money",
+]
+
+# https://iss.moex.com/iss/index.json?iss.only=markets
+Market = Literal[
+    "repo",
+    "deposit",
+    "otcindices",
+    "index",
+    "shares",
+    "bonds",
+    "ndm",
+    "otc",
+    "ccp",
+    "qnv",
+    "mamc",
+    "foreignshares",
+    "foreignndm",
+    "moexboard",
+    "gcc",
+    "credit",
+    "selt",
+    "futures",
+    "main",
+    "forts",
+    "options",
+    "fortsiqs",
+    "optionsiqs",
+    "sharesndm",
+    "nonresndm",
+    "nonresrepo",
+    "nonresccp",
+    "grain",
+    "sugar",
+    "auctions",
+    "buyauctions",
+    "saleauctions",
+    "standard",
+    "classica",
+]

grind_t_moex-0.1.0/src/moex/daily_table.py

@@ -0,0 +1,24 @@
+# Imported as a module: the `date` field would otherwise shadow the type.
+import datetime as dt
+
+import httpx
+from pydantic import BaseModel
+
+from .core.fetch import moex_fetch
+
+
+# Exceptions to the regular calendar: weekday holidays and working weekends.
+class MoexDailyTableRow(BaseModel):
+    date: dt.date
+    is_work_day: bool
+    # None (or 00:00:00 for both) on some non-working days, so start < stop
+    # does not always hold.
+    start_time: dt.time | None
+    stop_time: dt.time | None
+
+
+async def get_moex_daily_table(
+    *, client: httpx.AsyncClient | None = None
+) -> list[MoexDailyTableRow]:
+    rows = await moex_fetch("engines/stock.json", "dailytable", client=client)
+    return [MoexDailyTableRow.model_validate(row) for row in rows]

grind_t_moex-0.1.0/src/moex/securities.py

@@ -0,0 +1,75 @@
+from typing import Annotated, Literal
+
+import httpx
+from pydantic import BaseModel, BeforeValidator, Field
+
+from .core.fetch import moex_fetch
+from .core.types import Engine, Market
+
+# ISS sends "" (and for isin even "None") instead of null for some indices,
+# currencies and old state bonds.
+MaybeStr = Annotated[
+    str | None, BeforeValidator(lambda v: None if v in ("", "None") else v)
+]
+
+
+# Issuer fields (emitent_*), isin and regnumber are None for derivatives,
+# indices, currencies and commodities, and for some foreign securities.
+class MoexSecurity(BaseModel):
+    # \w: an old commodity future has a Cyrillic letter ("R1Н4").
+    secid: str = Field(pattern=r"^[\w.+-]+$")
+    # None for some delisted securities and futures spreads.
+    shortname: str | None = Field(min_length=1)
+    regnumber: MaybeStr = Field(min_length=1)
+    name: str | None = Field(min_length=1)
+    # The check digit is missing for a few bond indices.
+    isin: MaybeStr = Field(pattern=r"^[A-Z]{2}[A-Z0-9]{9}[0-9]?$")
+    # None for some futures spreads.
+    is_traded: bool | None
+    emitent_id: int | None = Field(gt=0)
+    emitent_title: str | None = Field(min_length=1)
+    # Not always a real INN: foreign issuers have short registry numbers.
+    emitent_inn: str | None = Field(pattern=r"^[0-9]{1,12}$")
+    # Leading zeros are sometimes dropped.
+    emitent_okpo: str | None = Field(pattern=r"^[0-9]{5,8}$")
+    # Open sets, e.g. "common_share" in "stock_shares", "option" in
+    # "futures_options".
+    type: str = Field(pattern=r"^[a-z]+(_[a-z]+)*$")
+    group: str = Field(pattern=r"^[a-z]+(_[a-z]+)*$")
+    # None for some delisted securities (mostly bonds); 3 letters for a few old
+    # boards ("FOB", "BKT").
+    primary_boardid: str | None = Field(pattern=r"^[A-Z0-9]{3,4}$")
+    # Only set for some stock market securities (shares, bonds, funds).
+    marketprice_boardid: str | None = Field(pattern=r"^[A-Z0-9]{4}$")
+
+
+async def get_moex_securities(
+    *,
+    q: str | None = None,
+    lang: Literal["ru", "en"] | None = None,
+    engine: Engine | None = None,
+    is_trading: Literal[1, 0] | None = None,
+    market: Market | None = None,
+    group_by: Literal["group", "type"] | None = None,
+    limit: Literal[5, 10, 20, 100] | None = None,
+    group_by_filter: str | None = None,
+    start: int | None = None,
+    client: httpx.AsyncClient | None = None,
+) -> list[MoexSecurity]:
+    rows = await moex_fetch(
+        "securities.json",
+        "securities",
+        {
+            "q": q,
+            "lang": lang,
+            "engine": engine,
+            "is_trading": is_trading,
+            "market": market,
+            "group_by": group_by,
+            "limit": limit,
+            "group_by_filter": group_by_filter,
+            "start": start,
+        },
+        client,
+    )
+    return [MoexSecurity.model_validate(row) for row in rows]

grind_t_moex-0.1.0/src/moex/security_description.py

@@ -0,0 +1,167 @@
+from datetime import date, time
+from typing import Literal
+
+import httpx
+from pydantic import BaseModel, Field
+
+from .core.fetch import moex_get_json
+
+
+# Keys vary by security type; only TYPE, TYPENAME, GROUP and GROUPNAME are
+# present for every security. Absent keys are None.
+class MoexSecurityDescription(BaseModel):
+    # Absent for currency fixings and OTC currency indices.
+    SECID: str | None = Field(default=None, min_length=1)
+    # Absent for old commodity futures and some indices.
+    SHORTNAME: str | None = Field(default=None, min_length=1)
+    NAME: str | None = Field(default=None, min_length=1)
+    LATSHORTNAME: str | None = Field(default=None, min_length=1)
+    LATNAME: str | None = Field(default=None, min_length=1)
+    CALCMODE: str | None = Field(default=None, pattern=r"^[A-Z0-9-]+$")
+    CALCMODEDESCR: str | None = Field(default=None, min_length=1)
+    CURRENCYID: str | None = Field(default=None, pattern=r"^[A-Z]{3}$")
+    FREQUENCY: str | None = Field(default=None, min_length=1)
+    SCHEDULE: str | None = Field(default=None, min_length=1)
+    DECIMALS: int | None = Field(default=None, ge=0)
+    INITIALVALUE: float | None = Field(default=None, gt=0)
+    ISSUEDATE: date | None = None
+    TRADINGSESSION: str | None = Field(default=None, min_length=1)
+    # iNAV indices mark the fund with a leading or trailing underscore.
+    UNDERLYINGTICKER: str | None = Field(default=None, pattern=r"^_?[A-Z0-9]+_?$")
+    UNDERLYINGISIN: str | None = Field(
+        default=None, pattern=r"^_?[A-Z]{2}[A-Z0-9]{9}[0-9]_?$"
+    )
+    REBALANCE: str | None = Field(default=None, min_length=1)
+    WEIGHTLIMITTYPE: str | None = Field(default=None, min_length=1)
+    TYPENAME: str = Field(min_length=1)
+    GROUP: str = Field(pattern=r"^[a-z_]+$")
+    TYPE: str = Field(pattern=r"^[a-z_]+$")
+    GROUPNAME: str = Field(min_length=1)
+    FIRSTCALCDATE: date | None = None
+    # A count, but "переменное" (variable) for some indices.
+    CONSTITUENTS: str | None = Field(default=None, min_length=1)
+    DESCRIPTION: str | None = Field(default=None, min_length=1)
+    INITIALCAPITALIZATION: float | None = Field(default=None, gt=0)
+    INITIALD: float | None = Field(default=None, gt=0)
+    ISSUENAME: str | None = Field(default=None, min_length=1)
+    # One index has a truncated 11-character ISIN (check digit missing).
+    ISIN: str | None = Field(default=None, pattern=r"^[A-Z]{2}[A-Z0-9]{9}[0-9]?$")
+    # Not always whole: down to 1e-05 for some shares.
+    FACEVALUE: float | None = Field(default=None, gt=0)
+    # Includes non-ISO codes such as SUR, GLD and BKT.
+    FACEUNIT: str | None = Field(default=None, pattern=r"^[A-Z]{3}$")
+    HASPROSPECTUS: bool | None = None
+    HASDEFAULT: bool | None = None
+    HASTECHNICALDEFAULT: bool | None = None
+    # A 0/1 flag, though ISS declares it a number.
+    EMITENTMISMATCHCUR: int | None = Field(default=None, ge=0, le=1)
+    ISQUALIFIEDINVESTORS: bool | None = None
+    QUALINVESTORGROUP: str | None = Field(default=None, min_length=1)
+    EMITTER_ID: int | None = Field(default=None, gt=0)
+    REGNUMBER: str | None = Field(default=None, min_length=1)
+    ISSUESIZE: int | None = Field(default=None, gt=0)
+    REGISTRY_DATE: date | None = None
+    DECISIONDATE: date | None = None
+    LISTLEVEL: int | None = Field(default=None, ge=1, le=3)
+    MORNINGSESSION: bool | None = None
+    EVENINGSESSION: bool | None = None
+    WEEKENDSESSION: bool | None = None
+    MATDATE: date | None = None
+    INITIALFACEVALUE: float | None = Field(default=None, gt=0)
+    STARTDATEMOEX: date | None = None
+    ISCONCESSIONAGREEMENT: bool | None = None
+    INCLUDEDBYMOEX: bool | None = None
+    DAYSTOREDEMPTION: int | None = Field(default=None, ge=0)
+    COUPONFREQUENCY: int | None = Field(default=None, gt=0)
+    COUPONDATE: date | None = None
+    # 0 for some structured bonds.
+    COUPONPERCENT: float | None = Field(default=None, ge=0)
+    COUPONVALUE: float | None = Field(default=None, ge=0)
+    BOND_TYPE: str | None = Field(default=None, min_length=1)
+    BOND_SUBTYPE: (
+        Literal["До погашения", "До оферты (put)", "До оферты (call)", "Бессрочные"]
+        | None
+    ) = None
+    EARLYREPAYMENT: bool | None = None
+    COUPON_BENCHMARK: str | None = Field(default=None, pattern=r"^[A-Z]+$")
+    # ISS declares it a string, e.g. "1.30".
+    COUPON_BENCHMARK_SPREAD: str | None = Field(
+        default=None, pattern=r"^-?[0-9]+\.[0-9]+$"
+    )
+    AMORTBOND: bool | None = None
+    BUYBACKDATE: date | None = None
+    EMITTER_VALUE_BUILDING: bool | None = None
+    LOTSIZE: int | None = Field(default=None, gt=0)
+    TIMETABLE: str | None = Field(default=None, min_length=1)
+    DELIVERYTYPE: str | None = Field(default=None, min_length=1)
+    FRSTTRADE: date | None = None
+    LSTTRADE: date | None = None
+    LSTDELDATE: date | None = None
+    ASSETCODE: str | None = Field(default=None, pattern=r"^[A-Za-z0-9]+$")
+    EXECTYPE: str | None = Field(default=None, min_length=1)
+    CONTRACTNAME: str | None = Field(default=None, min_length=1)
+    GROUPTYPE: str | None = Field(default=None, min_length=1)
+    UNIT: str | None = Field(default=None, min_length=1)
+    EXPIRATION_TYPE: str | None = Field(default=None, min_length=1)
+    EXPIRATION_TIME: time | None = None
+    SETTLETYPE: Literal["Расчетный", "Поставочный"] | None = None
+    OPTIONTYPE: Literal["C", "P"] | None = None
+    STRIKE: float | None = Field(default=None, gt=0)
+    MARGINSTYLE: Literal["Премиальный", "Маржируемый"] | None = None
+    UNDERLYINGASSET: str | None = Field(default=None, min_length=1)
+    SERIES_NAME: str | None = Field(default=None, min_length=1)
+    DEPOSITARY_ORG_NAME: str | None = Field(default=None, min_length=1)
+    # Not always whole: e.g. 0.2 shares per receipt.
+    SHARESPERRECEIPT: float | None = Field(default=None, gt=0)
+    HIGHRISK: bool | None = None
+    SECSUBTYPE: str | None = Field(default=None, min_length=1)
+    SUBORDBOND: bool | None = None
+    PROGRAMREGISTRYNUMBER: str | None = Field(default=None, min_length=1)
+    STRUCTBOND: bool | None = None
+    ASSET: str | None = Field(default=None, min_length=1)
+    PARENTINDEX: str | None = Field(default=None, min_length=1)
+    ISPARENT: bool | None = None
+    BBG: str | None = Field(default=None, min_length=1)
+    RIC: str | None = Field(default=None, min_length=1)
+    VOLUME_UNIT: str | None = Field(default=None, min_length=1)
+    DEPOSITARYNOTETYPE: str | None = Field(default=None, min_length=1)
+    ISSUESIZEPLANNED: int | None = Field(default=None, gt=0)
+    PERPETUAL_FUTURES: bool | None = None
+    FOSECTYPE: str | None = Field(default=None, pattern=r"^[A-Z0-9]+$")
+    # The fields below come only with old commodity futures.
+    FACEUNITNAME: str | None = Field(default=None, min_length=1)
+    DELIVERYMINQTY: str | None = Field(default=None, min_length=1)
+    PRICEFULLNAME: str | None = Field(default=None, min_length=1)
+    MINPRICEFLUCT: str | None = Field(default=None, min_length=1)
+    DURATION: int | None = Field(default=None, gt=0)
+    DELCOMMISSION: str | None = Field(default=None, min_length=1)
+    COMMISSIONRATE: float | None = Field(default=None, gt=0)
+    FINALPRICEMETHOD: str | None = Field(default=None, min_length=1)
+    STARTDELDATE: date | None = None
+    PRICEMVTLIMITEXTNAME: str | None = Field(default=None, min_length=1)
+    SHARELIMIT: float | None = Field(default=None, gt=0, le=100)
+    THRESHOLD: int | None = Field(default=None, gt=0)
+    MAXORDVOL: int | None = Field(default=None, gt=0)
+    DMRATEEXTNAME: str | None = Field(default=None, min_length=1)
+    TIMECOURSEINT: time | None = None
+    TIMECOURSECLR: time | None = None
+    # Only for the bi-currency basket.
+    BASKET_DESCR1: str | None = Field(default=None, min_length=1)
+    BASKET_DESCR2: str | None = Field(default=None, min_length=1)
+    BASKET_DESCR3: str | None = Field(default=None, min_length=1)
+    BASKET_DESCR4: str | None = Field(default=None, min_length=1)
+    BASKET_DESCR5: str | None = Field(default=None, min_length=1)
+
+
+async def get_moex_security_description(
+    id: str, *, client: httpx.AsyncClient | None = None
+) -> MoexSecurityDescription:
+    data = await moex_get_json(f"securities/{id}.json", "description", client=client)
+    description = data["description"]
+    columns = description["columns"]
+    name_index = columns.index("name")
+    value_index = columns.index("value")
+
+    # Values are strings; the model converts them by field type.
+    result = {row[name_index]: row[value_index] for row in description["data"]}
+    return MoexSecurityDescription.model_validate(result)