feat: improve documentation and add tests for existing features

This PR verifies and improves the implementation of three quick-win features
that were already implemented in the recent refactoring:

1. Image Watermark Support (Issue #11)
   - Already supports FileInput (str, Path, bytes, file-like, URL)
   - Improved docstring with comprehensive examples
   - Added unit tests for bytes and Path inputs

2. Multi-Language OCR Support (Issue #10)
   - Already supports List[OcrLanguage] for multiple languages
   - Improved docstring with multi-language examples
   - Added unit tests for three languages and ISO codes

3. Selective Annotation Flattening (Issue #12)
   - Already supports annotation_ids parameter (str or int)
   - Improved docstring with examples for string, int, and mixed IDs
   - Added comprehensive unit tests for all ID types

All features maintain backward compatibility.
257 unit tests passing.

Author: jdrhyne

src/nutrient_dws/client.py

@@ -440,18 +440,35 @@ async def watermark_image(
 
         Args:
             file: The input file to watermark
-            image: The watermark image
+            image: The watermark image. Can be a file path (string or Path),
+                bytes, file-like object, or a URL to a remote image.
             options: Watermark options
 
         Returns:
             The watermarked document
 
         Example:
             ```python
-            result = await client.watermark_image('document.pdf', 'watermark.jpg', {
+            # Using a local file path
+            result = await client.watermark_image('document.pdf', 'watermark.png', {
                 'opacity': 0.5
             })
 
+            # Using a Path object
+            from pathlib import Path
+            result = await client.watermark_image('document.pdf', Path('logo.png'))
+
+            # Using bytes (e.g., from a database or API)
+            with open('logo.png', 'rb') as f:
+                image_bytes = f.read()
+            result = await client.watermark_image('document.pdf', image_bytes)
+
+            # Using a remote URL
+            result = await client.watermark_image(
+                'document.pdf',
+                'https://example.com/logo.png'
+            )
+
             # Access the watermarked PDF buffer
             pdf_buffer = result['buffer']
             ```
@@ -531,15 +548,20 @@ async def ocr(
 
         Args:
             file: The input file to perform OCR on
-            language: The language(s) to use for OCR
+            language: The language(s) to use for OCR. Can be a single language
+                or a list of languages for multi-language documents.
 
         Returns:
             The OCR result
 
         Example:
             ```python
+            # Single language OCR
             result = await client.ocr('scanned-document.pdf', 'english')
 
+            # Multi-language OCR for documents with mixed content
+            result = await client.ocr('multilang-document.pdf', ['english', 'german', 'french'])
+
             # Access the OCR-processed PDF buffer
             pdf_buffer = result['buffer']
             ```
@@ -952,7 +974,9 @@ async def flatten(
 
         Args:
             pdf: The PDF file to flatten
-            annotation_ids: Optional specific annotation IDs to flatten
+            annotation_ids: Optional list of specific annotation IDs to flatten.
+                If not provided, all annotations are flattened. IDs can be
+                strings or integers.
 
         Returns:
             The flattened document
@@ -962,8 +986,14 @@ async def flatten(
             # Flatten all annotations
             result = await client.flatten('annotated-document.pdf')
 
-            # Flatten specific annotations by ID
+            # Flatten specific annotations by string ID
             result = await client.flatten('annotated-document.pdf', ['annotation1', 'annotation2'])
+
+            # Flatten specific annotations by integer ID
+            result = await client.flatten('annotated-document.pdf', [1, 2, 3])
+
+            # Mix of string and integer IDs
+            result = await client.flatten('annotated-document.pdf', ['note1', 2, 'highlight3'])
             ```
         """
         # Validate PDF