feat: Core components - exceptions, file handling, and HTTP client

[jdrhyne]

Overview

This PR implements the core components of the Nutrient DWS Python client library as specified in the Software Design Specification v1.1.

🎯 Major Discovery: Implicit Document Conversion

During implementation and testing with the live API, we discovered that the Nutrient API automatically converts Office documents (DOCX, XLSX, PPTX) to PDF when processing them. This means:

• No explicit conversion needed - Just pass Office documents to any method
• All methods accept Office documents - rotate_pages(), ocr_pdf(), etc. work seamlessly with DOCX files
• Simplified workflows - Users can merge PDFs and Office documents in a single operation

This significantly enhances the library's capabilities beyond the original specification.

Features Implemented

🏗️ Project Structure

• Modern Python packaging with src layout
• Comprehensive development tooling (pytest, mypy, ruff)
• Pre-commit hooks for code quality
• GitHub Actions CI/CD pipeline

🔧 Core Components

• Custom Exception Hierarchy

  • NutrientError (base exception)
  • AuthenticationError (401/403 errors)
  • APIError (general API errors with status codes)
  • ValidationError (request validation failures)
  • TimeoutError (request timeouts)
  • FileProcessingError (file operation failures)

• HTTP Client Layer

  • Connection pooling for performance
  • Automatic retry logic with exponential backoff
  • Bearer token authentication
  • Request/response logging capabilities

• File Handling Utilities

  • Support for multiple input types (paths, Path objects, bytes, file-like objects)
  • Automatic streaming for large files (>10MB)
  • Memory-efficient processing

📚 API Implementation

• Supported Operations (via API testing):

  • convert_to_pdf - Leverages implicit conversion
  • flatten_annotations - Flatten PDF annotations and forms
  • rotate_pages - Rotate specific or all pages
  • ocr_pdf - Make PDFs searchable (supports English and German)
  • watermark_pdf - Add text/image watermarks
  • apply_redactions - Apply existing redaction annotations
  • merge_pdfs - Merge multiple files (PDFs and Office docs)

• Builder API: Fluent interface for complex workflows

  # Works with Office documents too\!
  client.build(input_file="report.docx") \
      .add_step("watermark-pdf", {"text": "DRAFT", "width": 200, "height": 100}) \
      .add_step("flatten-annotations") \
      .execute(output_path="processed.pdf")

🧪 Testing

• Unit Tests: 82 tests with 92.46% coverage
• Live API Testing: Validated all operations against production API
• Type Safety: Full mypy type checking
• Code Quality: Ruff linting and formatting

📖 Documentation

• Comprehensive README with examples
• SUPPORTED_OPERATIONS.md documenting all available methods
• Inline code documentation
• Type hints throughout

🚀 CI/CD

• GitHub Actions workflow for Python 3.8-3.12
• Automated testing, linting, and type checking
• PyPI release automation
• Dependabot configuration

Test Results

# Unit Tests
✅ 82 tests passing
✅ 92.46% code coverage

# Live API Tests
✅ All supported operations validated
✅ Implicit conversion confirmed
✅ Error handling verified

# Type Checking
✅ mypy: Success: no issues found

# Linting
✅ ruff: All checks passed

Usage Examples

from nutrient import NutrientClient

# Initialize client
client = NutrientClient(api_key="your-api-key")

# Convert Office document to PDF (implicit conversion)
client.convert_to_pdf("document.docx", output_path="converted.pdf")

# Process Office document directly
client.ocr_pdf("scanned_document.docx", output_path="searchable.pdf")

# Merge PDFs and Office documents together
client.merge_pdfs([
    "report.pdf",
    "data.xlsx",
    "presentation.pptx"
], output_path="combined.pdf")

# Builder API with Office document
client.build(input_file="contract.docx") \
    .add_step("watermark-pdf", {
        "text": "CONFIDENTIAL",
        "width": 300,
        "height": 150,
        "opacity": 0.5
    }) \
    .add_step("flatten-annotations") \
    .execute(output_path="final_contract.pdf")

Checklist

• Project structure and packaging
• Core exception classes
• HTTP client with Bearer authentication
• File handling utilities (with Path support)
• Direct API implementation (7 supported methods)
• Builder API implementation
• Unit tests (92.46% coverage)
• Live API testing and validation
• Type checking (mypy)
• Linting (ruff)
• CI/CD with GitHub Actions
• Comprehensive README
• Pre-commit hooks
• API compatibility fixes (watermark, OCR, auth)
• Implicit conversion discovery and implementation

Next Steps

After this PR is merged, the following tasks remain:

• Set up documentation site (Sphinx/MkDocs)
• Prepare for PyPI publication
• Add more integration test scenarios
• Performance benchmarking

This implementation follows the Software Design Document specifications and includes significant enhancements discovered during API testing.

[jdrhyne]

Test Results Update ✅

All tests are now passing! Here's the latest status:

Test Suite

• 82 tests passing
• 92.46% code coverage
• All unit tests for core components working correctly

Type Checking

• All mypy type checking errors resolved
• Added proper TYPE_CHECKING imports to handle circular dependencies
• Improved type annotations throughout the codebase

Code Quality

• Linting with ruff completed successfully
• All style issues automatically fixed
• Code follows Python best practices

Changes Made

1. Fixed file handler to properly extract basenames from Path objects
2. Updated session close tests to match requests library behavior
3. Resolved circular import issues with TYPE_CHECKING
4. Improved type safety across all modules

The core components implementation is now complete and ready for review!