mod: 0.1.2 description

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+Все заметные изменения в этом проекте будут задокументированы в этом файле.
+
+Формат основан на [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+и этот проект придерживается [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.2] - 2025-05-02
+### Исправлено
+- **Критическое исправление:** Добавлена отсутствующая зависимость `regex` в `pyproject.toml`. Без неё библиотека
+  падала при импорте.
+- Файл `LIBRARY_SPECS.md` для LLM.
+
+## [0.1.1] - 2025-05-02
+### Добавлено
+- Ссылки на зеркала репозитория (GitVerse, Gitea) в `pyproject.toml` и `README.md`.
+- Раздел Credits в документации.
+
+## [0.1.0] - 2025-05-01
+### Добавлено
+- Первый публичный релиз библиотеки `etpgrf`.
+- Основные модули:
+    - `Typographer`: основной класс-оркестратор.
+    - `Hyphenator`: расстановка мягких переносов (алгоритм Ляна-Кнута).
+    - `QuotesProcessor`: замена кавычек («ёлочки», „лапки“).
+    - `Unbreakables`: неразрывные пробелы для предлогов, союзов и частиц.
+    - `LayoutProcessor`: типографика тире, инициалов, акронимов, единиц измерения.
+    - `SymbolsProcessor`: псевдографика.
+    - `HangingPunctuationProcessor`: висячая пунктуация.
+    - `SanitizerProcessor`: очистка HTML перед обработкой.
+- Поддержка русского, русского дореформенного и английского языков.
+- Поддержка обработки HTML (через BeautifulSoup).

LIBRARY_SPECS.md

@@ -0,0 +1,100 @@
+# Библиотека 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`).
+*   Вставляет `&shy;` (мягкий перенос).
+*   Настройки: `MAX_UNHYPHENATED_LEN` (не переносить длинные слова), `MIN_TAIL_LEN` (минимальный остаток).
+
+### 4.4. Компоновка (`layout.py`)
+*   Тире: ` - ` -> `&nbsp;— ` (рус), `—` (анг).
+*   Инициалы: `А. С. Пушкин` -> `А.&nbsp;С.&thinsp;Пушкин`.
+*   Единицы измерения: `10 км` -> `10&nbsp;км`.
+*   Сокращения: `и т.д.` -> `и&nbsp;т.&thinsp;д.`.
+
+## 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)
+```

README.md

@@ -1,15 +1,22 @@
-# etpgrf — типограф для Web
+# etpgrf — единый типограф для веба / effortless typography for web
 
 [![PyPI version](https://badge.fury.io/py/etpgrf.svg)](https://badge.fury.io/py/etpgrf)
 [![Python Version](https://img.shields.io/pypi/pyversions/etpgrf.svg)](https://pypi.org/project/etpgrf/)
 [![License](https://img.shields.io/pypi/l/etpgrf.svg)](https://pypi.org/project/etpgrf/)
 
 
-# Типограф для Web
+# Типограф для веба 
 
 Экранная типографика для веба — способствует повышению читабельности текста в интернете,
 приближая его к печатной типографике.
 
+## Репозитории / Repositories
+
+Исходный код доступен на нескольких площадках:
+*   [Gitea](https://git.cube2.ru/erjemin/2025-etpgrf) (Основной self-hosted)
+*   [GitHub](https://github.com/erjemin/etpgrf) (Главное зеркало & homepage/issues)
+*   [GitVerse](https://gitverse.ru/erjemin/etpgrf) (Зеркало на GitVerse)
+
 ## Установка
 
 ```bash

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "etpgrf"
-version = "0.1.0"
+version = "0.1.2"
 description = "Electro-Typographer: Python library for advanced web typography (non-breaking spaces, hyphenation, hanging punctuation and ."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -27,11 +27,14 @@ classifiers = [
 dependencies = [
     "beautifulsoup4>=4.10.0",
     "lxml>=4.9.0",  # Рекомендуемый парсер
+    "regex>=2022.1.18", # Критически важная зависимость для Unicode
 ]
 
 [project.urls]
 "Homepage" = "https://github.com/erjemin/etpgrf"
 "Bug Tracker" = "https://github.com/erjemin/etpgrf/issues"
+"Mirror (GitVerse)" = "https://gitverse.ru/erjemin/etpgrf"
+"Selfhosted (Gitea)" = "https://gitverse.ru/erjemin/etpgrf"
 
 [tool.setuptools.packages.find]
 where = ["."]  # Искать пакеты в корне (найдет папку etpgrf)