Agents and LLM Integration Leave feedback

pip show -f groupdocs-parser-net | grep AGENTS

{
  "format": "Portable Document Format File",
  "pages": 1,
  "characters": 1714,
  "tables": [
    [
      [
        "Invoice Number",
        "INV-3337"
      ],
      ...

# GroupDocs.Parser for Python via .NET -- AGENTS.md

> Instructions for AI agents working with this package.

Extract text, formatted text (HTML, Markdown), tables, images, metadata, hyperlinks, barcodes, annotations and the table of contents from PDF, Word, Excel, PowerPoint, email, eBook, archive and image files (65+ formats).

## Install

```bash
pip install groupdocs-parser-net
```

**Python**: 3.5 - 3.14 | **Platforms**: Windows x64, Linux x64 (glibc 2.27+), macOS 13+ (Intel, Apple Silicon; OCR needs 13.3+)

## Resources

| Resource | URL |
|---|---|
| Documentation | https://docs.groupdocs.com/parser/python-net/ |
| LLM-optimized docs | https://docs.groupdocs.com/parser/python-net/llms-full.txt |
| API reference | https://reference.groupdocs.com/parser/python-net/ |
| Code examples | https://github.com/groupdocs-parser/GroupDocs.Parser-for-Python-via-.NET |
| Release notes | https://releases.groupdocs.com/parser/python-net/release-notes/ |
| PyPI | https://pypi.org/project/groupdocs-parser-net/ |
| Free support forum | https://forum.groupdocs.com/c/parser/ |
| Temporary license | https://purchase.groupdocs.com/temporary-license |

## MCP Server

If your environment has MCP configured, you can connect your AI tool to the GroupDocs documentation server for on-demand API lookups:

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

Works with Claude Code (`~/.claude/settings.json`), Cursor (`.cursor/mcp.json`), VS Code Copilot (`.vscode/mcp.json`), and any MCP-compatible client. If MCP is unavailable, fall back to the LLM-optimized docs URL above and to this file, which is shipped inside the wheel.

## Imports

Each class lives in one module; the root exports only `Parser`, `License`, `Metered` and `Resources`. The exceptions are in `groupdocs.parser.exceptions`.

```python
from groupdocs.parser import License, Parser
from groupdocs.parser.data import AnnotationItem, PageImageArea, PageTableArea, Rectangle, Point, Size, ...
from groupdocs.parser.export import JsonExporter, XmlExporter
from groupdocs.parser.options import (FileType, FormattedTextMode, FormattedTextOptions, LoadOptions,
                                      PageAreaOptions, ParserSettings, PreviewOptions, TextOptions, ...)
from groupdocs.parser.templates import Template, TemplateField, TemplateTable, TemplateTableLayout, ...
from groupdocs.parser.exceptions import InvalidPasswordException, UnsupportedDocumentFormatException
```

## Extract Text

```python
from groupdocs.parser import Parser

with Parser("document.pdf") as parser:
    text = parser.get_text()          # str, or None when the format has no text
    if text is not None:
        print(text)
```

- `get_text()` / `get_formatted_text()` return a `str` that also answers `read_to_end()` -- 25.12 code and .NET-style code both work. `None` means not supported.
- One page: `parser.get_text(page_index)` (0-based). Options: `parser.get_text(TextOptions(True))` for raw mode, `TextOptions(False, True)` for OCR.
- Markdown or HTML: `parser.get_formatted_text(FormattedTextOptions(FormattedTextMode.MARKDOWN))`.

## Other Extraction

```python
from groupdocs.parser import Parser

with Parser("document.pdf") as parser:
    info = parser.get_document_info()                     # file_type.file_format, page_count, size
    for table in parser.get_tables() or []:               # PageTableArea
        rows = [[table[r, c].text for c in range(table.column_count)] for r in range(table.row_count)]
    for image in parser.get_images() or []:               # PageImageArea
        image.save("img%s" % image.file_type.extension)   # or image.get_image_stream().read() -> bytes
    for note in parser.get_annotations() or []:           # AnnotationItem: value, author_name, page_index
        print(note.author_name, note.value.strip())
    for item in parser.get_metadata() or []:              # MetadataItem: name, value
        print(item.name, item.value)
```

Check `parser.features.<name>` (text, tables, images, hyperlinks, annotations, metadata, structure, toc, ...) before a call when the format is unknown; an unsupported call returns `None`.

## Callbacks

```python
import io

from groupdocs.parser.options import ParserSettings, PreviewOptions

settings = ParserSettings(lambda level, message, exception: print(level, message))       # logger
settings = ParserSettings(external_resource_handler=lambda args: setattr(args, "skipped", True))
pages = {}
options = PreviewOptions(lambda page_number: pages.setdefault(page_number, io.BytesIO()))  # page previews
options.preview_page_render = lambda info: print("rendering page", info.page_number)
```

- `ParserSettings` has no empty constructor: pass a logger, an OCR connector or a resource handler (keywords pick which).
- The logger may be an object with `trace`/`warning`/`error`; the resource handler an object with `on_loading(args)` or a subclass of `ExternalResourceHandler`. The engine consults the handler for images in HTML and MHTML only.

## Command Line

`groupdocs-parser text|info|metadata|images|annotations|list-formats FILE` (or `python -m groupdocs.parser`). `text` takes `--page N` (from 1), `--format plain|markdown|html`, `--ocr`, `--include-annotations`, `-o FILE`; `info`, `metadata` and `annotations` take `--json`; `images` takes `--out DIR`; every command takes `--password`. Exit codes: 0 ok, 2 user error, 1 engine error or unsupported operation.

## Licensing

```python
from groupdocs.parser import License

# From file
License().set_license("path/to/license.lic")

# From stream
with open("license.lic", "rb") as f:
    License().set_license(f)
```

Or auto-apply: `export GROUPDOCS_LIC_PATH="path/to/license.lic"`

**Evaluation vs licensed.** Without a license the library still runs, but extracted text stops after about 20 lines and ends with "Evaluation only. Created with GroupDocs.Parser for .NET.", and only the first 5 metadata items are returned. Set `GROUPDOCS_LIC_PATH` (or call `License().set_license(...)`) and re-run to clear both. A 30-day full license is free: https://purchase.groupdocs.com/temporary-license

## API Reference

### Parser

| Method | Returns | Description |
|---|---|---|
| `Parser(path_or_stream, load_options=None, parser_settings=None)` | | Open a file path or a binary stream |
| `get_text(options=None, page_index=None)` | `str` or `None` | Plain text |
| `get_formatted_text(options, page_index=None)` | `str` or `None` | HTML / Markdown / plain |
| `get_document_info()` | `DocumentInfo` | Format, pages, size |
| `search(keyword, options=None)` | list of `SearchResult` | Keyword or regex search |
| `get_highlight(position, is_direct, options)` | `HighlightItem` | Text around a position |
| `get_structure()` | `XmlReader` | Document structure as XML |
| `get_toc()` | list of `TocItem` | Table of contents; `item.extract_text()` returns the section text |
| `get_container()` | list of `ContainerItem` | Archive entries / attachments |
| `get_metadata()` | list of `MetadataItem` | Document properties |
| `get_text_areas()` / `get_images()` / `get_hyperlinks()` / `get_barcodes()` / `get_tables()` | lists | Page areas, whole document or `(page_index, options)` |
| `get_annotations(page_index=None)` | list of `AnnotationItem` | Comments and notes |
| `get_page_preview(page_index)` | `Stream` (`.read()` -> bytes) | PNG preview of one page |
| `generate_preview(preview_options)` | `None` | Previews through callbacks |
| `parse_by_template(template)` | `DocumentData` | Fields and tables by layout |
| `parse_form()` | `DocumentData` | PDF form fields |
| `Parser.get_file_info(path_or_stream)` | `FileInfo` | static: format and encryption, without opening |

## Key Patterns

- **Properties**: use `snake_case` -- auto-mapped to .NET `PascalCase`. Assigning a misspelled property raises `AttributeError`.
- **Context managers**: `with Parser(...) as x:` ensures resources are released
- **Streams**: pass `open("file", "rb")` or `io.BytesIO(data)` where .NET expects Stream; a Stream the engine returns has `.read()`
- **Truth tests**: an engine object is true; a returned list is false when empty. Prefer `is None` checks for "not supported"
- **Enums**: case-insensitive, lazy-loaded (e.g., `FileType.DOCX`, `FormattedTextMode.MARKDOWN`)
- **Collections**: `for item in result`, `len(result)` and `result[i]` work on returned lists
- **Errors**: engine errors raise `GroupDocsParserException` or a subclass (`InvalidPasswordException`, `CorruptedDocumentException`, `UnsupportedDocumentFormatException`) from `groupdocs.parser.exceptions`, not `RuntimeError` as in 25.12

## Platform Requirements

| Platform | Requirements |
|---|---|
| Windows | None |
| Linux | `apt install libicu-dev libfontconfig1 fonts-liberation libgdiplus` (no Microsoft core fonts) |
| macOS | macOS 13 or newer; OCR (text from scanned pages and images) needs 13.3 or newer. `brew install mono-libgdiplus` |

libgdiplus serves presentations: page previews, ODP and OTP files, and PowerPoint files with tables or hyperlinks. Every other format works without it.

## Troubleshooting

**The process aborts with `Couldn't find a valid ICU package`** -- install ICU: `sudo apt install libicu-dev`. Do NOT set `DOTNET_SYSTEM_GLOBALIZATION_INVARIANT`.

**Merged table cells come out as separate rows in `get_structure()`** -- install the Liberation fonts: `sudo apt install fonts-liberation`

**`The type initializer for 'Gdip' threw an exception` / `DllNotFoundException: libgdiplus`** -- install libgdiplus: `sudo apt install libgdiplus` (macOS: `brew install mono-libgdiplus`). Presentations need it: page previews, ODP and OTP files, and PowerPoint files with tables or hyperlinks.

**The first `Parser(...)` takes 20-30 seconds** -- expected: the engine loads once per process; later documents open in a fraction of a second.

**An `aspose_data` folder of about 80 MB appears in the working directory** -- the first OCR call unpacks the recognition models there (no download). Set `Resources.storage_path = "/path/to/cache"` (`from groupdocs.parser import Resources`) before the first OCR call to choose the folder, e.g. when the working directory is read-only.

**`TypeError: __init__() - no overload matched` for `ParserSettings()`** -- there is no empty `ParserSettings`; pass a logger, OCR connector or resource handler.

**`is not a supported wheel on this platform`** -- the OS is older than glibc 2.27 / macOS 13, or pip is older than 20.3: `python -m pip install --upgrade pip`

**OCR, or text from an image, raises `GroupDocsParserException` naming `Microsoft.ML.OnnxRuntime.NativeMethods` / `DllNotFoundException` on macOS 13.0-13.2** -- OCR's ONNX Runtime library needs macOS 13.3 or newer; update macOS. Every other feature works on 13.0.

**`XType: com.apple.fonts is not accessible.` on stderr (macOS, in CI or a background service)** -- harmless: with no logged-in desktop session macOS reads the system font folders directly. Nothing to fix.

**`TypeLoadException`** -- reinstall: `pip install --force-reinstall groupdocs-parser-net`

**Still stuck?** Post your question at https://forum.groupdocs.com/c/parser/ -- the development team responds directly.