Metadata-Version: 2.4
Name: smev-transform
Version: 2.0.0
Summary: Реализация алгоритма трансформации urn://smev-gov-ru/xmldsig/transform для СМЭВ 3.5.0.27
Home-page: https://github.com/imdeniil/smev-transform
Author: Daniil
Author-email: Daniil <keemor821@gmail.com>
Maintainer-email: Daniil <keemor821@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Daniil
        
        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.
        
Project-URL: Homepage, https://github.com/imdeniil/smev-transform
Project-URL: Repository, https://github.com/imdeniil/smev-transform
Project-URL: Bug Reports, https://github.com/imdeniil/smev-transform/issues
Project-URL: Documentation, https://info.gosuslugi.ru/docs/section/%D0%A1%D0%9C%D0%AD%D0%92/%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B5_%D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D1%8B/%D0%A1%D0%9C%D0%AD%D0%923/?id=758
Keywords: smev,смэв,xml,xmldsig,transformation,gosuslugi
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Markup :: XML
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# SMEV Transform (Python) v2.0

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

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

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

Алгоритм адаптирован для **СМЭВ версии 3.5.0.27** согласно официальной документации:
- [Методические документы СМЭВ3](https://info.gosuslugi.ru/docs/section/%D0%A1%D0%9C%D0%AD%D0%92/%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B5_%D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D1%8B/%D0%A1%D0%9C%D0%AD%D0%923/?id=758)
- Версия спецификации: 3.5.0.27

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

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

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

✅ **Шаг 9.1 - Декодирование текстовых блоков:**
- Снятие экранирования символов (`&#xd;`, `&lt;`, `&amp;` и др.)
- Корректная обработка 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 (рекомендовано)
```bash
pip install smev-transform
```

### Из исходников
```bash
git clone https://github.com/imdeniil/smev-transform
cd smev-transform
pip install -e .
```

### С использованием uv
```bash
uv pip install smev-transform
```

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

### Базовое использование
```python
from smev_transform import Transform

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

### Использование отдельных компонентов
```python
from smev_transform import TextDecoder, AttributeDecoder

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

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

## Примеры

### Пример 1: Базовая трансформация
```python
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)
```python
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)
```python
from smev_transform import Transform

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

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

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

### Пример 4: CDATA секции
```python
from smev_transform import Transform

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

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

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

```bash
# Все тесты
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:

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

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

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

## Разработка

### Установка зависимостей для разработки
```bash
uv pip install -e ".[dev]"
```

### Запуск тестов
```bash
pytest
# или
python -m pytest -v
```

### Проверка покрытия кода тестами
```bash
pytest --cov=smev_transform --cov-report=html
```

## Ссылки

- 📦 [PyPI Package](https://pypi.org/project/smev-transform/)
- 🐙 [GitHub Repository](https://github.com/imdeniil/smev-transform)
- 📚 [СМЭВ3 Документация](https://info.gosuslugi.ru/docs/section/%D0%A1%D0%9C%D0%AD%D0%92/%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B5_%D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D1%8B/%D0%A1%D0%9C%D0%AD%D0%923/?id=758)
- 🔗 [Оригинальная PHP библиотека](https://github.com/danbka/smev-transform)

## Автор

**Daniil** ([@imdeniil](https://github.com/imdeniil))
- Email: keemor821@gmail.com
- GitHub: https://github.com/imdeniil/

## Лицензия

MIT License - см. файл [LICENSE](LICENSE) для деталей.

---

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

## Поддержка

Если вы обнаружили баг или у вас есть предложения по улучшению, пожалуйста, создайте [issue на GitHub](https://github.com/imdeniil/smev-transform/issues).
