onvif-python 0.0.6__tar.gz → 0.0.7__tar.gz

{onvif_python-0.0.6/onvif_python.egg-info → onvif_python-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onvif-python
-Version: 0.0.6
+Version: 0.0.7
 Summary: A comprehensive and developer-friendly Python library for working with ONVIF-compliant devices
 Author-email: Nirsimetri Technologies® <open@nirsimetri.com>
 Maintainer: Kaburagi
@@ -43,9 +43,9 @@ Dynamic: license-file
 
 [![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/nirsimetri/onvif-python?tab=MIT-1-ov-file)
 [![DeepWiki](https://img.shields.io/badge/DeepWiki-AI%20Wiki-orange)](https://deepwiki.com/nirsimetri/onvif-python)
-[![Release](https://img.shields.io/badge/Release-v0.0.6-red?logo=archive)](https://github.com/nirsimetri/onvif-python/releases)
+[![Release](https://img.shields.io/badge/Release-v0.0.7-red?logo=archive)](https://github.com/nirsimetri/onvif-python/releases)
 <br>
-[![PyPI](https://img.shields.io/badge/PyPI-0.0.6-yellow?logo=archive)](https://pypi.org/project/onvif-python/)
+[![PyPI](https://img.shields.io/badge/PyPI-0.0.7-yellow?logo=archive)](https://pypi.org/project/onvif-python/)
 [![Downloads](https://img.shields.io/pypi/dm/onvif-python?label=PyPI%20Downloads)](https://clickpy.clickhouse.com/dashboard/onvif-python)
 
 Are you having trouble finding a Python ONVIF library that supports your device?  
@@ -150,6 +150,191 @@ Explore more advanced usage and service-specific operations in the [`examples/`]
 > [!IMPORTANT]
 > If you're new to ONVIF and want to learn more, we highly recommend taking the official free online course provided by ONVIF at [Introduction to ONVIF Course](https://www.onvif.org/about/introduction-to-onvif-course). Please note that we are not endorsed or sponsored by ONVIF, see [Legal Notice](#legal-notice) for details.
 
+## ONVIFClient Parameters
+
+The `ONVIFClient` class provides various configuration options to customize the connection behavior, caching strategy, security settings, and debugging capabilities. Below is a detailed description of all available parameters:
+
+### Basic Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `host` | `str` | ✅ Yes | - | IP address or hostname of the ONVIF device (e.g., `"192.168.1.17"`) |
+| `port` | `int` | ✅ Yes | - | Port number for ONVIF service (common ports: `80`, `8000`, `8080`) |
+| `username` | `str` | ✅ Yes | - | Username for device authentication (use digest authentication) |
+| `password` | `str` | ✅ Yes | - | Password for device authentication |
+
+### Connection Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `timeout` | `int` | ❌ No | `10` | Connection timeout in seconds for SOAP requests |
+| `use_https` | `bool` | ❌ No | `False` | Use HTTPS instead of HTTP for secure communication |
+| `verify_ssl` | `bool` | ❌ No | `True` | Verify SSL certificates when using HTTPS (set to `False` for self-signed certificates) |
+
+### Caching Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `cache` | `CacheMode` | ❌ No | `CacheMode.ALL` | WSDL caching strategy (see [Cache Modes](#cache-modes) below) |
+
+### Feature Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `apply_patch` | `bool` | ❌ No | `True` | Enable zeep patching for better xsd:any field parsing and automatic flattening |
+| `capture_xml` | `bool` | ❌ No | `False` | Enable XML capture plugin for debugging SOAP requests/responses |
+
+### Cache Modes
+
+The library provides four caching strategies via the `CacheMode` enum:
+
+| Mode | Description | Best For | Startup Speed | Disk Usage | Memory Usage |
+|------|-------------|----------|---------------|------------|--------------|
+| `CacheMode.ALL` | In-memory + disk cache (SQLite) | Production servers, multi-device apps | ⚡⚡⚡ Fast | 💾 High | 🧠 High |
+| `CacheMode.DB` | Disk cache only (SQLite) | Batch jobs, CLI tools | ⚡⚡ Medium | 💾 Medium | 🧠 Low |
+| `CacheMode.MEM` | In-memory cache only | Short-lived scripts, demos | ⚡⚡ Medium | 💾 None | 🧠 Medium |
+| `CacheMode.NONE` | No caching | Testing, debugging | ⚡ Slow | 💾 None | 🧠 Low |
+
+**Recommendation:** Use `CacheMode.ALL` (default) for production applications to maximize performance.
+
+### Usage Examples
+
+**Basic Connection:**
+```python
+from onvif import ONVIFClient
+
+# Minimal configuration
+client = ONVIFClient("192.168.1.17", 80, "admin", "password")
+```
+
+**Secure Connection (HTTPS):**
+```python
+from onvif import ONVIFClient
+
+# Connect via HTTPS with custom timeout
+client = ONVIFClient(
+    "your-cctv-node.viewplexus.com", 
+    443,  # HTTPS port
+    "admin", 
+    "password",
+    timeout=30,
+    use_https=True,
+    verify_ssl=False  # For self-signed certificates
+)
+```
+
+**Performance Optimized (Memory Cache):**
+```python
+from onvif import ONVIFClient, CacheMode
+
+# Use memory-only cache for quick scripts
+client = ONVIFClient(
+    "192.168.1.17", 
+    80, 
+    "admin", 
+    "password",
+    cache=CacheMode.MEM
+)
+```
+
+**No Caching (Testing):**
+```python
+from onvif import ONVIFClient, CacheMode
+
+# Disable all caching for testing
+client = ONVIFClient(
+    "192.168.1.17", 
+    80, 
+    "admin", 
+    "password",
+    cache=CacheMode.NONE,
+    apply_patch=False  # Use original zeep behavior
+)
+```
+
+**Debugging Mode (XML Capture):**
+```python
+from onvif import ONVIFClient
+
+# Enable XML capture for debugging
+client = ONVIFClient(
+    "192.168.1.17", 
+    80, 
+    "admin", 
+    "password",
+    capture_xml=True  # Captures all SOAP requests/responses
+)
+
+# Make some ONVIF calls
+device = client.devicemgmt()
+info = device.GetDeviceInformation()
+services = device.GetCapabilities()
+
+# Access the XML capture plugin
+if client.xml_plugin:
+    # Get last captured request/response
+    print("Last Request XML:")
+    print(client.xml_plugin.last_sent_xml)
+    
+    print("\nLast Response XML:")
+    print(client.xml_plugin.last_received_xml)
+    
+    print(f"\nLast Operation: {client.xml_plugin.last_operation}")
+    
+    # Get complete history of all requests/responses
+    print(f"\nTotal captured operations: {len(client.xml_plugin.history)}")
+    for item in client.xml_plugin.history:
+        print(f"  - {item['operation']} ({item['type']})")
+    
+    # Save captured XML to files
+    client.xml_plugin.save_to_file(
+        request_file="last_request.xml",
+        response_file="last_response.xml"
+    )
+    
+    # Clear history when done
+    client.xml_plugin.clear_history()
+```
+
+> [!NOTE]
+> **XML Capture Plugin Methods:**
+> - `last_sent_xml` - Get the last SOAP request XML
+> - `last_received_xml` - Get the last SOAP response XML
+> - `last_operation` - Get the name of the last operation
+> - `history` - List of all captured requests/responses with metadata
+> - `get_last_request()` - Method to get last request
+> - `get_last_response()` - Method to get last response
+> - `get_history()` - Method to get all history
+> - `save_to_file(request_file, response_file)` - Save XML to files
+> - `clear_history()` - Clear captured history
+
+
+**Production Configuration:**
+```python
+from onvif import ONVIFClient, CacheMode
+
+# Recommended production settings
+client = ONVIFClient(
+    host="your-cctv-node.viewplexus.com",
+    port=443,
+    username="admin",
+    password="secure_password",
+    timeout=15,
+    cache=CacheMode.ALL,        # Maximum performance
+    use_https=True,             # Secure communication
+    verify_ssl=True,            # Verify certificates (default)
+    apply_patch=True,           # Enhanced parsing (default)
+    capture_xml=False           # Disable debug mode (default)
+)
+```
+
+### Notes
+
+- **Authentication:** This library uses **WS-UsernameToken with Digest** authentication by default, which is the standard for ONVIF devices.
+- **Patching:** The `apply_patch=True` (default) enables custom zeep patching that improves `xsd:any` field parsing. This is recommended for better compatibility with ONVIF responses.
+- **XML Capture:** Only use `capture_xml=True` during development/debugging as it increases memory usage and may expose sensitive data in logs.
+- **Cache Location:** Disk cache (when using `CacheMode.DB` or `CacheMode.ALL`) is stored in `~/.onvif-python/onvif_zeep_cache.sqlite`.
+
 ## Service Discovery: Understanding Device Capabilities
 
 > [!WARNING]

{onvif_python-0.0.6 → onvif_python-0.0.7}/README.md

@@ -2,9 +2,9 @@
 
 [![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/nirsimetri/onvif-python?tab=MIT-1-ov-file)
 [![DeepWiki](https://img.shields.io/badge/DeepWiki-AI%20Wiki-orange)](https://deepwiki.com/nirsimetri/onvif-python)
-[![Release](https://img.shields.io/badge/Release-v0.0.6-red?logo=archive)](https://github.com/nirsimetri/onvif-python/releases)
+[![Release](https://img.shields.io/badge/Release-v0.0.7-red?logo=archive)](https://github.com/nirsimetri/onvif-python/releases)
 <br>
-[![PyPI](https://img.shields.io/badge/PyPI-0.0.6-yellow?logo=archive)](https://pypi.org/project/onvif-python/)
+[![PyPI](https://img.shields.io/badge/PyPI-0.0.7-yellow?logo=archive)](https://pypi.org/project/onvif-python/)
 [![Downloads](https://img.shields.io/pypi/dm/onvif-python?label=PyPI%20Downloads)](https://clickpy.clickhouse.com/dashboard/onvif-python)
 
 Are you having trouble finding a Python ONVIF library that supports your device?  
@@ -109,6 +109,191 @@ Explore more advanced usage and service-specific operations in the [`examples/`]
 > [!IMPORTANT]
 > If you're new to ONVIF and want to learn more, we highly recommend taking the official free online course provided by ONVIF at [Introduction to ONVIF Course](https://www.onvif.org/about/introduction-to-onvif-course). Please note that we are not endorsed or sponsored by ONVIF, see [Legal Notice](#legal-notice) for details.
 
+## ONVIFClient Parameters
+
+The `ONVIFClient` class provides various configuration options to customize the connection behavior, caching strategy, security settings, and debugging capabilities. Below is a detailed description of all available parameters:
+
+### Basic Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `host` | `str` | ✅ Yes | - | IP address or hostname of the ONVIF device (e.g., `"192.168.1.17"`) |
+| `port` | `int` | ✅ Yes | - | Port number for ONVIF service (common ports: `80`, `8000`, `8080`) |
+| `username` | `str` | ✅ Yes | - | Username for device authentication (use digest authentication) |
+| `password` | `str` | ✅ Yes | - | Password for device authentication |
+
+### Connection Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `timeout` | `int` | ❌ No | `10` | Connection timeout in seconds for SOAP requests |
+| `use_https` | `bool` | ❌ No | `False` | Use HTTPS instead of HTTP for secure communication |
+| `verify_ssl` | `bool` | ❌ No | `True` | Verify SSL certificates when using HTTPS (set to `False` for self-signed certificates) |
+
+### Caching Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `cache` | `CacheMode` | ❌ No | `CacheMode.ALL` | WSDL caching strategy (see [Cache Modes](#cache-modes) below) |
+
+### Feature Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `apply_patch` | `bool` | ❌ No | `True` | Enable zeep patching for better xsd:any field parsing and automatic flattening |
+| `capture_xml` | `bool` | ❌ No | `False` | Enable XML capture plugin for debugging SOAP requests/responses |
+
+### Cache Modes
+
+The library provides four caching strategies via the `CacheMode` enum:
+
+| Mode | Description | Best For | Startup Speed | Disk Usage | Memory Usage |
+|------|-------------|----------|---------------|------------|--------------|
+| `CacheMode.ALL` | In-memory + disk cache (SQLite) | Production servers, multi-device apps | ⚡⚡⚡ Fast | 💾 High | 🧠 High |
+| `CacheMode.DB` | Disk cache only (SQLite) | Batch jobs, CLI tools | ⚡⚡ Medium | 💾 Medium | 🧠 Low |
+| `CacheMode.MEM` | In-memory cache only | Short-lived scripts, demos | ⚡⚡ Medium | 💾 None | 🧠 Medium |
+| `CacheMode.NONE` | No caching | Testing, debugging | ⚡ Slow | 💾 None | 🧠 Low |
+
+**Recommendation:** Use `CacheMode.ALL` (default) for production applications to maximize performance.
+
+### Usage Examples
+
+**Basic Connection:**
+```python
+from onvif import ONVIFClient
+
+# Minimal configuration
+client = ONVIFClient("192.168.1.17", 80, "admin", "password")
+```
+
+**Secure Connection (HTTPS):**
+```python
+from onvif import ONVIFClient
+
+# Connect via HTTPS with custom timeout
+client = ONVIFClient(
+    "your-cctv-node.viewplexus.com", 
+    443,  # HTTPS port
+    "admin", 
+    "password",
+    timeout=30,
+    use_https=True,
+    verify_ssl=False  # For self-signed certificates
+)
+```
+
+**Performance Optimized (Memory Cache):**
+```python
+from onvif import ONVIFClient, CacheMode
+
+# Use memory-only cache for quick scripts
+client = ONVIFClient(
+    "192.168.1.17", 
+    80, 
+    "admin", 
+    "password",
+    cache=CacheMode.MEM
+)
+```
+
+**No Caching (Testing):**
+```python
+from onvif import ONVIFClient, CacheMode
+
+# Disable all caching for testing
+client = ONVIFClient(
+    "192.168.1.17", 
+    80, 
+    "admin", 
+    "password",
+    cache=CacheMode.NONE,
+    apply_patch=False  # Use original zeep behavior
+)
+```
+
+**Debugging Mode (XML Capture):**
+```python
+from onvif import ONVIFClient
+
+# Enable XML capture for debugging
+client = ONVIFClient(
+    "192.168.1.17", 
+    80, 
+    "admin", 
+    "password",
+    capture_xml=True  # Captures all SOAP requests/responses
+)
+
+# Make some ONVIF calls
+device = client.devicemgmt()
+info = device.GetDeviceInformation()
+services = device.GetCapabilities()
+
+# Access the XML capture plugin
+if client.xml_plugin:
+    # Get last captured request/response
+    print("Last Request XML:")
+    print(client.xml_plugin.last_sent_xml)
+    
+    print("\nLast Response XML:")
+    print(client.xml_plugin.last_received_xml)
+    
+    print(f"\nLast Operation: {client.xml_plugin.last_operation}")
+    
+    # Get complete history of all requests/responses
+    print(f"\nTotal captured operations: {len(client.xml_plugin.history)}")
+    for item in client.xml_plugin.history:
+        print(f"  - {item['operation']} ({item['type']})")
+    
+    # Save captured XML to files
+    client.xml_plugin.save_to_file(
+        request_file="last_request.xml",
+        response_file="last_response.xml"
+    )
+    
+    # Clear history when done
+    client.xml_plugin.clear_history()
+```
+
+> [!NOTE]
+> **XML Capture Plugin Methods:**
+> - `last_sent_xml` - Get the last SOAP request XML
+> - `last_received_xml` - Get the last SOAP response XML
+> - `last_operation` - Get the name of the last operation
+> - `history` - List of all captured requests/responses with metadata
+> - `get_last_request()` - Method to get last request
+> - `get_last_response()` - Method to get last response
+> - `get_history()` - Method to get all history
+> - `save_to_file(request_file, response_file)` - Save XML to files
+> - `clear_history()` - Clear captured history
+
+
+**Production Configuration:**
+```python
+from onvif import ONVIFClient, CacheMode
+
+# Recommended production settings
+client = ONVIFClient(
+    host="your-cctv-node.viewplexus.com",
+    port=443,
+    username="admin",
+    password="secure_password",
+    timeout=15,
+    cache=CacheMode.ALL,        # Maximum performance
+    use_https=True,             # Secure communication
+    verify_ssl=True,            # Verify certificates (default)
+    apply_patch=True,           # Enhanced parsing (default)
+    capture_xml=False           # Disable debug mode (default)
+)
+```
+
+### Notes
+
+- **Authentication:** This library uses **WS-UsernameToken with Digest** authentication by default, which is the standard for ONVIF devices.
+- **Patching:** The `apply_patch=True` (default) enables custom zeep patching that improves `xsd:any` field parsing. This is recommended for better compatibility with ONVIF responses.
+- **XML Capture:** Only use `capture_xml=True` during development/debugging as it increases memory usage and may expose sensitive data in logs.
+- **Cache Location:** Disk cache (when using `CacheMode.DB` or `CacheMode.ALL`) is stored in `~/.onvif-python/onvif_zeep_cache.sqlite`.
+
 ## Service Discovery: Understanding Device Capabilities
 
 > [!WARNING]

{onvif_python-0.0.6 → onvif_python-0.0.7}/onvif/__init__.py

@@ -2,8 +2,7 @@
 
 from .client import ONVIFClient
 from .operator import ONVIFOperator, CacheMode
-from .utils import ONVIFWSDL, ONVIFOperationException
-from .utils.zeep import apply_patch, remove_patch, is_patched
+from .utils import ONVIFWSDL, ONVIFOperationException, ONVIFErrorHandler, ZeepPatcher
 
 __all__ = [
     "ONVIFClient",
@@ -11,7 +10,6 @@ __all__ = [
     "CacheMode",
     "ONVIFWSDL",
     "ONVIFOperationException",
-    "apply_patch",
-    "remove_patch",
-    "is_patched",
+    "ONVIFErrorHandler",
+    "ZeepPatcher",
 ]

{onvif_python-0.0.6 → onvif_python-0.0.7}/onvif/client.py

@@ -41,12 +41,7 @@ from .services import (
     MediaSigning,
 )
 from .operator import CacheMode
-from .utils.zeep import (
-    apply_patch as _apply_zeep_patch,
-    remove_patch as _remove_zeep_patch,
-)
-from .utils.wsdl import ONVIFWSDL
-from .utils.xml_capture import XMLCapturePlugin
+from .utils import ONVIFWSDL, ZeepPatcher, XMLCapturePlugin
 
 
 class ONVIFClient:
@@ -67,9 +62,9 @@ class ONVIFClient:
 
         # Apply or remove zeep patch based on user preference
         if apply_patch:
-            _apply_zeep_patch()
+            ZeepPatcher.apply_patch()
         else:
-            _remove_zeep_patch()
+            ZeepPatcher.remove_patch()
 
         # Initialize XML capture plugin if requested
         self.xml_plugin = None

{onvif_python-0.0.6 → onvif_python-0.0.7}/onvif/operator.py

@@ -10,8 +10,7 @@ from zeep.cache import SqliteCache
 from zeep.exceptions import Fault
 from zeep.wsse.username import UsernameToken
 
-from .utils import ONVIFOperationException
-from .utils.zeep import flatten_xsd_any_fields
+from .utils import ONVIFOperationException, ZeepPatcher
 
 
 class CacheMode(Enum):
@@ -117,7 +116,7 @@ class ONVIFOperator:
             raise ValueError("Bindings must be set according to the WSDL service")
 
         self.service = self.client.create_service(binding, self.address)
-        logging.debug(f"ONVIFCore initialized {binding} at {self.address}")
+        # logging.debug(f"ONVIFOperator initialized {binding} at {self.address}")
 
     def call(self, method: str, *args, **kwargs):
         try:
@@ -129,7 +128,7 @@ class ONVIFOperator:
             result = func(*args, **kwargs)
             # Post-process to flatten xsd:any fields if enabled (> v0.0.4 patch)
             if self.apply_flatten:
-                return flatten_xsd_any_fields(result)
+                return ZeepPatcher.flatten_xsd_any_fields(result)
             return result
         except Fault as e:
             # logging.error(f"SOAP Fault in {method}: {e}")

{onvif_python-0.0.6 → onvif_python-0.0.7}/onvif/services/imaging.py

@@ -28,7 +28,9 @@ class Imaging:
             "GetImagingSettings", VideoSourceToken=VideoSourceToken
         )
 
-    def SetImagingSettings(self, VideoSourceToken, ImagingSettings, ForcePersistence=None):
+    def SetImagingSettings(
+        self, VideoSourceToken, ImagingSettings, ForcePersistence=None
+    ):
         return self.operator.call(
             "SetImagingSettings",
             VideoSourceToken=VideoSourceToken,

{onvif_python-0.0.6 → onvif_python-0.0.7}/onvif/services/provisioning.py

@@ -10,7 +10,7 @@ class Provisioning:
         # - ONVIF Release 16.12 (December 2016) Release Notes
         # - ProvisioningBinding (ver10/provisioning/wsdl/provisioning.wsdl)
         # - Operations: https://developer.onvif.org/pub/specs/branches/development/wsdl/ver10/provisioning/wsdl/provisioning.wsdl
-        
+
         definition = ONVIFWSDL.get_definition("provisioning")
         self.operator = ONVIFOperator(
             definition["path"],

onvif_python-0.0.7/onvif/utils/__init__.py

@@ -0,0 +1,14 @@
+from .wsdl import ONVIFWSDL
+from .exceptions import ONVIFOperationException
+from .zeep import ZeepPatcher
+from .xml_capture import XMLCapturePlugin
+from .error_handlers import ONVIFErrorHandler
+
+
+__all__ = [
+    "ONVIFWSDL",
+    "ONVIFOperationException",
+    "ZeepPatcher",
+    "XMLCapturePlugin",
+    "ONVIFErrorHandler",
+]

onvif_python-0.0.7/onvif/utils/error_handlers.py

@@ -0,0 +1,76 @@
+# onvif/utils/error_handlers.py
+
+import logging
+from zeep.exceptions import Fault
+from .exceptions import ONVIFOperationException
+
+
+class ONVIFErrorHandler:
+    """
+    Error handling utilities for ONVIF operations.
+
+    Provides static methods to handle ONVIF errors gracefully,
+    especially ActionNotSupported SOAP faults.
+    """
+
+    @staticmethod
+    def is_action_not_supported(exception):
+        """Check if an ONVIFOperationException is caused by ActionNotSupported SOAP fault."""
+        try:
+            # Handle ONVIFOperationException
+            if isinstance(exception, ONVIFOperationException):
+                original = exception.original_exception
+            else:
+                original = exception
+
+            # Check if it's a Fault with subcodes
+            if isinstance(original, Fault):
+                subcodes = getattr(original, "subcodes", None)
+                if subcodes:
+                    for subcode in subcodes:
+                        if hasattr(subcode, "localname"):
+                            if subcode.localname == "ActionNotSupported":
+                                return True
+                        elif "ActionNotSupported" in str(subcode):
+                            return True
+        except:
+            pass
+
+        return False
+
+    @staticmethod
+    def safe_call(func, default=None, ignore_unsupported=True, log_error=True):
+        """Safely call an ONVIF operation with graceful error handling."""
+        try:
+            return func()
+        except ONVIFOperationException as e:
+            # Check if it's ActionNotSupported error
+            if ignore_unsupported and ONVIFErrorHandler.is_action_not_supported(e):
+                # if log_error:
+                # logging.warning(f"Operation not supported: {e.operation}")
+                return default
+            # Re-raise other errors
+            raise
+        except Exception as e:
+            # Wrap unexpected exceptions
+            # if log_error:
+            # logging.error(f"Unexpected error in safe_call: {e}")
+            raise
+
+    @staticmethod
+    def ignore_unsupported(func):
+        """
+        Decorator to ignore ActionNotSupported SOAP faults.
+        Returns None for unsupported operations, raises other exceptions.
+        """
+
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except ONVIFOperationException as e:
+                if ONVIFErrorHandler.is_action_not_supported(e):
+                    # logging.warning(f"Operation not supported: {e.operation}")
+                    return None
+                raise
+
+        return wrapper

onvif_python-0.0.7/onvif/utils/exceptions.py

@@ -0,0 +1,69 @@
+# onvif/utils/exceptions.py
+
+"""
+(1) SOAP Errors
+(2) Transport/Protocol Errors
+(3) Application Errors
+"""
+
+from zeep.exceptions import Fault
+import requests
+
+
+class ONVIFOperationException(Exception):
+    def __init__(self, operation, original_exception):
+        self.operation = operation
+        self.original_exception = original_exception
+
+        if isinstance(original_exception, Fault):
+            # SOAP-level error
+            category = "SOAP Error"
+
+            # Extract fault information (supports both SOAP 1.1 and 1.2)
+            code = getattr(original_exception, "code", None) or getattr(
+                original_exception, "faultcode", None
+            )
+            subcodes = getattr(original_exception, "subcodes", None)
+            message = getattr(original_exception, "message", None) or str(
+                original_exception
+            )
+            detail = getattr(original_exception, "detail", None)
+
+            # Convert subcodes from QName objects to readable strings
+            if subcodes:
+                try:
+                    # subcodes is a list of lxml.etree.QName objects
+                    # QName objects have .localname (e.g., "ActionNotSupported")
+                    # and .namespace (e.g., "http://www.onvif.org/ver10/error")
+                    subcode_strings = []
+                    for qname in subcodes:
+                        if hasattr(qname, "localname"):
+                            # Use only the local name without namespace
+                            subcode_strings.append(qname.localname)
+                        else:
+                            # Fallback to string representation
+                            subcode_strings.append(str(qname))
+                    subcodes = ", ".join(subcode_strings)
+                except:
+                    subcodes = str(subcodes)
+
+            # Build comprehensive error message
+            parts = [f"code={code}"]
+            if subcodes:
+                parts.append(f"subcode={subcodes}")
+            if message:
+                parts.append(f"msg={message}")
+            if detail:
+                parts.append(f"detail={detail}")
+
+            msg = f"{category}: {', '.join(parts)}"
+        elif isinstance(original_exception, requests.exceptions.RequestException):
+            # Transport/Protocol error
+            category = "Protocol Error"
+            msg = f"{category}: {str(original_exception)}"
+        else:
+            # Application or generic error
+            category = "Application Error"
+            msg = f"{category}: {str(original_exception)}"
+
+        super().__init__(f"ONVIF operation '{operation}' failed: {msg}")