moex-iss-client 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of moex-iss-client might be problematic. Click here for more details.
- moex_iss_client/__init__.py +40 -0
- moex_iss_client/auth.py +98 -0
- moex_iss_client/client.py +313 -0
- moex_iss_client/endpoints/__init__.py +5 -0
- moex_iss_client/endpoints/candles.py +157 -0
- moex_iss_client/endpoints/securities.py +111 -0
- moex_iss_client/exceptions.py +23 -0
- moex_iss_client/models.py +65 -0
- moex_iss_client/utils.py +258 -0
- moex_iss_client-0.1.0.dist-info/METADATA +176 -0
- moex_iss_client-0.1.0.dist-info/RECORD +12 -0
- moex_iss_client-0.1.0.dist-info/WHEEL +4 -0
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""moex-iss-client — Python client for the MOEX ISS API.
|
|
2
|
+
|
|
3
|
+
Public API
|
|
4
|
+
----------
|
|
5
|
+
- :class:`MoexISSClient` — the main client class.
|
|
6
|
+
- Exceptions: :class:`MoexISSError`, :class:`ValidationError`, :class:`AuthError`,
|
|
7
|
+
:class:`NotFoundError`, :class:`TransportError`.
|
|
8
|
+
- Timeframe constants and helpers from :mod:`moex_iss_client.models`.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
from moex_iss_client.client import MoexISSClient
|
|
14
|
+
from moex_iss_client.exceptions import (
|
|
15
|
+
AuthError,
|
|
16
|
+
MoexISSError,
|
|
17
|
+
NotFoundError,
|
|
18
|
+
TransportError,
|
|
19
|
+
ValidationError,
|
|
20
|
+
)
|
|
21
|
+
from moex_iss_client.models import (
|
|
22
|
+
ISS_INTERVAL_BY_TIMEFRAME,
|
|
23
|
+
InstrumentType,
|
|
24
|
+
timeframe_to_interval,
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
__version__ = "0.1.0"
|
|
28
|
+
|
|
29
|
+
__all__ = [
|
|
30
|
+
"ISS_INTERVAL_BY_TIMEFRAME",
|
|
31
|
+
"AuthError",
|
|
32
|
+
"InstrumentType",
|
|
33
|
+
"MoexISSClient",
|
|
34
|
+
"MoexISSError",
|
|
35
|
+
"NotFoundError",
|
|
36
|
+
"TransportError",
|
|
37
|
+
"ValidationError",
|
|
38
|
+
"__version__",
|
|
39
|
+
"timeframe_to_interval",
|
|
40
|
+
]
|
moex_iss_client/auth.py
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
"""Basic authentication and cookie management for the MOEX passport service."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import logging
|
|
6
|
+
import threading
|
|
7
|
+
|
|
8
|
+
import httpx
|
|
9
|
+
|
|
10
|
+
from moex_iss_client.exceptions import AuthError
|
|
11
|
+
from moex_iss_client.models import PASSPORT_BASE_URL
|
|
12
|
+
|
|
13
|
+
logger = logging.getLogger(__name__)
|
|
14
|
+
|
|
15
|
+
# Cookie name that the passport service sets on successful authentication.
|
|
16
|
+
PASSPORT_COOKIE_NAME = "MicexPassportCert"
|
|
17
|
+
# Header that the ISS data endpoints use to report access level.
|
|
18
|
+
PASSPORT_MARKER_HEADER = "X-MicexPassport-Marker"
|
|
19
|
+
PASSPORT_MARKER_GRANTED = "granted"
|
|
20
|
+
PASSPORT_MARKER_DENIED = "denied"
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class PassportAuth:
|
|
24
|
+
"""Thread-safe basic-auth handler for ``passport.moex.com``.
|
|
25
|
+
|
|
26
|
+
The handler authenticates once, stores the resulting ``MicexPassportCert``
|
|
27
|
+
cookie inside the provided :class:`httpx.Client`, and can re-authenticate
|
|
28
|
+
on demand (e.g. when the ISS returns ``X-MicexPassport-Marker: denied``).
|
|
29
|
+
|
|
30
|
+
Parameters
|
|
31
|
+
----------
|
|
32
|
+
client : httpx.Client
|
|
33
|
+
Shared HTTP client whose cookie jar will receive ``MicexPassportCert``.
|
|
34
|
+
login : str
|
|
35
|
+
MOEX passport login.
|
|
36
|
+
password : str
|
|
37
|
+
MOEX passport password.
|
|
38
|
+
"""
|
|
39
|
+
|
|
40
|
+
def __init__(self, client: httpx.Client, login: str, password: str) -> None:
|
|
41
|
+
self._client = client
|
|
42
|
+
self._login = login
|
|
43
|
+
self._password = password
|
|
44
|
+
self._lock = threading.Lock()
|
|
45
|
+
self._authenticated = False
|
|
46
|
+
|
|
47
|
+
@property
|
|
48
|
+
def authenticated(self) -> bool:
|
|
49
|
+
"""Whether a successful authentication has already happened."""
|
|
50
|
+
return self._authenticated
|
|
51
|
+
|
|
52
|
+
def ensure_authenticated(self) -> None:
|
|
53
|
+
"""Authenticate if not done yet.
|
|
54
|
+
|
|
55
|
+
Thread-safe: concurrent callers block until the first authentication
|
|
56
|
+
attempt completes, then reuse its result.
|
|
57
|
+
"""
|
|
58
|
+
if self._authenticated:
|
|
59
|
+
return
|
|
60
|
+
with self._lock:
|
|
61
|
+
if self._authenticated:
|
|
62
|
+
return
|
|
63
|
+
self._do_authenticate()
|
|
64
|
+
|
|
65
|
+
def refresh(self) -> None:
|
|
66
|
+
"""Force a re-authentication (used when the ISS reports ``denied``).
|
|
67
|
+
|
|
68
|
+
Thread-safe: if several threads detect ``denied`` at the same time,
|
|
69
|
+
only the first one actually hits the passport service; the others
|
|
70
|
+
see ``_authenticated`` already reset and wait.
|
|
71
|
+
"""
|
|
72
|
+
with self._lock:
|
|
73
|
+
self._do_authenticate()
|
|
74
|
+
|
|
75
|
+
def _do_authenticate(self) -> None:
|
|
76
|
+
"""Perform the actual basic-auth request against the passport service."""
|
|
77
|
+
url = f"{PASSPORT_BASE_URL}/authenticate"
|
|
78
|
+
logger.debug("Authenticating against %s", url)
|
|
79
|
+
try:
|
|
80
|
+
response = self._client.get(url, auth=(self._login, self._password))
|
|
81
|
+
except httpx.HTTPError as exc:
|
|
82
|
+
self._authenticated = False
|
|
83
|
+
raise AuthError(f"Transport error during authentication: {exc}") from exc
|
|
84
|
+
|
|
85
|
+
if response.status_code != 200:
|
|
86
|
+
self._authenticated = False
|
|
87
|
+
raise AuthError(
|
|
88
|
+
f"Authentication failed with status {response.status_code}: {response.text[:200]!r}"
|
|
89
|
+
)
|
|
90
|
+
|
|
91
|
+
if PASSPORT_COOKIE_NAME not in self._client.cookies:
|
|
92
|
+
self._authenticated = False
|
|
93
|
+
raise AuthError(
|
|
94
|
+
f"Authentication response did not set the {PASSPORT_COOKIE_NAME} cookie"
|
|
95
|
+
)
|
|
96
|
+
|
|
97
|
+
self._authenticated = True
|
|
98
|
+
logger.debug("Authentication successful, cookie %r acquired", PASSPORT_COOKIE_NAME)
|
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
"""HTTP transport, retries and thread-pool management for the ISS client."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import logging
|
|
6
|
+
import ssl
|
|
7
|
+
import time
|
|
8
|
+
import warnings
|
|
9
|
+
from concurrent.futures import ThreadPoolExecutor
|
|
10
|
+
from types import TracebackType
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
import httpx
|
|
14
|
+
|
|
15
|
+
from moex_iss_client.auth import (
|
|
16
|
+
PASSPORT_MARKER_DENIED,
|
|
17
|
+
PASSPORT_MARKER_GRANTED,
|
|
18
|
+
PASSPORT_MARKER_HEADER,
|
|
19
|
+
PassportAuth,
|
|
20
|
+
)
|
|
21
|
+
from moex_iss_client.exceptions import (
|
|
22
|
+
MoexISSError,
|
|
23
|
+
NotFoundError,
|
|
24
|
+
TransportError,
|
|
25
|
+
)
|
|
26
|
+
from moex_iss_client.models import ISS_BASE_URL
|
|
27
|
+
|
|
28
|
+
logger = logging.getLogger(__name__)
|
|
29
|
+
|
|
30
|
+
# Status codes that the ISS documentation recommends retrying.
|
|
31
|
+
RETRYABLE_STATUS_CODES = frozenset({500, 501, 502, 503, 504})
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class MoexISSClient:
|
|
35
|
+
"""Synchronous client for the MOEX Information and Statistical Server (ISS).
|
|
36
|
+
|
|
37
|
+
Parameters
|
|
38
|
+
----------
|
|
39
|
+
login : str | None, default None
|
|
40
|
+
MOEX passport login. If omitted, the client works in anonymous mode
|
|
41
|
+
(public data, delayed quotes).
|
|
42
|
+
password : str | None, default None
|
|
43
|
+
MOEX passport password. Must be provided together with ``login``.
|
|
44
|
+
timeout : float, default 30.0
|
|
45
|
+
Per-request timeout in seconds.
|
|
46
|
+
max_retries : int, default 3
|
|
47
|
+
Number of retries for retryable status codes and transport errors.
|
|
48
|
+
retry_backoff : float, default 1.0
|
|
49
|
+
Base delay between retries in seconds (exponential growth).
|
|
50
|
+
max_workers : int, default 4
|
|
51
|
+
Maximum number of worker threads for parallel requests.
|
|
52
|
+
verify : bool | str | ssl.SSLContext, default True
|
|
53
|
+
TLS verification policy passed to :class:`httpx.Client`.
|
|
54
|
+
|
|
55
|
+
- ``True`` (default): verify against the ``certifi`` bundle shipped
|
|
56
|
+
with ``httpx``. Safe for public networks.
|
|
57
|
+
- ``False``: disable verification. **Insecure** — only for local
|
|
58
|
+
debugging. A :class:`UserWarning` is emitted when this value is used.
|
|
59
|
+
- ``str``: path to a PEM bundle (e.g. a combined ``certifi`` +
|
|
60
|
+
corporate CA file).
|
|
61
|
+
- :class:`ssl.SSLContext`: custom context, e.g. built via
|
|
62
|
+
``ssl.create_default_context()`` to use the system trust store.
|
|
63
|
+
trust_env : bool, default True
|
|
64
|
+
If ``True``, ``httpx`` reads ``SSL_CERT_FILE`` /
|
|
65
|
+
``REQUESTS_CA_BUNDLE`` from the environment. Useful when the CA is
|
|
66
|
+
already configured system-wide.
|
|
67
|
+
|
|
68
|
+
Examples
|
|
69
|
+
--------
|
|
70
|
+
>>> with MoexISSClient() as client:
|
|
71
|
+
... data = client.get_securities(return_df=True)
|
|
72
|
+
|
|
73
|
+
Use the system trust store (handles corporate MITM proxies and the
|
|
74
|
+
Russian Ministry of Digital Development root CA):
|
|
75
|
+
|
|
76
|
+
>>> import ssl
|
|
77
|
+
>>> ctx = ssl.create_default_context()
|
|
78
|
+
>>> with MoexISSClient(verify=ctx) as client:
|
|
79
|
+
... data = client.get_securities()
|
|
80
|
+
"""
|
|
81
|
+
|
|
82
|
+
def __init__(
|
|
83
|
+
self,
|
|
84
|
+
login: str | None = None,
|
|
85
|
+
password: str | None = None,
|
|
86
|
+
timeout: float = 30.0,
|
|
87
|
+
max_retries: int = 3,
|
|
88
|
+
retry_backoff: float = 1.0,
|
|
89
|
+
max_workers: int = 4,
|
|
90
|
+
verify: bool | str | ssl.SSLContext = True,
|
|
91
|
+
trust_env: bool = True,
|
|
92
|
+
) -> None:
|
|
93
|
+
if (login is None) ^ (password is None):
|
|
94
|
+
raise ValueError("login and password must be provided together")
|
|
95
|
+
|
|
96
|
+
if verify is False:
|
|
97
|
+
warnings.warn(
|
|
98
|
+
"TLS verification is disabled (verify=False). "
|
|
99
|
+
"This is insecure and intended for local debugging only.",
|
|
100
|
+
UserWarning,
|
|
101
|
+
stacklevel=2,
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
self._timeout = timeout
|
|
105
|
+
self._max_retries = max_retries
|
|
106
|
+
self._retry_backoff = retry_backoff
|
|
107
|
+
self._max_workers = max_workers
|
|
108
|
+
|
|
109
|
+
self._client = httpx.Client(
|
|
110
|
+
base_url=ISS_BASE_URL,
|
|
111
|
+
timeout=httpx.Timeout(timeout),
|
|
112
|
+
follow_redirects=True,
|
|
113
|
+
headers={"User-Agent": "moex-iss-client/0.1.0"},
|
|
114
|
+
verify=verify,
|
|
115
|
+
trust_env=trust_env,
|
|
116
|
+
)
|
|
117
|
+
|
|
118
|
+
self._auth: PassportAuth | None = None
|
|
119
|
+
if login is not None and password is not None:
|
|
120
|
+
self._auth = PassportAuth(self._client, login, password)
|
|
121
|
+
|
|
122
|
+
self._executor: ThreadPoolExecutor | None = None
|
|
123
|
+
self._closed = False
|
|
124
|
+
self._retried_auth = False
|
|
125
|
+
|
|
126
|
+
# ------------------------------------------------------------------ #
|
|
127
|
+
# Lifecycle
|
|
128
|
+
# ------------------------------------------------------------------ #
|
|
129
|
+
def close(self) -> None:
|
|
130
|
+
"""Close the underlying HTTP client and shut down the thread pool."""
|
|
131
|
+
if self._closed:
|
|
132
|
+
return
|
|
133
|
+
self._closed = True
|
|
134
|
+
if self._executor is not None:
|
|
135
|
+
self._executor.shutdown(wait=True)
|
|
136
|
+
self._executor = None
|
|
137
|
+
self._client.close()
|
|
138
|
+
|
|
139
|
+
def __enter__(self) -> MoexISSClient:
|
|
140
|
+
return self
|
|
141
|
+
|
|
142
|
+
def __exit__(
|
|
143
|
+
self,
|
|
144
|
+
exc_type: type[BaseException] | None,
|
|
145
|
+
exc_val: BaseException | None,
|
|
146
|
+
exc_tb: TracebackType | None,
|
|
147
|
+
) -> None:
|
|
148
|
+
self.close()
|
|
149
|
+
|
|
150
|
+
# ------------------------------------------------------------------ #
|
|
151
|
+
# Thread pool
|
|
152
|
+
# ------------------------------------------------------------------ #
|
|
153
|
+
@property
|
|
154
|
+
def executor(self) -> ThreadPoolExecutor:
|
|
155
|
+
"""Lazily-created thread pool for parallel requests."""
|
|
156
|
+
if self._closed:
|
|
157
|
+
raise MoexISSError("Client is closed")
|
|
158
|
+
if self._executor is None:
|
|
159
|
+
self._executor = ThreadPoolExecutor(max_workers=self._max_workers)
|
|
160
|
+
return self._executor
|
|
161
|
+
|
|
162
|
+
@property
|
|
163
|
+
def max_workers(self) -> int:
|
|
164
|
+
"""Maximum number of worker threads for parallel requests."""
|
|
165
|
+
return self._max_workers
|
|
166
|
+
|
|
167
|
+
# ------------------------------------------------------------------ #
|
|
168
|
+
# Core request logic
|
|
169
|
+
# ------------------------------------------------------------------ #
|
|
170
|
+
def _request(
|
|
171
|
+
self,
|
|
172
|
+
method: str,
|
|
173
|
+
url: str,
|
|
174
|
+
*,
|
|
175
|
+
params: dict[str, Any] | None = None,
|
|
176
|
+
) -> httpx.Response:
|
|
177
|
+
"""Send a request with retries and authentication handling.
|
|
178
|
+
|
|
179
|
+
Parameters
|
|
180
|
+
----------
|
|
181
|
+
method : str
|
|
182
|
+
HTTP method (``"GET"`` is the only one ISS uses).
|
|
183
|
+
url : str
|
|
184
|
+
Path relative to :data:`ISS_BASE_URL`, or an absolute URL.
|
|
185
|
+
params : dict | None, default None
|
|
186
|
+
Query parameters.
|
|
187
|
+
|
|
188
|
+
Returns
|
|
189
|
+
-------
|
|
190
|
+
httpx.Response
|
|
191
|
+
The final response (successful or not).
|
|
192
|
+
|
|
193
|
+
Raises
|
|
194
|
+
------
|
|
195
|
+
AuthError
|
|
196
|
+
If authentication was required but failed.
|
|
197
|
+
NotFoundError
|
|
198
|
+
If the server responded with 404.
|
|
199
|
+
TransportError
|
|
200
|
+
If all retries for a transport error were exhausted.
|
|
201
|
+
"""
|
|
202
|
+
if self._auth is not None and not self._auth.authenticated:
|
|
203
|
+
self._auth.ensure_authenticated()
|
|
204
|
+
|
|
205
|
+
last_exc: Exception | None = None
|
|
206
|
+
for attempt in range(self._max_retries + 1):
|
|
207
|
+
try:
|
|
208
|
+
response = self._client.request(method, url, params=params)
|
|
209
|
+
except httpx.HTTPError as exc:
|
|
210
|
+
last_exc = exc
|
|
211
|
+
if attempt < self._max_retries:
|
|
212
|
+
self._sleep_before_retry(attempt, reason=str(exc))
|
|
213
|
+
continue
|
|
214
|
+
raise TransportError(
|
|
215
|
+
f"Request to {url!r} failed after {self._max_retries} retries: {exc}"
|
|
216
|
+
) from exc
|
|
217
|
+
|
|
218
|
+
if response.status_code == 404:
|
|
219
|
+
raise NotFoundError(f"Resource not found: {url}")
|
|
220
|
+
|
|
221
|
+
if response.status_code in RETRYABLE_STATUS_CODES and attempt < self._max_retries:
|
|
222
|
+
self._sleep_before_retry(attempt, reason=f"HTTP {response.status_code}")
|
|
223
|
+
continue
|
|
224
|
+
|
|
225
|
+
marker = response.headers.get(PASSPORT_MARKER_HEADER)
|
|
226
|
+
if (
|
|
227
|
+
marker == PASSPORT_MARKER_DENIED
|
|
228
|
+
and self._auth is not None
|
|
229
|
+
and not self._retried_auth
|
|
230
|
+
):
|
|
231
|
+
logger.warning(
|
|
232
|
+
"ISS returned %s=%r; re-authenticating and retrying once",
|
|
233
|
+
PASSPORT_MARKER_HEADER,
|
|
234
|
+
marker,
|
|
235
|
+
)
|
|
236
|
+
self._retried_auth = True
|
|
237
|
+
try:
|
|
238
|
+
self._auth.refresh()
|
|
239
|
+
finally:
|
|
240
|
+
self._retried_auth = False
|
|
241
|
+
continue
|
|
242
|
+
|
|
243
|
+
if marker == PASSPORT_MARKER_GRANTED:
|
|
244
|
+
logger.debug("Request authenticated (marker=granted)")
|
|
245
|
+
|
|
246
|
+
if not response.is_success:
|
|
247
|
+
raise MoexISSError(
|
|
248
|
+
f"ISS returned HTTP {response.status_code} for {url!r}: {response.text[:300]!r}"
|
|
249
|
+
)
|
|
250
|
+
|
|
251
|
+
return response
|
|
252
|
+
|
|
253
|
+
raise TransportError(f"Request to {url!r} failed: {last_exc}")
|
|
254
|
+
|
|
255
|
+
def _sleep_before_retry(self, attempt: int, *, reason: str) -> None:
|
|
256
|
+
delay = self._retry_backoff * (2**attempt)
|
|
257
|
+
logger.debug(
|
|
258
|
+
"Retrying in %.2fs (attempt %d/%d): %s",
|
|
259
|
+
delay,
|
|
260
|
+
attempt + 1,
|
|
261
|
+
self._max_retries,
|
|
262
|
+
reason,
|
|
263
|
+
)
|
|
264
|
+
time.sleep(delay)
|
|
265
|
+
|
|
266
|
+
# ------------------------------------------------------------------ #
|
|
267
|
+
# Public endpoint methods
|
|
268
|
+
# ------------------------------------------------------------------ #
|
|
269
|
+
def get_securities(
|
|
270
|
+
self,
|
|
271
|
+
instrument_type: str = "stock",
|
|
272
|
+
*,
|
|
273
|
+
return_df: bool = False,
|
|
274
|
+
) -> dict[str, Any] | Any:
|
|
275
|
+
"""Fetch the list of securities for the given instrument type.
|
|
276
|
+
|
|
277
|
+
See :func:`moex_iss_client.endpoints.securities.get_securities`
|
|
278
|
+
for the full parameter description.
|
|
279
|
+
"""
|
|
280
|
+
from moex_iss_client.endpoints.securities import get_securities as _impl
|
|
281
|
+
|
|
282
|
+
return _impl(self, instrument_type=instrument_type, return_df=return_df)
|
|
283
|
+
|
|
284
|
+
def get_ohlcv(
|
|
285
|
+
self,
|
|
286
|
+
secid: str,
|
|
287
|
+
timeframe: str = "1D",
|
|
288
|
+
start: str | None = None,
|
|
289
|
+
end: str | None = None,
|
|
290
|
+
engine: str = "stock",
|
|
291
|
+
market: str = "shares",
|
|
292
|
+
board: str = "TQBR",
|
|
293
|
+
return_df: bool = False,
|
|
294
|
+
show_progress: bool = True,
|
|
295
|
+
) -> dict[str, Any] | Any:
|
|
296
|
+
"""Fetch OHLCV candles for a given instrument and period.
|
|
297
|
+
|
|
298
|
+
See :func:`moex_iss_client.endpoints.candles.get_ohlcv`.
|
|
299
|
+
"""
|
|
300
|
+
from moex_iss_client.endpoints.candles import get_ohlcv as _impl
|
|
301
|
+
|
|
302
|
+
return _impl(
|
|
303
|
+
self,
|
|
304
|
+
secid=secid,
|
|
305
|
+
timeframe=timeframe,
|
|
306
|
+
start=start,
|
|
307
|
+
end=end,
|
|
308
|
+
engine=engine,
|
|
309
|
+
market=market,
|
|
310
|
+
board=board,
|
|
311
|
+
return_df=return_df,
|
|
312
|
+
show_progress=show_progress,
|
|
313
|
+
)
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
"""Implementation of the ISS candles (OHLCV) endpoint."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import logging
|
|
6
|
+
from concurrent.futures import ThreadPoolExecutor
|
|
7
|
+
from typing import TYPE_CHECKING, Any
|
|
8
|
+
|
|
9
|
+
from moex_iss_client.exceptions import MoexISSError, NotFoundError, ValidationError
|
|
10
|
+
from moex_iss_client.models import CANDLES_MAX_ROWS_PER_RESPONSE, timeframe_to_interval
|
|
11
|
+
from moex_iss_client.utils import (
|
|
12
|
+
ProgressIndicator,
|
|
13
|
+
column_names_from_metadata,
|
|
14
|
+
parse_user_date,
|
|
15
|
+
rows_to_dataframe,
|
|
16
|
+
)
|
|
17
|
+
|
|
18
|
+
if TYPE_CHECKING:
|
|
19
|
+
from moex_iss_client.client import MoexISSClient
|
|
20
|
+
|
|
21
|
+
logger = logging.getLogger(__name__)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def get_ohlcv(
|
|
25
|
+
client: MoexISSClient,
|
|
26
|
+
secid: str,
|
|
27
|
+
timeframe: str = "1D",
|
|
28
|
+
start: str | None = None,
|
|
29
|
+
end: str | None = None,
|
|
30
|
+
engine: str = "stock",
|
|
31
|
+
market: str = "shares",
|
|
32
|
+
board: str = "TQBR",
|
|
33
|
+
return_df: bool = False,
|
|
34
|
+
show_progress: bool = True,
|
|
35
|
+
) -> dict[str, Any] | Any:
|
|
36
|
+
"""Fetch OHLCV candles for a given instrument and period.
|
|
37
|
+
|
|
38
|
+
See :func:`moex_iss_client.endpoints.candles.get_ohlcv` for parameters.
|
|
39
|
+
"""
|
|
40
|
+
interval = timeframe_to_interval(timeframe)
|
|
41
|
+
|
|
42
|
+
from_date: str | None = parse_user_date(start) if start else None
|
|
43
|
+
till_date: str | None = parse_user_date(end) if end else None
|
|
44
|
+
|
|
45
|
+
if from_date and till_date and from_date > till_date:
|
|
46
|
+
raise ValidationError(f"Start date {start!r} is after end date {end!r}")
|
|
47
|
+
|
|
48
|
+
path = f"/iss/engines/{engine}/markets/{market}/boards/{board}/securities/{secid}/candles.json"
|
|
49
|
+
|
|
50
|
+
base_params: dict[str, Any] = {
|
|
51
|
+
"interval": interval,
|
|
52
|
+
"iss.meta": "on",
|
|
53
|
+
"iss.only": "candles",
|
|
54
|
+
}
|
|
55
|
+
if from_date:
|
|
56
|
+
base_params["from"] = from_date
|
|
57
|
+
if till_date:
|
|
58
|
+
base_params["till"] = till_date
|
|
59
|
+
|
|
60
|
+
def fetch_page(start_row: int) -> dict[str, Any]:
|
|
61
|
+
params = dict(base_params)
|
|
62
|
+
params["start"] = start_row
|
|
63
|
+
response = client._request("GET", path, params=params)
|
|
64
|
+
if response.status_code == 404:
|
|
65
|
+
raise NotFoundError(f"Candles endpoint not found: {path}")
|
|
66
|
+
if not response.is_success:
|
|
67
|
+
raise MoexISSError(
|
|
68
|
+
f"ISS returned HTTP {response.status_code} for {path!r}: {response.text[:300]!r}"
|
|
69
|
+
)
|
|
70
|
+
content_type = response.headers.get("content-type", "")
|
|
71
|
+
if "json" not in content_type.lower():
|
|
72
|
+
raise MoexISSError(
|
|
73
|
+
f"ISS returned non-JSON response for {path!r}: "
|
|
74
|
+
f"content-type={content_type!r}, body[:300]={response.text[:300]!r}"
|
|
75
|
+
)
|
|
76
|
+
return response.json()
|
|
77
|
+
|
|
78
|
+
def extract_rows(page: dict[str, Any]) -> list[list[Any]]:
|
|
79
|
+
return (page.get("candles") or {}).get("data") or []
|
|
80
|
+
|
|
81
|
+
progress = ProgressIndicator(label=secid, enabled=show_progress)
|
|
82
|
+
|
|
83
|
+
# --- First page sequentially: columns + first rows. ---
|
|
84
|
+
first_page = fetch_page(0)
|
|
85
|
+
columns = column_names_from_metadata(first_page, "candles")
|
|
86
|
+
all_rows: list[list[Any]] = list(extract_rows(first_page))
|
|
87
|
+
progress.advance(len(all_rows))
|
|
88
|
+
|
|
89
|
+
# --- Second page as a probe (sequential). ---
|
|
90
|
+
if len(all_rows) < CANDLES_MAX_ROWS_PER_RESPONSE:
|
|
91
|
+
progress.finish()
|
|
92
|
+
return _format_result(all_rows, columns, secid, timeframe, show_progress, return_df)
|
|
93
|
+
|
|
94
|
+
second_start = len(all_rows)
|
|
95
|
+
second_rows = extract_rows(fetch_page(second_start))
|
|
96
|
+
progress.advance(len(second_rows))
|
|
97
|
+
if not second_rows:
|
|
98
|
+
progress.finish()
|
|
99
|
+
return _format_result(all_rows, columns, secid, timeframe, show_progress, return_df)
|
|
100
|
+
all_rows.extend(second_rows)
|
|
101
|
+
if len(second_rows) < CANDLES_MAX_ROWS_PER_RESPONSE:
|
|
102
|
+
progress.finish()
|
|
103
|
+
return _format_result(all_rows, columns, secid, timeframe, show_progress, return_df)
|
|
104
|
+
|
|
105
|
+
# --- Parallel probing in batches of `max_workers` pages. ---
|
|
106
|
+
step = CANDLES_MAX_ROWS_PER_RESPONSE
|
|
107
|
+
next_start = len(all_rows)
|
|
108
|
+
max_batches = 10_000 # safety limit
|
|
109
|
+
with ThreadPoolExecutor(max_workers=client.max_workers) as executor:
|
|
110
|
+
for _ in range(max_batches):
|
|
111
|
+
batch_starts = [next_start + i * step for i in range(client.max_workers)]
|
|
112
|
+
batch_rows = list(executor.map(lambda s: extract_rows(fetch_page(s)), batch_starts))
|
|
113
|
+
|
|
114
|
+
stop = False
|
|
115
|
+
for rows in batch_rows:
|
|
116
|
+
if not rows:
|
|
117
|
+
stop = True
|
|
118
|
+
break
|
|
119
|
+
all_rows.extend(rows)
|
|
120
|
+
progress.advance(len(rows))
|
|
121
|
+
if len(rows) < step:
|
|
122
|
+
stop = True
|
|
123
|
+
break
|
|
124
|
+
if stop:
|
|
125
|
+
break
|
|
126
|
+
next_start = batch_starts[-1] + step
|
|
127
|
+
else:
|
|
128
|
+
logger.warning(
|
|
129
|
+
"OHLCV pagination stopped after %d batches (max_batches reached)",
|
|
130
|
+
max_batches,
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
progress.finish()
|
|
134
|
+
return _format_result(all_rows, columns, secid, timeframe, show_progress, return_df)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def _format_result(
|
|
138
|
+
rows: list[list[Any]],
|
|
139
|
+
columns: list[str],
|
|
140
|
+
secid: str,
|
|
141
|
+
timeframe: str,
|
|
142
|
+
show_progress: bool,
|
|
143
|
+
return_df: bool,
|
|
144
|
+
) -> dict[str, Any] | Any:
|
|
145
|
+
if columns and "begin" in columns:
|
|
146
|
+
begin_idx = columns.index("begin")
|
|
147
|
+
rows.sort(key=lambda row: row[begin_idx])
|
|
148
|
+
|
|
149
|
+
if return_df:
|
|
150
|
+
return rows_to_dataframe(rows, columns)
|
|
151
|
+
|
|
152
|
+
return {
|
|
153
|
+
"candles": {
|
|
154
|
+
"metadata": {"columns": columns} if columns else {},
|
|
155
|
+
"data": rows,
|
|
156
|
+
}
|
|
157
|
+
}
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
"""Implementation of the ISS securities endpoint."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import logging
|
|
6
|
+
from typing import TYPE_CHECKING, Any
|
|
7
|
+
|
|
8
|
+
from moex_iss_client.exceptions import MoexISSError, NotFoundError, ValidationError
|
|
9
|
+
from moex_iss_client.models import InstrumentType
|
|
10
|
+
from moex_iss_client.utils import column_names_from_metadata, rows_to_dataframe
|
|
11
|
+
|
|
12
|
+
if TYPE_CHECKING:
|
|
13
|
+
from moex_iss_client.client import MoexISSClient
|
|
14
|
+
|
|
15
|
+
logger = logging.getLogger(__name__)
|
|
16
|
+
|
|
17
|
+
_ENGINE_MARKET: dict[InstrumentType, tuple[str, str]] = {
|
|
18
|
+
InstrumentType.STOCK: ("stock", "shares"),
|
|
19
|
+
InstrumentType.FUTURES: ("futures", "forts"),
|
|
20
|
+
InstrumentType.INDEX: ("stock", "index"),
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def get_securities(
|
|
25
|
+
client: MoexISSClient,
|
|
26
|
+
instrument_type: str = "stock",
|
|
27
|
+
*,
|
|
28
|
+
return_df: bool = False,
|
|
29
|
+
) -> dict[str, Any] | Any:
|
|
30
|
+
"""Fetch the list of securities for the given instrument type.
|
|
31
|
+
|
|
32
|
+
Parameters
|
|
33
|
+
----------
|
|
34
|
+
client : MoexISSClient
|
|
35
|
+
The client instance used to perform HTTP requests.
|
|
36
|
+
instrument_type : str, default "stock"
|
|
37
|
+
One of ``"stock"``, ``"futures"``, ``"index"``.
|
|
38
|
+
return_df : bool, default False
|
|
39
|
+
If ``True``, return a :class:`pandas.DataFrame` instead of a dict.
|
|
40
|
+
|
|
41
|
+
Returns
|
|
42
|
+
-------
|
|
43
|
+
dict | pandas.DataFrame
|
|
44
|
+
Raw ISS response with the ``securities`` block, or a DataFrame
|
|
45
|
+
built from the ``securities.data`` rows.
|
|
46
|
+
|
|
47
|
+
Raises
|
|
48
|
+
------
|
|
49
|
+
ValidationError
|
|
50
|
+
If ``instrument_type`` is not supported.
|
|
51
|
+
NotFoundError
|
|
52
|
+
If the ISS returns 404 for the constructed path.
|
|
53
|
+
MoexISSError
|
|
54
|
+
If the ISS returns a non-2xx status or a non-JSON response.
|
|
55
|
+
|
|
56
|
+
Notes
|
|
57
|
+
-----
|
|
58
|
+
The ISS endpoint used here returns the full list in a single response
|
|
59
|
+
and does not support pagination via ``start``. No pagination loop is
|
|
60
|
+
performed.
|
|
61
|
+
"""
|
|
62
|
+
try:
|
|
63
|
+
itype = InstrumentType(instrument_type)
|
|
64
|
+
except ValueError as exc:
|
|
65
|
+
supported = ", ".join(t.value for t in InstrumentType)
|
|
66
|
+
raise ValidationError(
|
|
67
|
+
f"Unsupported instrument_type {instrument_type!r}. Supported: {supported}"
|
|
68
|
+
) from exc
|
|
69
|
+
|
|
70
|
+
engine, market = _ENGINE_MARKET[itype]
|
|
71
|
+
# The ISS returns XML by default; the `.json` suffix is required
|
|
72
|
+
# to get a JSON response. See the ISS docs, "Формат ответа от сервера".
|
|
73
|
+
path = f"/iss/engines/{engine}/markets/{market}/securities.json"
|
|
74
|
+
|
|
75
|
+
response = client._request(
|
|
76
|
+
"GET",
|
|
77
|
+
path,
|
|
78
|
+
params={
|
|
79
|
+
"iss.meta": "on",
|
|
80
|
+
"iss.only": "securities",
|
|
81
|
+
},
|
|
82
|
+
)
|
|
83
|
+
if response.status_code == 404:
|
|
84
|
+
raise NotFoundError(f"Securities endpoint not found: {path}")
|
|
85
|
+
if not response.is_success:
|
|
86
|
+
raise MoexISSError(
|
|
87
|
+
f"ISS returned HTTP {response.status_code} for {path!r}: {response.text[:300]!r}"
|
|
88
|
+
)
|
|
89
|
+
content_type = response.headers.get("content-type", "")
|
|
90
|
+
if "json" not in content_type.lower():
|
|
91
|
+
raise MoexISSError(
|
|
92
|
+
f"ISS returned non-JSON response for {path!r}: "
|
|
93
|
+
f"content-type={content_type!r}, body[:300]={response.text[:300]!r}"
|
|
94
|
+
)
|
|
95
|
+
|
|
96
|
+
parsed: dict[str, Any] = response.json()
|
|
97
|
+
block = parsed.get("securities") or {}
|
|
98
|
+
rows = block.get("data") or []
|
|
99
|
+
columns = column_names_from_metadata(parsed, "securities")
|
|
100
|
+
|
|
101
|
+
merged: dict[str, Any] = {
|
|
102
|
+
"securities": {
|
|
103
|
+
"metadata": {"columns": columns} if columns else {},
|
|
104
|
+
"data": rows,
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
if return_df:
|
|
109
|
+
return rows_to_dataframe(rows, columns)
|
|
110
|
+
|
|
111
|
+
return merged
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""Иерархия исключений для библиотеки moex-iss-client"""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class MoexISSError(Exception):
|
|
7
|
+
"""Базовое исключение для всех ошибок вызванных библиотекой moex-iss-client."""
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class ValidationError(MoexISSError):
|
|
11
|
+
"""Вызывается, когда входной аргумент не проходит валидацию (например, даты до 2000-01-01)."""
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class AuthError(MoexISSError):
|
|
15
|
+
"""Вызывается, когда непроходит авторизация на passport.moex.com."""
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class NotFoundError(MoexISSError):
|
|
19
|
+
"""Вызывается, когда запрашиваемых данных нет на сервере ISS."""
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class TransportError(MoexISSError):
|
|
23
|
+
"""Вызывается, когда возникают ошибки передачи данных или сети после прохождения всех повторов (попыток)"""
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
"""Domain constants and mappings for MOEX ISS endpoints."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from enum import StrEnum
|
|
6
|
+
|
|
7
|
+
# ISS accepts `interval` as an integer. See the ISS documentation for details.
|
|
8
|
+
# 1 = 1 minute, 10 = 10 minutes, 60 = 1 hour, 24 = 1 day, 7 = 1 week,
|
|
9
|
+
# 31 = 1 month, 4 = 1 quarter.
|
|
10
|
+
ISS_INTERVAL_BY_TIMEFRAME: dict[str, int] = {
|
|
11
|
+
"1m": 1,
|
|
12
|
+
"10m": 10,
|
|
13
|
+
"1H": 60,
|
|
14
|
+
"1D": 24,
|
|
15
|
+
"1W": 7,
|
|
16
|
+
"1M": 31,
|
|
17
|
+
"1Q": 4,
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def timeframe_to_interval(timeframe: str) -> int:
|
|
22
|
+
"""Map a human-readable timeframe to the ISS `interval` integer.
|
|
23
|
+
|
|
24
|
+
Parameters
|
|
25
|
+
----------
|
|
26
|
+
timeframe : str
|
|
27
|
+
Human-readable timeframe, e.g. ``"1D"``, ``"1H"``, ``"1W"``.
|
|
28
|
+
|
|
29
|
+
Returns
|
|
30
|
+
-------
|
|
31
|
+
int
|
|
32
|
+
The corresponding ISS ``interval`` value.
|
|
33
|
+
|
|
34
|
+
Raises
|
|
35
|
+
------
|
|
36
|
+
moex_iss_client.exceptions.ValidationError
|
|
37
|
+
If the timeframe is not supported.
|
|
38
|
+
"""
|
|
39
|
+
from moex_iss_client.exceptions import ValidationError
|
|
40
|
+
|
|
41
|
+
try:
|
|
42
|
+
return ISS_INTERVAL_BY_TIMEFRAME[timeframe]
|
|
43
|
+
except KeyError as exc:
|
|
44
|
+
supported = ", ".join(ISS_INTERVAL_BY_TIMEFRAME)
|
|
45
|
+
raise ValidationError(
|
|
46
|
+
f"Unsupported timeframe {timeframe!r}. Supported: {supported}"
|
|
47
|
+
) from exc
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class InstrumentType(StrEnum):
|
|
51
|
+
"""Instrument types supported by the securities endpoint."""
|
|
52
|
+
|
|
53
|
+
STOCK = "stock"
|
|
54
|
+
FUTURES = "futures"
|
|
55
|
+
INDEX = "index"
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
# Base URL for the ISS data endpoints.
|
|
59
|
+
ISS_BASE_URL = "http://iss.moex.com"
|
|
60
|
+
# Base URL for the passport/authentication endpoint.
|
|
61
|
+
PASSPORT_BASE_URL = "https://passport.moex.com"
|
|
62
|
+
# Oldest date the ISS server returns data for.
|
|
63
|
+
MIN_SUPPORTED_DATE = "2000-01-01"
|
|
64
|
+
# Maximum number of rows the ISS server returns per response for /candles.
|
|
65
|
+
CANDLES_MAX_ROWS_PER_RESPONSE = 500
|
moex_iss_client/utils.py
ADDED
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
"""Utility helpers shared by ISS endpoints: pagination, date conversion, progress."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import logging
|
|
6
|
+
import sys
|
|
7
|
+
import threading
|
|
8
|
+
from collections.abc import Callable, Iterator
|
|
9
|
+
from datetime import datetime
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
from moex_iss_client.exceptions import MoexISSError, ValidationError
|
|
13
|
+
from moex_iss_client.models import MIN_SUPPORTED_DATE
|
|
14
|
+
|
|
15
|
+
logger = logging.getLogger(__name__)
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def iter_cursor_pages(
|
|
19
|
+
fetch_page: Callable[[int], dict[str, Any]],
|
|
20
|
+
*,
|
|
21
|
+
cursor_block: str = "securities.cursor",
|
|
22
|
+
max_pages: int = 10_000,
|
|
23
|
+
) -> Iterator[list[list[Any]]]:
|
|
24
|
+
"""Iterate over pages of a cursor-paginated ISS block.
|
|
25
|
+
|
|
26
|
+
Uses the ``cursor`` block returned by ISS endpoints such as
|
|
27
|
+
``/iss/engines/{engine}/markets/{market}/securities``. The cursor
|
|
28
|
+
contains ``INDEX`` (start row), ``TOTAL`` (total rows) and
|
|
29
|
+
``PAGESIZE`` (rows in this response).
|
|
30
|
+
|
|
31
|
+
Parameters
|
|
32
|
+
----------
|
|
33
|
+
fetch_page : Callable[[int], dict]
|
|
34
|
+
Function that takes ``start`` and returns the raw ISS JSON
|
|
35
|
+
response (parsed as ``dict``).
|
|
36
|
+
cursor_block : str, default "securities.cursor"
|
|
37
|
+
Name of the cursor block in the response.
|
|
38
|
+
max_pages : int, default 10000
|
|
39
|
+
Safety limit to avoid infinite loops on malformed responses.
|
|
40
|
+
|
|
41
|
+
Yields
|
|
42
|
+
------
|
|
43
|
+
list[list[Any]]
|
|
44
|
+
Rows of the ``securities`` block for each page.
|
|
45
|
+
"""
|
|
46
|
+
start = 0
|
|
47
|
+
for _ in range(max_pages):
|
|
48
|
+
response = fetch_page(start)
|
|
49
|
+
cursor_rows = _extract_cursor(response, cursor_block)
|
|
50
|
+
if cursor_rows is None:
|
|
51
|
+
# Fallback: no cursor block — caller should use row-count pagination.
|
|
52
|
+
raise RuntimeError(
|
|
53
|
+
f"Cursor block {cursor_block!r} not found in response; "
|
|
54
|
+
"this endpoint may not support cursor pagination"
|
|
55
|
+
)
|
|
56
|
+
|
|
57
|
+
index, total, pagesize = cursor_rows
|
|
58
|
+
data_block = response.get("securities", {}).get("data", [])
|
|
59
|
+
if data_block:
|
|
60
|
+
yield data_block
|
|
61
|
+
|
|
62
|
+
if index + pagesize >= total:
|
|
63
|
+
break
|
|
64
|
+
start += pagesize
|
|
65
|
+
else:
|
|
66
|
+
logger.warning("Pagination stopped after %d pages (max_pages reached)", max_pages)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _extract_cursor(response: dict[str, Any], cursor_block: str) -> tuple[int, int, int] | None:
|
|
70
|
+
"""Extract (INDEX, TOTAL, PAGESIZE) from a cursor block."""
|
|
71
|
+
block = response.get(cursor_block)
|
|
72
|
+
if not block or not block.get("data"):
|
|
73
|
+
return None
|
|
74
|
+
# The cursor block has one row: [INDEX, TOTAL, PAGESIZE].
|
|
75
|
+
row = block["data"][0]
|
|
76
|
+
if len(row) < 3:
|
|
77
|
+
return None
|
|
78
|
+
return int(row[0]), int(row[1]), int(row[2])
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def column_names_from_metadata(response: dict[str, Any], block: str) -> list[str]:
|
|
82
|
+
"""Extract column names from the metadata section of an ISS block.
|
|
83
|
+
|
|
84
|
+
The ISS has used several shapes for the ``metadata`` section over time:
|
|
85
|
+
|
|
86
|
+
- a dict of ``{name: {"type": ..., "bytes": ...}}`` (current format);
|
|
87
|
+
- a list of names under ``metadata.columns``;
|
|
88
|
+
- a list of ``[name, type, length]`` triples under ``metadata.columns``.
|
|
89
|
+
|
|
90
|
+
All three are handled.
|
|
91
|
+
"""
|
|
92
|
+
block_data = response.get(block) or {}
|
|
93
|
+
metadata = block_data.get("metadata")
|
|
94
|
+
if not metadata:
|
|
95
|
+
return []
|
|
96
|
+
|
|
97
|
+
# Format 1: metadata itself is a dict of column descriptions.
|
|
98
|
+
if isinstance(metadata, dict) and "columns" not in metadata:
|
|
99
|
+
return list(metadata.keys())
|
|
100
|
+
|
|
101
|
+
# Format 2 / 3: column names live under metadata["columns"].
|
|
102
|
+
columns = metadata.get("columns") if isinstance(metadata, dict) else None
|
|
103
|
+
if not columns:
|
|
104
|
+
return []
|
|
105
|
+
|
|
106
|
+
names: list[str] = []
|
|
107
|
+
for col in columns:
|
|
108
|
+
if isinstance(col, (list, tuple)):
|
|
109
|
+
if not col:
|
|
110
|
+
continue
|
|
111
|
+
names.append(str(col[0]))
|
|
112
|
+
elif isinstance(col, dict):
|
|
113
|
+
name = col.get("name")
|
|
114
|
+
if name is not None:
|
|
115
|
+
names.append(str(name))
|
|
116
|
+
else:
|
|
117
|
+
names.append(str(col))
|
|
118
|
+
return names
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def iter_rows_pages(
|
|
122
|
+
fetch_page: Callable[[int], dict[str, Any]],
|
|
123
|
+
*,
|
|
124
|
+
data_block: str = "securities",
|
|
125
|
+
max_pages: int = 10_000,
|
|
126
|
+
) -> Iterator[list[list[Any]]]:
|
|
127
|
+
"""Iterate over pages using row-count pagination.
|
|
128
|
+
|
|
129
|
+
Unlike cursor-based pagination, this is used for endpoints that do not
|
|
130
|
+
return a ``<block>.cursor`` block. After each response we look at the
|
|
131
|
+
actual number of rows returned; a zero-row response marks the end.
|
|
132
|
+
"""
|
|
133
|
+
start = 0
|
|
134
|
+
for _ in range(max_pages):
|
|
135
|
+
response = fetch_page(start)
|
|
136
|
+
block = response.get(data_block) or {}
|
|
137
|
+
rows = block.get("data") or []
|
|
138
|
+
if not rows:
|
|
139
|
+
break
|
|
140
|
+
yield rows
|
|
141
|
+
start += len(rows)
|
|
142
|
+
else:
|
|
143
|
+
logger.warning("Pagination stopped after %d pages (max_pages reached)", max_pages)
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def parse_user_date(value: str) -> str:
|
|
147
|
+
"""Convert a ``DD-MM-YYYY`` date to the ISS ``YYYY-MM-DD`` format.
|
|
148
|
+
|
|
149
|
+
Parameters
|
|
150
|
+
----------
|
|
151
|
+
value : str
|
|
152
|
+
Date in ``DD-MM-YYYY`` format.
|
|
153
|
+
|
|
154
|
+
Returns
|
|
155
|
+
-------
|
|
156
|
+
str
|
|
157
|
+
Date in ``YYYY-MM-DD`` format accepted by ISS.
|
|
158
|
+
|
|
159
|
+
Raises
|
|
160
|
+
------
|
|
161
|
+
moex_iss_client.exceptions.ValidationError
|
|
162
|
+
If the date cannot be parsed or is earlier than 2000-01-01.
|
|
163
|
+
"""
|
|
164
|
+
|
|
165
|
+
try:
|
|
166
|
+
parsed = datetime.strptime(value, "%d-%m-%Y").date()
|
|
167
|
+
except ValueError as exc:
|
|
168
|
+
raise ValidationError(f"Invalid date {value!r}. Expected format: DD-MM-YYYY") from exc
|
|
169
|
+
|
|
170
|
+
min_date = datetime.strptime(MIN_SUPPORTED_DATE, "%Y-%m-%d").date()
|
|
171
|
+
if parsed < min_date:
|
|
172
|
+
raise ValidationError(
|
|
173
|
+
f"Date {value!r} is earlier than the minimum supported date {MIN_SUPPORTED_DATE}"
|
|
174
|
+
)
|
|
175
|
+
|
|
176
|
+
return parsed.strftime("%Y-%m-%d")
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
def rows_to_dataframe(rows: list[list[Any]], columns: list[str]) -> Any:
|
|
180
|
+
"""Build a :class:`pandas.DataFrame` from ISS rows.
|
|
181
|
+
|
|
182
|
+
Parameters
|
|
183
|
+
----------
|
|
184
|
+
rows : list[list[Any]]
|
|
185
|
+
Rows as returned by the ISS ``data`` block.
|
|
186
|
+
columns : list[str]
|
|
187
|
+
Column names from the ISS ``metadata`` block.
|
|
188
|
+
|
|
189
|
+
Returns
|
|
190
|
+
-------
|
|
191
|
+
pandas.DataFrame
|
|
192
|
+
DataFrame with the given columns.
|
|
193
|
+
|
|
194
|
+
Raises
|
|
195
|
+
------
|
|
196
|
+
moex_iss_client.exceptions.MoexISSError
|
|
197
|
+
If ``pandas`` is not installed.
|
|
198
|
+
"""
|
|
199
|
+
try:
|
|
200
|
+
import pandas as pd
|
|
201
|
+
except ImportError as exc:
|
|
202
|
+
raise MoexISSError(
|
|
203
|
+
"pandas is required for return_df=True. "
|
|
204
|
+
"Install it with: uv add pandas (or uv sync --extra pandas)."
|
|
205
|
+
) from exc
|
|
206
|
+
|
|
207
|
+
return pd.DataFrame(rows, columns=columns)
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
class ProgressIndicator:
|
|
211
|
+
"""Thread-safe console progress indicator for paginated downloads.
|
|
212
|
+
|
|
213
|
+
The total number of pages/rows is not known in advance (ISS does not
|
|
214
|
+
return a cursor for ``/candles``), so the indicator shows a running
|
|
215
|
+
count of loaded rows and pages instead of a percentage.
|
|
216
|
+
|
|
217
|
+
Parameters
|
|
218
|
+
----------
|
|
219
|
+
label : str, default ""
|
|
220
|
+
Label prepended to the progress line, e.g. the secid.
|
|
221
|
+
enabled : bool, default True
|
|
222
|
+
If ``False``, all methods are no-ops.
|
|
223
|
+
|
|
224
|
+
Notes
|
|
225
|
+
-----
|
|
226
|
+
The indicator writes to ``sys.stderr`` so that it does not pollute
|
|
227
|
+
stdout (which may be piped to a file or another program). The final
|
|
228
|
+
line is terminated with a newline on :meth:`finish`.
|
|
229
|
+
"""
|
|
230
|
+
|
|
231
|
+
def __init__(self, label: str = "", enabled: bool = True) -> None:
|
|
232
|
+
self._label = label
|
|
233
|
+
self._enabled = enabled
|
|
234
|
+
self._rows = 0
|
|
235
|
+
self._pages = 0
|
|
236
|
+
self._lock = threading.Lock()
|
|
237
|
+
|
|
238
|
+
def advance(self, rows: int = 1) -> None:
|
|
239
|
+
"""Record one page with ``rows`` rows and redraw the progress line."""
|
|
240
|
+
if not self._enabled:
|
|
241
|
+
return
|
|
242
|
+
with self._lock:
|
|
243
|
+
self._rows += rows
|
|
244
|
+
self._pages += 1
|
|
245
|
+
self._render()
|
|
246
|
+
|
|
247
|
+
def finish(self) -> None:
|
|
248
|
+
"""Terminate the progress line with a newline."""
|
|
249
|
+
if not self._enabled:
|
|
250
|
+
return
|
|
251
|
+
with self._lock:
|
|
252
|
+
sys.stderr.write("\n")
|
|
253
|
+
sys.stderr.flush()
|
|
254
|
+
|
|
255
|
+
def _render(self) -> None:
|
|
256
|
+
prefix = f"{self._label}: " if self._label else ""
|
|
257
|
+
sys.stderr.write(f"\r{prefix}{self._rows} rows loaded ({self._pages} pages)")
|
|
258
|
+
sys.stderr.flush()
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: moex-iss-client
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python client for the MOEX Information and Statistical Server (ISS) API
|
|
5
|
+
Keywords: moex,iss,stock,futures,ohlcv,trading
|
|
6
|
+
Author: moex-iss-client contributors
|
|
7
|
+
License: MIT
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
12
|
+
Classifier: Topic :: Office/Business :: Financial :: Investment
|
|
13
|
+
Requires-Dist: httpx>=0.27
|
|
14
|
+
Requires-Dist: pytest>=8.0 ; extra == 'dev'
|
|
15
|
+
Requires-Dist: pytest-httpx>=0.30 ; extra == 'dev'
|
|
16
|
+
Requires-Dist: ruff>=0.6 ; extra == 'dev'
|
|
17
|
+
Requires-Dist: pandas>=2.0 ; extra == 'pandas'
|
|
18
|
+
Requires-Python: >=3.14
|
|
19
|
+
Provides-Extra: dev
|
|
20
|
+
Provides-Extra: pandas
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# moex-iss-client
|
|
24
|
+
|
|
25
|
+
Python-клиент к [Информационно-статистическому серверу Московской Биржи (MOEX ISS)](http://iss.moex.com/iss/reference/).
|
|
26
|
+
|
|
27
|
+
Библиотека «чистая»: без CLI, без собственного сервера. Предназначена для импорта в другие Python-проекты.
|
|
28
|
+
|
|
29
|
+
## Возможности
|
|
30
|
+
|
|
31
|
+
- Получение OHLCV-свечей по акциям, фьючерсам и индексам за указанный период с заданным таймфреймом.
|
|
32
|
+
- Получение списка тикеров с описанием (акции, фьючерсы, индексы).
|
|
33
|
+
- Аутентификация через `passport.moex.com` (basic-auth + cookie `MicexPassportCert`), с автоматическим продлением. Библиотека работает и без авторизации — для публичных данных.
|
|
34
|
+
- Опциональный возврат `pandas.DataFrame` (`return_df=True`).
|
|
35
|
+
- Ретраи для статусов 500–504 и транспортных ошибок.
|
|
36
|
+
- Многопоточный пул (`max_workers`) заложен архитектурно; `get_ohlcv` использует последовательную пагинацию (см. раздел «Пагинация»).
|
|
37
|
+
|
|
38
|
+
## Установка
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
uv sync
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
С `pandas` (для `return_df=True`):
|
|
45
|
+
```bash
|
|
46
|
+
uv sync --extra pandas
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
С dev-зависимостями (тесты, линтер):
|
|
50
|
+
```bash
|
|
51
|
+
uv sync --extra dev --extra pandas
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Быстрый старт
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
from moex_iss_client import MoexISSClient
|
|
58
|
+
|
|
59
|
+
with MoexISSClient() as client:
|
|
60
|
+
df = client.get_ohlcv(
|
|
61
|
+
"SBER",
|
|
62
|
+
timeframe="1D",
|
|
63
|
+
start="01-01-2024",
|
|
64
|
+
end="31-01-2024",
|
|
65
|
+
return_df=True,
|
|
66
|
+
)
|
|
67
|
+
print(df.head())
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Список акций:
|
|
71
|
+
```python
|
|
72
|
+
with MoexISSClient() as client:
|
|
73
|
+
df = client.get_securities("stock", return_df=True)
|
|
74
|
+
print(df[["SECID", "SHORTNAME"]].head())
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
С авторизацией:
|
|
78
|
+
```python
|
|
79
|
+
with MoexISSClient(login="...", password="...") as client:
|
|
80
|
+
df = client.get_ohlcv("SBER", "1D", start="01-01-2024", end="31-01-2024", return_df=True)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Таймфреймы
|
|
84
|
+
|
|
85
|
+
| Обозначение | Значение | ISS `interval` |
|
|
86
|
+
|:---:|:---:|:---:|
|
|
87
|
+
| `1m` | 1 минута | 1 |
|
|
88
|
+
| `10m` | 10 минут | 10 |
|
|
89
|
+
| `1H` | 1 час | 60 |
|
|
90
|
+
| `1D` | 1 день | 24 |
|
|
91
|
+
| `1W` | 1 неделя | 7 |
|
|
92
|
+
| `1M` | 1 месяц | 31 |
|
|
93
|
+
| `1Q` | 1 квартал | 4 |
|
|
94
|
+
|
|
95
|
+
Маппинг задан в `moex_iss_client.models.ISS_INTERVAL_BY_TIMEFRAME`.
|
|
96
|
+
|
|
97
|
+
## Параметры `MoexISSClient`
|
|
98
|
+
|
|
99
|
+
| Параметр | По умолчанию | Описание |
|
|
100
|
+
|:---|:---|:---|
|
|
101
|
+
| `login` | `None` | Логин MOEX passport. |
|
|
102
|
+
| `password` | `None` | Пароль MOEX passport. |
|
|
103
|
+
| `timeout` | `30.0` | Таймаут запроса, сек. |
|
|
104
|
+
| `max_retries` | `3` | Число ретраев для 500–504 и транспортных ошибок. |
|
|
105
|
+
| `retry_backoff` | `1.0` | Базовая задержка между ретраями, сек (экспоненциальный рост). |
|
|
106
|
+
| `max_workers` | `4` | Максимум потоков для параллельных запросов. |
|
|
107
|
+
| `verify` | `True` | TLS-проверка. `True` / `False` / путь к PEM / `ssl.SSLContext`. |
|
|
108
|
+
| `trust_env` | `True` | Читать `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` из окружения. |
|
|
109
|
+
|
|
110
|
+
## TLS и корпоративные сети
|
|
111
|
+
|
|
112
|
+
Если `passport.moex.com` или `iss.moex.com` возвращают ошибку проверки сертификата (`CERTIFICATE_VERIFY_FAILED: self-signed certificate in certificate chain`), это значит, что в цепочке есть корень, отсутствующий в `certifi`. Два типичных случая: корпоративный MITM-прокси или переход MOEX на сертификаты НУЦ Минцифры.
|
|
113
|
+
|
|
114
|
+
Варианты решения:
|
|
115
|
+
1. **Системное хранилище доверия** (рекомендуется):
|
|
116
|
+
```python
|
|
117
|
+
import ssl
|
|
118
|
+
from moex_iss_client import MoexISSClient
|
|
119
|
+
|
|
120
|
+
ctx = ssl.create_default_context()
|
|
121
|
+
with MoexISSClient(verify=ctx) as client:
|
|
122
|
+
...
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
2. **Путь к PEM-bundle:**
|
|
126
|
+
```python
|
|
127
|
+
with MoexISSClient(verify="/path/to/combined_cacert.pem") as client:
|
|
128
|
+
...
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
3. **Переменные окружения** (при `trust_env=True`, по умолчанию):
|
|
132
|
+
```bash
|
|
133
|
+
export SSL_CERT_FILE=/path/to/combined_cacert.pem
|
|
134
|
+
uv run python examples/get_ohlcv.py
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
4. **Отключение проверки** — только для локальной отладки. Вызов `MoexISSClient(verify=False)` эмитит `UserWarning`.
|
|
138
|
+
|
|
139
|
+
## Пагинация
|
|
140
|
+
|
|
141
|
+
- `get_securities` запрашивает весь список одним запросом: ISS не поддерживает пагинацию для этого эндпоинта (`start` игнорируется).
|
|
142
|
+
- `get_ohlcv` использует последовательную пагинацию через параметр `start`, поскольку блок `cursor` для `/candles` не отдаётся. Ответ содержит не более 500 строк (`CANDLES_MAX_ROWS_PER_RESPONSE`); цикл останавливается на пустой или частичной странице. Результат сортируется по колонке `begin`.
|
|
143
|
+
|
|
144
|
+
## Ограничения ISS
|
|
145
|
+
|
|
146
|
+
- Данные ранее `2000-01-01` недоступны. `get_ohlcv` валидирует даты и бросает `ValidationError`.
|
|
147
|
+
- Онлайн-данные и итоги торгов доступны по подписке. Без авторизации данные приходят с задержкой (индексы — без задержки).
|
|
148
|
+
- Формат ответа задаётся расширением в URL: `.json`, `.xml`, `.csv`, `.html`. Библиотека использует `.json`.
|
|
149
|
+
|
|
150
|
+
## Исключения
|
|
151
|
+
|
|
152
|
+
Иерархия в `moex_iss_client.exceptions`:
|
|
153
|
+
- `MoexISSError` — базовое.
|
|
154
|
+
- `ValidationError` — неверные аргументы (таймфрейм, даты).
|
|
155
|
+
- `AuthError` — ошибка аутентификации.
|
|
156
|
+
- `NotFoundError` — 404 от ISS.
|
|
157
|
+
- `TransportError` — транспортная ошибка после всех ретраев.
|
|
158
|
+
|
|
159
|
+
## Разработка
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
uv sync --extra dev --extra pandas
|
|
163
|
+
uv run ruff check
|
|
164
|
+
uv run ruff format --check
|
|
165
|
+
uv run pytest -q
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Примеры:
|
|
169
|
+
```bash
|
|
170
|
+
uv run python examples/get_ohlcv.py
|
|
171
|
+
uv run python examples/list_securities.py
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## Лицензия
|
|
175
|
+
|
|
176
|
+
**MIT**
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
moex_iss_client/__init__.py,sha256=Z8F_LWnC5HQROm8i_QHT-7J5S45VfN_1vzcmVHWQ1eM,946
|
|
2
|
+
moex_iss_client/auth.py,sha256=jodXkiFnjbHhuF8DRVyl494njqYEt9zzX4LKrm5qAnM,3438
|
|
3
|
+
moex_iss_client/client.py,sha256=5TtdbMi9cNTJj4yUiHyvAb2aF_PHL9wDs4kYSIZ3S50,10679
|
|
4
|
+
moex_iss_client/endpoints/__init__.py,sha256=0Q8e-6_5bjoGm-2jhzDiyKcAl_s1qJFMIFH6fxPAIEU,127
|
|
5
|
+
moex_iss_client/endpoints/candles.py,sha256=SUthuzVKxrDQQzzSXGdn2enpsMTgAL7q2jOOJXXmUzA,5420
|
|
6
|
+
moex_iss_client/endpoints/securities.py,sha256=jBetwWSZQXMuI_jmnrYA3gIeBcW7-FnvGLgR9nxuiLw,3549
|
|
7
|
+
moex_iss_client/exceptions.py,sha256=nbAj5z-D3tVFvqbJ3leGNUCuUsy9NaqjDp40XY30dRM,1024
|
|
8
|
+
moex_iss_client/models.py,sha256=mbPVvHHrNw1nlqVppoMeigkkm6zBqz3I0rfXXVfVrJE,1757
|
|
9
|
+
moex_iss_client/utils.py,sha256=yUi0oaUr_W8cRfJUwhrpL6qxXgpsl61xJvgnJukgMg4,8178
|
|
10
|
+
moex_iss_client-0.1.0.dist-info/WHEEL,sha256=1dD_GoEqEIxQ7VnrUExgdj_eExY4b4UgfR0iBlGKVac,80
|
|
11
|
+
moex_iss_client-0.1.0.dist-info/METADATA,sha256=_CEwV_D1GhWKZsjMdTkhq6VGO8pAXkdB6PQX0-JtwVA,7564
|
|
12
|
+
moex_iss_client-0.1.0.dist-info/RECORD,,
|