pyRegRep

Бібліотека Python для парсування та обробки XML документів у форматі RIM (Registry Information Model) / ebXML.

Опис

pyRegRep — інструмент для роботи з XML документами стандарту Registry Information Model (RIM), що застосовується в системах eGovernment та обміну даними (зокрема, OOTS/EDM). Бібліотека дозволяє легко витягувати, аналізувати та серіалізувати дані з RIM/ebXML документів, а також програмно створювати коректні RIM-слоти різних типів.

Можливості

• ✅ Парсування RIM/ebXML XML документів (bytes або str)
• ✅ Автоматична обробка просторів імен (namespaces)
• ✅ Витягування запитів (Query), винятків (Exception) та об'єктів реєстру (RegistryObject)
• ✅ Обробка всіх типів значень: Boolean, String, Integer, DateTime, Collection, InternationalString, AnyValue
• ✅ Серіалізація даних у зручний Python-формат (dict)
• ✅ Фабрика слотів get_slot() — програмне створення RIM-слотів за типом
• ✅ Builder-класи для елементів RegistryObject, RepositoryItemRef, QueryResponse, Classification
• ✅ Серіалізація AnyValueType через xmltodict (параметр any_type=True)
• ✅ Підтримка вкладених колекцій та складних структур
• ✅ Безпечний доступ до вкладених даних через deep_get()

Вимоги

• Python: >= 3.10
• Залежності:
  • lxml >= 5.2.1 — робота з XML
  • xmltodict >= 0.13.0 — серіалізація AnyValueType

Установка

Проєкт використовує uv як менеджер залежностей і середовище розробки.

# Створити віртуальне середовище та встановити пакет з dev-залежностями
uv sync --extra dev

# Або встановити лише пакет без dev-залежностей
uv pip install -e .

Після цього можна запускати команди через uv run, наприклад:

uv run pytest
uv run ruff check .

Швидкий старт

Парсування XML документу

from pyRegRep4.RIMParsing import Parsing

with open("document.xml", "rb") as f:
    parser = Parsing(f.read())

# Усі слоти у вигляді {category: {name: (type, value)}}
print(parser.slots)

# Серіалізовані дані (без типової інформації)
print(parser.serialize())

# Серіалізація з обробкою AnyValueType в dict
print(parser.serialize(any_type=True))

from pyRegRep4 import deep_get

# Безпечний доступ до вкладених ключів
spec_id = deep_get(parser.serialize(), "doc", "SpecificationIdentifier", default="unknown")
print(spec_id)

Програмне створення RIM-слотів

import datetime
from lxml import etree
from pyRegRep4.RIMElement import get_slot

# Текстовий слот
slot = get_slot("SpecificationIdentifier", "StringValueType", "oots-edm:v1.2")
print(slot.name)   # 'SpecificationIdentifier'
print(slot.value)  # 'oots-edm:v1.2'
print(slot.text)   # XML як bytes

# Логічний слот
slot = get_slot("PossibilityForPreview", "BooleanValueType", True)

# Слот дата/час
slot = get_slot("IssueDateTime", "DateTimeValueType", datetime.datetime.now())

# Багатомовний слот через dict-список
slot = get_slot(
    "Title",
    "InternationalStringValueType",
    [
        {"lang": "en", "text": "Birth Certificate"},
        {"lang": "uk", "text": "Свідоцтво про народження"},
    ],
)

# Довільний XML (AnyValueType)
elem = etree.Element("CustomData")
elem.text = "Payload"
slot = get_slot("CustomPayload", "AnyValueType", elem)

API Довідник

Клас Parsing (pyRegRep4.RIMParsing)

Конструктор

Parsing(doc: bytes | str)

Атрибути

Категорії slots: "doc", "query", "exception", "object".

Метод serialize(any_type: bool = False) -> dict

Серіалізує слоти в чистий Python-формат, видаляючи типову інформацію.

Функція get_slot() (pyRegRep4.RIMElement)

get_slot(name: str, slot_type: str, value: Any) -> Xml

Фабрика для програмного створення RIM-слотів.

Підтримані типи:

Повертає об'єкт Xml з властивостями:

• name — ім'я слота
• value — значення
• element — XML елемент (etree._Element)
• text — серіалізований XML (bytes)

Викидає ValueError при невідомому типі слота.

try:
    slot = get_slot("Bad", "UnknownType", "value")
except ValueError as e:
    print(e)  # Невідомий тип слота: UnknownType. Підтримувані типи: [...]

Builder-класи XML елементів (pyRegRep4.RIMElement)

Публічні класи для побудови типових елементів RIM/query:

• RegistryObject
• RepositoryItemRef
• QueryResponse
• Classification

Усі класи мають однаковий базовий контракт:

• element — повертає etree._Element (або ValueError, якщо елемент ще не створено)
• text — серіалізований XML (bytes)
• create_element(...) — будує XML елемент і повертає self (chain-style)

from pyRegRep4.RIMElement import RepositoryItemRef, QueryResponse

ref = RepositoryItemRef().create_element(
    "https://example.org/document.xml",
    "Document",
)
print(ref.text)

response = QueryResponse().create_element(
    "urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success",
    "req-1",
)
print(response.element.tag)

Функція deep_get() (pyRegRep4.utils)

deep_get(data: dict, *keys, default=None)

Безпечно дістає значення з вкладеного dict за послідовністю ключів.

Поведінка:

• якщо на будь-якому кроці значення не є dict — повертається default
• якщо кінцеве значення None — повертається default
• якщо keys не передані — повертається data

from pyRegRep4 import deep_get

data = {
    "doc": {
        "Procedure": [{"lang": "en", "value": "GetBirthCertificate"}]
    }
}

value = deep_get(data, "doc", "Procedure", 0, "value", default="n/a")
print(value)  # n/a (бо deep_get працює тільки з dict-ланцюжком)

procedure = deep_get(data, "doc", "Procedure", default=[])
print(procedure)  # [{"lang": "en", "value": "GetBirthCertificate"}]

Клас NS (pyRegRep4.NS)

Базовий клас для управління RIM namespace. Надає метод _tname(prefix, localname) для генерування кваліфікованих імен тегів у нотації Clark.

Виняток ParsingError (pyRegRep4.RIMParsing)

Базовий клас для помилок парсування. Кидається при некоректному XML або відсутньому namespace.

Структура проекту

pyRegRep/
├── pyRegRep4/
│   ├── __init__.py          # Експорт: get_slot, deep_get, Parsing, serialize_any_value_type
│   ├── RIMElement.py        # Класи слотів + фабрика get_slot()
│   ├── RIMParsing.py        # Парсер Parsing + serialize()
│   ├── utils.py             # deep_get() для вкладених словників
│   └── NS.py                # Базовий клас для namespace
├── tests/
│   ├── conftest.py          # sys.path для CI
│   ├── test_rim_parsing.py  # Тести парсера
│   ├── test_rim_element.py  # Тести get_slot() та типів слотів
│   ├── test_utils.py        # Тести deep_get()
│   ├── EDM_Ferst_Request.xml
│   ├── EDM_Ferst_Response.xml
│   ├── EDM_Second_Request.xml
│   └── EDM_Second_Response.xml
├── example/
│   ├── Example_1.py
│   ├── example_anyvaluetype_usage.py
│   └── example_get_slot_usage.py
├── pyproject.toml
├── uv.lock
├── README.md
└── .github/workflows/

Запуск тестів

# Встановити залежності проекту
uv sync --extra dev

# Усі тести
uv run pytest --disable-warnings -q

# Тільки тести парсера
uv run pytest tests/test_rim_parsing.py -v

# Тільки тести слотів
uv run pytest tests/test_rim_element.py -v

# Збірка source distribution та wheel
uv run python -m build

Логування

Бібліотека використовує стандартний logging. Для увімкнення:

import logging
logging.basicConfig(level=logging.DEBUG)

Технічні деталі

Обробка просторів імен

Namespace витягуються автоматично з кореневого елемента документа та зберігаються у parser._ns у форматі {prefix: uri}.

Формат slots

{
    "doc": {
        "SpecificationIdentifier": ("StringValueType", "oots-edm:v1.2"),
        "IssueDateTime": ("DateTimeValueType", "2024-03-15T10:30:00"),
        "PossibilityForPreview": ("BooleanValueType", "false"),
    },
    "query": {},
    "exception": {},
    "object": {}
}

Автор

Andrey Shapovalov — mt.andrey@gmail.com

Ліцензія

MIT License — див. файл LICENSE

Посилання

• ebXML / Registry Information Model
• OOTS EDM Specification
• lxml Documentation
• xmltodict

Версія: 15 · Оновлено: 2026-09-07