v0.0.7 — 2025-10-14

Overview

This release introduces a major architectural improvement with class-based error handling and zeep patching utilities. Key highlights include:

1. ONVIFErrorHandler Class: New structured error handling for graceful failure management
2. ZeepPatcher Class: Refactored zeep patching logic into a clean, organized class
3. Enhanced Exception Messages: Improved SOAP Fault error reporting with readable subcodes
4. Device Compatibility: Better handling of unsupported operations across different ONVIF devices

Changelog Summary

PyPI

https://pypi.org/project/onvif-python/0.0.7 (18482692659)

New Features

• Added ONVIFErrorHandler class for graceful error management (b278de0)

  • safe_call(): Execute operations with automatic fallback on failure

  • ignore_unsupported(): Decorator to return None for unsupported operations

  • is_action_not_supported(): Check if error is ActionNotSupported

  • Example:

    from onvif import ONVIFClient, ONVIFErrorHandler
    
    client = ONVIFClient("192.168.1.100", 80, "admin", "password")
    device = client.devicemgmt()
    
    # Safe call with fallback
    services = ONVIFErrorHandler.safe_call(
        lambda: device.GetServices(IncludeCapability=True),
        default=None
    )
    
    if services is None:
        # Fallback for devices that don't support IncludeCapability=True
        services = device.GetServices(IncludeCapability=False)

• Added ZeepPatcher class for organized zeep patching (d7d8f11)

  • Consolidated all zeep patching logic into a single class

  • Static methods for all patching operations

  • Backward compatible function wrappers maintained

  • Example:

    from onvif import ZeepPatcher
    
    # Apply patch (or use legacy apply_patch())
    ZeepPatcher.apply_patch()
    
    # Check patch status
    if ZeepPatcher.is_patched():
        print("Zeep patch is active")
    
    # Remove patch if needed
    ZeepPatcher.remove_patch()

Fixed

• Enhanced ONVIFOperationException with detailed SOAP Fault messages (f8c88b2)
  • Extract readable subcode from QName (e.g., ter:ActionNotSupported instead of {http://www.onvif.org/ver10/error}ActionNotSupported)
  • Better error context with operation name and original exception details
  • Improved debugging experience for SOAP Fault errors

Documentation

• Updated examples to demonstrate error handling patterns (b278de0)
  • Added comprehensive error_handling.py example at examples/error_handling.py
  • Demonstrated graceful fallback for device compatibility issues

Refactoring

• Code formatting and readability improvements (ecdef62)
  • Applied Black formatter across codebase
  • Consistent code style throughout the project
  • Better PEP 8 compliance

---

Breaking Changes

None — This release maintains full backward compatibility:

• Existing code will continue to function without modifications
• New class-based APIs are opt-in enhancements

---

Full Changelog: v0.0.6...v0.0.7