components/parser/xml/README.md

# XML Parser

> ВАЖНО!!! README.md сгенерировано автоматически, поэтому может содержать неточности.

Модуль для извлечения структурированной информации из XML-файлов документов.

## Общий процесс парсинга

1. Рекурсивный поиск всех XML-файлов в указанной директории
2. Для каждого файла:
   - Извлечение основной информации (статус, владелец, название)
   - При необходимости извлечение содержимого (таблицы и текст)
3. Фильтрация документов по статусу
4. Формирование итоговой коллекции документов

## Подробное описание компонентов

### XMLParser

Основной класс, координирующий работу всех парсеров. Использует три специализированных парсера:
- XMLInfoParser - для основной информации
- XMLTableParser - для таблиц
- XMLTextParser - для текстового содержимого

### XMLInfoParser

Извлекает основную информацию о документе:
1. Находит специальные теги (STATUS_TAG, OWNER_TAG, NAME_TAG)
2. Извлекает значения между тегами `<w:t>` и `</w:t>`
3. Проверяет статус документа (только USEFUL_STATUSES)
4. Формирует объект ParsedXML

### XMLTableParser

Обрабатывает таблицы в документе:
1. Находит все блоки таблиц (`<w:tbl>`)
2. Определяет тип таблицы (обычная/сокращения/регламентирующие документы)
3. Извлекает строки (`<w:tr>`) и ячейки (`<w:tc>`)
4. Обрабатывает специальные случаи (таблицы с шапкой)
5. Формирует текстовое представление таблиц

### XMLTextParser

Очищает текст от XML-разметки:
1. Удаляет таблицы
2. Удаляет бинарные данные
3. Удаляет специальные конструкции (KCC, CC patterns)
4. Очищает от XML-тегов
5. Обрабатывает специальные символы

## Структуры данных

- ParsedXML - информация об одном документе
- ParsedXMLs - коллекция документов
- ParsedTable - данные одной таблицы
- ParsedTables - коллекция таблиц
- ParsedRow - данные одной строки таблицы

## Особенности реализации

1. Кодировка по умолчанию: cp866
2. Фильтрация по статусам: 'Актуальный', 'Требует актуализации', 'Упразднён'
3. Специальная обработка таблиц сокращений и регламентирующих документов
4. Возможность исключения определенных файлов при парсинге
5. Опциональное извлечение содержимого (флаг include_content)

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

```python
from components.parser.xml.xml_parser import XMLParser

# Создание парсера
parser = XMLParser()

# Парсинг одного файла
result = parser.parse("path/to/file.xml", include_content=True)

# Парсинг всех файлов в директории
results = parser.parse_all(
    "path/to/dir",
    encoding='cp866',
    include_content=True,
    ignore_files_contains=['temp', 'draft']
)
```