onvif-python 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

onvif/__init__.py

@@ -6,10 +6,12 @@ from onvif.operator import CacheMode
 from onvif.utils import (
     ONVIFWSDL,
     ONVIFDiscovery,
-    ONVIFErrorHandler,
     ONVIFOperationException,
     ONVIFParser,
     ZeepPatcher,
+    ignore_unsupported,
+    is_action_not_supported,
+    safe_call,
 )
 
 __all__ = [
@@ -17,9 +19,11 @@ __all__ = [
     "CacheMode",
     "ONVIFWSDL",
     "ONVIFOperationException",
-    "ONVIFErrorHandler",
     "ZeepPatcher",
     "ONVIFCLI",
     "ONVIFDiscovery",
     "ONVIFParser",
+    "ignore_unsupported",
+    "is_action_not_supported",
+    "safe_call",
 ]

onvif/cli/helpers/discovery.py

@@ -1,5 +1,7 @@
 """ONVIF discovery helpers."""
 
+from datetime import datetime
+
 from onvif.cli.utils import colorize
 from onvif.utils import ONVIFDiscovery
 
@@ -16,7 +18,7 @@ def discover_devices(
         timeout (int): Discovery timeout in seconds
         interface (str | None): Network interface to use for discovery
         prefer_https (bool): If True, prioritize HTTPS XAddrs when available
-        filter_term (str | None): Optional search term to filter devices by types or scopes
+        filter_term (str | None): Optional search term to filter devices by types or scopes (case-insensitive)
 
     Returns:
         List of discovered devices with connection info
@@ -36,6 +38,7 @@ def discover_devices(
     return devices
 
 
+# pylint: disable=too-many-locals,too-many-statements,too-many-branches
 def select_device_interactive(devices: list) -> tuple[str, int, bool] | None:
     """Display devices and allow user to select one interactively.
 
@@ -70,15 +73,43 @@ def select_device_interactive(devices: list) -> tuple[str, int, bool] | None:
             epr_display = epr_display.replace("uuid:", "")
         print(f"    [uuid] {epr_display}")
 
-        if device["xaddrs"]:
+        if device.get("hostname"):
+            print(f"    [hostname] {device["hostname"]}")
+
+        if device.get("xaddrs"):
             xaddrs_parts = [f"[{xaddr}]" for xaddr in device["xaddrs"]]
             print(f"    [xaddrs] {' '.join(xaddrs_parts)}")
 
-        if device["types"]:
+        if device.get("date_time"):
+            utc = (
+                datetime.fromisoformat(device["date_time"].get("utc")).strftime(
+                    "%H:%M:%S %d-%m-%Y"
+                )
+                if device["date_time"].get("utc")
+                else ""
+            )
+            local = (
+                datetime.fromisoformat(device["date_time"].get("local")).strftime(
+                    "%H:%M:%S %d-%m-%Y"
+                )
+                if device["date_time"].get("local")
+                else ""
+            )
+            print(
+                f"    [date_time]"
+                f'{" [UTC: " + utc + "]" if utc else ""}'
+                f'{" [Local: " + local + "]" if local else ""}'
+            )
+
+        if device.get("types"):
             types_parts = [f"[{t}]" for t in device["types"]]
             print(f"    [types] {' '.join(types_parts)}")
 
-        if device["scopes"]:
+        if device.get("services"):
+            service = [colorize(f"[{t}]", "cyan") for t in device["services"]]
+            print(f"    [services] {' '.join(service)}")
+
+        if device.get("scopes"):
             scope_parts = []
             for scope in device["scopes"]:
                 # Remove the prefix "onvif://www.onvif.org/" if present
@@ -110,13 +141,14 @@ def select_device_interactive(devices: list) -> tuple[str, int, bool] | None:
                 print(
                     f"\n{colorize('Selected:', 'green')} {colorize(protocol, 'cyan')}://{colorize(host_port, 'yellow')}"
                 )
+
                 return (
                     selected["host"],
                     selected["port"],
                     selected.get("use_https", False),
                 )
-            else:
-                print(colorize("Invalid selection. Please try again.", "red"))
+
+            print(colorize("Invalid selection. Please try again.", "red"))
 
         except ValueError:
             print(colorize("Invalid input. Please enter a number.", "red"))

onvif/cli/helpers/files.py

@@ -102,6 +102,7 @@ def save_output_to_file(
         print(str(result))
 
 
+# pylint: disable=too-many-return-statements,too-many-branches,too-many-nested-blocks
 def _serialize_for_json(obj: Any) -> Any:
     """Recursively serialize ONVIF objects for JSON output.
 
@@ -113,17 +114,17 @@ def _serialize_for_json(obj: Any) -> Any:
     """
     if obj is None:
         return None
-    elif isinstance(obj, (str, int, float, bool)):
+    if isinstance(obj, (str, int, float, bool)):
         return obj
-    elif isinstance(obj, datetime):
+    if isinstance(obj, datetime):
         return obj.isoformat()
-    elif isinstance(obj, (list, tuple)):
+    if isinstance(obj, (list, tuple)):
         return [_serialize_for_json(item) for item in obj]
-    elif isinstance(obj, dict):
+    if isinstance(obj, dict):
         return {key: _serialize_for_json(value) for key, value in obj.items()}
 
     # Check if this is a Zeep object (has _xsd_type attribute)
-    elif hasattr(obj, "_xsd_type"):
+    if hasattr(obj, "_xsd_type"):
         result = {}
         # Try to get all elements from XSD type
         if hasattr(obj._xsd_type, "elements"):  # pylint: disable=protected-access
@@ -154,7 +155,7 @@ def _serialize_for_json(obj: Any) -> Any:
 
         return result
 
-    elif hasattr(obj, "__dict__"):
+    if hasattr(obj, "__dict__"):
         # Handle regular objects with attributes
         result = {}
         for key, value in obj.__dict__.items():
@@ -176,14 +177,15 @@ def _serialize_for_json(obj: Any) -> Any:
                         pass
 
         return result
-    elif hasattr(obj, "_value_1"):
+
+    if hasattr(obj, "_value_1"):
         # Handle zeep objects with special structure
         return _serialize_for_json(obj._value_1)  # pylint: disable=protected-access
-    else:
-        # Try to convert to dict using vars() if available
-        try:
-            obj_dict = vars(obj)
-            return _serialize_for_json(obj_dict)
-        except TypeError:
-            # Fallback to string representation
-            return str(obj)
+
+    # Try to convert to dict using vars() if available
+    try:
+        obj_dict = vars(obj)
+        return _serialize_for_json(obj_dict)
+    except TypeError:
+        # Fallback to string representation
+        return str(obj)

onvif/cli/helpers/messages.py

@@ -69,7 +69,8 @@ def print_interactive_intro(args, device_info_text) -> str:
         f"{banner}\n"
         f"{repo_info}\n"
         f"{terminal_header}\n"
-        f"  Connected to  : {colorize(f'{args.host}:{args.port}', 'yellow')}"
+        f"  Connected to  : {colorize(f'{args.host}:{args.port}', 'yellow')}\n"
+        f"  Auth Method   : {colorize(f'{'HTTP Digest' if args.digest else 'WS-UsernameToken'}', 'yellow')}"
         f"{options_display}{device_info_text}\n\n"
         f"{colorize('[Quick Start]', 'green')}\n"
         f"  - Type {colorize('dev', 'yellow')} + {colorize('TAB', 'yellow')} to see `devicemgmt` suggestion\n"
@@ -105,7 +106,6 @@ INTERACTIVE_HELP = f"""
   cd <service>             - Enter service mode (alias)
   ls                       - List commands/services/methods in grid format
   up                       - Exit current service mode (go up one level)
-  pwd                      - Show current service context
   clear                    - Clear terminal screen
   help <command>           - Show help for a specific command
 
@@ -165,7 +165,6 @@ INTERACTIVE_SHORTCUTS = f"""
   cd <service>             - Enter service (same as '<service>')
   ls                       - List commands/services in grid format (like TAB)
   up                       - Go up one level
-  pwd                      - Show current context
   clear                    - Clear terminal screen
   help <command>           - Show help for a command
 
@@ -193,7 +192,7 @@ Examples:
   # Discover ONVIF devices on network
   {colorize('onvif', 'yellow')} --discover --username admin --password admin123 --interactive
   {colorize('onvif', 'yellow')} media GetProfiles --discover --username admin
-  {colorize('onvif', 'yellow')} -d -i
+  {colorize('onvif', 'yellow')} -d --interface 192.168.1.77 -i
 
   # Discover with filtering
   {colorize('onvif', 'yellow')} --discover --filter ptz --interactive

onvif/cli/helpers/products.py

@@ -10,6 +10,8 @@ from pathlib import Path
 from onvif.cli.utils import colorize
 
 
+# pylint: disable=too-many-locals,too-many-nested-blocks
+# pylint: disable=too-many-statements,too-many-branches
 def search_products(search_term: str, page: int = 1, per_page: int = 20) -> None:
     """Search ONVIF products database and display results in table format with
     pagination.

onvif/cli/helpers/wsdl_parser.py

@@ -36,6 +36,7 @@ class OperationTypeInfo(TypedDict):
     output: MessageInfo | None
 
 
+# pylint: disable=too-many-locals,too-many-statements,too-many-branches
 def get_method_documentation(service_obj, method_name: str) -> dict[str, Any] | None:
     """Extracts documentation from WSDL and parameters from the Python method signature.
 
@@ -45,7 +46,7 @@ def get_method_documentation(service_obj, method_name: str) -> dict[str, Any] |
     required_args: list[str] = []
     optional_args: list[str] = []
 
-    try:
+    try:  # pylint: disable=too-many-nested-blocks
         # 1. Get documentation from WSDL (existing logic)
         wsdl_path = service_obj.operator.wsdl_path
 
@@ -308,8 +309,7 @@ def clean_documentation_html(doc_text: str) -> str:
         text = match.group(2).strip()  # Strip whitespace from link text
         if text:
             return f"{text} ({url})"
-        else:
-            return url  # If no text, just return URL
+        return url  # If no text, just return URL
 
     # Replace anchor tags - handle newlines and whitespace
     doc_text = re.sub(
@@ -361,7 +361,9 @@ def extract_documentation_text(doc_elem) -> str:
 def _load_imported_schemas(root, schema_context: dict, namespaces: dict):
     """Recursively load all imported and included schemas into the schema context."""
     # Find all xs:import and xs:include in xs:schema elements
-    for schema in root.findall(".//xs:schema", namespaces):
+    for schema in root.findall(  # pylint: disable=too-many-nested-blocks
+        ".//xs:schema", namespaces
+    ):
         # Process imports
         for import_elem in schema.findall("xs:import", namespaces):
             schema_location = import_elem.get("schemaLocation")
@@ -443,6 +445,7 @@ def _load_imported_schemas(root, schema_context: dict, namespaces: dict):
                         continue
 
 
+# pylint: disable=too-many-locals,too-many-statements,too-many-branches
 def resolve_element_type(
     element_name: str,
     namespaces: dict,
@@ -605,6 +608,7 @@ def resolve_element_type(
     return parameters
 
 
+# pylint: disable=too-many-locals,too-many-statements,too-many-branches
 def resolve_complex_type(
     type_name: str,
     namespaces: dict,
@@ -794,6 +798,7 @@ def resolve_complex_type(
     return children
 
 
+# pylint: disable=too-many-locals,too-many-statements,too-many-branches
 def parse_inline_complex_type(
     complex_type,
     namespaces: dict,

onvif/cli/interactive.py

@@ -1,3 +1,5 @@
+# pylint: disable=too-many-lines,too-many-instance-attributes,too-many-locals
+# pylint: disable=too-many-statements,too-many-public-methods,too-many-branches
 """ONVIF CLI interactive shell implementation."""
 
 import cmd
@@ -70,7 +72,6 @@ class InteractiveShell(cmd.Cmd):
             "debug",
             "ls",
             "cd",
-            "pwd",
             "shortcuts",
             "desc",
             "type",
@@ -274,6 +275,7 @@ class InteractiveShell(cmd.Cmd):
                     depth = max(0, depth - 1)
 
             # Detect top-level &&
+            # pylint: disable=too-many-boolean-expressions
             if (
                 not in_single
                 and not in_double
@@ -522,6 +524,8 @@ class InteractiveShell(cmd.Cmd):
             print(f"{colorize('Unknown command:', 'red')} {line}")
             print(f"Type {colorize('help', 'white')} for available commands")
 
+        return None
+
     def get_suggestions(self, partial_cmd: str) -> list[str]:
         """Get command suggestions based on partial input."""
         suggestions = []
@@ -1026,7 +1030,7 @@ class InteractiveShell(cmd.Cmd):
             available_services = get_device_available_services(self.client)
             colored_services = [colorize(svc, "cyan") for svc in available_services]
             print(f"Available services: {', '.join(colored_services)}")
-            return
+            return None
         return self.do_enter_service(line)
 
     def complete_cd(
@@ -1036,17 +1040,6 @@ class InteractiveShell(cmd.Cmd):
         services = get_device_available_services(self.client)
         return [s for s in services if s.lower().startswith(text.lower())]
 
-    def do_pwd(self, line):  # pylint: disable=unused-argument
-        """Show current service context."""
-        if self.current_service_name:
-            print(
-                f"{colorize('Current service:', 'yellow')} {colorize(self.current_service_name, 'cyan')}"
-            )
-        else:
-            print(
-                f"{colorize('Current context:', 'yellow')} {colorize('root', 'blue')}"
-            )
-
     def do_shortcuts(self, line):  # pylint: disable=unused-argument
         """Show available shortcuts."""
         print(INTERACTIVE_SHORTCUTS)
@@ -1221,6 +1214,7 @@ class InteractiveShell(cmd.Cmd):
         print(
             f"\n{colorize('[ONVIF Terminal Client]', 'yellow')}"
             f"\n  Connected to  : {colorize(f'{self.args.host}:{self.args.port}', 'yellow')}"
+            f"\n  Auth Method   : {colorize(f'{'HTTP Digest' if self.args.digest else 'WS-UsernameToken'}', 'yellow')}"
             f"{options_display}{self.device_info_text}"
         )
         print()  # Extra newline for spacing

onvif/cli/main.py

@@ -24,7 +24,6 @@ from onvif.operator import CacheMode
 from onvif.utils import ONVIFOperationException
 
 
-# pylint: disable=line-too-long
 def create_parser() -> ArgumentParser:
     """Create argument parser for ONVIF CLI."""
     parser = ArgumentParser(
@@ -97,6 +96,11 @@ def create_parser() -> ArgumentParser:
         default=10,
         help="ONVIF connection timeout in seconds (default: 10)",
     )
+    parser.add_argument(
+        "--digest",
+        action="store_true",
+        help="Use HTTP Digest instead of WS-UsernameToken",
+    )
     parser.add_argument(
         "--https", action="store_true", help="Use HTTPS instead of HTTP"
     )
@@ -118,9 +122,9 @@ def create_parser() -> ArgumentParser:
     parser.add_argument(
         "--cache",
         choices=[mode.value for mode in CacheMode],
-        default=CacheMode.ALL.value,
-        help="Caching mode for ONVIFClient (default: all). "
-        "'all': memory+disk, 'db': disk-only, 'mem': memory-only, 'none': disabled.",
+        default=CacheMode.DB.value,
+        help="Caching mode for ONVIFClient (default: db). "
+        "'db': disk-only, 'mem': memory-only, 'none': disabled.",
     )
     parser.add_argument(
         "--health-check-interval",
@@ -159,6 +163,7 @@ def create_parser() -> ArgumentParser:
     return parser
 
 
+# pylint: disable=too-many-statements,too-many-branches
 def main() -> None:
     """Main CLI entry point."""
     # Setup custom warning format for cleaner output
@@ -278,6 +283,7 @@ def main() -> None:
             port=args.port,
             username=args.username,
             password=args.password,
+            http_digest=args.digest,
             timeout=args.timeout,
             cache=CacheMode(args.cache),
             use_https=args.https,

onvif/cli/utils.py

@@ -80,6 +80,7 @@ def _is_valid_json(s: str) -> bool:
     return True
 
 
+# pylint: disable=too-many-statements,too-many-branches
 def parse_json_params(params_str: str) -> dict[str, Any]:
     """Parse parameters from a JSON string or key=value pairs into a dict.
 
@@ -406,6 +407,7 @@ def format_services_list(services_list) -> str:
     return result
 
 
+# pylint: disable=too-many-statements,too-many-branches
 def get_device_available_services(client) -> list:
     """Get list of services actually available on the connected device.
 

onvif/client.py

@@ -9,6 +9,7 @@ from typing import ParamSpec, TypeVar
 from urllib.parse import urlparse, urlunparse
 
 from lxml import etree
+from zeep import Plugin
 
 from onvif.operator import CacheMode
 from onvif.services import (
@@ -50,13 +51,10 @@ from onvif.services import (
     TLSServer,
     Uplink,
 )
-from onvif.utils import (
-    ONVIFWSDL,
-    ONVIFOperationException,
-    XMLCapturePlugin,
-    ZeepPatcher,
-)
-from onvif.utils.plugins import ReferenceParametersPlugin
+from onvif.utils.exceptions import ONVIFOperationException
+from onvif.utils.plugins import ReferenceParametersPlugin, XMLCapturePlugin
+from onvif.utils.wsdl import ONVIFWSDL
+from onvif.utils.zeep import ZeepPatcher
 
 logger = logging.getLogger(__name__)
 logger.addHandler(logging.NullHandler())
@@ -66,7 +64,8 @@ R = TypeVar("R")
 
 
 def service(func: Callable[P, R]) -> Callable[P, R]:
-    """Decorator to wrap service accessor methods with `ONVIFOperationException` handling.
+    """Decorator to wrap service accessor methods with `ONVIFOperationException`
+    handling.
 
     This decorator catches any exception raised during service initialization and
     wraps it in `ONVIFOperationException` for consistent error handling across all
@@ -104,21 +103,25 @@ def service(func: Callable[P, R]) -> Callable[P, R]:
     return wrapper
 
 
-# pylint: disable=too-many-instance-attributes,too-many-locals,too-many-public-methods,too-many-statements
+# pylint: disable=too-many-instance-attributes,too-many-locals
+# pylint: disable=too-many-public-methods,too-many-statements
 class ONVIFClient:
-    """ONVIF Client for communicating with ONVIF-compliant devices.
+    """High-level ONVIF client for interacting with ONVIF-compliant devices.
 
     This is the main class for interacting with ONVIF devices. It provides access to
     all ONVIF services including Device Management, Media, PTZ, Events, Analytics, and more.
 
-    The client automatically discovers available services on the device using GetServices
-    or GetCapabilities, and provides lazy initialization for service endpoints.
+    The client automatically discovers available services on the device using `GetServices`
+    or `GetCapabilities`, and provides lazy initialization for service endpoints.
 
     Attributes:
-        services (list): List of available services from GetServices response
-        capabilities (CompoundValue): Device capabilities from GetCapabilities response (fallback)
-        xml_plugin (XMLCapturePlugin): XML capture plugin for debugging (if capture_xml=True)
+        services (list): List of available services from `GetServices` response
+        capabilities (CompoundValue): Device capabilities from `GetCapabilities` response (fallback)
+        xml_plugin (XMLCapturePlugin): XML capture plugin for debugging (if `capture_xml=True`)
         wsdl_dir (str | None): Custom WSDL directory path (if provided)
+
+    !!! tip "Version History"
+        - Available since [`>=v0.0.1`](/onvif-python/releases/#v0.0.1) (first release).
     """
 
     def __init__(
@@ -127,15 +130,15 @@ class ONVIFClient:
         port: int,
         username: str | None = None,
         password: str | None = None,
-        http_digest: bool = False,  # will use WS-Usernametoken by default (recommended! trust me)
+        http_digest: bool = False,  # will use WS-UsernameToken by default
         timeout: int = 10,
-        cache: CacheMode = CacheMode.ALL,
+        cache: CacheMode = CacheMode.DB,
         use_https: bool = False,
         verify_ssl: bool = False,
         apply_patch: bool = True,
         capture_xml: bool = False,
         wsdl_dir: str | None = None,
-        plugins: list | None = None,
+        plugins: list[Plugin] | None = None,
     ):
         """Initialize the ONVIF client.
 
@@ -144,7 +147,7 @@ class ONVIFClient:
             port (int): Device port number
             username (str | None): ONVIF username
             password (str | None): ONVIF password
-            http_digest (bool): Whether to use **HTTP Digest** or **WS-Usernametoken** for auth
+            http_digest (bool): Whether to use **HTTP Digest** or **WS-UsernameToken** for auth
             timeout (int): Request timeout in seconds
             cache (CacheMode): WSDL caching strategy
             use_https (bool): Use HTTPS instead of HTTP for secure communication
@@ -152,9 +155,16 @@ class ONVIFClient:
             apply_patch (bool): Whether to apply ``xsd:any`` flattening patch
             capture_xml (bool): Whether to use XML capture plugin for debugging SOAP requests/responses
             wsdl_dir (str | None): Custom WSDL directory path for using external WSDL files instead of built-in ones
-            plugins (list | None): List of enabled Zeep plugins
+            plugins (list[Plugin] | None): List of user-provided Zeep plugins (zeep.plugins)
+
+        !!! tip "Version History"
+            - Added in [`>=v0.0.4`](/onvif-python/releases/#v0.0.4): `apply_patch`
+            - Added in [`>=v0.0.6`](/onvif-python/releases/#v0.0.6): `capture_xml`
+            - Added in [`>=v0.1.0`](/onvif-python/releases/#v0.1.0): `wsdl_dir`
+            - Added in [`>=v0.2.2`](/onvif-python/releases/#v0.2.2): `plugins`
+            - Added in [`>=v0.3.0`](/onvif-python/releases/#v0.3.0): `http_digest`
+            - Changed in [`>=v0.3.0`](/onvif-python/releases/#v0.3.0): `username` → `str | None`, `password` → `str | None`
         """
-
         logger.info("Initializing ONVIF client for %s:%d", host, port)
         logger.debug(
             "Connection settings: HTTPS=%s, SSL_verify=%s, cache=%s, timeout=%ds",
@@ -219,14 +229,14 @@ class ONVIFClient:
                 if namespace and xaddr:
                     self._service_map[namespace] = xaddr
                     logger.debug("Mapped service: %s -> %s", namespace, xaddr)
-        except Exception as e:  # pylint: disable=broad-except
+        except (ValueError, AttributeError, ONVIFOperationException) as e:
             logger.warning("GetServices failed: %s", e)
             # Fallback to GetCapabilities if GetServices is not supported on device
             try:
                 logger.debug("Falling back to GetCapabilities")
                 self.capabilities = self._devicemgmt.GetCapabilities(Category="All")
                 logger.info("Successfully retrieved device capabilities")
-            except Exception as e2:  # pylint: disable=broad-except
+            except ONVIFOperationException as e2:
                 # If both fail, we'll use default URLs
                 logger.error("Both GetServices and GetCapabilities failed: %s", e2)
                 logger.warning("Using default URLs for services")
@@ -293,9 +303,9 @@ class ONVIFClient:
         self._authorizationserver: AuthorizationServer | None = None
         self._mediasigning: MediaSigning | None = None
 
-    def _get_xaddr(
+    def _get_xaddr(  # pylint: disable=too-many-branches
         self, service_name: str, service_path: str
-    ) -> str:  # pylint: disable=too-many-branches
+    ) -> str:
         """Resolve XAddr for ONVIF services using a comprehensive 3-tier discovery
         approach.
 

onvif/meta.py

@@ -1,6 +1,6 @@
-"""onvif-python: A Python library for interacting with ONVIF-compliant devices."""
+"""ONVIF Python: A Python library for interacting with ONVIF-compliant devices."""
 
 from typing import Final
 
-__version__: Final[str] = "0.3.1"
+__version__: Final[str] = "0.4.0"
 __repository__: Final[str] = "https://github.com/nirsimetri/onvif-python"