Приведіть ваші документи у AI‑конвеєри — безпосередньо з Python, локально, за допомогою одного pip install.

Сьогодні ми випускаємо перший публічний реліз GroupDocs.Markdown для Python через .NET на PyPI. Бібліотека перетворює PDF, Word, Excel, EPUB та понад 20 інших форматів у чистий, семантичний Markdown — формат, з яким найкраще працюють LLM, RAG‑конвеєри та статичні генератори сайтів.

Якщо ви слідкували за .NET‑релізом у вересні (або повним оновленням API у 26.3), мотивація та сама: форматування документу несе семантику, і збереження цієї семантичної структури — це те, що дозволяє RAG‑системі давати хороші відповіді. Попередній пост охоплює проблему (OCR сплющує структуру, LLM‑и потребують markdown) та рішення (рендерер на основі DOM, який проходить по документу і генерує Markdown) детально — ми не будемо повторювати цю історію тут.

Натомість зосередимося на новинках для розробників Python.

Що ви отримуєте

  • Один wheel, без залежностей під час виконання. pip install groupdocs-markdown-net завантажує самодостатній wheel, який включає .NET‑runtime та всі необхідні нативні бібліотеки. Ніякої установки dotnet, Microsoft Office, Adobe Acrobat чи хмарних сервісів.
  • Крос‑платформений. Windows x64/x86, Linux x64, macOS x64 та Apple Silicon (ARM64). Python 3.5‑3.14.
  • Pythonic API. Класи використовують PascalCase, методи та властивості — snake_case, значення enum — UPPER_SNAKE_CASE. Менеджери контексту детерміновано звільняють завантажені документи.
  • Справжня асинхронність. Кожен статичний і екземплярний метод має відповідник з суфіксом _async. Файловий I/O асинхронний, а CPU‑інтенсивне перетворення виконується у воркер‑потоці — ваш цикл asyncio залишається вільним.
  • Дружній до AI‑агентів. Встановлений wheel містить файл AGENTS.md, щоб код‑асистенти (Claude Code, Cursor, GitHub Copilot, Codex) автоматично виявляли API, типові патерни використання та поради з налагодження. Документація також публікується як llms.txt, один‑файловий корпус (llms-full.txt), по‑сторінковий Markdown та MCP‑сервер — дивіться розділ AI‑friendly by design нижче для деталей.

Перші кроки

pip install groupdocs-markdown-net

Найпростіше перетворення — однорядковий виклик:

from groupdocs.markdown import MarkdownConverter

# Перетворити у рядок
md = MarkdownConverter.to_markdown("business-plan.docx")

# Або записати безпосередньо у файл
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

Все — без налаштувань, без параметрів, без шаблонного коду. Режим оцінки обробляє перші 3 сторінки та додає водяний знак. Щоб зняти обмеження, застосуйте ліцензію:

from groupdocs.markdown import License

License().set_license("path/to/license.lic")

Або встановіть змінну середовища GROUPDOCS_LIC_PATH, і вона буде застосована автоматично під час імпорту.

Підтримувані формати

Python‑пакет обробляє той самий спектр форматів, що й .NET‑бібліотека:

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • Spreadsheets — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • eBooks — .epub, .mobi
  • Text / Markup / Help — .txt, .xml, .chm

Pythonic приклади

Параметри конвертації та стратегії зображень

from groupdocs.markdown import (
    MarkdownConverter,
    ConvertOptions,
    MarkdownFlavor,
    ExportImagesToFileSystemStrategy,
)

strategy = ExportImagesToFileSystemStrategy("output/images")
strategy.images_relative_path = "images"  # ![](images/img-001.png)

options = ConvertOptions()
options.flavor = MarkdownFlavor.GIT_HUB
options.heading_level_offset = 1      # # Title -> ## Title
options.include_front_matter = True    # prepend YAML metadata
options.image_export_strategy = strategy

MarkdownConverter.to_file("report.docx", "output/report.md", convert_options=options)

Перевірка документа без конвертації

from groupdocs.markdown import MarkdownConverter

info = MarkdownConverter.get_info("business-plan.docx")
print(f"{info.file_format}, {info.page_count} pages, author: {info.author}")

Завантаження файлу, захищеного паролем

from groupdocs.markdown import MarkdownConverter, LoadOptions, FileFormat

load_opts = LoadOptions(FileFormat.DOCX)
load_opts.password = "secret"

MarkdownConverter.to_file("protected.docx", "output.md", load_options=load_opts)

Потоки та менеджери контексту

from groupdocs.markdown import MarkdownConverter

with open("document.docx", "rb") as stream:
    with MarkdownConverter(stream) as converter:
        converter.convert("document.md")

Async API — одночасне конвертування багатьох документів

Оскільки файловий I/O асинхронний, asyncio.gather() дозволяє одному воркеру обробляти багато документів без блокувань:

import asyncio
from groupdocs.markdown import MarkdownConverter

async def convert_many():
    await asyncio.gather(
        MarkdownConverter.to_file_async("a.docx", "a.md", None),
        MarkdownConverter.to_file_async("b.pdf",  "b.md", None),
        MarkdownConverter.to_file_async("c.xlsx", "c.md", None),
    )

asyncio.run(convert_many())

Це робить бібліотеку природним вибором для ASGI‑фреймворків типу FastAPI — один воркер може обслуговувати багато одночасних запитів на конвертацію без конкуренції потоків.

Обробка помилок

Усі методи конвертації піднімають виключення у разі збою, з конкретними типами для поширених сценаріїв:

from groupdocs.markdown import (
    MarkdownConverter,
    DocumentProtectedException,
    InvalidFormatException,
    GroupDocsMarkdownException,
)

try:
    MarkdownConverter.to_file("annual-report.docx", "annual-report.md")
except DocumentProtectedException:
    print("Wrong or missing password.")
except InvalidFormatException:
    print("File is corrupt or unsupported.")
except GroupDocsMarkdownException as ex:
    print(f"Conversion failed: {ex}")

Створено для RAG та LLM‑конвеєрів

Markdown — бажаний вхідний формат для моделей embedding та retrieval‑конвеєрів — він зберігає заголовки, списки, таблиці та акценти, залишаючись простим для розбиття та токенізації. Типовий процес інжесту RAG виглядає так:

import re
from groupdocs.markdown import MarkdownConverter, ConvertOptions, SkipImagesStrategy, MarkdownFlavor

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # text-only for RAG
options.flavor = MarkdownFlavor.COMMON_MARK

MarkdownConverter.to_file("business-plan.pdf", "business-plan.md", convert_options=options)

with open("business-plan.md", "r", encoding="utf-8") as f:
    markdown = f.read()

# Split by top-level headings, then embed/index each chunk
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

Оскільки бібліотека працює повністю локально, конфіденційні документи ніколи не залишають ваше середовище — типова вимога для регульованих галузей, юридичних команд та внутрішніх баз знань.

AI‑friendly by design

Більшість Python‑SDK розглядають AI‑асистентів як післядум — розробнику доводиться вказувати агенту документацію, копіювати приклади або відлагоджувати методом проб‑і‑помилок. GroupDocs.Markdown для Python через .NET змінює це: бібліотека спроектована так, щоб агенти типу Claude Code, Cursor, GitHub Copilot та Codex могли одразу її підхопити без будь‑якої ручної настройки.

AGENTS.md постачається всередині wheel

Це перший пакет GroupDocs, який включає AGENTS.md безпосередньо у встановлений wheel. Файл слідує новій AGENTS.md конвенції — простому Markdown‑README, написаному спеціально для AI‑асистентів, а не для людей.

Після pip install groupdocs-markdown-net файл розташовується за шляхом:

site-packages/groupdocs/markdown/AGENTS.md

AI‑асистент, відкривши ваш проєкт, може прочитати його і миттєво дізнатися:

  • Повну public API surface (класи, методи, enum‑и, виключення) та їх взаємозв’язки.
  • Ідіоматичні патерни використання для найпоширеніших сценаріїв — статичний vs екземплярний API, sync vs async, стратегії зображень, front matter, обробка помилок.
  • Типові підводні камені і як їх уникнути — напр., які перевантаження ConvertOptions приймають None, як працювати з файлами, захищеними паролем, як захоплювати попередження конвертації.
  • Трюки з налагодженням для платформенно‑специфічних проблем (libSkiaSharp на macOS, ICU на Linux).

На практиці це означає, що ви можете сказати «використай groupdocs-markdown-net, щоб конвертувати цю папку PDF у Markdown для мого RAG‑конвеєра», і агент напише працюючий код з першої спроби — без вигаданих імен методів, без неправильного порядку аргументів, без вгадуваних імпортів.

Машинозчитувана документація

Для агентів, яким потрібно знайти щось, чого немає в AGENTS.md, повна документація також доступна у машинозчитуваному вигляді:

  • Одно‑файловий корпус — повна документація як один об’єднаний Markdown‑файл, готовий до вставки у контекст агента:
    https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • По‑сторінковий Markdown — додайте .md до будь‑якої URL‑адреси документації, щоб отримати сирий вихідний код:
    https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • Індекс llms.txt — таблиця змісту у стилі llms.txt, що вказує агентам потрібні сторінки:
    https://docs.groupdocs.com/markdown/python-net/llms.txt

MCP‑сервер для живих запитів до документації

Для агентів, які підтримують Model Context Protocol, ми надаємо документацію як MCP‑сервер. Додайте це у конфігурацію Claude Code або Cursor:

{
  "mcpServers": {
    "groupdocs-docs": {
      "url": "https://docs.groupdocs.com/mcp"
    }
  }
}

Після цього ваш агент зможе запитувати документацію за потребою, замість того, щоб покладатися на потенційно застарілі навчальні дані.

Markdown вхід — Markdown вихід

Тут є приємна симетрія: вихід бібліотеки — Markdown — формат, який LLM‑и найкраще розбирають у RAG, а документація також у Markdown, подана як один файл для легкого вживання у вікно контексту. Будь‑то ви просите агента написати код, що використовує бібліотеку, чи просите його зрозуміти ваші документи за її допомогою, Markdown є спільним середовищем.

Приклад експорту

Наведених вище фрагментів коду — це майже найкоротша корисна програма, яку можна написати з бібліотекою. Ось те ж саме, упаковане у готовий проєкт — вихідний документ, Python‑скрипт, попередньо згенерований результат, requirements.txt та Dockerfile — щоб ви могли спробувати end‑to‑end без написання чого‑небудь з нуля.

Вихідний DOCX

Вихідний файл business-plan.docx — короткий, багатоформатний бізнес‑план з заголовками, таблицями, зображеннями та метаданими.

Python‑скрипт

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """Convert a Word document to Markdown with GitHub flavor and YAML front matter."""

    # One-liner — returns a Markdown string
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # With options — writes to a file
    options = ConvertOptions()
    options.flavor = MarkdownFlavor.GIT_HUB
    options.include_front_matter = True
    options.heading_level_offset = 1
    MarkdownConverter.to_file("business-plan.docx", "quick-example.md", convert_options=options)

if __name__ == "__main__":
    quick_example()

Вихідний Markdown

Вихідний файл quick-example.md починається з блоку YAML front‑matter, автоматично витягнутого з метаданих документа, після чого йде конвертований вміст з таблицями у GitHub Flavored стилі та зсунутою ієрархією заголовків (готовий до вбудовування у більший документ).

Запускний приклад застосунку

Все в одному пакеті: sample-app.zip. Розпакуйте, потім:

cd src
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python quick_example.py

Або запустіть у Docker — включений Dockerfile встановлює залежність ICU, яку потребує вбудований .NET‑runtime на Linux:

cd src
docker build -t groupdocs-markdown-python-example .
docker run --rm -v "$(pwd)/output:/app/output" groupdocs-markdown-python-example

Підсумок

GroupDocs.Markdown для Python через .NET доставляє повноцінний движок перетворення документ‑у‑Markdown у Python у вигляді самодостатнього wheel — без зовнішнього рантайму, без хмари, без сюрпризів. Pythonic API, підтримка async та інтеграція першокласних AI‑інструментів роблять його практичним вибором для Python‑команд, які будують RAG‑системи, статичні генератори сайтів або конвеєри обробки документів.

Дізнатись більше

Підтримка та зворотний зв’язок

Для запитань або технічної допомоги, будь ласка, використовуйте наш Free Support Forum — будемо раді допомогти.