Metadata-Version: 2.4
Name: groupdocs-annotation-net
Version: 0.0.0
Summary: GroupDocs.Annotation for Python via .NET - Add annotations, markups and comments to documents and images
Author-email: GroupDocs <support@groupdocs.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://products.groupdocs.com/annotation/python-net/
Project-URL: Documentation, https://docs.groupdocs.com/annotation/python-net/
Keywords: annotation,annotate,markup,comment,document,pdf,docx,image,groupdocs,dotnet
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: <3.15,>=3.5
Description-Content-Type: text/markdown

[![banner](https://raw.githubusercontent.com/groupdocs/groupdocs.github.io/master/img/banners/groupdocs-annotation-python-net-banner.png)](https://docs.groupdocs.com/annotation/python-net/)

[![PyPI](https://img.shields.io/pypi/v/groupdocs-annotation-net)](https://pypi.org/project/groupdocs-annotation-net/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/groupdocs-annotation-net)](https://pypi.org/project/groupdocs-annotation-net/)

[Product Page](https://products.groupdocs.com/annotation/python-net/) | [Docs](https://docs.groupdocs.com/annotation/python-net/) | [Demos](https://products.groupdocs.app/annotation/family) | [API Reference](https://reference.groupdocs.com/annotation/python-net/) | [Blog](https://blog.groupdocs.com/category/annotation/) | [Free Support](https://forum.groupdocs.com/c/annotation) | [Temporary License](https://purchase.groupdocs.com/temporary-license)

GroupDocs.Annotation for Python via .NET is a document-annotation API for adding, editing, and removing markup on documents and images. Draw area, point, arrow, ellipse, and distance shapes; highlight, underline, strikeout, squiggly, and replace text; add watermarks, images, links, and text fields; thread review comments (replies) on any annotation; then save the result back to the original format or export/import the annotations as XML — across PDF, Word, Excel, PowerPoint, Visio, images, and more through one unified API, with no MS Office or other external software required.

## Get Started

```bash
pip install groupdocs-annotation-net
```

```python
from groupdocs.annotation import Annotator
from groupdocs.annotation.models.annotation_models import AreaAnnotation
from groupdocs.annotation.models import Rectangle

with Annotator("document.pdf") as annotator:
    area = AreaAnnotation()
    area.box = Rectangle(100, 100, 200, 80)   # x, y, width, height
    area.page_number = 0
    area.message = "Review this section"
    annotator.add(area)
    annotator.save("annotated.pdf")
```

## How It Works

The package is a self-contained Python wheel that bundles the embedded .NET runtime and every native dependency (SkiaSharp, Aspose.Drawing) needed to load, annotate, render, and save documents. No external software installation is required — just `pip install` and start annotating. The wheel works across Python 3.5 – 3.14 on Windows, Linux, and macOS (Intel + Apple Silicon).

## Features

- **Shape annotations** — area, point, arrow, ellipse, polyline, and distance markups with configurable box, color, pen style, and opacity.
- **Text markup** — highlight, underline, strikeout, squiggly, replacement, and redaction annotations over document text.
- **Content annotations** — watermarks, image stamps, link annotations, and editable text-field annotations.
- **Comments & replies** — thread review comments on any annotation, each with an author and timestamp.
- **Add / update / remove** — full lifecycle on annotations, individually or in batches, addressed by object or id.
- **Versioning** — read back annotation versions and a specific version's annotations.
- **Import / export** — round-trip annotations to/from an XML file or another document, separate from the source.
- **Previews** — render pages to PNG/JPEG/BMP images via a page-stream callback.
- **Document introspection** — read format, page count, and per-page dimensions before processing.
- **Cross-Platform** — Windows x64/x86, Linux x64, macOS x64/ARM64.

## Common Tasks

- Add a colored box or arrow over a region of a PDF page and save it back
- Highlight, underline, or strike out a passage of text in a document
- Stamp a watermark or an image annotation onto a page
- Attach a thread of review comments (replies) to an annotation
- List, update, or remove the annotations already on a document
- Export a document's annotations to XML and re-import them later
- Render annotated pages to images for a preview UI

## Supported File Formats

For a complete list, see [supported formats](https://docs.groupdocs.com/annotation/net/supported-document-formats/).

| Category | Formats |
|---|---|
| **Word Processing** | DOC, DOCX, DOCM, DOT, DOTX, DOTM, RTF, ODT, OTT, TXT |
| **Spreadsheets** | XLS, XLSX, XLSM, XLSB, ODS, CSV |
| **Presentations** | PPT, PPTX, PPTM, PPS, PPSX, ODP |
| **Fixed-Layout** | PDF, TEX |
| **Diagrams** | VSD, VSDX, VSS, VSSX, VSDM |
| **Images** | BMP, JPG, JPEG, PNG, GIF, TIFF, WEBP, DCM, EMF, WMF |
| **Web & Email** | HTML, MHTML, EML, EMLX, MSG |

## Examples

### Add an area annotation

```python
from groupdocs.annotation import Annotator
from groupdocs.annotation.models.annotation_models import AreaAnnotation
from groupdocs.annotation.models import Rectangle

with Annotator("document.pdf") as annotator:
    area = AreaAnnotation()
    area.box = Rectangle(100, 100, 200, 80)     # x, y, width, height
    area.background_color = 65535               # ARGB integer
    area.page_number = 0
    area.message = "Needs review"
    annotator.add(area)
    annotator.save("annotated.pdf")
```

### Attach review comments (replies)

```python
from groupdocs.annotation import Annotator
from groupdocs.annotation.models.annotation_models import AreaAnnotation
from groupdocs.annotation.models import Rectangle, Reply

reply1 = Reply(); reply1.comment = "Please double-check the figures"
reply2 = Reply(); reply2.comment = "Confirmed — looks good"

with Annotator("document.pdf") as annotator:
    area = AreaAnnotation()
    area.box = Rectangle(80, 80, 160, 60)
    area.page_number = 0
    area.replies = [reply1, reply2]
    annotator.add(area)
    annotator.save("reviewed.pdf")
```

### List, update and remove annotations

```python
from groupdocs.annotation import Annotator

with Annotator("annotated.pdf") as annotator:
    annotations = annotator.get()              # all annotations on the document
    for a in annotations:
        print(a.id, a.page_number, a.message)
    if annotations:
        annotator.remove(annotations[0])        # by object (or annotator.remove(id))
    annotator.save("cleaned.pdf")
```

### Read annotation versions

```python
from groupdocs.annotation import Annotator

with Annotator("annotated.pdf") as annotator:
    versions = annotator.get_versions_list()    # available annotation versions
    for v in versions:
        print("version:", v)
        for a in annotator.get_version(v):      # annotations in that version
            print("  ", a.id, a.message)
```

### Render a page preview

```python
from groupdocs.annotation import Annotator
from groupdocs.annotation.options import PreviewOptions, PreviewFormats

def create_page_stream(page_number):
    return open(f"page-{page_number}.png", "wb")

with Annotator("document.pdf") as annotator:
    opts = PreviewOptions(create_page_stream)
    opts.preview_format = PreviewFormats.PNG
    opts.page_numbers = [0, 1]
    annotator.document.generate_preview(opts)
```

### Annotate from / to a binary stream

```python
import io
from groupdocs.annotation import Annotator
from groupdocs.annotation.models.annotation_models import AreaAnnotation
from groupdocs.annotation.models import Rectangle

with open("document.pdf", "rb") as src:
    with Annotator(src) as annotator:
        area = AreaAnnotation(); area.box = Rectangle(50, 50, 120, 40); area.page_number = 0
        annotator.add(area)
        buffer = io.BytesIO()
        annotator.save(buffer)          # BytesIO is updated after save
        data = buffer.getvalue()
```

## AI Agent & LLM Friendly

This package is designed for seamless integration with AI agents, LLMs, and automated code generation tools.

- **`AGENTS.md` in the package** — AI coding assistants (Claude Code, Cursor, GitHub Copilot) auto-discover the API surface, usage patterns, and troubleshooting tips from the installed package
- **MCP server** — connect your AI tool to GroupDocs documentation for on-demand API lookups:
  ```json
  { "mcpServers": { "groupdocs-docs": { "url": "https://docs.groupdocs.com/mcp" } } }
  ```
- **Machine-readable docs** — full documentation available as plain text for RAG and LLM context:
  - Single file: `https://docs.groupdocs.com/annotation/python-net/llms-full.txt`
  - Per page: append `.md` to any docs URL

## Evaluation Mode

The API works without a license in evaluation mode, with these limitations:
- Output is restricted: PDF output carries an evaluation watermark and other formats show an equivalent evaluation mark.
- A page/document-count cap applies to processed documents.

To remove these limitations, apply a license or request a [temporary license](https://purchase.groupdocs.com/temporary-license):

```python
from groupdocs.annotation import License
License().set_license("path/to/license.lic")
```

Or set the environment variable (auto-applied at import):
```bash
export GROUPDOCS_LIC_PATH="path/to/license.lic"
```

## Troubleshooting

| Issue | Platform | Fix |
|---|---|---|
| Evaluation watermark on output | All | Apply a license — `License().set_license(...)` or set `GROUPDOCS_LIC_PATH` |
| `System.Drawing.Common is not supported` | Linux/macOS | `apt-get install libgdiplus` (Linux) or `brew install mono-libgdiplus` (macOS) |
| `The type initializer for 'Gdip' threw an exception` | macOS | `brew install mono-libgdiplus` |
| Garbled text / missing fonts in output | Linux | `apt-get install ttf-mscorefonts-installer fontconfig && fc-cache -f` |
| `DOTNET_SYSTEM_GLOBALIZATION_INVARIANT` errors | Linux | Do NOT set this variable. ICU must be available. |

## System Requirements

- Python 3.5 - 3.14
- Windows x64/x86, Linux x64, macOS x64/ARM64
- No additional software required

## More Resources

- [Documentation](https://docs.groupdocs.com/annotation/python-net/)
- [Code Examples](https://github.com/groupdocs-annotation/GroupDocs.Annotation-for-Python-via-.NET)
- [Free Support Forum](https://forum.groupdocs.com/c/annotation)
- [Temporary License](https://purchase.groupdocs.com/temporary-license)

Also available for other platforms:
[.NET](https://products.groupdocs.com/annotation/net/) | [Java](https://products.groupdocs.com/annotation/java/) | [Node.js](https://products.groupdocs.com/annotation/nodejs-java/)

---

[Product Page](https://products.groupdocs.com/annotation/python-net/) | [Docs](https://docs.groupdocs.com/annotation/python-net/) | [Demos](https://products.groupdocs.app/annotation/family) | [API Reference](https://reference.groupdocs.com/annotation/python-net/) | [Blog](https://blog.groupdocs.com/category/annotation/) | [Free Support](https://forum.groupdocs.com/c/annotation) | [Temporary License](https://purchase.groupdocs.com/temporary-license)
