tg-export 1.0.0__tar.gz

tg_export-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vitaly Ostanin
+
+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.

tg_export-1.0.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: tg-export
+Version: 1.0.0
+Summary: Flexible Telegram data export tool
+Author-email: Vitaly Ostanin <vitaly.ostanin@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/VitalyOstanin/tg-export
+Project-URL: Repository, https://github.com/VitalyOstanin/tg-export
+Project-URL: Issues, https://github.com/VitalyOstanin/tg-export/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: telethon>=1.36
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: jinja2>=3.1
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Provides-Extra: proxy
+Requires-Dist: python-socks[asyncio]>=2.0; extra == "proxy"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# tg-export
+
+Экспорт данных из Telegram на локальный диск с гибкой настройкой.
+
+## Содержание
+
+- [Возможности](#возможности)
+- [Сценарии использования](#сценарии-использования)
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+- [Структура конфигов](#структура-конфигов)
+- [Конфигурация экспорта](#конфигурация-экспорта)
+- [Тесты](#тесты)
+
+## Возможности
+
+- **Инкрементальный экспорт** -- при повторном запуске скачиваются только новые сообщения и файлы, состояние хранится в SQLite
+- **Sibling-дедупликация** -- при экспорте нескольких аккаунтов (семья, рабочий/личный) общие файлы не скачиваются повторно, а линкуются через hardlink
+- **Импорт из tdesktop** -- файлы из стандартного экспорта Telegram Desktop копируются вместо повторного скачивания
+- **Takeout API** -- использует официальный Takeout для обхода rate-limiting
+- **Гибкие правила экспорта** -- настройка по чатам, папкам, типам (personal, groups, channels, bots), с фильтрами по датам, типам медиа и размеру файлов
+- **Логика архивных чатов** -- чат считается архивным (`is_archived`) только если он присутствует исключительно в архиве Telegram. Если чат есть в основном списке диалогов или в именованной папке, он не помечается как архивный, даже если одновременно находится в архиве
+- **Проверка размера в runtime** -- если реальный размер файла превышает лимит, скачивание прерывается и частичный файл удаляется
+- **HTML-рендеринг по месяцам** -- каждый месяц в отдельном файле, с оглавлением (TOC) и навигацией prev/next
+- **Progress bars** -- основной прогресс по сообщениям + sub-progress bars для каждого скачиваемого файла
+- **Контроль свободного места** -- экспорт останавливается, если свободное место на диске падает ниже порога (`min_free_space` в `config.yaml`, по умолчанию 20 GB)
+- **Корректный shutdown** -- Ctrl+C сохраняет состояние, двойной Ctrl+C -- force shutdown с cleanup
+- **Поддержка прокси** -- SOCKS5, SOCKS4, HTTP прокси для подключения к Telegram API
+- **Данные в SQLite** -- все сообщения и метаданные хранятся в SQLite, что позволяет пересоздать HTML без обращения к Telegram API, строить поисковые индексы, подключить веб-интерфейс или использовать данные в любых других целях
+- **CLI для анализа** -- команда `tg info` для batch-запросов информации о чатах через API
+- **Очистка данных чата** -- команда `purge` для удаления данных конкретного чата из БД и с диска
+
+## Сценарии использования
+
+**Личный архив** -- экспорт всех личных переписок и групп с медиафайлами на локальный диск для долгосрочного хранения.
+
+**Семейный экспорт** -- экспорт аккаунтов нескольких членов семьи. Общие группы и каналы содержат одинаковые файлы -- sibling-дедупликация экономит место на диске через hardlink.
+
+**Выборочный экспорт** -- экспорт только нужных чатов/папок с правилами: рабочие чаты экспортируются, боты и публичные каналы пропускаются, для флудилок скачиваются только фото.
+
+**Миграция с tdesktop** -- если уже есть экспорт из Telegram Desktop, файлы из него импортируются без повторного скачивания.
+
+## Установка
+
+Из PyPI (экспериментально, не проверялось):
+
+```bash
+pip install tg-export
+```
+
+Для работы через прокси:
+
+```bash
+pip install tg-export[proxy]
+```
+
+Из исходников:
+
+```bash
+uv pip install -e .
+```
+
+## Быстрый старт
+
+### 1. Получить API credentials
+
+Зайти на [my.telegram.org](https://my.telegram.org), создать приложение, получить `api_id` и `api_hash`.
+
+```bash
+uv run tg-export auth credentials
+```
+
+Ввести `api_id` и `api_hash`. Они сохраняются в `~/.config/tg-export/api_credentials.yaml` и используются для всех аккаунтов.
+
+### 2. Настроить прокси (если нужен)
+
+Создать файл `~/.config/tg-export/config.yaml`:
+
+```yaml
+proxy:
+  type: socks5      # socks5, socks4, http
+  host: 127.0.0.1
+  port: 1080
+  # username: user   # опционально
+  # password: pass   # опционально
+```
+
+### 3. Залогиниться в Telegram
+
+```bash
+uv run tg-export auth add --name myaccount
+```
+
+Ввести номер телефона и код подтверждения. Сессия сохранится в `~/.config/tg-export/sessions/myaccount.session`.
+
+Для нескольких аккаунтов повторить с разными именами. Установить аккаунт по умолчанию:
+
+```bash
+uv run tg-export account default myaccount
+```
+
+### 4. Анализ чатов и каталог
+
+Получить каталог всех чатов аккаунта:
+
+```bash
+uv run tg-export list --output catalog.yaml
+uv run tg-export list --format json --output catalog.json
+```
+
+Посмотреть информацию о конкретных чатах (количество сообщений, последние сообщения):
+
+```bash
+uv run tg-export info 123456789 987654321
+uv run tg-export info --from-catalog catalog.json --type personal --last 3
+```
+
+### 5. Настройка правил экспорта
+
+Сгенерировать шаблон конфига:
+
+```bash
+uv run tg-export init
+```
+
+Конфиг создается в `~/.config/tg-export/myaccount.yaml`. Настроить правила: какие чаты экспортировать, какие пропускать, какие типы медиа скачивать.
+
+AI-агенты (Claude Code, Cursor и т.д.) могут помочь с настройкой: показать список чатов по категориям, задать вопросы о каждом и сформировать конфиг интерактивно.
+
+Пример конфига:
+
+```yaml
+output:
+  path: ./export_output/myaccount
+
+defaults:
+  media:
+    types: [all]
+    max_file_size: 100MB
+    concurrent_downloads: 3
+
+# Импорт файлов из существующего экспорта tdesktop
+import_existing:
+  - path: ~/Downloads/Telegram Desktop/DataExport
+    type: tdesktop
+
+# Правила по типам чатов
+type_rules:
+  bots:
+    skip: true
+  public:
+    skip: true
+  personal: {}    # экспортировать все личные чаты
+  self: {}        # экспортировать Saved Messages
+
+# Правила по папкам Telegram
+folders:
+  Work: {}
+  Family:
+    media:
+      types: [photo, video]
+
+# Правила по конкретным чатам
+chats:
+  - id: 777000
+    name: Telegram
+    action: skip
+  - id: 123456789
+    name: "Important Chat"
+    media:
+      types: []    # без медиа
+
+# Что делать с чатами, не попавшими ни в одно правило
+unmatched: skip
+```
+
+### 6. Запустить экспорт
+
+```bash
+uv run tg-export run
+```
+
+Для пробного запуска без скачивания:
+
+```bash
+uv run tg-export run --dry-run
+```
+
+При повторном запуске скачиваются только новые сообщения (инкрементальный экспорт).
+
+### 7. Sibling-дедупликация
+
+При экспорте нескольких аккаунтов в один каталог (`./export_output/`), tg-export автоматически находит соседние базы данных и использует уже скачанные файлы через hardlink:
+
+```
+export_output/
+  account1/         # первый аккаунт
+  account2/         # файлы из общих чатов линкуются из account1
+```
+
+## Структура конфигов
+
+```
+~/.config/tg-export/
+  api_credentials.yaml      # API ID и Hash (общие для всех аккаунтов)
+  config.yaml               # Глобальные настройки (proxy, min_free_space)
+  default_account            # Имя аккаунта по умолчанию
+  sessions/
+    myaccount.session        # Telethon-сессия
+  myaccount.yaml             # Конфиг экспорта для аккаунта
+
+export_output/
+  myaccount/
+    .tg-export-state.db      # SQLite: состояние экспорта, сообщения, файлы
+    unfiled/
+      Chat_Name_123456/
+        messages.html         # Redirect на первый месяц
+        messages_2024-01.html # Сообщения за январь 2024
+        messages_2024-02.html # Сообщения за февраль 2024
+        photos/               # Скачанные фото
+        videos/               # Скачанные видео
+        files/                # Скачанные документы
+    folders/
+      Work/
+        ...
+```
+
+## Тесты
+
+```bash
+uv run python -m pytest tests/ -v
+```
+
+## Лицензия
+
+[MIT License](LICENSE)

tg_export-1.0.0/README.md

@@ -0,0 +1,236 @@
+# tg-export
+
+Экспорт данных из Telegram на локальный диск с гибкой настройкой.
+
+## Содержание
+
+- [Возможности](#возможности)
+- [Сценарии использования](#сценарии-использования)
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+- [Структура конфигов](#структура-конфигов)
+- [Конфигурация экспорта](#конфигурация-экспорта)
+- [Тесты](#тесты)
+
+## Возможности
+
+- **Инкрементальный экспорт** -- при повторном запуске скачиваются только новые сообщения и файлы, состояние хранится в SQLite
+- **Sibling-дедупликация** -- при экспорте нескольких аккаунтов (семья, рабочий/личный) общие файлы не скачиваются повторно, а линкуются через hardlink
+- **Импорт из tdesktop** -- файлы из стандартного экспорта Telegram Desktop копируются вместо повторного скачивания
+- **Takeout API** -- использует официальный Takeout для обхода rate-limiting
+- **Гибкие правила экспорта** -- настройка по чатам, папкам, типам (personal, groups, channels, bots), с фильтрами по датам, типам медиа и размеру файлов
+- **Логика архивных чатов** -- чат считается архивным (`is_archived`) только если он присутствует исключительно в архиве Telegram. Если чат есть в основном списке диалогов или в именованной папке, он не помечается как архивный, даже если одновременно находится в архиве
+- **Проверка размера в runtime** -- если реальный размер файла превышает лимит, скачивание прерывается и частичный файл удаляется
+- **HTML-рендеринг по месяцам** -- каждый месяц в отдельном файле, с оглавлением (TOC) и навигацией prev/next
+- **Progress bars** -- основной прогресс по сообщениям + sub-progress bars для каждого скачиваемого файла
+- **Контроль свободного места** -- экспорт останавливается, если свободное место на диске падает ниже порога (`min_free_space` в `config.yaml`, по умолчанию 20 GB)
+- **Корректный shutdown** -- Ctrl+C сохраняет состояние, двойной Ctrl+C -- force shutdown с cleanup
+- **Поддержка прокси** -- SOCKS5, SOCKS4, HTTP прокси для подключения к Telegram API
+- **Данные в SQLite** -- все сообщения и метаданные хранятся в SQLite, что позволяет пересоздать HTML без обращения к Telegram API, строить поисковые индексы, подключить веб-интерфейс или использовать данные в любых других целях
+- **CLI для анализа** -- команда `tg info` для batch-запросов информации о чатах через API
+- **Очистка данных чата** -- команда `purge` для удаления данных конкретного чата из БД и с диска
+
+## Сценарии использования
+
+**Личный архив** -- экспорт всех личных переписок и групп с медиафайлами на локальный диск для долгосрочного хранения.
+
+**Семейный экспорт** -- экспорт аккаунтов нескольких членов семьи. Общие группы и каналы содержат одинаковые файлы -- sibling-дедупликация экономит место на диске через hardlink.
+
+**Выборочный экспорт** -- экспорт только нужных чатов/папок с правилами: рабочие чаты экспортируются, боты и публичные каналы пропускаются, для флудилок скачиваются только фото.
+
+**Миграция с tdesktop** -- если уже есть экспорт из Telegram Desktop, файлы из него импортируются без повторного скачивания.
+
+## Установка
+
+Из PyPI (экспериментально, не проверялось):
+
+```bash
+pip install tg-export
+```
+
+Для работы через прокси:
+
+```bash
+pip install tg-export[proxy]
+```
+
+Из исходников:
+
+```bash
+uv pip install -e .
+```
+
+## Быстрый старт
+
+### 1. Получить API credentials
+
+Зайти на [my.telegram.org](https://my.telegram.org), создать приложение, получить `api_id` и `api_hash`.
+
+```bash
+uv run tg-export auth credentials
+```
+
+Ввести `api_id` и `api_hash`. Они сохраняются в `~/.config/tg-export/api_credentials.yaml` и используются для всех аккаунтов.
+
+### 2. Настроить прокси (если нужен)
+
+Создать файл `~/.config/tg-export/config.yaml`:
+
+```yaml
+proxy:
+  type: socks5      # socks5, socks4, http
+  host: 127.0.0.1
+  port: 1080
+  # username: user   # опционально
+  # password: pass   # опционально
+```
+
+### 3. Залогиниться в Telegram
+
+```bash
+uv run tg-export auth add --name myaccount
+```
+
+Ввести номер телефона и код подтверждения. Сессия сохранится в `~/.config/tg-export/sessions/myaccount.session`.
+
+Для нескольких аккаунтов повторить с разными именами. Установить аккаунт по умолчанию:
+
+```bash
+uv run tg-export account default myaccount
+```
+
+### 4. Анализ чатов и каталог
+
+Получить каталог всех чатов аккаунта:
+
+```bash
+uv run tg-export list --output catalog.yaml
+uv run tg-export list --format json --output catalog.json
+```
+
+Посмотреть информацию о конкретных чатах (количество сообщений, последние сообщения):
+
+```bash
+uv run tg-export info 123456789 987654321
+uv run tg-export info --from-catalog catalog.json --type personal --last 3
+```
+
+### 5. Настройка правил экспорта
+
+Сгенерировать шаблон конфига:
+
+```bash
+uv run tg-export init
+```
+
+Конфиг создается в `~/.config/tg-export/myaccount.yaml`. Настроить правила: какие чаты экспортировать, какие пропускать, какие типы медиа скачивать.
+
+AI-агенты (Claude Code, Cursor и т.д.) могут помочь с настройкой: показать список чатов по категориям, задать вопросы о каждом и сформировать конфиг интерактивно.
+
+Пример конфига:
+
+```yaml
+output:
+  path: ./export_output/myaccount
+
+defaults:
+  media:
+    types: [all]
+    max_file_size: 100MB
+    concurrent_downloads: 3
+
+# Импорт файлов из существующего экспорта tdesktop
+import_existing:
+  - path: ~/Downloads/Telegram Desktop/DataExport
+    type: tdesktop
+
+# Правила по типам чатов
+type_rules:
+  bots:
+    skip: true
+  public:
+    skip: true
+  personal: {}    # экспортировать все личные чаты
+  self: {}        # экспортировать Saved Messages
+
+# Правила по папкам Telegram
+folders:
+  Work: {}
+  Family:
+    media:
+      types: [photo, video]
+
+# Правила по конкретным чатам
+chats:
+  - id: 777000
+    name: Telegram
+    action: skip
+  - id: 123456789
+    name: "Important Chat"
+    media:
+      types: []    # без медиа
+
+# Что делать с чатами, не попавшими ни в одно правило
+unmatched: skip
+```
+
+### 6. Запустить экспорт
+
+```bash
+uv run tg-export run
+```
+
+Для пробного запуска без скачивания:
+
+```bash
+uv run tg-export run --dry-run
+```
+
+При повторном запуске скачиваются только новые сообщения (инкрементальный экспорт).
+
+### 7. Sibling-дедупликация
+
+При экспорте нескольких аккаунтов в один каталог (`./export_output/`), tg-export автоматически находит соседние базы данных и использует уже скачанные файлы через hardlink:
+
+```
+export_output/
+  account1/         # первый аккаунт
+  account2/         # файлы из общих чатов линкуются из account1
+```
+
+## Структура конфигов
+
+```
+~/.config/tg-export/
+  api_credentials.yaml      # API ID и Hash (общие для всех аккаунтов)
+  config.yaml               # Глобальные настройки (proxy, min_free_space)
+  default_account            # Имя аккаунта по умолчанию
+  sessions/
+    myaccount.session        # Telethon-сессия
+  myaccount.yaml             # Конфиг экспорта для аккаунта
+
+export_output/
+  myaccount/
+    .tg-export-state.db      # SQLite: состояние экспорта, сообщения, файлы
+    unfiled/
+      Chat_Name_123456/
+        messages.html         # Redirect на первый месяц
+        messages_2024-01.html # Сообщения за январь 2024
+        messages_2024-02.html # Сообщения за февраль 2024
+        photos/               # Скачанные фото
+        videos/               # Скачанные видео
+        files/                # Скачанные документы
+    folders/
+      Work/
+        ...
+```
+
+## Тесты
+
+```bash
+uv run python -m pytest tests/ -v
+```
+
+## Лицензия
+
+[MIT License](LICENSE)

tg_export-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tg-export"
+version = "1.0.0"
+description = "Flexible Telegram data export tool"
+license = "MIT"
+requires-python = ">=3.11"
+readme = "README.md"
+authors = [{name = "Vitaly Ostanin", email = "vitaly.ostanin@gmail.com"}]
+dependencies = [
+    "telethon>=1.36",
+    "pyyaml>=6.0",
+    "aiosqlite>=0.20",
+    "jinja2>=3.1",
+    "click>=8.0",
+    "rich>=13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/VitalyOstanin/tg-export"
+Repository = "https://github.com/VitalyOstanin/tg-export"
+Issues = "https://github.com/VitalyOstanin/tg-export/issues"
+
+[project.optional-dependencies]
+proxy = [
+    "python-socks[asyncio]>=2.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.setuptools.packages.find]
+include = ["tg_export*"]
+
+[project.scripts]
+tg-export = "tg_export.cli:main"

tg_export-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+