onecdc 0.2.0__py3-none-any.whl

onecdc/__init__.py

@@ -0,0 +1,20 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("onecdc")
+except PackageNotFoundError:
+    __version__ = "dev"
+
+from .metadata_reader import MetadataReader
+from .data_reader import DataReader, DataObject
+from .change_reader import ChangeReader
+from .name_mapper import NameMapper
+from .db_writer import DBWriter
+from .handlers import Handler, HandlerContext, HandlerLoop
+from .replicator import Replicator
+from .cron_runner import FullLoadCron
+
+__all__ = ["MetadataReader", "DataReader", "DataObject", "ChangeReader", "NameMapper",
+           "DBWriter", "Handler", "HandlerContext", "HandlerLoop", "Replicator",
+           "FullLoadCron", "__version__"]
+

onecdc/__main__.py

@@ -0,0 +1,108 @@
+"""
+Entrypoint для запуска из окружения без единой строки своего кода: `python -m onecdc` или команда
+`onecdc`. Все настройки — переменные окружения ONECDC_*; режим задаёт ONECDC_MODE: `loop`
+(по умолчанию) запускает run_forever с периодом ONECDC_POLL_INTERVAL, `once` — один run_once.
+
+Обязательные: ONECDC_ODATA_URL, ONECDC_EXCHANGE_NAME, ONECDC_QUEUE_GUID, ONECDC_DB_URL.
+ONECDC_QUEUE_GUID не знаете — запустите без него: в лог выведется список узлов плана обмена.
+Необязательные: ONECDC_ODATA_USER, ONECDC_ODATA_PASSWORD (без пользователя — без авторизации),
+ONECDC_DB_SCHEMA, ONECDC_DB_TEMP_SCHEMA, ONECDC_FULL_LOAD_WORKERS, ONECDC_POLL_INTERVAL, ONECDC_LOG_LEVEL, ONECDC_MODE.
+
+Обработчиков здесь нет: они объявляются кодом, а тут кода пользователя нет. Нужны обработчики —
+берите за основу config/runner.py: там ровно та же сборка, плюс по HandlerLoop на каждого
+обработчика, а значения при желании заменяются литералами.
+"""
+import logging
+import os
+
+import requests
+from sqlalchemy import create_engine
+
+from onecdc.replicator import Replicator
+
+
+def _required(name: str) -> str:
+    """Обязательная переменная окружения. KeyError в трейсбеке ничего не объясняет тому, кто
+    запускает контейнер, — говорим прямо, чего не хватает."""
+    value = os.environ.get(name, "").strip()
+    if not value:
+        raise SystemExit(f"{name} is not set (required: ONECDC_ODATA_URL, ONECDC_EXCHANGE_NAME, "
+                         f"ONECDC_DB_URL)")
+    return value
+
+
+def _number(name: str, default: str, cast=float):
+    """Числовая переменная окружения с понятным сообщением вместо голого ValueError."""
+    value = os.environ.get(name, default).strip() or default
+    try:
+        number = cast(value)
+    except ValueError:
+        raise SystemExit(f"{name}={value!r} is not a number")
+    if number <= 0:
+        raise SystemExit(f"{name}={value!r} must be positive")
+    return number
+
+
+def main() -> None:
+    odata_user = os.environ.get("ONECDC_ODATA_USER")
+    odata_url = _required("ONECDC_ODATA_URL")
+    full_load_workers = _number("ONECDC_FULL_LOAD_WORKERS", "2", int)
+
+    mode = os.environ.get("ONECDC_MODE", "loop")
+    if mode not in ("loop", "once"):
+        # Проверяем до соединений с БД и 1С: незачем поднимать пул ради заведомо неверного режима.
+        raise SystemExit(f"Unknown ONECDC_MODE={mode!r} (expected 'loop' or 'once')")
+
+    # Пул: одновременно соединение держат цикл изменений, ДВА потока отметки живости (реестр
+    # незавершённых merge и захват полной выгрузки) и страницы полной выгрузки, отсюда
+    # full_load_workers + 3 (см. README_DB.md, «Сколько нужно соединений к БД»). Отметке живости,
+    # не получившей соединения дольше своего TTL, никто не верит: её захват или её границу окна
+    # считают брошенными.
+    # Обработчиков здесь нет — были бы, добавилось бы по соединению на каждого.
+    engine = create_engine(_required("ONECDC_DB_URL"), pool_size=full_load_workers + 3)
+
+    # Параметры присваиваются явно, по одному — как и в config/runner.py: сборка одинаково
+    # читается и здесь, и в пользовательском коде, где значения будут литералами.
+    # Недоступная БД — не ошибка в коде, а состояние окружения: показываем строку, ради которой
+    # человек и полез бы в стотридцатистрочный трейс (см. _check_db_connection в replicator).
+    try:
+        replicator = Replicator(
+            odata_url=odata_url,
+            odata_auth=(odata_user, os.environ.get("ONECDC_ODATA_PASSWORD", "")) if odata_user else None,
+            exchange_name=_required("ONECDC_EXCHANGE_NAME"),
+            # Без узла обмена работать нельзя, но KeyError тут ничего не подскажет: пустое значение
+            # дойдёт до чтения изменений, и оно выведет в лог список узлов плана обмена.
+            queue_guid=os.environ.get("ONECDC_QUEUE_GUID", ""),
+            engine=engine,
+            db_schema=os.environ.get("ONECDC_DB_SCHEMA"),
+            # Схема промежуточных таблиц dbmerge; не задана — та же, что у данных.
+            db_temp_schema=os.environ.get("ONECDC_DB_TEMP_SCHEMA"),
+            full_load_workers=full_load_workers,
+        )
+    except ConnectionError as exc:
+        raise SystemExit(str(exc))
+
+    # Уровень логирования — после конструктора: он вешает обработчик на логгер onecdc
+    # (по умолчанию INFO), а тут переопределяем на заданный (например, DEBUG/WARNING).
+    log_level = os.environ.get("ONECDC_LOG_LEVEL", "INFO").strip().upper() or "INFO"
+    # getLevelName на известное имя отвечает числом, на неизвестное — строкой "Level FOO".
+    # Не getLevelNamesMapping(): он появился только в 3.11, а поддерживаем с 3.10.
+    level = logging.getLevelName(log_level)
+    if not isinstance(level, int):
+        raise SystemExit(f"Unknown ONECDC_LOG_LEVEL={log_level!r} "
+                         "(expected DEBUG/INFO/WARNING/ERROR/CRITICAL)")
+    logging.getLogger("onecdc").setLevel(level)
+
+    # run_forever недоступную 1С переживает сам (логирует и повторяет с backoff), а run_once
+    # обязан отдать ошибку наружу — здесь она и превращается в строку вместо трейса.
+    try:
+        if mode == "once":
+            replicator.run_once()
+        else:
+            replicator.run_forever(interval=_number("ONECDC_POLL_INTERVAL", "60"))
+    except requests.RequestException as exc:
+        raise SystemExit(f"1C is not available at {odata_url}: {exc}")
+
+
+if __name__ == "__main__":
+    main()

onecdc/change_reader.py

@@ -0,0 +1,130 @@
+import requests
+
+import xmltodict
+
+from onecdc.data_reader import DataReader
+from onecdc.metadata_reader import ACCOUNTING_REGISTER_TYPE, MetadataReader, resolve_timeout
+from onecdc.common_functions import format_bytes, raise_for_status
+from onecdc.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class ChangeReader(DataReader):
+    def __init__(self, odata_url: str, exchange_name: str, queue_guid: str,
+                 metadata: MetadataReader, odata_auth: tuple[str, str] | None = None,
+                 request_timeout: float | None = None):
+        super().__init__(odata_url, metadata, odata_auth, request_timeout)
+        self.exchange_name = exchange_name
+        self.queue_guid = queue_guid
+        self.message_no = 0
+
+    def read_changes(self):
+        # Узел не задан — дальше идти бессмысленно: подсказываем, из чего выбирать.
+        if not self.queue_guid:
+            self._raise_no_queue_guid()
+        # Сбрасываем накопленные данные предыдущего цикла (важно для run_forever).
+        self.clear()
+        self.message_no = self.get_last_received_no()+1
+        self.exchange_message_no = self.message_no
+
+        logger.info(f"Reading changes from 1C (message {self.message_no})")
+
+        url = f"{self.odata_url}/SelectChanges?DataExchangePoint='{self.odata_url}/ExchangePlan_{self.exchange_name}(guid'{self.queue_guid}')'&MessageNo={self.message_no}"
+
+        response = requests.post(url,auth=self.odata_auth,timeout=resolve_timeout(self.request_timeout))
+        raise_for_status(response, f'SelectChanges (message {self.message_no})')
+        self.last_response_bytes = len(response.content)
+
+        change_data = xmltodict.parse(response.text,force_list=('d:element','entry'))
+        change_entries = (change_data.get('feed') or {}).get('entry') or []
+
+        parsed = self.read_data_entries(change_entries)
+        # Пакет приносит набор записей регистра бухгалтерии БЕЗ субконто (их нет в описании
+        # движения вовсе) — дочитываем их отдельным запросом по периодам пакета, иначе колонки
+        # приехали бы пустыми и затёрли аналитику, полученную полной выгрузкой.
+        for object_name in list(self.keys()):
+            if object_name.startswith(ACCOUNTING_REGISTER_TYPE):
+                self.fill_ext_dimensions(object_name)
+        # Одна строка на пакет: что пришло, сколько строк и сколько весил ответ. Раньше лог писался
+        # на каждую entry, и один пакет давал сотни одинаковых строк.
+        logger.info("Read changes (message %s): %s entries, %s rows, %s%s",
+                    self.message_no, len(change_entries), self.rows_read(),
+                    format_bytes(self.last_response_bytes),
+                    ''.join(f'\n    {name}: {n} entries' for name, n in parsed.items()))
+
+    def notify_changes_received(self):
+        """
+        Подтвердить получение изменений, отправив запрос на сервер
+        """
+        url = f"{self.odata_url}/NotifyChangesReceived?DataExchangePoint='{self.odata_url}/ExchangePlan_{self.exchange_name}(guid'{self.queue_guid}')'&MessageNo={self.message_no}"
+        response = requests.post(url,auth=self.odata_auth,timeout=resolve_timeout(self.request_timeout))
+        # Не-2xx -> HTTPError. Подтверждение не прошло — изменения не списаны и придут снова
+        # (в run_forever цикл повторится, save идемпотентен).
+        raise_for_status(response, f'NotifyChangesReceived (message {self.message_no})')
+        logger.info(f"Changes confirmed for queue {self.queue_guid} (message {self.message_no})")
+
+
+    def read_nodes(self) -> list[dict]:
+        """
+        Все узлы плана обмена (как их отдаёт OData), включая ЭтотУзел.
+        """
+        url = f"{self.odata_url}/ExchangePlan_{self.exchange_name}?$format=json"
+        response = requests.get(url,auth=self.odata_auth,timeout=resolve_timeout(self.request_timeout))
+        raise_for_status(response, f'ExchangePlan_{self.exchange_name}')
+        return response.json().get('value') or []
+
+    def available_nodes(self) -> list[dict]:
+        """
+        Узлы, которые можно указать в queue_guid: всё, кроме ЭтотУзел (ThisNode) — он описывает
+        саму базу-источник, подписаться на его изменения нельзя.
+        """
+        return [node for node in self.read_nodes() if not node.get('ThisNode')]
+
+    def _raise_no_queue_guid(self):
+        """
+        queue_guid не задан: выводим в лог список узлов плана обмена, чтобы guid можно было взять
+        прямо отсюда, не открывая конфигуратор и не имея обработки в 1С.
+        """
+        try:
+            nodes = self.available_nodes()
+        except Exception as error:
+            # Список не получили (нет связи / неверный exchange_name) — сообщение об этом не должно
+            # подменять собой главную ошибку: она всё равно ниже.
+            logger.warning("Could not list nodes of exchange plan %s: %s", self.exchange_name, error)
+        else:
+            if nodes:
+                logger.error("queue_guid is not set. Available nodes of exchange plan %s:%s",
+                             self.exchange_name,
+                             ''.join(f"\n    {node.get('Ref_Key')}  {node.get('Code') or ''}"
+                                     f"  {node.get('Description') or ''}".rstrip()
+                                     for node in nodes))
+            else:
+                logger.error("queue_guid is not set, and exchange plan %s has no nodes besides "
+                             "ThisNode: create a node for this replication in 1C",
+                             self.exchange_name)
+        raise ValueError(f"queue_guid is not set (exchange plan {self.exchange_name}): "
+                         "specify the Ref_Key of the exchange node")
+
+    def get_last_received_no(self)->int:
+        """
+        Получить номер последнего пакета обмена, который был получен и подтвержден
+        """
+        queues = self.read_nodes()
+        receive_no = 0
+        found = False
+
+        for queue in queues:
+            if self.queue_guid == queue['Ref_Key']:
+                receive_no = int(queue['ReceivedNo'])
+                found = True
+
+        if not found:
+            # Очередь по guid не нашлась — вернём 0 (запросится пакет №1), но это почти наверняка
+            # неверный queue_guid или план обмена: без предупреждения ошибку конфигурации не видно.
+            logger.warning("Exchange queue %s not found in plan %s (check queue_guid/exchange_name)",
+                           self.queue_guid, self.exchange_name)
+
+        return receive_no
+    
+

onecdc/common_functions.py

@@ -0,0 +1,187 @@
+import json
+import re
+
+from datetime import date, datetime
+
+import requests
+from sqlalchemy import DateTime, func
+
+from onecdc.logging_config import get_logger
+
+ODATA_PREFIX = 'StandardODATA.'
+
+# Часы БД без часового пояса. Просто now() не годится: PostgreSQL отдаёт timestamptz, драйвер —
+# offset-aware datetime, а merged_on, started_at и onecdc_handlers.last_run_at лежат в колонках без
+# пояса и читаются offset-naive. Сравнить такие значения в Python нельзя — «can't compare
+# offset-naive and offset-aware datetimes», — а сравниваются они постоянно (граница окна против
+# last_run_at, guard'ы полной выгрузки против merged_on).
+#
+# Приведение делает сама БД, а не Python: там же, где живут эти часы, и ровно так же, как при
+# записи timestamptz в колонку timestamp — перевод в часовой пояс сессии, затем отбрасывание
+# смещения. Значение при этом не меняется, меняется только его тип.
+DB_NOW_WITHOUT_TIMEZONE = func.now().cast(DateTime)
+
+
+logger = get_logger(__name__)
+
+# Предел длины описания ошибки в логе — на случай, если распознать формат не удалось и в лог идёт
+# сырое тело. У распознанных ответов описание короткое, до предела не доходит.
+MAX_ERROR_BODY_CHARS = 500
+
+BYTE_UNITS = ('B', 'KB', 'MB', 'GB', 'TB')
+
+
+def format_bytes(size: float) -> str:
+    """
+    Размер ответа для лога в удобной единице: байты для мелочи, дальше КБ/МБ/ГБ. Ответы 1С
+    различаются на порядки (страница справочника — килобайты, набор движений — мегабайты),
+    и в сырых байтах разницу глазом не поймать.
+    """
+    for unit in BYTE_UNITS:
+        if size < 1024 or unit == BYTE_UNITS[-1]:
+            return f'{size:.0f} {unit}' if unit == BYTE_UNITS[0] else f'{size:.1f} {unit}'
+        size /= 1024
+
+
+def format_duration(seconds: float) -> str:
+    """
+    Длительность для лога: секунды с десятой долей, от минуты — «1m 04s», от часа — «1h 05m 03s».
+    Обработка пакета занимает от долей секунды до десятков минут, и в сырых секундах такой разброс
+    читается плохо.
+    """
+    if seconds < 60:
+        return f'{seconds:.1f}s'
+    minutes, sec = divmod(int(seconds), 60)
+    hours, minutes = divmod(minutes, 60)
+    if hours:
+        return f'{hours}h {minutes:02d}m {sec:02d}s'
+    return f'{minutes}m {sec:02d}s'
+
+
+def _one_line(text: str) -> str:
+    """Схлопывает переносы и лишние пробелы: описание ошибки должно занимать одну строку лога."""
+    text = re.sub(r'\s+', ' ', text).strip()
+    if len(text) > MAX_ERROR_BODY_CHARS:
+        return f'{text[:MAX_ERROR_BODY_CHARS]}... [+{len(text) - MAX_ERROR_BODY_CHARS} chars]'
+    return text
+
+
+def _exception_descriptions(payload: dict) -> list[str]:
+    """
+    Описания из цепочки exception -> inner в JSON-исключении сервера приложений 1С. Берём только
+    descr: рядом лежат creationStack (адреса в DLL) и base64-дамп на сотни строк, которые в логе
+    бесполезны. Вложенные описания часто повторяют друг друга — оставляем только те, что не
+    являются куском уже отобранного.
+
+    Внешнюю обёртку вида «HTTP: Forbidden. Ошибка при выполнении запроса GET к ресурсу …»
+    отбрасываем: код, метод и ресурс уже есть в нашем же сообщении. Но если она единственная —
+    оставляем, лучше так, чем пустая ошибка.
+    """
+    kept: list[str] = []
+    node = payload.get('exception') or payload
+    while isinstance(node, dict):
+        descr = _one_line(node.get('descr') or '')
+        if descr and not any(descr in text for text in kept):
+            kept = [text for text in kept if text not in descr]
+            kept.append(descr)
+        node = node.get('inner')
+
+    meaningful = [text for text in kept if not text.startswith('HTTP: ')]
+    return meaningful or kept
+
+
+def extract_error_text(body: str) -> str:
+    """
+    Человекочитаемое описание ошибки из ответа 1С. Отвечает она тремя разными способами:
+
+    - ошибка OData: XML `<m:error><m:message>…</m:message></m:error>`;
+    - исключение сервера приложений: JSON с цепочкой exception/inner, где полезен только descr;
+    - ошибка платформы/веб-сервера: HTML «1C:Enterprise 8 application error … by reason: …».
+
+    Если формат не распознан, отдаём тело как есть (обрезанное). В любом случае результат —
+    одна строка: полный дамп тела в лог не нужен, там мегабайты служебного мусора.
+    """
+    text = (body or '').lstrip('').strip()
+    if not text:
+        return '<empty body>'
+
+    match = re.search(r'<m:message[^>]*>(.*?)</m:message>', text, re.S)
+    if match:
+        return _one_line(match.group(1))
+
+    if text.startswith('{'):
+        try:
+            payload = json.loads(text)
+        except ValueError:
+            payload = None
+        if isinstance(payload, dict):
+            descriptions = _exception_descriptions(payload)
+            if descriptions:
+                return ' | '.join(descriptions)
+
+    match = re.search(r'by reason:\s*</b>\s*<br>(.*?)</body>', text, re.S | re.I)
+    if match:
+        return _one_line(re.sub(r'<[^>]+>', ' ', match.group(1)))
+
+    return _one_line(text)
+
+
+def odata_datetime_value(value: "date | datetime") -> str:
+    """
+    Дата-время в виде YYYY-MM-DDTHH:MM:SS для OData-литерала datetime'…'.
+
+    Собирается вручную, а не strftime: у %Y год НЕ дополняется нулями до четырёх знаков (на этой
+    платформе datetime(1,1,1).strftime('%Y-…') даёт '1-01-01'), а 1С такой литерал отвергает —
+    400 «Ошибка при разборе опции запроса $filter». Проверено на живой 1С: datetime'1-01-01T00:00:00'
+    → 400, datetime'0001-01-01T00:00:00' → 200.
+
+    Это не экзотика: `0001-01-01` — ПУСТАЯ ДАТА 1С, она приходит в обычных данных (например, в
+    измерении-дате независимого регистра сведений), и литералы строятся в том числе из значений,
+    прочитанных из самой 1С (курсор по периоду, перепроверка кандидатов на пометку). Годы меньше 1000
+    встречаются и как опечатка оператора.
+
+    1С хранит дату-время с точностью до секунды, поэтому доли секунды усекаются — для 1С безопасно.
+    """
+    return (f'{value.year:04d}-{value.month:02d}-{value.day:02d}'
+            f'T{getattr(value, "hour", 0):02d}:{getattr(value, "minute", 0):02d}'
+            f':{getattr(value, "second", 0):02d}')
+
+
+def raise_for_status(response: requests.Response, context: str = '') -> None:
+    """
+    Замена response.raise_for_status(): всё содержательное в ответе 1С лежит в теле, а штатный
+    raise_for_status отдаёт наружу только «HTTPError: 500» и причину из логов не видно.
+    В лог и в текст HTTPError идёт разобранное описание (см. extract_error_text), а не сырое тело.
+    """
+    if response.ok:
+        return
+
+    message = (f'1C request failed: {response.status_code} {response.reason} '
+               f'for {context or response.url}: {extract_error_text(response.text)}')
+    logger.error(message)
+    raise requests.HTTPError(message, response=response)
+
+def parse_object_full_name(object_full_name):
+    """
+    Очищаем имя объекта от разных префиксов, постфиксов и скобок.
+    Возвращает очищенное имя и тип объекта
+    """
+    if object_full_name is None:
+        logger.error('Object full name is None')
+        return None, None
+
+    object_name = object_full_name
+
+    if object_name.startswith('Collection'):
+        object_name = object_name.removeprefix('Collection(')
+        object_name = object_name.removesuffix(')')
+
+    object_name = object_name.removeprefix(ODATA_PREFIX)
+    object_name = object_name.removesuffix('_RowType')
+
+    if '_' in object_name:
+        object_type = object_name.split('_')[0]
+    else:
+        logger.error(f'Object type not found in object full name {object_full_name}')
+        return None, None
+    return object_name, object_type