2025-etpgrf/LIBRARY_SPECS.md

Библиотека etpgrf: Контекст и Спецификация для LLM

Этот документ описывает архитектуру и API библиотеки etpgrf (Electro-Typographer), предназначенной для типографирования текста в вебе. Используйте этот контекст при разработке зависимых проектов (например, веб-сайтов).

1. Назначение

Библиотека выполняет комплексную обработку текста для улучшения его читаемости и внешнего вида в браузере:

• Замена кавычек («ёлочки», „лапки“).
• Расстановка неразрывных пробелов (предлоги, союзы, инициалы, единицы измерения).
• Замена дефисов на тире (—, –).
• Преобразование псевдографики (... -> …, (c) -> ©).
• Расстановка мягких переносов (­).
• Висячая пунктуация (оборачивание символов в <span>).
• Санитизация (очистка HTML от старой типографики).

2. Архитектура

• Язык: Python 3.10+.
• Зависимости: beautifulsoup4, lxml, regex.
• Главный класс: etpgrf.Typographer.
• Принцип работы:
  1. Принимает текст или HTML.
  2. Если HTML: парсит через BeautifulSoup (lxml), очищает от старой разметки (Sanitizer).
  3. Извлекает текстовые узлы, склеивает их в "супер-строку" для контекстных правил (кавычки).
  4. Применяет правила к тексту.
  5. Восстанавливает структуру HTML.
  6. Применяет висячую пунктуацию (модификация дерева DOM).
  7. Возвращает строку.

3. API: Класс Typographer

Инициализация

from etpgrf import Typographer

typo = Typographer(
    langs='ru',                 # Языки: 'ru', 'en', 'ru+en'
    mode='mixed',               # Режим вывода: 'unicode', 'mnemonic', 'mixed'
    process_html=True,          # Обрабатывать HTML-теги (иначе экранирует их)
    
    # Модули (можно отключить, передав False)
    hyphenation=True,           # Переносы слов
    quotes=True,                # Кавычки
    unbreakables=True,          # Неразрывные пробелы (предлоги, союзы)
    layout=True,                # Тире, спецсимволы, инициалы, единицы измерения
    symbols=True,               # Псевдографика (стрелочки, копирайт)
    
    # Специфические настройки
    sanitizer='etp',            # Очистка перед обработкой: 'etp' (удалить висячую), 'html' (удалить все теги)
    hanging_punctuation='both'  # Висячая пунктуация: 'left', 'right', 'both', None
)

Метод process

html = '<p>Привет, мир!</p>'
result = typo.process(html)
# Результат: '<p>Привет, мир!</p>' (с неразрывными пробелами и т.д.)

4. Особенности модулей

4.1. Висячая пунктуация (hanging.py)

• Оборачивает символы («, „, (, ., , и др.) в теги <span class="etp-...">.
• Логика:
  • Левые символы («): оборачиваются, если в начале узла ИЛИ перед ними пробел/другой левый символ.
  • Правые символы (», .): оборачиваются, если в конце узла ИЛИ после них пробел/другой правый символ.
• Классы CSS: etp-laquo, etp-r-dot, etp-r-comma и т.д. (см. config.py).
• Важно: Не добавляет компенсирующие пробелы. Визуализация — задача CSS.

4.2. Санитайзер (sanitizer.py)

• Запускается до основного типографирования.
• mode='etp': Удаляет теги <span> с классами висячей пунктуации (unwrap), сохраняя текст.
• mode='html': Удаляет ВСЕ теги, возвращает чистый текст.

4.3. Переносы (hyphenation.py)

• Использует алгоритм Ляна-Кнута (портирован из hyphen).
• Вставляет ­ (мягкий перенос).
• Настройки: MAX_UNHYPHENATED_LEN (не переносить длинные слова), MIN_TAIL_LEN (минимальный остаток).

4.4. Компоновка (layout.py)

• Тире: - ->  — (рус), — (анг).
• Инициалы: А. С. Пушкин -> А. С. Пушкин.
• Единицы измерения: 10 км -> 10 км.
• Сокращения: и т.д. -> и т. д..

5. Конфигурация (config.py)

Все константы (списки слов, коды символов, CSS-классы) находятся здесь.

• HANGING_PUNCTUATION_CLASSES: словарь {символ: класс}.
• PROTECTED_HTML_TAGS: теги, внутри которых типографика не применяется (script, code, pre...).

6. Пример использования (FastAPI/Flask/Django)

from etpgrf import Typographer

# Создаем экземпляр один раз (он stateless, кроме конфигурации)
typo = Typographer(langs='ru', process_html=True, hanging_punctuation='both')

def process_request(text):
    return typo.process(text)