SMEV Transform (Python) v2.0

Полная реализация алгоритма трансформации "urn://smev-gov-ru/xmldsig/transform" для Python согласно официальной документации СМЭВ 3.5.0.27.

Это улучшенный порт оригинальной PHP библиотеки danbka/smev-transform на Python с полной поддержкой всех 9 шагов трансформации.

📚 Документация СМЭВ

Алгоритм адаптирован для СМЭВ версии 3.5.0.27 согласно официальной документации:

• Методические документы СМЭВ3
• Версия спецификации: 3.5.0.27

🆕 Новое в версии 2.0

КРИТИЧЕСКОЕ ОБНОВЛЕНИЕ: Добавлена полная поддержка Шага 9 - Декодирование текста, который отсутствовал в оригинальной PHP библиотеке!

Что добавлено:

✅ Шаг 9.1 - Декодирование текстовых блоков:

• Снятие экранирования символов (
, <, & и др.)
• Корректная обработка CDATA секций
• Умное кодирование блоков по размеру (до 11 символов / от 12 символов)
• Условное кодирование символа > согласно спецификации

✅ Шаг 9.2 - Декодирование атрибутов:

• Нормализация пробельных символов в атрибутах
• Снятие экранирования в значениях атрибутов
• Правильное кодирование атрибутов

Описание

При подписании XML-фрагментов ЭП в формате XMLDSig, обязательно использование трансформации urn://smev-gov-ru/xmldsig/transform.

Полный алгоритм трансформации (9 шагов)

1. ✅ XML declaration и processing instructions удаляются
2. ✅ Пробельные символы удаляются из текстовых узлов
3. ✅ Empty element tags преобразуются в пары start-tag + end-tag
4. ✅ Неиспользуемые namespace prefix удаляются
5. ✅ Namespace declarations проверяются и добавляются при необходимости
6. ✅ Автоматические префиксы генерируются (ns1, ns2, ...)
7. ✅ Атрибуты сортируются в алфавитном порядке
8. ✅ Namespace declarations размещаются перед атрибутами
9. ✅ Декодирование текста (НОВОЕ!) - полная обработка текстовых блоков и атрибутов

Установка

Из PyPI (рекомендовано)

pip install smev-transform

Из исходников

git clone https://github.com/imdeniil/smev-transform
cd smev-transform
pip install -e .

С использованием uv

uv pip install smev-transform

Использование

Базовое использование

from smev_transform import Transform

transform = Transform()
result = transform.process(xml_string)

Использование отдельных компонентов

from smev_transform import TextDecoder, AttributeDecoder

# Декодирование текстовых блоков
decoded_text = TextDecoder.decode_text_block(text_with_entities)

# Декодирование атрибутов
decoded_attr = AttributeDecoder.decode_attribute_value(attr_value)

Примеры

Пример 1: Базовая трансформация

from smev_transform import Transform

xml = '''<?xml version="1.0" encoding="UTF-8"?>
<elementOne xmlns="http://test/1" xmlns:qwe="http://test/2">
    <qwe:elementTwo attB="bbb" attA="aaa"/>
</elementOne>'''

transform = Transform()
result = transform.process(xml)

print(result)
# Результат: <ns1:elementOne xmlns:ns1="http://test/1"><ns2:elementTwo xmlns:ns2="http://test/2" attA="aaa" attB="bbb"></ns2:elementTwo></ns1:elementOne>

Пример 2: Обработка текста с экранированием (Шаг 9.1)

from smev_transform import Transform

xml = '''<root>&gt;&gt;text&amp;content&lt;</root>'''

transform = Transform()
result = transform.process(xml)

print(result)
# Текст проходит декодирование согласно алгоритму СМЭВ

Пример 3: Обработка атрибутов с пробелами (Шаг 9.2)

from smev_transform import Transform

xml = '''<root attr="value	with	tabs and
newlines"/>'''

transform = Transform()
result = transform.process(xml)

print(result)
# Пробельные символы в атрибутах нормализуются согласно СМЭВ

Пример 4: CDATA секции

from smev_transform import Transform

xml = '''<root>
    Текст до CDATA
    <![CDATA[Сырой контент < & > остается нетронутым]]>
    Текст после CDATA
</root>'''

transform = Transform()
result = transform.process(xml)
# CDATA секции обрабатываются корректно согласно спецификации

Тестирование

# Все тесты
python -m unittest discover tests/

# Конкретные тесты
python -m unittest tests.test_transform -v
python -m unittest tests.test_text_decoder -v
python -m unittest tests.test_attribute_decoder -v

Различия с оригинальной PHP библиотекой

Функциональность	PHP версия	Python v2.0
Шаги 1-8 (базовая трансформация)	✅	✅
Шаг 9.1 (декодирование текста)	❌ ОТСУТСТВУЕТ	✅ РЕАЛИЗОВАНО
Шаг 9.2 (декодирование атрибутов)	❌ ОТСУТСТВУЕТ	✅ РЕАЛИЗОВАНО
Обработка CDATA	⚠️ Частично	✅ Полностью
Соответствие официальной спецификации	⚠️ 89%	✅ 100%

Требования

• Python 3.7+
• Только стандартная библиотека Python (xml.etree.ElementTree)

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

smev_transform/
├── __init__.py              # Основной модуль
├── transform.py             # Главный класс Transform
├── text_decoder.py          # Декодирование текстовых блоков (Шаг 9.1)
├── attribute_decoder.py     # Декодирование атрибутов (Шаг 9.2)
├── xml_namespace.py         # Работа с XML namespaces
├── attribute.py            # Представление XML атрибутов
├── comparators.py          # Сортировка атрибутов
└── exceptions.py           # Исключения

tests/                      # Полное покрытие тестами
├── test_transform.py
├── test_text_decoder.py    # Тесты Шага 9.1
└── test_attribute_decoder.py # Тесты Шага 9.2

Совместимость и миграция

Миграция с версии 1.0:

• API полностью совместимо - никаких изменений в коде не требуется
• Результаты трансформации могут отличаться из-за добавления Шага 9
• Рекомендуется протестировать с реальными СМЭВ сообщениями

Для продакшен-использования:

• ✅ Версия 2.0 рекомендована для всех новых проектов
• ✅ Полное соответствие официальной документации СМЭВ3
• ✅ Корректная работа с реальными СМЭВ сообщениями

Публикация на PyPI

Для публикации пакета на PyPI:

# Установка инструментов сборки
uv pip install build twine

# Сборка дистрибутива
python -m build

# Публикация на PyPI
python -m twine upload dist/*

Разработка

Установка зависимостей для разработки

uv pip install -e ".[dev]"

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

pytest
# или
python -m pytest -v

Проверка покрытия кода тестами

pytest --cov=smev_transform --cov-report=html

Ссылки

• 📦 PyPI Package
• 🐙 GitHub Repository
• 📚 СМЭВ3 Документация
• 🔗 Оригинальная PHP библиотека

Автор

Daniil (@imdeniil)

• Email: keemor821@gmail.com
• GitHub: https://github.com/imdeniil/

Лицензия

MIT License - см. файл LICENSE для деталей.

---

⚠️ ВАЖНО: Если вы используете эту библиотеку для интеграции с СМЭВ3, настоятельно рекомендуется использовать версию 2.0, так как она включает все требования официальной спецификации СМЭВ 3.5.0.27.

Поддержка

Если вы обнаружили баг или у вас есть предложения по улучшению, пожалуйста, создайте issue на GitHub.