confluence-md-exporter 1.0.0__tar.gz

confluence_md_exporter-1.0.0/.env.example

@@ -0,0 +1,18 @@
+# Optional. Prefer CLI flags: --user, --token, --base-url, --input, --output.
+# Do not commit `.env`.
+
+# Application base: origin + optional context path. No /wiki, no trailing slash.
+# If empty, inferred from absolute URLs in the input file.
+CONFLUENCE_BASE_URL=
+CONFLUENCE_EDITION=datacenter
+# anonymous | bearer | basic. If empty, inferred from username/token.
+CONFLUENCE_AUTH_TYPE=
+CONFLUENCE_TOKEN=
+CONFLUENCE_USERNAME=
+CONFLUENCE_VERIFY_SSL=true
+CONFLUENCE_TIMEOUT_SECONDS=30
+CONFLUENCE_MAX_RETRIES=3
+EXPORT_OUTPUT_DIR=output
+EXPORT_INPUT_FILE=input/urls.txt
+EXPORT_FORCE_REFRESH=false
+LOG_LEVEL=INFO

confluence_md_exporter-1.0.0/.gitignore

@@ -0,0 +1,41 @@
+# Local export dumps
+data/
+output/
+
+# Local URL lists (keep the example committed)
+input/*
+!input/urls.txt.example
+
+# Credentials (keep `.env.example`)
+.env
+.env.*
+!.env.example
+
+# IDE
+.idea/
+.vscode/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+pip-log.txt
+pip-delete-this-directory.txt
+.tox
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+.hypothesis
+.pytest_cache/
+*.egg-info/
+dist/
+build/

confluence_md_exporter-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

confluence_md_exporter-1.0.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Изменения в сервисе
+
+## Unreleased
+
+## 1.0.0 — 2026-09-15
+
+Первый публичный релиз на PyPI.
+
+- запуск без `.env`: аноним по умолчанию, `-u`/`-t` для доступа, база из списка URL
+- выгрузка всегда однопоточная, без Prefect; прогресс каждой страницы в консоли; снимок Prefect — тег `history/prefect-orchestration`
+- default `EXPORT_OUTPUT_DIR` — `output/` (`01-configuration.md`, `03-output.md#layout`)
+- 17 именованные HTML-сущности в Storage Format не валят страницу (`05-transform.md#edge-cases`)
+- тест-кейсы живут в `tests/`, не отдельным каталогом в `docs/` (`07-testing.md#test-cases`)
+- процесс: `/init-requirements` при непустом `docs/init/` спрашивает архив, сброс или стоп (`01-init-requirements.md#existing-init`)
+- процесс: тесты слайса сначала красные на текущем коде, затем фиксация; красное не коммитить
+- процесс: в конце реализации явно `spec unchanged`, если `docs/spec/**` не менялся
+- 15 проба идентичности fail-closed: любой не-успех (в т.ч. 404, HTML) — выход `2`
+- 14 явные причины отклонения URL (`invalid_urls` как `{url, reason}`)
+- процесс: фреймворк DeltaFuse (`delta-fuse`), гайд `docs/process/using.md`
+- процесс: сквозной NN inbox, auto-commit шага, таблица Closed в docs/todo/README.md

confluence_md_exporter-1.0.0/LICENSE

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

confluence_md_exporter-1.0.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.5
+Name: confluence-md-exporter
+Version: 1.0.0
+Summary: Local read-only export of Confluence Server/Data Center pages to Markdown
+Project-URL: Homepage, https://github.com/gste/confluence-md-exporter
+Project-URL: Repository, https://github.com/gste/confluence-md-exporter
+Project-URL: Issues, https://github.com/gste/confluence-md-exporter/issues
+Project-URL: Changelog, https://github.com/gste/confluence-md-exporter/blob/master/CHANGELOG.md
+Author-email: gste <ghostegor@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: confluence,datacenter,export,markdown,wiki
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+
+# confluence-md-exporter
+
+Локальный read-only конвейер: выгрузка страниц Confluence Server/Data Center → Markdown, медиа-ассеты, diff-сравнение версий и каталог батча. Закон реализации — [спецификация](https://github.com/gste/confluence-md-exporter/blob/master/docs/spec/README.md).
+
+## Установка
+
+Требуется Python `>=3.11,<3.14`.
+
+```bash
+pip install confluence-md-exporter
+```
+
+Или через `uv`:
+
+```bash
+uv tool install confluence-md-exporter
+```
+
+Из исходников:
+
+```bash
+uv sync
+```
+
+## Запуск
+
+По умолчанию: вход `input/urls.txt`, выход `output/`, доступ анонимный. База Confluence берётся из абсолютных URL в списке — отдельный `--base-url` не нужен, если в файле есть полные ссылки.
+
+Стартовый список ссылок:
+
+```bash
+cp input/urls.txt.example input/urls.txt
+```
+
+Закрытый инстанс (нужны учётные данные):
+
+```bash
+uv run confluence-md-exporter -u USER -t TOKEN
+```
+
+Только PAT (Bearer):
+
+```bash
+uv run confluence-md-exporter -t TOKEN
+```
+
+`.env` не обязателен. Если удобнее держать креды в файле — [`.env.example`](https://github.com/gste/confluence-md-exporter/blob/master/.env.example) и `uv run --env-file .env confluence-md-exporter`. CLI-флаги перекрывают окружение.
+
+---
+
+## Форматы входных ссылок (input/urls.txt)
+
+Файл `input/urls.txt` (UTF-8, одна ссылка на строку; строки с `#` и пустые строки игнорируются).
+
+Поддерживаются:
+1. **Прямые страницы по ID**:
+   - `https://confluence.example.com/pages/viewpage.action?pageId=123456`
+   - `https://confluence.example.com/wiki/spaces/SPACE/pages/123456/Some+Page+Title`
+   - `123456` (чистый идентификатор)
+2. **Страницы по Space и Title**:
+   - `https://confluence.example.com/display/SPACE/Page+Title`
+3. **Diff-страницы (сравнение версий)**:
+   - `https://confluence.example.com/pages/diffpagesbyversion.action?pageId=607636678&selectedPageVersions=41&selectedPageVersions=42`
+   - `https://confluence.example.com/pages/diffpagesbyversion.action?pageId=607636678&originalVersion=41&revisedVersion=42`
+
+*Примечание: неподдерживаемые форматы (tiny-link `/x/...` и т.д.) помечаются в `run_report.json` как `invalid_urls` и не валят батч.*
+
+---
+
+## CLI команды и флаги
+
+```text
+usage: confluence-md-exporter [-h] [--version] [-i INPUT] [-o OUTPUT]
+                              [-u USER] [-t TOKEN] [--base-url URL] [-r] [-c] [-s]
+
+options:
+  --version             Версия пакета
+  -i, --input INPUT     Список URL (default: input/urls.txt)
+  -o, --output OUTPUT   Каталог выгрузки (default: output)
+  -u, --user USER       Имя пользователя (вместе с -t — HTTP Basic)
+  -t, --token TOKEN     PAT или пароль
+  --base-url URL        База инстанса, если её нельзя вывести из списка URL
+  -r, --refresh         Игнорировать disk-skip
+  -c, --clean           Очистить каталог выгрузки перед работой
+```
+
+Выгрузка всегда однопоточная: один процесс, страницы строго последовательно, без Prefect и без лишних серверов. В консоли на уровне INFO виден прогресс каждой страницы и итоговая сводка.
+
+---
+
+## Примеры использования
+
+### 1. Обычный запуск
+Выгрузка страниц по списку из `input/urls.txt` (анонимно, база из URL):
+```bash
+uv run confluence-md-exporter
+```
+
+### 2. Чистая выгрузка с очисткой папки
+Полная очистка папки выгрузки и выгрузка заново:
+```bash
+uv run confluence-md-exporter -c
+```
+
+### 3. Принудительное обновление кэша (Refresh)
+Перескачивание контента даже при совпадении версий на диске:
+```bash
+uv run confluence-md-exporter -r
+```
+
+### 4. Указание произвольных входных и выходных путей
+```bash
+uv run confluence-md-exporter -i ./my_pages.txt -o ./exports/march_release
+```
+
+### 5. Выгрузка разницы версий (Diff)
+Добавь в файл ссылок URL вида:
+```text
+https://confluence.example.com/pages/diffpagesbyversion.action?pageId=607636678&selectedPageVersions=41&selectedPageVersions=42
+```
+И запусти:
+```bash
+uv run confluence-md-exporter
+```
+В результате в папке `05_diffs/` будет создан файл `607636678_title_v41_to_v42.md` с YAML-метаданными (авторы версий, даты, статистика `+X/-Y`) и блоком ` ```diff `.
+
+---
+
+## Структура выгрузки (Output)
+
+```text
+output/
+├── 01_raw/             # Сырой Confluence JSON ответа REST API
+├── 02_interim/         # Storage XML страницы
+├── 03_assets/          # Скачанные вложения и картинки (по page_id)
+├── 04_markdown/        # Итоговый Markdown (*.md) и manifest.json
+├── 05_diffs/           # Unified diff между версиями страниц (*_v41_to_v42.md)
+└── run_report.json     # Сводный отчет о результатах выгрузки батча
+```
+
+---
+
+## Коды возврата (Exit Codes)
+
+- `0` — успех (все страницы обработаны со статусом `ok` или `skipped`);
+- `1` — частичная ошибка (хотя бы одна страница завершилась со статусом `failed`);
+- `2` — критическая ошибка конфигурации / непройденная авторизация / отсутствует входной файл.
+
+---
+
+## Разработка и тестирование
+
+Запуск полного набора тестов:
+```bash
+uv run python -m pytest
+```

confluence_md_exporter-1.0.0/README.md

@@ -0,0 +1,156 @@
+# confluence-md-exporter
+
+Локальный read-only конвейер: выгрузка страниц Confluence Server/Data Center → Markdown, медиа-ассеты, diff-сравнение версий и каталог батча. Закон реализации — [спецификация](https://github.com/gste/confluence-md-exporter/blob/master/docs/spec/README.md).
+
+## Установка
+
+Требуется Python `>=3.11,<3.14`.
+
+```bash
+pip install confluence-md-exporter
+```
+
+Или через `uv`:
+
+```bash
+uv tool install confluence-md-exporter
+```
+
+Из исходников:
+
+```bash
+uv sync
+```
+
+## Запуск
+
+По умолчанию: вход `input/urls.txt`, выход `output/`, доступ анонимный. База Confluence берётся из абсолютных URL в списке — отдельный `--base-url` не нужен, если в файле есть полные ссылки.
+
+Стартовый список ссылок:
+
+```bash
+cp input/urls.txt.example input/urls.txt
+```
+
+Закрытый инстанс (нужны учётные данные):
+
+```bash
+uv run confluence-md-exporter -u USER -t TOKEN
+```
+
+Только PAT (Bearer):
+
+```bash
+uv run confluence-md-exporter -t TOKEN
+```
+
+`.env` не обязателен. Если удобнее держать креды в файле — [`.env.example`](https://github.com/gste/confluence-md-exporter/blob/master/.env.example) и `uv run --env-file .env confluence-md-exporter`. CLI-флаги перекрывают окружение.
+
+---
+
+## Форматы входных ссылок (input/urls.txt)
+
+Файл `input/urls.txt` (UTF-8, одна ссылка на строку; строки с `#` и пустые строки игнорируются).
+
+Поддерживаются:
+1. **Прямые страницы по ID**:
+   - `https://confluence.example.com/pages/viewpage.action?pageId=123456`
+   - `https://confluence.example.com/wiki/spaces/SPACE/pages/123456/Some+Page+Title`
+   - `123456` (чистый идентификатор)
+2. **Страницы по Space и Title**:
+   - `https://confluence.example.com/display/SPACE/Page+Title`
+3. **Diff-страницы (сравнение версий)**:
+   - `https://confluence.example.com/pages/diffpagesbyversion.action?pageId=607636678&selectedPageVersions=41&selectedPageVersions=42`
+   - `https://confluence.example.com/pages/diffpagesbyversion.action?pageId=607636678&originalVersion=41&revisedVersion=42`
+
+*Примечание: неподдерживаемые форматы (tiny-link `/x/...` и т.д.) помечаются в `run_report.json` как `invalid_urls` и не валят батч.*
+
+---
+
+## CLI команды и флаги
+
+```text
+usage: confluence-md-exporter [-h] [--version] [-i INPUT] [-o OUTPUT]
+                              [-u USER] [-t TOKEN] [--base-url URL] [-r] [-c] [-s]
+
+options:
+  --version             Версия пакета
+  -i, --input INPUT     Список URL (default: input/urls.txt)
+  -o, --output OUTPUT   Каталог выгрузки (default: output)
+  -u, --user USER       Имя пользователя (вместе с -t — HTTP Basic)
+  -t, --token TOKEN     PAT или пароль
+  --base-url URL        База инстанса, если её нельзя вывести из списка URL
+  -r, --refresh         Игнорировать disk-skip
+  -c, --clean           Очистить каталог выгрузки перед работой
+```
+
+Выгрузка всегда однопоточная: один процесс, страницы строго последовательно, без Prefect и без лишних серверов. В консоли на уровне INFO виден прогресс каждой страницы и итоговая сводка.
+
+---
+
+## Примеры использования
+
+### 1. Обычный запуск
+Выгрузка страниц по списку из `input/urls.txt` (анонимно, база из URL):
+```bash
+uv run confluence-md-exporter
+```
+
+### 2. Чистая выгрузка с очисткой папки
+Полная очистка папки выгрузки и выгрузка заново:
+```bash
+uv run confluence-md-exporter -c
+```
+
+### 3. Принудительное обновление кэша (Refresh)
+Перескачивание контента даже при совпадении версий на диске:
+```bash
+uv run confluence-md-exporter -r
+```
+
+### 4. Указание произвольных входных и выходных путей
+```bash
+uv run confluence-md-exporter -i ./my_pages.txt -o ./exports/march_release
+```
+
+### 5. Выгрузка разницы версий (Diff)
+Добавь в файл ссылок URL вида:
+```text
+https://confluence.example.com/pages/diffpagesbyversion.action?pageId=607636678&selectedPageVersions=41&selectedPageVersions=42
+```
+И запусти:
+```bash
+uv run confluence-md-exporter
+```
+В результате в папке `05_diffs/` будет создан файл `607636678_title_v41_to_v42.md` с YAML-метаданными (авторы версий, даты, статистика `+X/-Y`) и блоком ` ```diff `.
+
+---
+
+## Структура выгрузки (Output)
+
+```text
+output/
+├── 01_raw/             # Сырой Confluence JSON ответа REST API
+├── 02_interim/         # Storage XML страницы
+├── 03_assets/          # Скачанные вложения и картинки (по page_id)
+├── 04_markdown/        # Итоговый Markdown (*.md) и manifest.json
+├── 05_diffs/           # Unified diff между версиями страниц (*_v41_to_v42.md)
+└── run_report.json     # Сводный отчет о результатах выгрузки батча
+```
+
+---
+
+## Коды возврата (Exit Codes)
+
+- `0` — успех (все страницы обработаны со статусом `ok` или `skipped`);
+- `1` — частичная ошибка (хотя бы одна страница завершилась со статусом `failed`);
+- `2` — критическая ошибка конфигурации / непройденная авторизация / отсутствует входной файл.
+
+---
+
+## Разработка и тестирование
+
+Запуск полного набора тестов:
+```bash
+uv run python -m pytest
+```

confluence_md_exporter-1.0.0/input/urls.txt.example

@@ -0,0 +1,3 @@
+# Copy to input/urls.txt. One URL per line. Lines starting with # are ignored.
+https://confluence.example.com/pages/viewpage.action?pageId=123456
+https://confluence.example.com/display/SPACE/Page+Title

confluence_md_exporter-1.0.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "confluence-md-exporter"
+version = "1.0.0"
+description = "Local read-only export of Confluence Server/Data Center pages to Markdown"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11,<3.14"
+authors = [
+    { name = "gste", email = "ghostegor@gmail.com" },
+]
+keywords = [
+    "confluence",
+    "markdown",
+    "export",
+    "datacenter",
+    "wiki",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Documentation",
+    "Topic :: Text Processing :: Markup",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/gste/confluence-md-exporter"
+Repository = "https://github.com/gste/confluence-md-exporter"
+Issues = "https://github.com/gste/confluence-md-exporter/issues"
+Changelog = "https://github.com/gste/confluence-md-exporter/blob/master/CHANGELOG.md"
+
+[project.scripts]
+confluence-md-exporter = "confluence_md_exporter.cli:entry"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/confluence_md_exporter"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.cursor",
+    "/.github",
+    "/docs",
+    "/AGENTS.md",
+    "/TODO.md",
+    "/uv.lock",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

confluence_md_exporter-1.0.0/src/confluence_md_exporter/__init__.py

@@ -0,0 +1,8 @@
+"""Local read-only Confluence Server/Data Center to Markdown exporter."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("confluence-md-exporter")
+except PackageNotFoundError:  # pragma: no cover - source tree without install
+    __version__ = "1.0.0"

confluence_md_exporter-1.0.0/src/confluence_md_exporter/assets.py

@@ -0,0 +1,70 @@
+"""Download page attachments over REST and write them under 03_assets."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from confluence_md_exporter.client import ConfluenceClient
+from confluence_md_exporter.layout import asset_file_path, unique_safe_filenames
+from confluence_md_exporter.output import write_asset_sidecar
+
+logger = logging.getLogger(__name__)
+
+
+def missing_attachment_placeholder(original: str) -> str:
+    return f"[missing-attachment: {original}]"
+
+
+@dataclass
+class AssetSyncResult:
+    original_to_safe: dict[str, str]
+    missing_placeholders: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    sidecar_path: Path | None = None
+
+    @property
+    def page_failed(self) -> bool:
+        return False
+
+
+def sync_page_assets(
+    client: ConfluenceClient,
+    output_dir: Path,
+    page_id: str,
+    attachments: Sequence[Mapping[str, Any]],
+) -> AssetSyncResult:
+    originals = [str(item.get("title") or "") for item in attachments]
+    names = unique_safe_filenames(originals)
+    downloaded: dict[str, str] = {}
+    missing: list[str] = []
+    warnings: list[str] = []
+
+    for item in attachments:
+        original = str(item.get("title") or "")
+        safe = names[original]
+        url = client.attachment_download_url(item)
+        if "/download/attachments/" in url:
+            raise RuntimeError("UI attachment path must not be used as the primary download")
+        response = client.download(url)
+        if response.status >= 400:
+            placeholder = missing_attachment_placeholder(original)
+            warning = f"attachment not downloaded: {original}"
+            missing.append(placeholder)
+            warnings.append(warning)
+            logger.warning(warning)
+            continue
+        path = output_dir / asset_file_path(page_id, safe)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(response.body)
+        downloaded[original] = safe
+
+    sidecar = write_asset_sidecar(output_dir, page_id, downloaded)
+    return AssetSyncResult(
+        original_to_safe=downloaded,
+        missing_placeholders=missing,
+        warnings=warnings,
+        sidecar_path=sidecar,
+    )