fedstat 0.1.0__py3-none-any.whl

fedstat/__init__.py

@@ -0,0 +1,43 @@
+"""fedstat — неофициальный Python-клиент к fedstat.ru (ЕМИСС).
+
+Быстрый старт:
+    import fedstat
+    fedstat.list_filters("31452")          # какие фильтры доступны
+    f = fedstat.filter_template("31452")   # шаблон со всеми полями
+    f["Год"] = "2023"
+    df = fedstat.load("31452", filters=f)  # нормализованный DataFrame
+"""
+
+from .api import filter_template, get_data_ids, list_filters, load
+from .client import FedstatClient
+from .discovery import DataIds, parse_indicator_page
+from .errors import (
+    CSRFTokenError,
+    DownloadError,
+    FedstatError,
+    FilterError,
+    IndicatorPageError,
+    SDMXParseError,
+)
+from .reshape import to_wide
+from .sdmx import sdmx_to_dataframe
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "load",
+    "list_filters",
+    "filter_template",
+    "get_data_ids",
+    "to_wide",
+    "FedstatClient",
+    "DataIds",
+    "parse_indicator_page",
+    "sdmx_to_dataframe",
+    "FedstatError",
+    "IndicatorPageError",
+    "CSRFTokenError",
+    "FilterError",
+    "DownloadError",
+    "SDMXParseError",
+]

fedstat/api.py

@@ -0,0 +1,79 @@
+"""Высокоуровневый API: get_data_ids, list_filters, filter_template, load."""
+
+import time
+
+from .client import FedstatClient
+from .discovery import build_download_body, parse_indicator_page
+from .errors import CSRFTokenError, DownloadError
+from .filters import select_rows
+from .sdmx import sdmx_to_dataframe
+
+
+def _client(client):
+    return client if client is not None else FedstatClient()
+
+
+def get_data_ids(indicator_id, *, client=None):
+    """Скачивает и разбирает страницу индикатора -> DataIds (поля, значения, CSRF)."""
+    cl = _client(client)
+    html = cl.get_indicator_html(str(indicator_id))
+    return parse_indicator_page(html, str(indicator_id))
+
+
+def list_filters(indicator_id, *, client=None):
+    """DataFrame со всеми доступными полями-фильтрами и их значениями."""
+    return get_data_ids(indicator_id, client=client).to_frame()
+
+
+def filter_template(indicator_id, *, client=None):
+    """Готовый словарь {field_title: '*'} — заполни нужные поля и передай в load()."""
+    return get_data_ids(indicator_id, client=client).template()
+
+
+def load(indicator_id, filters=None, *, client=None, retry_max_times=3,
+         retry_pause=3.0, try_numeric=True, with_codes=False, drop_empty=False):
+    """Скачивает подмножество данных индикатора -> нормализованный DataFrame.
+
+    filters: dict(field_title -> value | [values] | '*'); пропущенное поле = все значения.
+    Повторяет весь цикл (свежий CSRF + новая попытка) при отклонении POST,
+    с нарастающей паузой между попытками (fedstat часто отвечает 503 при перегрузке).
+
+    retry_max_times: сколько раз пытаться скачать.
+    retry_pause: базовая пауза (сек) между попытками; растёт как retry_pause * 2**n.
+    """
+    indicator_id = str(indicator_id)
+    cl = _client(client)
+
+    attempts = max(1, retry_max_times)
+    last_exc = None
+    for attempt in range(attempts):
+        data_ids = get_data_ids(indicator_id, client=cl)
+        if not data_ids.csrf_token or not data_ids.csrf_token_name:
+            raise CSRFTokenError(
+                f"На странице индикатора {indicator_id} не найден CSRF-токен."
+            )
+        selected = select_rows(data_ids, filters)
+        body = build_download_body(data_ids, selected)
+        referer = f"{getattr(cl, 'base_url', '')}/indicator/{indicator_id}"
+        try:
+            raw = cl.download(body, data_format="sdmx", referer=referer)
+        except DownloadError as exc:
+            last_exc = exc  # CSRF одноразовый -> следующая попытка перезаберёт токен
+            if attempt < attempts - 1:
+                # чистая сессия (новые cookies + новый UA) — аналог Cmd+Shift+R
+                if hasattr(cl, "reset_session"):
+                    cl.reset_session()
+                time.sleep(retry_pause * (2 ** attempt))  # 3, 6, 12 ... сек
+            continue
+        return sdmx_to_dataframe(
+            raw, try_numeric=try_numeric, with_codes=with_codes, drop_empty=drop_empty
+        )
+
+    raise DownloadError(
+        f"Не удалось скачать данные индикатора {indicator_id} за {attempts} попыток. "
+        f"Последняя ошибка: {last_exc} "
+        "Если это 503 — временная перегрузка fedstat, повторите позже или увеличьте "
+        "retry_max_times/retry_pause. Если стабильно 302 — почти наверняка выбранная "
+        "комбинация фильтров пустая: проверьте значения через list_filters() "
+        "(частый случай — похожие варианты значения одного поля)."
+    )

fedstat/client.py

@@ -0,0 +1,179 @@
+"""HTTP-клиент для fedstat.ru: сессия, заголовки, ретраи GET, POST на скачивание."""
+
+import random
+import time
+
+import requests
+
+from .errors import DownloadError
+
+BASE_URL = "https://www.fedstat.ru"
+
+# Пул реалистичных User-Agent (разные браузеры/ОС) — ротируется между сессиями,
+# чтобы снизить шанс антибота/кэширования на стороне fedstat.
+USER_AGENTS = [
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15",
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:124.0) Gecko/20100101 Firefox/124.0",
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:124.0) Gecko/20100101 Firefox/124.0",
+    "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:123.0) Gecko/20100101 Firefox/123.0",
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36 Edg/124.0.0.0",
+    "Mozilla/5.0 (Windows NT 11.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (X11; Fedora; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+]
+
+
+def _build_headers(user_agent):
+    """Набор «браузерных» заголовков (снижает шанс блокировки/кэша)."""
+    return {
+        "User-Agent": user_agent,
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+        "Accept-Language": "ru-RU,ru;q=0.9,en-US;q=0.8,en;q=0.7",
+        "Accept-Encoding": "gzip, deflate, br",
+        "Connection": "keep-alive",
+        "Upgrade-Insecure-Requests": "1",
+        "Sec-Fetch-Dest": "document",
+        "Sec-Fetch-Mode": "navigate",
+        "Sec-Fetch-Site": "none",
+        "Sec-Fetch-User": "?1",
+        # аналог Cmd+Shift+R — не отдавать кэшированную страницу/токен
+        "Cache-Control": "no-cache",
+        "Pragma": "no-cache",
+    }
+
+
+# для обратной совместимости (использовалось в ноутбуках снятия фикстур)
+DEFAULT_HEADERS = _build_headers(USER_AGENTS[0])
+
+
+class FedstatClient:
+    """Тонкая обёртка над requests.Session с ретраями (сайт часто лагает).
+
+    rotate_user_agent: на каждую свежую сессию выбирать случайный User-Agent из пула.
+    reset_session(): начать чистую сессию (новые cookies + новый UA) — аналог
+    жёсткого обновления страницы (Cmd+Shift+R), помогает при 302/ошибке CSRF.
+    """
+
+    def __init__(self, base_url=BASE_URL, timeout=180.0, retry_max_times=3,
+                 verify=True, session=None, user_agent=None, rotate_user_agent=True,
+                 warm_up=True):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.retry_max_times = retry_max_times
+        self.verify = verify
+        self.rotate_user_agent = rotate_user_agent
+        self.warm_up = warm_up
+        self._warmed = False
+        self._user_agent = user_agent or random.choice(USER_AGENTS)
+        self.session = session or requests.Session()
+        self.session.headers.update(_build_headers(self._user_agent))
+
+    def reset_session(self):
+        """Чистая сессия: новые cookies и (при rotate_user_agent) новый User-Agent."""
+        if self.rotate_user_agent:
+            self._user_agent = random.choice(USER_AGENTS)
+        self.session = requests.Session()
+        self.session.headers.update(_build_headers(self._user_agent))
+        self._warmed = False
+        return self
+
+    def _warm_up(self):
+        """Зайти на главную, чтобы получить стартовые cookies сессии (как браузер).
+
+        Best-effort: ошибки прогрева не критичны и игнорируются.
+        """
+        if self._warmed or not self.warm_up:
+            return
+        try:
+            self.session.get(self.base_url + "/", timeout=self.timeout,
+                             verify=self.verify)
+        except requests.RequestException:
+            pass
+        self._warmed = True
+
+    def get_indicator_html(self, indicator_id):
+        """GET страницы индикатора с ретраями и растущей паузой. Возвращает text."""
+        self._warm_up()
+        url = f"{self.base_url}/indicator/{indicator_id}"
+        last_exc = None
+        for attempt in range(self.retry_max_times):
+            try:
+                resp = self.session.get(url, timeout=self.timeout, verify=self.verify)
+            except requests.RequestException as exc:
+                last_exc = exc
+            else:
+                if resp.status_code == 200:
+                    return resp.text
+                if resp.status_code == 403:
+                    raise DownloadError(
+                        f"fedstat вернул 403 (Forbidden) для {indicator_id}: "
+                        "запрос заблокирован антиботом. Попробуйте задать заголовки/UA."
+                    )
+                if resp.status_code != 503:  # 503 = перегрузка, имеет смысл повторить
+                    raise DownloadError(
+                        f"fedstat вернул HTTP {resp.status_code} для {indicator_id}."
+                    )
+                last_exc = DownloadError(f"HTTP {resp.status_code}")
+            time.sleep(2 ** attempt)  # 1, 2, 4 ... сек
+        raise DownloadError(
+            f"Не удалось получить страницу индикатора {indicator_id}: {last_exc}"
+        )
+
+    def download(self, body, data_format="sdmx", referer=None):
+        """POST на downloadData.do. Возвращает сырые байты (SDMX/Excel).
+
+        Без ретраев: CSRF-токен одноразовый. Повтор — на уровне api.load
+        (перезабор токена + новая попытка). referer — URL страницы индикатора,
+        с которой «пришёл» запрос (fedstat может проверять Referer).
+        """
+        url = f"{self.base_url}/indicator/downloadData.do?format={data_format}"
+        headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Referer": referer or f"{self.base_url}/indicator/",
+            "Origin": self.base_url,
+            "Sec-Fetch-Dest": "document",
+            "Sec-Fetch-Mode": "navigate",
+            "Sec-Fetch-Site": "same-origin",
+            "Sec-Fetch-User": "?1",
+        }
+        try:
+            resp = self.session.post(
+                url, data=body.encode("utf-8"), headers=headers,
+                timeout=self.timeout, verify=self.verify, allow_redirects=False,
+            )
+        except requests.RequestException as exc:
+            raise DownloadError(f"POST на скачивание не удался: {exc}") from exc
+
+        status = resp.status_code
+        ctype = resp.headers.get("content-type", "")
+
+        if status == 302:
+            raise DownloadError(
+                "fedstat отклонил запрос (302). Чаще всего это значит, что выбранная "
+                "комбинация фильтров НЕ содержит данных — проверьте значения фильтров. "
+                "Типичный подвох: похожие значения одного поля (например для ОКАТО за 2023 "
+                "данные лежат под 'Российская Федерация без учёта новых субъектов', "
+                "а не под 'Российская Федерация'). Реже причина — устаревший CSRF-токен."
+            )
+        if status == 403:
+            raise DownloadError("fedstat вернул 403 (Forbidden): заблокировано антиботом.")
+        if status == 503:
+            raise DownloadError("fedstat вернул 503 (Service Unavailable): сервер перегружен.")
+        if status != 200:
+            raise DownloadError(f"fedstat вернул HTTP {status}.")
+
+        if not any(t in ctype for t in ("xml", "excel", "octet-stream")):
+            preview = resp.content[:400].decode("utf-8", "replace")
+            if "csrf" in preview.lower():
+                raise DownloadError(
+                    "Проверка CSRF-токена не пройдена (токен устарел/использован). "
+                    "Повторите запрос заново."
+                )
+            raise DownloadError(
+                f"Ожидались данные, а пришёл content-type={ctype!r}. Начало ответа: {preview[:200]}"
+            )
+        return resp.content

fedstat/discovery.py

@@ -0,0 +1,183 @@
+"""Discovery: разбор страницы индикатора в таблицу фильтров (data_ids) + CSRF.
+
+Здесь только парсинг (без сети), поэтому легко тестируется на сохранённом HTML.
+Сетевую часть выполняет client.FedstatClient, а связывает всё api.get_data_ids.
+"""
+
+from dataclasses import dataclass, field
+from urllib.parse import quote
+
+from lxml import html as lxml_html
+
+from .errors import IndicatorPageError
+from .jsparse import parse_js1, parse_js2
+from .utils import normalize, xpath_literal
+
+# left_columns/top_columns/groups/filterObjectIds -> тип расположения поля
+_OBJECT_RENAME = {
+    "left_columns": "lineObjectIds",
+    "top_columns": "columnObjectIds",
+    "groups": "lineObjectIds",
+    "filterObjectIds": "lineObjectIds",
+}
+
+
+@dataclass
+class DataIds:
+    """Результат discovery по одному индикатору.
+
+    rows: список dict(filter_field_id, filter_field_title, filter_value_id,
+                      filter_value_title, filter_field_object_ids)
+    object_map: field_id -> 'lineObjectIds'|'columnObjectIds'|'filterObjectIds'
+    """
+
+    indicator_id: str
+    indicator_title: str
+    rows: list = field(default_factory=list)
+    object_map: dict = field(default_factory=dict)
+    csrf_token_name: str = None
+    csrf_token: str = None
+
+    # --- удобные представления ---------------------------------------------
+    def fields(self):
+        """OrderedDict: filter_field_title -> {field_id, object, values: [titles]}."""
+        from collections import OrderedDict
+
+        out = OrderedDict()
+        for r in self.rows:
+            info = out.setdefault(
+                r["filter_field_title"],
+                {"field_id": r["filter_field_id"],
+                 "object": r["filter_field_object_ids"], "values": []},
+            )
+            info["values"].append(r["filter_value_title"])
+        return out
+
+    def to_frame(self):
+        """DataFrame со всеми полями и значениями (то, что видит пользователь)."""
+        import pandas as pd
+
+        return pd.DataFrame(self.rows)[
+            ["filter_field_title", "filter_value_title",
+             "filter_field_id", "filter_value_id", "filter_field_object_ids"]
+        ]
+
+    def template(self):
+        """Готовый словарь фильтров {field_title: '*'} для правки пользователем."""
+        return {title: "*" for title in self.fields()}
+
+
+def _find_data_script(doc):
+    for node in doc.xpath(".//script"):
+        txt = node.text_content()
+        if "filters: {" in txt and "left_columns: [" in txt:
+            return txt
+    scripts = doc.xpath(".//script")
+    if len(scripts) >= 12:  # историческое поведение R (12-й скрипт)
+        return scripts[11].text_content()
+    return None
+
+
+def _extract_csrf(doc):
+    holder = doc.xpath("//div[@id='downloadTokenHolder']")
+    if not holder:
+        return None, None
+    name = holder[0].xpath(".//input[@name='struts.token.name']/@value")
+    if not name:
+        return None, None
+    token_name = name[0]
+    token = holder[0].xpath(f".//input[@name={xpath_literal(token_name)}]/@value")
+    return token_name, (token[0] if token else None)
+
+
+def _indicator_title_from_html(doc, fallback):
+    for xp in (".//h1", ".//title"):
+        node = doc.xpath(xp)
+        if node and normalize(node[0].text_content()):
+            return node[0].text_content().strip()
+    return fallback
+
+
+def parse_indicator_page(html_text, indicator_id):
+    """HTML страницы индикатора -> DataIds. Без сети."""
+    doc = lxml_html.fromstring(html_text)
+
+    script = _find_data_script(doc)
+    if script is None:
+        raise IndicatorPageError(
+            "Не найден <script> с filters/left_columns на странице индикатора "
+            f"{indicator_id} (структура страницы могла измениться)"
+        )
+    lines = script.split("\n")
+    filters = parse_js1(lines)
+    objects = parse_js2(lines)
+
+    object_map = {}
+    for key, val in objects.items():
+        obj_type = _OBJECT_RENAME.get(key, "lineObjectIds")
+        ids = val if isinstance(val, list) else [val]
+        for fid in ids:
+            object_map[str(fid)] = obj_type
+    object_map.setdefault("0", "filterObjectIds")  # сам индикатор — скрытый фильтр
+
+    rows = []
+    indicator_title = None
+    for field_id, fld in filters.items():
+        field_id = str(field_id)
+        title = fld.get("title", "")
+        values = fld.get("values", {}) or {}
+        obj_type = object_map.get(field_id, "lineObjectIds")
+        for value_id, value in values.items():
+            vtitle = value.get("title", "") if isinstance(value, dict) else str(value)
+            rows.append({
+                "filter_field_id": field_id,
+                "filter_field_title": title,
+                "filter_value_id": str(value_id),
+                "filter_value_title": vtitle.replace("&quot;", '"'),
+                "filter_field_object_ids": obj_type,
+            })
+        if field_id == "0" and len(values) == 1:
+            (_, val), = values.items()
+            indicator_title = val.get("title") if isinstance(val, dict) else str(val)
+
+    token_name, token = _extract_csrf(doc)
+    if indicator_title is None:
+        indicator_title = _indicator_title_from_html(doc, str(indicator_id))
+
+    return DataIds(
+        indicator_id=str(indicator_id),
+        indicator_title=indicator_title,
+        rows=rows,
+        object_map=object_map,
+        csrf_token_name=token_name,
+        csrf_token=token,
+    )
+
+
+def build_download_body(data_ids, selected_rows):
+    """Собирает URL-encoded тело POST-запроса на downloadData.do (как в R)."""
+    parts = [
+        ("title", data_ids.indicator_title),
+        ("struts.token.name", data_ids.csrf_token_name),
+        (data_ids.csrf_token_name, data_ids.csrf_token),
+        ("id", data_ids.indicator_id),
+    ]
+
+    field_types = {}
+    for r in selected_rows:
+        field_types.setdefault(r["filter_field_id"], r["filter_field_object_ids"])
+
+    for fid, t in field_types.items():
+        if t == "lineObjectIds":
+            parts.append(("lineObjectIds", fid))
+        elif t == "columnObjectIds":
+            parts.append(("columnObjectIds", fid))
+    for r in selected_rows:
+        parts.append(("selectedFilterIds", f'{r["filter_field_id"]}_{r["filter_value_id"]}'))
+    for fid, t in field_types.items():
+        if t == "filterObjectIds":
+            parts.append(("filterObjectIds", fid))
+    if "0" not in field_types:
+        parts.append(("filterObjectIds", "0"))
+
+    return "&".join(f"{k}={quote(str(v), safe='')}" for k, v in parts)

fedstat/errors.py

@@ -0,0 +1,25 @@
+"""Типизированные исключения библиотеки fedstat."""
+
+
+class FedstatError(Exception):
+    """Базовое исключение библиотеки."""
+
+
+class IndicatorPageError(FedstatError):
+    """Не удалось разобрать страницу индикатора (структура JS/HTML изменилась)."""
+
+
+class CSRFTokenError(FedstatError):
+    """Не найден CSRF-токен на странице индикатора."""
+
+
+class FilterError(FedstatError):
+    """Неверное имя поля-фильтра или значение."""
+
+
+class DownloadError(FedstatError):
+    """Сервер отклонил запрос данных (302 / 403 / 503 / CSRF / нет данных)."""
+
+
+class SDMXParseError(FedstatError):
+    """Не удалось разобрать SDMX-ответ (например, вместо данных пришёл HTML)."""

fedstat/filters.py

@@ -0,0 +1,87 @@
+"""Отбор строк data_ids по человекочитаемым фильтрам.
+
+Правила:
+  * ключ фильтра — заголовок поля (как на fedstat.ru); сравнение нормализованное
+    (регистр и лишние пробелы игнорируются);
+  * значение "*" или пропущенное поле = взять все значения этого поля;
+  * значение может быть строкой или списком строк;
+  * неизвестное поле или значение -> FilterError с подсказкой похожего варианта.
+"""
+
+import difflib
+
+from .errors import FilterError
+from .utils import normalize
+
+
+def _suggest(name, candidates):
+    match = difflib.get_close_matches(
+        normalize(name), [normalize(c) for c in candidates], n=1, cutoff=0.5
+    )
+    if not match:
+        return ""
+    real = candidates[[normalize(c) for c in candidates].index(match[0])]
+    return f" Возможно, вы имели в виду {real!r}?"
+
+
+def _match_values(field_title, wanted, available_rows):
+    """Возвращает подмножество строк одного поля, подходящих под `wanted`."""
+    if wanted == "*" or wanted is None:
+        return available_rows
+
+    wanted_list = wanted if isinstance(wanted, (list, tuple, set)) else [wanted]
+    titles = [r["filter_value_title"] for r in available_rows]
+
+    selected = []
+    for w in wanted_list:
+        wn = normalize(w)
+        exact = [r for r in available_rows if normalize(r["filter_value_title"]) == wn]
+        if exact:
+            selected.extend(exact)
+            continue
+        substr = [r for r in available_rows if wn in normalize(r["filter_value_title"])]
+        if substr:
+            selected.extend(substr)
+            continue
+        raise FilterError(
+            f"Значение {w!r} не найдено в поле {field_title!r}."
+            + _suggest(w, titles)
+        )
+    # убрать дубли, сохранив порядок
+    seen, out = set(), []
+    for r in selected:
+        k = (r["filter_field_id"], r["filter_value_id"])
+        if k not in seen:
+            seen.add(k)
+            out.append(r)
+    return out
+
+
+def select_rows(data_ids, filters=None):
+    """DataIds + dict(field_title -> value|list|'*') -> список выбранных строк.
+
+    Поля, не упомянутые в filters, берутся целиком (все значения).
+    """
+    filters = filters or {}
+    fields = data_ids.fields()
+    field_titles = list(fields)
+    norm_to_title = {normalize(t): t for t in field_titles}
+
+    # проверка ключей на опечатки
+    for key in filters:
+        if normalize(key) not in norm_to_title:
+            raise FilterError(
+                f"Поля {key!r} нет у индикатора {data_ids.indicator_id}."
+                + _suggest(key, field_titles)
+                + f" Доступные поля: {field_titles}"
+            )
+
+    # нормализованный доступ к запрошенным значениям
+    requested = {normalize(k): v for k, v in filters.items()}
+
+    selected = []
+    for title in field_titles:
+        rows_of_field = [r for r in data_ids.rows if r["filter_field_title"] == title]
+        wanted = requested.get(normalize(title), "*")  # пропущено -> все значения
+        selected.extend(_match_values(title, wanted, rows_of_field))
+    return selected

fedstat/jsparse.py

@@ -0,0 +1,60 @@
+"""Разбор встроенного в страницу индикатора JavaScript.
+
+Порт parse_js1/parse_js2 из R-пакета fedstatAPIr. На странице индикатора
+fedstat.ru нужные данные (поля-фильтры, их значения и расположение) лежат не в
+JSON, а в исходнике JS. Здесь тот же трюк: «слова» вне уже закавыченных участков
+обрамляются кавычками, ' меняется на ", результат оборачивается в {...} и
+парсится как JSON.
+"""
+
+import json
+import re
+
+from .errors import IndicatorPageError
+
+# Вставляет ' на границе слова, только если это НЕ внутри одинарных кавычек
+# (в остатке строки чётное число кавычек). Эквивалент R-регекса из parse_js*.
+_WORD_QUOTE = re.compile(r"\b(?=([^']*'[^']*')*[^']*$)")
+# JS допускает хвостовые запятые перед } или ], JSON — нет.
+_TRAILING_COMMA = re.compile(r",\s*([}\]])")
+
+
+def js_lines_to_json(lines):
+    """Список строк JS -> объект Python (dict), как в parse_js1/parse_js2."""
+    quoted = [_WORD_QUOTE.sub("'", ln) for ln in lines]
+    text = "\n".join(quoted).replace("'", '"')
+    text = "{" + text + "}"
+    text = _TRAILING_COMMA.sub(r"\1", text)
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:  # pragma: no cover - диагностика
+        raise IndicatorPageError(
+            f"Не удалось преобразовать JS в JSON: {exc}"
+        ) from exc
+
+
+def _slice(lines, start_pat, end_pat, start_off, end_off):
+    start = end = None
+    for i, ln in enumerate(lines):
+        if start is None and re.search(start_pat, ln):
+            start = i
+        elif start is not None and re.search(end_pat, ln):
+            end = i
+            break
+    if start is None or end is None:
+        raise IndicatorPageError(
+            f"Не найдены границы блока в JS: {start_pat!r} .. {end_pat!r}"
+        )
+    return lines[start + start_off : end + end_off + 1]
+
+
+def parse_js1(script_lines):
+    """filters: { field_id: {title, values: {value_id: {title}}} }."""
+    block = _slice(script_lines, r"filters: \{", r"left_columns: \[", 1, -2)
+    return js_lines_to_json(block)
+
+
+def parse_js2(script_lines):
+    """left_columns/top_columns/groups/filterObjectIds -> списки field_id по типам."""
+    block = _slice(script_lines, r"left_columns: \[", r"grid\.init\(\);", 0, -2)
+    return js_lines_to_json(block)

fedstat/reshape.py

@@ -0,0 +1,37 @@
+"""Преобразование нормализованного ("длинного") DataFrame в "широкий" (pivot)."""
+
+from .errors import FedstatError
+
+
+def to_wide(df, columns="PERIOD", values="VALUE", index=None, aggfunc="mean"):
+    """Разносит одно измерение по столбцам (обёртка над pandas.pivot_table).
+
+    df:      результат fedstat.load(...) (длинный вид).
+    columns: какое поле развернуть в столбцы (напр. "PERIOD" или "TIME").
+    values:  столбец со значениями (по умолчанию "VALUE").
+    index:   что оставить в строках. По умолчанию — все прочие столбцы,
+             кроме `columns` и `values` (т.е. полный ключ наблюдения).
+    aggfunc: как агрегировать дубли (по умолчанию среднее).
+
+    Возвращает DataFrame с обычным (сброшенным) индексом.
+    """
+    import pandas as pd
+
+    for col in (columns, values):
+        if col not in df.columns:
+            raise FedstatError(
+                f"Столбца {col!r} нет в данных. Доступные: {list(df.columns)}"
+            )
+
+    if index is None:
+        index = [c for c in df.columns if c not in (columns, values)]
+    if not index:
+        raise FedstatError(
+            "Не осталось столбцов для строк (index). Укажите index явно."
+        )
+
+    wide = pd.pivot_table(df, index=index, columns=columns, values=values,
+                          aggfunc=aggfunc)
+    wide = wide.reset_index()
+    wide.columns.name = None
+    return wide

fedstat/sdmx.py

@@ -0,0 +1,111 @@
+"""Разбор SDMX-ML (GenericData v1.0) в нормализованный ("длинный") DataFrame.
+
+Структура ответа fedstat:
+  <CodeLists>                     -- справочники: код -> человекочитаемое название
+    <structure:CodeList id=...><structure:Name/>
+      <structure:Code value=...><structure:Description/></structure:Code>
+  <DataSet>
+    <generic:Series>
+      <generic:SeriesKey>   <generic:Value concept=.. value=../>   -- измерения
+      <generic:Attributes>  <generic:Value concept=.. value=../>   -- напр. EI, PERIOD
+      <generic:Obs>  <generic:Time/>  <generic:ObsValue value=../>
+
+Итог: одна строка = одно наблюдение. Столбцы измерений расшифрованы по CodeLists,
+ObsValue приведён к числу (десятичная запятая -> точка).
+"""
+
+from lxml import etree
+
+from .errors import SDMXParseError
+
+
+def _lname(tag):
+    return tag.rsplit("}", 1)[-1]
+
+
+def _iter_descendants(el, name):
+    return (c for c in el.iter() if _lname(c.tag) == name)
+
+
+def sdmx_to_dataframe(source, *, try_numeric=True, with_codes=False, drop_empty=False):
+    """Разбирает SDMX в pandas.DataFrame.
+
+    source: путь к файлу, bytes или file-like.
+    try_numeric: привести VALUE к числу (запятая -> точка).
+    with_codes: добавить исходные коды измерений колонками '<поле>_code'.
+    drop_empty: выбросить строки без значения.
+    """
+    import pandas as pd
+
+    if isinstance(source, (bytes, bytearray)):
+        head = bytes(source[:512]).lstrip().lower()
+        if head.startswith(b"<!doctype html") or head.startswith(b"<html"):
+            raise SDMXParseError(
+                "Вместо SDMX получен HTML (вероятно, страница ошибки или истёкший CSRF-токен)."
+            )
+        import io
+
+        source = io.BytesIO(source)
+
+    codelists = {}
+    rows = []
+    try:
+        for _, el in etree.iterparse(source, events=("end",), recover=True):
+            ln = _lname(el.tag)
+            if ln == "CodeList":
+                cid = el.get("id")
+                name = next((c.text for c in el if _lname(c.tag) == "Name"), cid)
+                codes = {}
+                for code in el:
+                    if _lname(code.tag) == "Code":
+                        desc = next(
+                            (d.text or "" for d in code if _lname(d.tag) == "Description"),
+                            "",
+                        )
+                        codes[code.get("value")] = desc
+                codelists[cid] = {"name": name, "codes": codes}
+                el.clear()
+            elif ln == "Series":
+                key, attrs = {}, {}
+                for v in _iter_descendants(el, "Value"):
+                    parent = _lname(v.getparent().tag)
+                    (key if parent == "SeriesKey" else attrs)[v.get("concept")] = v.get("value")
+                for obs in _iter_descendants(el, "Obs"):
+                    tv = next((c.text for c in obs if _lname(c.tag) == "Time"), None)
+                    ov = next(
+                        (c.get("value") for c in obs if _lname(c.tag) == "ObsValue"), None
+                    )
+                    row = dict(key)
+                    row.update(attrs)
+                    row["TIME"] = tv
+                    row["VALUE"] = ov
+                    rows.append(row)
+                el.clear()
+    except etree.XMLSyntaxError as exc:
+        raise SDMXParseError(f"Ошибка разбора SDMX-XML: {exc}") from exc
+
+    if not rows:
+        raise SDMXParseError(
+            "В SDMX не найдено наблюдений (пустой ответ или неверные фильтры)."
+        )
+
+    df = pd.DataFrame(rows)
+
+    # расшифровка кодов измерений в подписи
+    names = {cid: (cl["name"] or cid) for cid, cl in codelists.items()}
+    for cid, cl in codelists.items():
+        if cid in df.columns:
+            if with_codes:
+                df[f"{names[cid]}_code"] = df[cid]
+            df[cid] = df[cid].map(cl["codes"]).fillna(df[cid])
+    df = df.rename(columns=names)
+
+    if try_numeric:
+        df["VALUE"] = pd.to_numeric(
+            df["VALUE"].astype("string").str.replace(",", ".", regex=False),
+            errors="coerce",
+        )
+    if drop_empty:
+        df = df[df["VALUE"].notna()].reset_index(drop=True)
+
+    return df

fedstat/utils.py

@@ -0,0 +1,18 @@
+"""Мелкие вспомогательные функции."""
+
+import re
+
+
+def normalize(s):
+    """Нормализация заголовков: убрать лишние пробелы, привести к нижнему регистру."""
+    return re.sub(r"\s+", " ", (s or "")).strip().lower()
+
+
+def xpath_literal(s):
+    """Безопасный строковый литерал для XPath (учёт кавычек в значении)."""
+    if '"' not in s:
+        return f'"{s}"'
+    if "'" not in s:
+        return f"'{s}'"
+    parts = s.split('"')
+    return "concat(" + ", '\"', ".join(f'"{p}"' for p in parts) + ")"

fedstat-0.1.0.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: fedstat
+Version: 0.1.0
+Summary: Неофициальный Python-клиент к fedstat.ru (ЕМИСС): показатели с фильтрами в pandas.DataFrame
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fedstat,emiss,rosstat,sdmx,statistics,open-data,pandas
+Author: Timofei Ryadovoi
+Author-email: timtrue18@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: Russian
+Requires-Dist: lxml (>=5.0)
+Requires-Dist: openpyxl (>=3.1.5,<4.0.0)
+Requires-Dist: pandas (>=3.0.6,<4.0.0)
+Requires-Dist: requests (>=2.31)
+Project-URL: Homepage, https://github.com/timryadovouu/fedstat
+Project-URL: Issues, https://github.com/timryadovouu/fedstat/issues
+Project-URL: Repository, https://github.com/timryadovouu/fedstat
+Description-Content-Type: text/markdown
+
+# fedstat
+
+![tests](https://github.com/timryadovouu/fedstat/actions/workflows/tests.yml/badge.svg)
+
+Неофициальный Python-клиент к [fedstat.ru](https://www.fedstat.ru) (ЕМИСС) —
+порт идей R-пакета [`fedstatAPIr`](https://github.com/DenchPokepon/fedstatAPIr).
+Скачивает данные показателей с фильтрами и отдаёт нормализованный
+`pandas.DataFrame`.
+
+Статус: **MVP** — `list_filters` / `filter_template` / `load` (формат SDMX).
+Дальше планируется догнать полный функционал R-пакета (Excel, режим словаря,
+расширенные ретраи и т.д.).
+
+## Установка
+
+**Для использования** (после публикации на PyPI — планируется):
+
+```bash
+pip install fedstat
+```
+
+**Пока проект на GitHub** — ставится напрямую из репозитория, без ручного клонирования:
+
+```bash
+pip install git+ssh://git@github.com/timryadovouu/fedstat.git
+```
+
+**Для разработки** (клон + окружение poetry):
+
+```bash
+git clone git@github.com:timryadovouu/fedstat.git
+cd fedstat
+poetry install
+```
+
+`poetry install` ставит зависимости в локальное окружение проекта — эта команда
+предполагает, что исходники уже склонированы (вариант «для разработки»).
+
+## Пример
+
+Готовый ноутбук: [`notebooks/example.ipynb`](notebooks/example.ipynb).
+
+## Быстрый старт
+
+```python
+import fedstat
+
+# 1. Какие фильтры есть у показателя (id — из URL вида /indicator/31452)
+fedstat.list_filters("31452")            # DataFrame: поле -> допустимые значения
+
+# 2. Шаблон со всеми полями (значения по умолчанию "*" = все)
+f = fedstat.filter_template("31452")
+f["Год"] = "2023"
+f["Рынок жилья"] = "Первичный рынок жилья"
+
+# 3. Скачать нормализованный ("длинный") DataFrame
+df = fedstat.load("31452", filters=f)
+df.to_csv("cena.csv", index=False)
+df.to_excel("cena.xlsx", index=False)
+
+# 4. При желании — "широкий" вид (одно измерение по столбцам)
+wide = fedstat.to_wide(df, columns="PERIOD", values="VALUE", index="TIME")
+```
+
+Правила фильтров:
+- ключ — заголовок поля, как на сайте (регистр и лишние пробелы игнорируются);
+- значение — строка, список строк или `"*"` (все значения);
+- пропущенное поле = все значения;
+- неверное имя поля/значения -> `FilterError` с подсказкой похожего варианта.
+
+## Формат вывода
+
+Одна строка = одно наблюдение. Столбцы измерений расшифрованы из справочников
+(codelists) в человекочитаемые названия, `VALUE` приведён к числу (десятичная
+запятая -> точка). Опции `load(...)`:
+- `with_codes=True` — добавить исходные коды измерений (`<поле>_code`);
+- `drop_empty=True` — выбросить строки без значения;
+- `try_numeric=False` — оставить `VALUE` строкой.
+
+## Модули
+
+| модуль | назначение |
+|---|---|
+| `fedstat.client` | HTTP-сессия, заголовки, ретраи GET, POST на скачивание |
+| `fedstat.discovery` | разбор страницы индикатора -> `DataIds` (поля, значения, CSRF) |
+| `fedstat.jsparse` | разбор встроенного JS (порт `parse_js1/parse_js2`) |
+| `fedstat.filters` | отбор строк по фильтрам, шаблон, подсказки |
+| `fedstat.sdmx` | SDMX -> нормализованный `DataFrame` |
+| `fedstat.api` | высокоуровневые `load` / `list_filters` / `filter_template` |
+
+## Разработка и тесты
+
+Тесты гоняются офлайн на сохранённых фикстурах (`fixtures/`), сеть не нужна:
+
+```bash
+poetry run pytest -q
+```
+
+Снятие новых фикстур с живого сайта — ноутбук `notebooks/capture_fixtures.ipynb`
+(нужен доступ к fedstat.ru).
+

fedstat-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+fedstat/__init__.py,sha256=Sp1SlsxhhVBACxrFgxv2Lj434wWuJRgyT7y10gDrp9Y,1136
+fedstat/api.py,sha256=Gve_RmdsM6XUOZBkwvHnabzPgtSNdyqMUMjIzGyM4KE,4151
+fedstat/client.py,sha256=q9J_ZKN5z0pwetK-kLAGgZ1a5GwzXjD3-7NYm1zq0HU,9755
+fedstat/discovery.py,sha256=ZtFOkGSOCpLEcvh3EnzlQFsMd_Z85T9EdsiKNdrnClI,6916
+fedstat/errors.py,sha256=OshJyxir1kloXBjduq85UxOVfPCXpP3gOEVWbRveXsA,930
+fedstat/filters.py,sha256=NHn7eK4gbJkIR3702IG49IXkCaq7kcU1xnKj8Vhwjwg,3582
+fedstat/jsparse.py,sha256=OusweGNGbtJre4OJqn8egW8lAXtabR-WKILssTrPJCc,2713
+fedstat/reshape.py,sha256=zYUMUH90U3VBXdE9lMhBuYImBu4N8vEmScD02wz_HgU,1752
+fedstat/sdmx.py,sha256=kopTqLYVIe_JbXIrMGu2OxAJENDkuAhBl4oNlCvNbo4,4581
+fedstat/utils.py,sha256=9l2LYhPzeXTJtWdj6_WT-BbqFA_UrJUu8Ofj4vKFCPU,641
+fedstat-0.1.0.dist-info/METADATA,sha256=4Z8LKWppTHeQVCjl8hOKg-aqpokk8COnE3JGPA1p0qc,5690
+fedstat-0.1.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+fedstat-0.1.0.dist-info/licenses/LICENSE,sha256=3XAIMZgA_O17WMd8QK5TxYD30nExrfx_bxEK6FpULX8,1073
+fedstat-0.1.0.dist-info/RECORD,,

fedstat-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.1
+Root-Is-Purelib: true
+Tag: py3-none-any

fedstat-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timofei Ryadovoi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.