101 lines
6.2 KiB
Markdown
101 lines
6.2 KiB
Markdown
# Библиотека 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
|
||
|
||
### Инициализация
|
||
```python
|
||
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
|
||
```python
|
||
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)
|
||
|
||
```python
|
||
from etpgrf import Typographer
|
||
|
||
# Создаем экземпляр один раз (он stateless, кроме конфигурации)
|
||
typo = Typographer(langs='ru', process_html=True, hanging_punctuation='both')
|
||
|
||
def process_request(text):
|
||
return typo.process(text)
|
||
```
|