Wprowadź swoje dokumenty do potoków AI — prosto z Pythona, lokalnie, za pomocą jednego pip install.

Dziś udostępniamy pierwsze publiczne wydanie GroupDocs.Markdown dla Pythona poprzez .NET na PyPI. Biblioteka konwertuje PDF, Word, Excel, EPUB i ponad 20 innych formatów na czysty, semantyczny Markdown — format, z którym najlepiej współpracują LLM‑y, potoki RAG i generatory statycznych stron.

Jeśli śledziłeś .NET‑owe wydanie z września (lub pełny przegląd API w wersji 26.3), uzasadnienie jest takie samo: formatowanie dokumentu niesie semantykę, a zachowanie tej struktury semantycznej to klucz do uzyskiwania dobrych odpowiedzi w systemach RAG. Wcześniejszy wpis opisuje problem (OCR spłaszcza strukturę, LLM‑y potrzebują markdown) oraz rozwiązanie (renderer oparty na DOM, który przechodzi po dokumencie i generuje Markdown) szczegółowo — nie będziemy tego tutaj powtarzać.

Zamiast tego skupmy się na nowościach dla programistów Pythona.

Co otrzymujesz

  • Jedno koło, bez zależności w czasie wykonywania. pip install groupdocs-markdown-net pobiera samodzielne koło, które zawiera środowisko .NET oraz wszystkie potrzebne biblioteki natywne. Bez instalacji dotnet, bez Microsoft Office, bez Adobe Acrobat, bez usług w chmurze.
  • Wieloplatformowość. Windows x64/x86, Linux x64, macOS x64 oraz Apple Silicon (ARM64). Python 3.5‑3.14.
  • Pythonic API. Klasy używają PascalCase, metody i właściwości snake_case, wartości wyliczeń UPPER_SNAKE_CASE. Menedżery kontekstu zwalniają załadowane dokumenty deterministycznie.
  • Prawdziwie asynchroniczne. Każda metoda statyczna i instancyjna ma odpowiednik z _async. Operacje I/O są asynchroniczne, a konwersja CPU‑intensywna działa w wątku roboczym — Twoja pętla zdarzeń asyncio pozostaje wolna.
  • Przyjazne dla agentów AI. Zainstalowane koło zawiera plik AGENTS.md, dzięki czemu asystenci kodowania (Claude Code, Cursor, GitHub Copilot, Codex) automatycznie odkrywają interfejs API, idiomatyczne wzorce użycia i wskazówki rozwiązywania problemów. Dokumentacja jest także publikowana jako llms.txt, jednoplikowy korpus (llms-full.txt), Markdown per strona oraz serwer MCP — zobacz sekcję AI-friendly by design po szczegóły.

Rozpoczęcie

pip install groupdocs-markdown-net

Najprostsza konwersja to jednowierszowy kod:

from groupdocs.markdown import MarkdownConverter

# Convert to a string
md = MarkdownConverter.to_markdown("business-plan.docx")

# Or write directly to a file
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

To wszystko — bez konfiguracji, bez opcji, bez szablonów. Tryb ewaluacji przetwarza pierwsze 3 strony i dodaje znak wodny. Aby usunąć ograniczenia, zastosuj licencję:

from groupdocs.markdown import License

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

Albo ustaw zmienną środowiskową GROUPDOCS_LIC_PATH, a zostanie ona automatycznie zastosowana przy imporcie.

Obsługiwane formaty

Pakiet Pythona obsługuje taką samą gamę formatów jak biblioteka .NET:

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • Arkusze kalkulacyjne — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • e‑książki — .epub, .mobi
  • Tekst / Markup / Pomoc — .txt, .xml, .chm

Przykłady w stylu Pythonic

Opcje konwersji i strategie obrazów

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)

Inspekcja dokumentu bez konwersji

from groupdocs.markdown import MarkdownConverter

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

Ładowanie pliku zabezpieczonego hasłem

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)

Strumienie i menedżery kontekstu

from groupdocs.markdown import MarkdownConverter

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

Asynchroniczne API — konwersja wielu dokumentów jednocześnie

Ponieważ I/O jest asynchroniczne, asyncio.gather() pozwala jednemu pracownikowi przetwarzać wiele dokumentów bez blokowania:

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 sprawia, że biblioteka naturalnie pasuje do frameworków ASGI, takich jak FastAPI — jeden pracownik może obsługiwać wiele równoczesnych żądań konwersji bez rywalizacji wątków.

Obsługa błędów

Wszystkie metody konwersji zgłaszają wyjątki w razie niepowodzenia, z konkretnymi typami wyjątków dla typowych scenariuszy:

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}")

Zbudowane z myślą o RAG i potokach LLM

Markdown jest preferowanym formatem wejściowym dla modeli osadzających i potoków wyszukiwania — zachowuje nagłówki, listy, tabele i wyróżnienia, a jednocześnie jest łatwy do podziału i tokenizacji. Typowy proces ingestii RAG wygląda tak:

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

Ponieważ biblioteka działa w pełni lokalnie, wrażliwe dokumenty nigdy nie opuszczają Twojego środowiska — typowy wymóg w branżach regulowanych, zespołach prawnych i wewnętrznych bazach wiedzy.

AI-friendly by design

Większość SDK‑ów Pythona traktuje asystentów AI jako dodatek po fakcie — programista musi skierować agenta do dokumentacji, wkleić przykłady lub debugować metodą prób i błędów. GroupDocs.Markdown dla Pythona poprzez .NET odwraca tę sytuację: biblioteka jest zaprojektowana tak, aby agenci tacy jak Claude Code, Cursor, GitHub Copilot i Codex mogły ją wykorzystać bez żadnej ręcznej konfiguracji.

AGENTS.md jest dostarczany w kole

To pierwszy pakiet GroupDocs, który dołącza plik AGENTS.md bezpośrednio wewnątrz zainstalowanego koła. Plik podąża za rosnącą konwencją AGENTS.md — prostym README w Markdown napisanym specjalnie dla asystentów kodowania AI, a nie dla ludzi.

Po uruchomieniu pip install groupdocs-markdown-net plik znajduje się w:

site-packages/groupdocs/markdown/AGENTS.md

Asystent AI otwierający Twój projekt może go odczytać i od razu poznać:

  • Pełną publiczną powierzchnię API (klasy, metody, wyliczenia, wyjątki) oraz ich wzajemne zależności.
  • Idiomy użycia najczęstszych scenariuszy — API statyczne vs instancyjne, synchroniczne vs asynchroniczne, strategie obrazów, front matter, obsługa błędów.
  • Typowe pułapki i sposoby ich unikania — np. które przeciążenia ConvertOptions akceptują None, jak obsługiwać pliki zabezpieczone hasłem, jak przechwytywać ostrzeżenia konwersji.
  • Rozwiązywanie problemów specyficznych dla platform (libSkiaSharp na macOS, ICU na Linux).

W praktyce oznacza to, że możesz napisać: „użyj groupdocs-markdown-net, aby przekonwertować ten folder PDF‑ów na Markdown dla mojego potoku RAG” i agent wygeneruje działający kod za pierwszym razem — bez wymyślonych nazw metod, bez błędnej kolejności argumentów, bez zgadywania importów.

Dokumentacja czytelna dla maszyn

Dla agentów, które potrzebują informacji nieobecnych w AGENTS.md, pełna dokumentacja produktu jest również udostępniona w formacie przyjaznym maszynom:

  • Jednoplikowy korpus — kompletna dokumentacja jako jeden połączony plik Markdown, gotowy do wstawienia do okna kontekstu agenta:
    https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • Markdown per strona — dodaj .md do dowolnego URL dokumentacji, aby pobrać surowe źródło:
    https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • Indeks llms.txt — spis treści w stylu llms.txt, który kieruje agentów do potrzebnych stron:
    https://docs.groupdocs.com/markdown/python-net/llms.txt

Serwer MCP dla zapytań w czasie rzeczywistym

Dla agentów obsługujących Model Context Protocol, udostępniamy dokumentację jako serwer MCP. Dodaj to do konfiguracji Claude Code lub Cursor:

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

Po tym agenci mogą zapytać o dokumentację na żądanie, zamiast polegać na danych treningowych, które mogą być nieaktualne.

Markdown jako wejście i wyjście

Istnieje przyjemna symetria: wyjściem biblioteki jest Markdown — format, który LLM‑y najlepiej przetwarzają w RAG — a dokumentacja również jest w Markdown, udostępniona jako pojedynczy plik dla łatwego wczytania do okna kontekstu. Niezależnie od tego, czy prosisz agenta o napisanie kodu używającego biblioteki, czy o zrozumienie Twoich dokumentów przy jej pomocy, Markdown jest wspólnym medium.

Przykład eksportu

Powyższe fragmenty kodu to prawie najkrótszy użyteczny program, jaki możesz napisać z tą biblioteką. Oto ten sam pomysł spakowany jako gotowy projekt — dokument źródłowy, skrypt Pythona, wstępnie wygenerowany wynik, requirements.txt i Dockerfile — abyś mógł wypróbować go od początku do końca bez pisania czegokolwiek od zera.

Plik DOCX źródłowy

Plik źródłowy business-plan.docx to krótki, bogato sformatowany plan biznesowy z nagłówkami, tabelami, obrazami i metadanymi.

Skrypt Pythona

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

Wynikowy Markdown

Plik wyjściowy quick-example.md zaczyna się od bloku front‑matter w formacie YAML, automatycznie wyodrębnionego z metadanych dokumentu, po którym następuje skonwertowana treść z tabelami w stylu GitHub Flavored oraz przesuniętą hierarchią nagłówków (gotowa do wstawienia do większego dokumentu).

Uruchamialna aplikacja przykładowa

Wszystko w jednym pakiecie: sample-app.zip. Rozpakuj, a następnie:

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

Lub uruchom w Dockerze — dołączony Dockerfile konfiguruje zależność ICU, której wymaga dołączony runtime .NET na Linuxie:

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

Podsumowanie

GroupDocs.Markdown dla Pythona poprzez .NET dostarcza pełny silnik konwersji dokument‑do‑Markdown jako samodzielne koło — bez zewnętrznego runtime, bez chmury, bez niespodzianek. Pythonic API, wsparcie async oraz pierwszorzędna integracja z narzędziami AI czynią go praktycznym wyborem dla zespołów Pythona budujących systemy RAG, generatory statycznych stron lub potoki przetwarzania dokumentów.

Dowiedz się więcej

Wsparcie i opinie

W razie pytań lub potrzeby pomocy technicznej, skorzystaj z naszego Free Support Forum — chętnie pomożemy.