Metadata-Version: 2.4
Name: groupdocs-watermark-net
Version: 26.10.0
Summary: GroupDocs.Watermark for Python via .NET - Add, search and remove watermarks in documents
Author-email: GroupDocs <support@groupdocs.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://products.groupdocs.com/watermark/python-net/
Project-URL: Documentation, https://docs.groupdocs.com/watermark/python-net/
Keywords: watermark,stamp,text-watermark,image-watermark,document,pdf,docx,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.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
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-watermark-python-net-banner.png)](https://docs.groupdocs.com/watermark/python-net/)

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

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

GroupDocs.Watermark for Python via .NET is a document-watermarking API for adding, searching, and removing text and image watermarks. Stamp configurable text or image watermarks — with control over position, size, opacity, rotation, alignment, and tiling — then save the result back to the original format; search for and remove existing watermarks (including ones added by other tools) across PDF, Word, Excel, PowerPoint, Visio, email, and image formats through one unified API, with no MS Office or other external software required.

## Get Started

```bash
pip install groupdocs-watermark-net
```

```python
from groupdocs.watermark import Watermarker
from groupdocs.watermark.watermarks import TextWatermark, Font

with Watermarker("document.pdf") as watermarker:
    watermark = TextWatermark("CONFIDENTIAL", Font("Arial", 36.0))
    watermark.opacity = 0.5
    watermarker.add(watermark)
    watermarker.save("watermarked.pdf")
```

## How It Works

The package is a self-contained Python wheel that bundles the embedded .NET runtime and the native libraries it ships (SkiaSharp, Aspose.Drawing) to load, watermark, render, and save documents. On Windows nothing else is needed; on Linux and macOS a few system packages are - see [System Requirements](#system-requirements). The wheel works across Python 3.5 - 3.14 on 64-bit Windows, Linux, and macOS (Intel + Apple Silicon).

## Features

- **Text watermarks** — configurable font, foreground/background color, opacity, rotation, and alignment.
- **Image watermarks** — from a file or an in-memory stream, with scaling, opacity, and positioning.
- **Positioning & sizing** — absolute coordinates, horizontal/vertical alignment, margins, scale-to-parent sizing, and rotation.
- **Tiling** — repeat a watermark across the page with configurable tile lines and spacing.
- **Search** — find existing watermarks by text, image, color, size, or rotation, combined with AND/OR/NOT criteria.
- **Remove** — delete found watermarks individually or in batches and save the cleaned document.
- **Document introspection** — read format, page count, and per-page dimensions before processing.
- **Previews** — render pages to PNG/JPEG/BMP images via a page-stream callback.
- **Cross-Platform** - Windows x64, Linux x64, macOS x64/ARM64.

## Common Tasks

- Stamp a "CONFIDENTIAL" text watermark across every page of a PDF and save it back
- Add a semi-transparent logo image watermark to a Word or PowerPoint document
- Tile a watermark diagonally across a page
- Search a document for an existing watermark by its text and remove it
- Read a document's format and page count before processing
- Render watermarked pages to images for a preview UI

## Supported File Formats

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

| Category | Formats |
|---|---|
| **Word Processing** | DOC, DOCX, DOCM, DOT, DOTX, RTF, ODT |
| **Spreadsheets** | XLS, XLSX, XLSM, XLSB |
| **Presentations** | PPT, PPTX, PPTM, PPS, PPSX |
| **Fixed-Layout** | PDF |
| **Diagrams** | VSD, VSDX, VSS, VDX |
| **Email** | MSG, EML, EMLX |
| **Images** | BMP, JPG, JPEG, PNG, GIF, TIFF, WEBP |

## Examples

### Add a text watermark

```python
from groupdocs.watermark import Watermarker
from groupdocs.watermark.watermarks import TextWatermark, Font, Color

with Watermarker("document.pdf") as watermarker:
    watermark = TextWatermark("CONFIDENTIAL", Font("Arial", 48))
    watermark.foreground_color = Color.red
    watermark.opacity = 0.5
    watermark.rotate_angle = -45
    watermarker.add(watermark)
    watermarker.save("watermarked.pdf")
```

### Add an image watermark

```python
from groupdocs.watermark import Watermarker
from groupdocs.watermark.watermarks import ImageWatermark, SizingType

with Watermarker("document.docx") as watermarker:
    watermark = ImageWatermark("logo.png")
    watermark.sizing_type = SizingType.SCALE_TO_PARENT_DIMENSIONS
    watermark.scale_factor = 0.5
    watermark.opacity = 0.7
    watermarker.add(watermark)
    watermarker.save("watermarked.docx")
```

### Tile a watermark across the page

```python
from groupdocs.watermark import Watermarker
from groupdocs.watermark.watermarks import TextWatermark, Font, TileOptions, TileType

with Watermarker("document.pdf") as watermarker:
    watermark = TextWatermark("DRAFT", Font("Arial", 19))
    tile = TileOptions()
    tile.tile_type = TileType.STRAIGHT           # repeat across the page
    watermark.tile_options = tile
    watermark.opacity = 0.3
    watermarker.add(watermark)
    watermarker.save("tiled.pdf")
```

### Search for and remove a watermark

```python
from groupdocs.watermark import Watermarker
from groupdocs.watermark.search.search_criteria import TextSearchCriteria

with Watermarker("watermarked.pdf") as watermarker:
    criteria = TextSearchCriteria("CONFIDENTIAL")     # also: ImageSearchCriteria(...)
    possible = watermarker.search(criteria)
    print("found:", len(possible))
    for wm in possible:
        print(wm.text, wm.x, wm.y)
    watermarker.remove(possible)                       # remove the whole collection
    watermarker.save("clean.pdf")
```

### Read document info

```python
from groupdocs.watermark import Watermarker

with Watermarker("document.pdf") as watermarker:
    info = watermarker.get_document_info()
    print("format:", info.file_type)
    print("pages:", info.page_count)
```

### Render page previews

```python
from groupdocs.watermark import Watermarker
from groupdocs.watermark.options import PreviewOptions, PreviewFormats

def create_page_stream(page_number):
    return open("page-%d.png" % page_number, "wb")

def release_page_stream(page_number, stream):
    stream.close()                          # the object create_page_stream returned

with Watermarker("document.pdf") as watermarker:
    options = PreviewOptions(create_page_stream, release_page_stream)
    options.preview_format = PreviewFormats.PNG
    options.page_numbers = [1, 2]
    watermarker.generate_preview(options)
```

`create_page_stream` may also return an `io.BytesIO`; it is filled by the time `release_page_stream` gets it.

### Watermark from / to a binary stream

```python
import io
from groupdocs.watermark import Watermarker
from groupdocs.watermark.watermarks import TextWatermark, Font

with open("document.pdf", "rb") as src:
    with Watermarker(src) as watermarker:
        watermarker.add(TextWatermark("CONFIDENTIAL", Font("Arial", 36)))
        buffer = io.BytesIO()
        watermarker.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/watermark/python-net/llms-full.txt`
  - Per page: append `.md` to any docs URL

## Evaluation Mode

The API works without a license in evaluation mode. Every feature runs - adding several watermarks, search, and removal included - and there is no cap on the number of documents, but each saved document carries an evaluation mark:
- PDF and image files: the line "Evaluation only. Created with GroupDocs.Watermark."
- Word, PowerPoint, and Visio files: the line "Created with evaluation version of GroupDocs.Watermark".
- Excel files: an extra "Evaluation Warning" worksheet.

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

```python
from groupdocs.watermark 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 only" / "Created with evaluation version" line, or an "Evaluation Warning" sheet, in the output | All | No license is applied: set `GROUPDOCS_LIC_PATH` or call `License().set_license(path)` |
| `The type initializer for 'Gdip' threw an exception` / `DllNotFoundException: libgdiplus` when adding a watermark | Linux/macOS | Install libgdiplus: `apt-get install libgdiplus` / `brew install mono-libgdiplus`. Only text watermarks on Word, Excel, PowerPoint, Visio, and image files, text watermarks on PDF that set `sizing_type`, and image watermarks, removal, and previews on PowerPoint need it; the rest of PDF works without it |
| `FontNotFoundException` when adding a text watermark to a PDF | Linux | Install the font the watermark names - for Arial and the other Microsoft fonts: `apt-get install ttf-mscorefonts-installer` (Debian: enable `contrib`), then `fc-cache -f`. Liberation fonts are not substituted |
| `Not implemented.` from `generate_preview` on a PowerPoint file | Linux/macOS | PowerPoint previews need a GDI+ feature libgdiplus lacks; generate them on Windows. Previews of the other formats work |
| The process aborts on first use with `Couldn't find a valid ICU package` | Linux | Install ICU: `apt-get install libicu-dev`; do NOT set `DOTNET_SYSTEM_GLOBALIZATION_INVARIANT` |
| `is not a supported wheel on this platform`, or `No matching distribution found` | Linux/macOS | The OS is older than the wheel needs (glibc 2.27, macOS 12), or pip is older than 20.3: `python -m pip install --upgrade pip`. On an Intel Mac, a Python built against an old SDK reports macOS 10.16 - use pip 24.1+ or `SYSTEM_VERSION_COMPAT=0 pip install groupdocs-watermark-net` |

## System Requirements

- Python 3.5 - 3.14, pip 20.3 or newer
- Windows x64, Linux x64, macOS x64/ARM64 - 64-bit Python only; there is no 32-bit Windows wheel
- Linux: glibc 2.27 or newer (e.g. Ubuntu 18.04+, Debian 10+, RHEL 8+), plus ICU, fontconfig, libgdiplus and the Microsoft core fonts: `apt-get install libicu-dev libfontconfig1 libgdiplus ttf-mscorefonts-installer` (on Debian, enable the `contrib` component first). libgdiplus is needed for text watermarks on Word, Excel, PowerPoint, Visio, and image files, for text watermarks on PDF files that set `sizing_type`, and for image watermarks, removal, and previews on PowerPoint files; the core fonts for text watermarks on PDF files, which look their font up by name.
- macOS 12 or newer, Intel or Apple Silicon: `brew install mono-libgdiplus` for the same features.

## Upgrading from 26.6

- `release_page_stream(page_number, stream)` now gets the stream `create_page_stream` returned; 26.6 passed `None`. A one-argument `release_page_stream(page_number)` still works.
- Previews written through a release callback are complete (26.6 could leave a spreadsheet page truncated), and `io.BytesIO` pages are filled (26.6 left them empty).
- `WatermarkerSettings.logger` takes a Python object with `trace`, `warning`, and `error` methods, or a function `fn(level, message, exception)`.
- Assigning an attribute a class does not have raises `AttributeError` with a suggestion (`watermark.opactiy = 0.5` -> "Did you mean: 'opacity'?"); 26.6 stored it on the Python object and changed nothing.
- Python 3.5, 3.6, and 3.7 work; 26.6 could not be imported on 3.5 and 3.6 and failed on first use on 3.7.
- Evaluation mode allows several watermarks per document, search, and removal (engine 26.9).
- The wheels state the OS they need (`manylinux_2_27`, `macosx_12_0`), so installing needs pip 20.3 or newer.

The [release notes](https://releases.groupdocs.com/watermark/python-net/release-notes/) have the full list.

## More Resources

- [Documentation](https://docs.groupdocs.com/watermark/python-net/)
- [API Reference](https://reference.groupdocs.com/watermark/python-net/)
- [Code Examples](https://github.com/groupdocs-watermark/GroupDocs.Watermark-for-Python-via-.NET)
- [Release Notes](https://releases.groupdocs.com/watermark/python-net/release-notes/)
- [Free Support Forum](https://forum.groupdocs.com/c/watermark)
- [Temporary License](https://purchase.groupdocs.com/temporary-license)

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

---

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