Сегодня мы выпустили okama-macro 0.1.0 — новую Python-библиотеку для загрузки макроэкономических данных. Она объединяет наши прежние библиотеки и внутренние клиенты источников в один пакет с общим API.
В первой версии доступны 16 рядов по семи географиям: США, Китай, Великобритания, Израиль, еврозона, а теперь также Гонконг и Индия. Это месячная инфляция и ключевые ставки центральных банков — данные, которые нужны для оценки реальной доходности, сравнения рынков и других задач портфельного анализа.
Как развивалось направление
История началась с китайских данных. В 2022 году появилась библиотека nbsc, выросшая из форка открытого репозитория data Пола Натсуо Кишимото. Она загружала статистику Национального бюро статистики Китая, прежде всего данные по инфляции.
В том же году мы стали подключать другие официальные источники. Каждый новый источник тогда оформлялся как небольшая самостоятельная библиотека:
| Библиотека | Что загружала |
|---|---|
nbsc |
инфляцию и другие макропоказатели Китая из NBS |
cfets |
китайские ставки LPR из CFETS |
boi |
инфляцию и ставку Банка Израиля |
ons |
британскую инфляцию CPIH из ONS |
ecb |
ключевые ставки ЕЦБ |
boe |
ставку Банка Англии |
Такой подход хорошо работал на старте: каждый источник был изолирован, его можно было исправлять и проверять отдельно.
Позже часть клиентов стала жить непосредственно внутри конвейера okama-API: fred для данных США, а затем клиенты новых географий — censtatd и hkma для Гонконга, mospi, bis и rbi для Индии. В итоге сложилась случайная гибридная архитектура: шесть отдельных репозиториев, шесть внутренних модулей и разные соглашения о форматах данных.
Почему мы всё объединили
У всех клиентов повторялась одна и та же инфраструктура: HTTP-запросы, повторы при временных ошибках, прокси, User-Agent, обработка дат и преобразование ответов в pandas. Исправление общей проблемы приходилось переносить из проекта в проект, а okama-API зависел сразу от нескольких Git-репозиториев.
Для небольшой команды и одного основного потребителя такая раздробленность стала дороже, чем давала преимуществ. Поэтому мы собрали поддерживаемые загрузчики макроданных в один репозиторий, один пакет, один CI и одну зависимость.
При переносе история старых репозиториев была сохранена. Каждый используемый ряд прошёл отдельную проверку против независимых источников и получил контрактные тесты. После миграции прежние репозитории заархивированы и теперь указывают на okama-macro.
Что даёт okama-macro
У библиотеки два уровня:
okama_macro.sources.*— низкоуровневые клиенты официальных источников, возвращающие данные в исходных единицах;okama_macro.get()— единый реестр нормализованных рядов.
Единый API возвращает pandas.Series с одинаковыми правилами: значения в долях единицы, даты по возрастанию, инфляция месяц к месяцу. Ставки обычно содержат только опубликованные наблюдения; для ставки Банка Англии сохранено и явно описано заполнение между датами её изменения.
Новые географии представлены четырьмя рядами:
HKD.INFL— инфляция Гонконга;HK_BR.RATE— базовая ставка HKMA;INR.INFL— инфляция Индии;IND_RBI.RATE— ставка RBI.
Быстрый старт:
pip install okama-macro
import okama_macro
print(okama_macro.list_series())
india_inflation = okama_macro.get("INR.INFL")
hong_kong_rate = okama_macro.get("HK_BR.RATE")
Первая версия поддерживает Python 3.11–3.14 и pandas 2.x–3.x. Библиотека уже используется в рабочем конвейере данных okama.
Спасибо участникам
Вклад в это направление в разные годы внесли:
- Сергей Кикевич (
chilango74) — архитектура источников, интеграция с okama, сопровождение и объединение библиотек; - Фёдор Жулитов (
fzhulitov) — значительная часть первых клиентов CFETS, Банка Израиля, ONS, ЕЦБ и Банка Англии; - AAARRRT — обновления и исправления клиентов NBS Китая и Банка Израиля;
- Пол Натсуо Кишимото (
khaeru) — автор upstream-репозиторияdata, от которого началась история форкаnbsc.
Спасибо всем, кто писал код, проверял данные, сообщал о сломавшихся источниках и помогал этим библиотекам развиваться.
Если вы работаете с макроэкономическими данными и вам не хватает страны или конкретного ряда, напишите об этом в комментариях или создайте issue на GitHub.