Přiveďte své dokumenty do AI pipeline — přímo z Pythonu, on‑premise, jedním pip install.

Dnes uvádíme první veřejné vydání GroupDocs.Markdown pro Python přes .NET na PyPI. Knihovna převádí PDF, Word, Excel, EPUB a více než 20 dalších formátů do čistého, sémantického Markdownu — formátu, se kterým LLM, RAG pipeline a generátory statických webů pracují nejlépe.

Pokud jste sledovali .NET vydání ze září (nebo kompletní přepsání API ve verzi 26.3), motivace je stejná: formátování dokumentu nese sémantiku a zachování této sémantické struktury je to, co umožňuje RAG systému poskytovat dobré odpovědi. Předchozí příspěvek podrobně popisuje problém (OCR zplošťuje strukturu, LLM potřebují markdown) a řešení (renderer založený na DOM, který prochází dokument a generuje Markdown) — tuto část zde nebudeme opakovat.

Místo toho se zaměříme na to, co je nového pro vývojáře v Pythonu.

What you get

  • Jedna jediná wheel, žádné runtime závislosti. pip install groupdocs-markdown-net stáhne samostatnou wheel, která obsahuje .NET runtime i všechny nativní knihovny, které potřebuje. Žádná instalace dotnet, žádný Microsoft Office, žádný Adobe Acrobat, žádné cloudové služby.
  • Cross‑platform. Windows x64/x86, Linux x64, macOS x64 a Apple Silicon (ARM64). Python 3.5 až 3.14.
  • Pythonický API. Třídy používají PascalCase, metody a vlastnosti snake_case, enumy UPPER_SNAKE_CASE. Kontextoví manažeři deterministicky uvolňují načtené dokumenty.
  • Skutečně asynchronní. Každá statická i instance metoda má ekvivalent s příponou _async. I/O souborů je asynchronní a CPU‑intenzivní konverze běží ve worker threadu — váš asyncio event loop zůstává volný.
  • Přátelský k AI agentům. Instalovaná wheel obsahuje soubor AGENTS.md, takže kódovací asistenti (Claude Code, Cursor, GitHub Copilot, Codex) automaticky objeví API, idiomatické vzory použití a tipy na řešení problémů. Dokumentace je také publikována jako llms.txt, jednosouborový korpus (llms-full.txt), per‑page Markdown a MCP server — viz sekce AI-friendly by design níže.

Začínáme

pip install groupdocs-markdown-net

Nejjednodušší konverze je jednorázový příkaz:

from groupdocs.markdown import MarkdownConverter

# Převod na řetězec
md = MarkdownConverter.to_markdown("business-plan.docx")

# Nebo přímý zápis do souboru
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

A to je vše — žádná konfigurace, žádné volby, žádný boilerplate. Režim hodnocení zpracuje první 3 stránky a přidá vodoznak. Pro odstranění limitů použijte licenci:

from groupdocs.markdown import License

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

Nebo nastavte proměnnou prostředí GROUPDOCS_LIC_PATH a licence se aplikuje automaticky při importu.

Podporované formáty

Python balíček podporuje stejnou šíři formátů jako .NET knihovna:

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

Pythonické příklady

Možnosti konverze a strategie obrázků

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    # přidá YAML metadata na začátek
options.image_export_strategy = strategy

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

Inspekce dokumentu bez konverze

from groupdocs.markdown import MarkdownConverter

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

Načtení souboru chráněného heslem

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)

Streamy a kontextoví manažeři

from groupdocs.markdown import MarkdownConverter

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

Asynchroní API — konverze mnoha dokumentů najednou

Protože I/O souborů je asynchronní, asyncio.gather() umožní jednomu workeru zpracovat mnoho dokumentů bez blokování:

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())

To dělá knihovnu přirozenou volbou pro ASGI frameworky jako FastAPI — jeden worker může obsloužit mnoho souběžných požadavků na konverzi bez soutěže o vlákna.

Ošetření chyb

Všechny konverzní metody při selhání vyhazují výjimky, s konkrétními typy pro běžné scénáře:

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

try:
    MarkdownConverter.to_file("annual-report.docx", "annual-report.md")
except DocumentProtectedException:
    print("Špatné nebo chybějící heslo.")
except InvalidFormatException:
    print("Soubor je poškozený nebo nepodporovaný.")
except GroupDocsMarkdownException as ex:
    print(f"Konverze selhala: {ex}")

Vytvořeno pro RAG a LLM pipeline

Markdown je preferovaný vstupní formát pro embedding modely a retrieval pipeline — zachovává nadpisy, seznamy, tabulky a formátování a zároveň se snadno chunkuje a tokenizuje. Typický RAG ingest vypadá takto:

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

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # pouze text pro 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()

# Rozdělení podle nadpisů nejvyšší úrovně, pak embedování/indextování každého úseku
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

Protože knihovna běží zcela on‑premise, citlivé dokumenty nikdy neopustí vaše prostředí — běžná požadavek v regulovaných odvětvích, právních týmech a interních znalostních bázích.

AI‑friendly by design

Většina Python SDK považuje AI asistenty za doplněk — vývojář stále musí ukázat agentovi dokumentaci, vložit příklady nebo ladit zkoušením a omyly. GroupDocs.Markdown pro Python přes .NET to obrací: knihovna je navržena tak, aby asistenti jako Claude Code, Cursor, GitHub Copilot a Codex mohli pracovat bez jakékoli manuální konfigurace.

AGENTS.md je součástí wheelu

Jedná se o první balíček GroupDocs, který v balíčku wheel zahrnuje AGENTS.md. Soubor následuje rostoucí konvenci AGENTS.md — čistý Markdown README psaný speciálně pro AI kódovací asistenty, ne pro lidi.

Po pip install groupdocs-markdown-net se soubor objeví na:

site-packages/groupdocs/markdown/AGENTS.md

AI asistent, který otevře váš projekt, může soubor přečíst a okamžitě se naučit:

  • Kompletní veřejné API (třídy, metody, enumy, výjimky) a jejich vztahy.
  • Idiomatické vzory použití pro nejčastější scénáře — statické vs. instance API, sync vs. async, strategie obrázků, front matter, ošetření chyb.
  • Běžné úskalí a jak se jim vyhnout — např. které přetížení ConvertOptions akceptuje None, jak zacházet se soubory chráněnými heslem, jak zachytit varování konverze.
  • Řešení problémů specifických pro platformu (libSkiaSharp na macOS, ICU na Linuxu).

V praxi to znamená, že můžete říct „použij groupdocs-markdown-net k převodu této složky PDF do Markdownu pro můj RAG pipeline“ a agent napíše funkční kód na první pokus — žádná halucinovaná jména metod, žádné špatné pořadí argumentů, žádné hádání importů.

Strojově čitelná dokumentace

Pro agenty, kteří potřebují najít něco, co není v AGENTS.md, je plná produktová dokumentace také publikována ve strojově čitelné formě:

  • Jednosouborový korpus — kompletní dokumentace jako jeden spojený Markdown soubor, připravený vložit do kontextového okna agenta:
    https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • Per‑page Markdown — přidejte .md k libovolné URL dokumentace a získáte surový zdroj:
    https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • llms.txt index — tabulka obsahu ve stylu llms.txt, která agentům ukazuje, kde najít potřebné stránky:
    https://docs.groupdocs.com/markdown/python-net/llms.txt

MCP server pro živé dotazy do dokumentace

Pro agenty, kteří používají Model Context Protocol, poskytujeme dokumentaci jako MCP server. Přidejte toto do konfigurace Claude Code nebo Cursor:

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

Poté může váš agent dotazovat dokumentaci na vyžádání místo spoléhaní se na tréninková data, která mohou být zastaralá.

Markdown dovnitř, Markdown ven

Je zde pěkná symetrie: výstup knihovny je Markdown — formát, který LLM nejlépe parsují pro RAG — a její dokumentace je také v Markdownu, poskytovaná jako jeden soubor pro snadné nasazení do kontextového okna. Ať už žádáte agenta, aby napsal kód používající knihovnu, nebo aby pochopil vaše dokumenty pomocí knihovny, Markdown je společným médiem.

Příklad exportu

Ukázky výše jsou téměř nejkratším užitečným programem, který můžete s knihovnou napsat. Zde je stejný nápad zabalený jako spustitelný projekt — zdrojový dokument, Python skript, předgenerovaný výstup, requirements.txt a Dockerfile — abyste si to mohli vyzkoušet od začátku do konce bez psaní čehokoli od nuly.

Zdrojový DOCX

Zdrojový soubor business-plan.docx je krátký, bohatě formátovaný podnikatelský plán s nadpisy, tabulkami, obrázky a metadaty.

Python skript

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """Převod Word dokumentu do Markdownu s GitHub flavor a YAML front matter."""

    # Jednorázový řádek — vrací Markdown řetězec
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # S možnostmi — zapíše do souboru
    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()

Výstupní Markdown

Výstup quick-example.md začíná blokem YAML front‑matter automaticky extrahovaným z metadat dokumentu, následovaným převedeným obsahem s GitHub Flavored tabulkami a posunutou hierarchií nadpisů (připravený k vložení do většího dokumentu).

Spustitelná ukázková aplikace

Vše v jednom: sample-app.zip. Rozbalte, pak:

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

Nebo spusťte v Dockeru — přiložený Dockerfile nastaví závislost ICU, kterou potřebuje zabalený .NET runtime na Linuxu:

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

Shrnutí

GroupDocs.Markdown pro Python přes .NET přináší plnohodnotný engine pro převod dokumentů na Markdown do Pythonu jako samostatnou wheel — žádný externí runtime, žádný cloud, žádná překvapení. Pythonické API, podpora async a první třída integrace AI nástrojů z něj dělají praktickou volbu pro Python týmy stavějící RAG systémy, generátory statických stránek nebo pipeline pro zpracování dokumentů.

Další informace

Podpora a zpětná vazba

Pro otázky nebo technickou pomoc použijte náš Free Support Forum — rádi pomůžeme.