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

onvif/__init__.py

@@ -1,4 +1,4 @@
-"""ONVIF Python"""
+"""ONVIF Python."""
 
 from onvif.cli import main as ONVIFCLI
 from onvif.client import ONVIFClient

onvif/cli/helpers/__init__.py

@@ -0,0 +1,21 @@
+"""ONVIF CLI helpers."""
+
+from onvif.cli.helpers.discovery import discover_devices, select_device_interactive
+from onvif.cli.helpers.execution import execute_command, setup_warning_format
+from onvif.cli.helpers.files import save_output_to_file
+from onvif.cli.helpers.products import search_products
+from onvif.cli.helpers.wsdl_parser import (
+    get_method_documentation,
+    get_operation_type_info,
+)
+
+__all__ = [
+    "search_products",
+    "save_output_to_file",
+    "discover_devices",
+    "select_device_interactive",
+    "execute_command",
+    "setup_warning_format",
+    "get_method_documentation",
+    "get_operation_type_info",
+]

onvif/cli/helpers/discovery.py

@@ -0,0 +1,124 @@
+"""ONVIF discovery helpers."""
+
+from onvif.cli.utils import colorize
+from onvif.utils import ONVIFDiscovery
+
+
+def discover_devices(
+    timeout: int = 4,
+    interface: str | None = None,
+    prefer_https: bool = False,
+    filter_term: str | None = None,
+) -> list:
+    """Discover ONVIF devices on the network using WS-Discovery.
+
+    Args:
+        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
+
+    Returns:
+        List of discovered devices with connection info
+    """
+    # Use ONVIFDiscovery class
+    discovery = ONVIFDiscovery(timeout=timeout, interface=interface)
+
+    print(f"\n{colorize('Discovering ONVIF devices on network...', 'yellow')}")
+    print(f"Network interface: {colorize(discovery.get_local_ip(), 'white')}")
+    print(f"Timeout: {timeout}s")
+    if filter_term:
+        print(f"Filter: {colorize(filter_term, 'yellow')}")
+    print()
+
+    devices = discovery.discover(prefer_https=prefer_https, search=filter_term)
+
+    return devices
+
+
+def select_device_interactive(devices: list) -> tuple[str, int, bool] | None:
+    """Display devices and allow user to select one interactively.
+
+    Args:
+        devices (list): Discovered devices
+
+    Returns:
+        Tuple of (host, port, use_https) or None if cancelled
+    """
+    if not devices:
+        print(f"\n{colorize('No ONVIF devices found.', 'red')}")
+        return None
+
+    print(f"{colorize(f'Found {len(devices)} ONVIF device(s):', 'green')}")
+
+    for idx, device in enumerate(devices, 1):
+        idx_str = colorize(f"[{idx}]", "yellow")
+        protocol = "https" if device.get("use_https", False) else "http"
+        host_port = f"{device['host']}:{device['port']}"
+        protocol_indicator = (
+            colorize("🔒 HTTPS", "green")
+            if device.get("use_https", False)
+            else colorize("HTTP", "white")
+        )
+        print(f"\n{idx_str} {colorize(host_port, 'yellow')} ({protocol_indicator})")
+
+        # Remove uuid: or urn:uuid: prefix from EPR
+        epr_display = device["epr"]
+        if epr_display.startswith("urn:uuid:"):
+            epr_display = epr_display.replace("urn:uuid:", "")
+        elif epr_display.startswith("uuid:"):
+            epr_display = epr_display.replace("uuid:", "")
+        print(f"    [uuid] {epr_display}")
+
+        if device["xaddrs"]:
+            xaddrs_parts = [f"[{xaddr}]" for xaddr in device["xaddrs"]]
+            print(f"    [xaddrs] {' '.join(xaddrs_parts)}")
+
+        if device["types"]:
+            types_parts = [f"[{t}]" for t in device["types"]]
+            print(f"    [types] {' '.join(types_parts)}")
+
+        if device["scopes"]:
+            scope_parts = []
+            for scope in device["scopes"]:
+                # Remove the prefix "onvif://www.onvif.org/" if present
+                if scope.startswith("onvif://www.onvif.org/"):
+                    simplified = scope.replace("onvif://www.onvif.org/", "")
+                    scope_parts.append(f"[{simplified}]")
+                else:
+                    # Keep other scopes as-is (e.g., http:123)
+                    scope_parts.append(f"[{scope}]")
+
+            if scope_parts:
+                print(f"    [scopes] {' '.join(scope_parts)}")
+
+    # Simple selection (without arrow keys for cross-platform compatibility)
+    while True:
+        try:
+            selection = input(
+                f"\nSelect device number {colorize(f'1-{len(devices)}', 'white')} or {colorize('q', 'white')} to quit: "
+            )
+
+            if selection.lower() == "q":
+                return None
+
+            idx = int(selection)
+            if 1 <= idx <= len(devices):
+                selected = devices[idx - 1]
+                protocol = "https" if selected.get("use_https", False) else "http"
+                host_port = f"{selected['host']}:{selected['port']}"
+                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"))
+
+        except ValueError:
+            print(colorize("Invalid input. Please enter a number.", "red"))
+        except (EOFError, KeyboardInterrupt):
+            return None

onvif/cli/helpers/execution.py

@@ -0,0 +1,57 @@
+"""ONVIF command execution helpers."""
+
+import warnings
+from typing import Any
+
+from onvif.cli.utils import colorize, parse_json_params
+from onvif.client import ONVIFClient
+
+
+def execute_command(
+    client: ONVIFClient,
+    service_name: str,
+    method_name: str,
+    params_str: str | None = None,
+) -> Any:
+    """Execute a single ONVIF command.
+
+    Args:
+        client (ONVIFClient): ONVIFClient instance
+        service_name (str): Selected service for command execution
+        method_name (str): Method to execute by service
+        params_str (str | None): Provided params for method execution
+
+    Returns:
+        The operation response printed in terminal
+    """
+    # Get service instance
+    try:
+        service = getattr(client, service_name.lower())()
+    except AttributeError as e:
+        raise ValueError(f"{colorize('Unknown service:', 'red')} {service_name}") from e
+
+    # Get method
+    try:
+        method = getattr(service, method_name)
+    except AttributeError as e:
+        raise ValueError(
+            f"{colorize('Unknown method', 'red')} '{method_name}' for service '{service_name}'"
+        ) from e
+
+    # Parse parameters
+    params = parse_json_params(params_str) if params_str else {}
+
+    # Execute method
+    return method(**params)
+
+
+def setup_warning_format() -> None:
+    """Setup custom warning format to show clean, concise warnings."""
+
+    def custom_warning_format(
+        message, category, filename, lineno, line=None
+    ):  # pylint: disable=unused-argument
+        # Show only the warning message without file path and line number
+        return f"{category.__name__}: {message}\n"
+
+    warnings.formatwarning = custom_warning_format

onvif/cli/helpers/files.py

@@ -0,0 +1,189 @@
+"""File processing helpers."""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+from onvif.cli.utils import colorize
+from onvif.client import ONVIFClient
+
+
+def save_output_to_file(
+    result: Any, output_path: str, debug_mode: bool, client: ONVIFClient
+) -> None:
+    """Save command output to file in appropriate format based on file extension.
+
+    Args:
+        result (Any): The ONVIF command result
+        output_path (str): Path to output file
+        debug_mode (bool): Whether debug mode is enabled (for XML capture)
+        client (ONVIFClient): ONVIFClient instance (for accessing XML plugin)
+    """
+    try:
+        # Determine output format based on file extension
+        _, ext = os.path.splitext(output_path.lower())
+
+        if ext == ".json":
+            # Prepare output data
+            output_data = {}
+
+            # JSON format
+            output_data["result"] = _serialize_for_json(result)
+            output_data["timestamp"] = datetime.now(timezone.utc).isoformat()
+            output_data["raw_result"] = str(result)  # Add raw string as fallback
+
+            # Add XML data if debug mode is enabled and XML plugin is available
+            if debug_mode and client.xml_plugin:
+                output_data["debug"] = {
+                    "last_request_xml": client.xml_plugin.last_sent_xml,
+                    "last_response_xml": client.xml_plugin.last_received_xml,
+                    "last_operation": client.xml_plugin.last_operation,
+                }
+
+            with open(output_path, "w", encoding="utf-8") as f:
+                json.dump(output_data, f, indent=2, ensure_ascii=False)
+
+        elif ext == ".xml":
+            # XML format - prioritize raw SOAP XML over parsed result
+            if client.xml_plugin and client.xml_plugin.last_received_xml:
+                # Save the raw SOAP response XML with minimal wrapper
+                content = f"""<?xml version="1.0" encoding="UTF-8"?>
+<!-- ONVIF SOAP Response -->
+<!-- Timestamp: {datetime.now(timezone.utc).isoformat()} -->
+<!-- Operation: {client.xml_plugin.last_operation or 'Unknown'} -->
+
+{client.xml_plugin.last_received_xml}
+"""
+            else:
+                # Fallback: Simple XML wrapper for the parsed result
+                content = f"""<?xml version="1.0" encoding="UTF-8"?>
+<!-- ONVIF Command Output (Parsed Result) -->
+<!-- Timestamp: {datetime.now(timezone.utc).isoformat()} -->
+<!-- Note: Raw SOAP XML not available. Enable --debug for full SOAP capture. -->
+<onvif_result>
+<![CDATA[
+{result!s}
+]]>
+</onvif_result>
+"""
+
+            with open(output_path, "w", encoding="utf-8") as f:
+                f.write(content)
+
+        else:
+            # Plain text format (default)
+            content = "ONVIF Command Output\n"
+            content += f"Timestamp: {datetime.now(timezone.utc).isoformat()}\n"
+            content += f"{'='*50}\n\n"
+            content += str(result)
+
+            # Add debug information if available
+            if debug_mode and client.xml_plugin:
+                content += f"\n\n{'='*50}\n"
+                content += "DEBUG INFORMATION\n"
+                content += f"{'='*50}\n"
+                if client.xml_plugin.last_operation:
+                    content += f"Operation: {client.xml_plugin.last_operation}\n\n"
+                if client.xml_plugin.last_sent_xml:
+                    content += "SOAP Request:\n"
+                    content += client.xml_plugin.last_sent_xml + "\n\n"
+                if client.xml_plugin.last_received_xml:
+                    content += "SOAP Response:\n"
+                    content += client.xml_plugin.last_received_xml + "\n"
+
+            with open(output_path, "w", encoding="utf-8") as f:
+                f.write(content)
+
+    except (AttributeError, ValueError, OSError) as e:
+        print(f"{colorize('Error saving output:', 'red')} {e}", file=sys.stderr)
+        # Still print the result to console if file save fails
+        print(str(result))
+
+
+def _serialize_for_json(obj: Any) -> Any:
+    """Recursively serialize ONVIF objects for JSON output.
+
+    Args:
+        obj: Object to serialize
+
+    Returns:
+        JSON-serializable representation of the object
+    """
+    if obj is None:
+        return None
+    elif isinstance(obj, (str, int, float, bool)):
+        return obj
+    elif isinstance(obj, datetime):
+        return obj.isoformat()
+    elif isinstance(obj, (list, tuple)):
+        return [_serialize_for_json(item) for item in obj]
+    elif 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"):
+        result = {}
+        # Try to get all elements from XSD type
+        if hasattr(obj._xsd_type, "elements"):  # pylint: disable=protected-access
+            for (
+                elem_name,
+                _,
+            ) in obj._xsd_type.elements:  # pylint: disable=protected-access
+                try:
+                    value = getattr(obj, elem_name, None)
+                    if value is not None:
+                        result[elem_name] = _serialize_for_json(value)
+                except (AttributeError, TypeError):
+                    # Skip elements that can't be accessed or have type issues
+                    pass
+
+        # Also try regular attributes
+        for attr_name in dir(obj):
+            if not attr_name.startswith("_") and not callable(
+                getattr(obj, attr_name, None)
+            ):
+                try:
+                    attr_value = getattr(obj, attr_name)
+                    if attr_value is not None and attr_name not in result:
+                        result[attr_name] = _serialize_for_json(attr_value)
+                except (AttributeError, TypeError):
+                    # Skip attributes that can't be accessed or have type issues
+                    pass
+
+        return result
+
+    elif hasattr(obj, "__dict__"):
+        # Handle regular objects with attributes
+        result = {}
+        for key, value in obj.__dict__.items():
+            if not key.startswith("_"):  # Skip private attributes
+                result[key] = _serialize_for_json(value)
+
+        # If result is empty, try to get attributes using dir()
+        if not result:
+            for attr_name in dir(obj):
+                if not attr_name.startswith("_") and not callable(
+                    getattr(obj, attr_name, None)
+                ):
+                    try:
+                        attr_value = getattr(obj, attr_name)
+                        if attr_value is not None:
+                            result[attr_name] = _serialize_for_json(attr_value)
+                    except (AttributeError, TypeError):
+                        # Skip attributes that can't be accessed or have type issues
+                        pass
+
+        return result
+    elif 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)

onvif/cli/helpers/messages.py

@@ -0,0 +1,221 @@
+"""CLI messages."""
+
+from onvif.cli.utils import (
+    colorize,
+)
+from onvif.meta import __repository__, __version__
+
+
+def print_interactive_intro(args, device_info_text) -> str:
+    """Print interactive shell introduction."""
+    # Welcome message with enhanced info
+    banner_lines = [
+        "   ____  _   ___    ____________",
+        "  / __ \\/ | / / |  / /  _/ ____/",
+        " / / / /  |/ /| | / // // /_    ",
+        "/ /_/ / /|  / | |/ // // __/    ",
+        f"\\____/_/ |_/  |___/___/_/  v{__version__}",
+        "                                ",
+    ]
+
+    banner = "\n".join(colorize(line, "cyan") for line in banner_lines)
+    repo_info = "\n".join(
+        [
+            colorize("Star ⭐ this repo", "white"),
+            colorize(__repository__, "white"),
+        ]
+    )
+
+    # Build connection and CLI options info
+    options_info = []
+
+    # Connection options
+    if hasattr(args, "https") and args.https:
+        options_info.append(f"  Use HTTPS     : {colorize('True', 'green')}")
+
+    if hasattr(args, "no_verify_ssl") and args.no_verify_ssl:
+        options_info.append(f"  Verify SSL    : {colorize('False', 'red')}")
+
+    if hasattr(args, "timeout") and args.timeout != 10:  # 10 is default
+        options_info.append(
+            f"  Timeout       : {colorize(f'{args.timeout}s', 'yellow')}"
+        )
+
+    # CLI options
+    if hasattr(args, "debug") and args.debug:
+        options_info.append(f"  Debug Mode    : {colorize('True', 'green')}")
+
+    if hasattr(args, "no_patch") and args.no_patch:
+        options_info.append(f"  ZeepPatcher   : {colorize('Disabled', 'red')}")
+
+    if hasattr(args, "wsdl") and args.wsdl:
+        options_info.append(f"  Custom WSDL   : {colorize(args.wsdl, 'yellow')}")
+
+    if (
+        hasattr(args, "health_check_interval") and args.health_check_interval != 10
+    ):  # 10 is default
+        options_info.append(
+            f"  Health Check  : every {colorize(f'{args.health_check_interval}s', 'yellow')}"
+        )
+
+    # Format options info
+    options_display = ""
+    if options_info:
+        options_display = "\n" + "\n".join(options_info)
+
+    terminal_header = colorize("\n[ONVIF Terminal Client]", "yellow")
+
+    intro = (
+        f"{banner}\n"
+        f"{repo_info}\n"
+        f"{terminal_header}\n"
+        f"  Connected to  : {colorize(f'{args.host}:{args.port}', '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"
+        f"  - Type {colorize('devicemgmt', 'yellow')} to enter device management service\n"
+        f"  - Use {colorize('TAB', 'yellow')} completion for commands and methods\n\n"
+        f"{colorize('[Typical Commands]', 'magenta')}\n"
+        f"  - help        : Show help information\n"
+        f"  - ls          : List commands/services/methods in grid format\n"
+        f"  - <service>   : Enter service mode (e.g., devicemgmt)\n"
+        f"  - up          : Exit service mode (go up one level)\n"
+        f"  - info        : Show current device and connection info\n"
+        f"  - exit        : Exit shell\n\n"
+        f"Use {colorize('TAB', 'yellow')} for auto-completion. "
+        f"Type partial commands to see suggestions.\n"
+    )
+
+    return intro
+
+
+INTERACTIVE_HELP = f"""
+{colorize(f'ONVIF Interactive Shell — v{__version__}', 'cyan')}\n{colorize(__repository__, 'white')}
+
+{colorize('Basic Commands:', 'yellow')}
+  capabilities, caps       - Show device capabilities
+  services                 - Show available services with details
+  info                     - Show connection and device information
+  exit                     - Exit the shell
+  shortcuts                - Show available shortcuts
+
+{colorize('Navigation Commands:', 'yellow')}
+  <service>                - Enter service mode (e.g., devicemgmt, media)
+  <service> <argument>     - Enter service mode with argument (e.g. pullpoint SubscriptionRef=<value>)
+  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
+
+{colorize('Service Mode Commands:', 'yellow')}
+  desc <method>            - Show method documentation
+  type <method>            - Show input/output types from WSDL
+
+{colorize('Method Execution:', 'yellow')}
+  <method>                 - Execute method without parameters
+  <method> {{"param": "value"}}  - Execute method with JSON parameters
+  <method> param=value     - Execute method with simple parameters
+
+{colorize('Data Management:', 'yellow')}
+  store <name>             - Store last result with a name
+  show <name>              - Show stored data
+  show <name>[0]           - Show element at index (for lists)
+  show <name>.attribute    - Show specific attribute
+  show                     - List all stored data
+  rm <name>                - Remove stored data by name
+  cls                      - Clear all stored data
+
+{colorize('Using Stored Data in Methods:', 'yellow')}
+  Use $variable syntax to reference stored data in method parameters:
+  - $profiles[0].token                    - Access list element and attribute
+  - $profiles[0].VideoSourceConfiguration.SourceToken
+
+  Example:
+    GetProfiles                           - Get profiles
+    store profiles                        - Store result
+    show profiles[0].token                - Show first profile token
+    GetImagingSettings VideoSourceToken=$profiles[0].VideoSourceConfiguration.SourceToken
+
+{colorize('Debug Commands:', 'yellow')}
+  debug                    - Show last SOAP request & response (if --debug enabled)
+
+{colorize('Tab Completion:', 'yellow')}
+  Use {colorize('TAB', 'yellow')} key for auto-completion of commands, services, and methods
+  Type partial commands to see suggestions
+
+{colorize('Examples:', 'yellow')}
+  192.168.1.17:8000 > caps                # Show capabilities
+  192.168.1.17:8000 > dev<TAB>            # Completes to 'devicemgmt'
+  192.168.1.17:8000 > cd devicemgmt       # Enter device management
+  192.168.1.17:8000/devicemgmt > Get<TAB> # Show methods starting with 'Get'
+  192.168.1.17:8000/devicemgmt > GetServices {{"IncludeCapability": true}}
+  192.168.1.17:8000/devicemgmt > GetServices IncludeCapability=True
+  192.168.1.17:8000/devicemgmt > store services_info
+  192.168.1.17:8000/devicemgmt > up       # Exit service mode
+  192.168.1.17:8000 >                     # Back to root context
+            """
+
+INTERACTIVE_SHORTCUTS = f"""
+{colorize('Available Shortcuts:', 'cyan')}
+
+{colorize('Navigation:', 'yellow')}
+  <service>                - Enter service mode (e.g., devicemgmt, media)
+  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
+
+{colorize('Service Mode Commands:', 'yellow')}
+  desc <method>            - Show method documentation
+  type <method>            - Show input/output types from WSDL
+
+{colorize('Quick Access:', 'yellow')}
+  caps                     - Show capabilities (same as 'capabilities')
+
+{colorize('Tab Completion Examples:', 'yellow')}
+  dev<TAB>                 - Completes to 'devicemgmt'
+  med<TAB>                 - Completes to 'media'
+  Get<TAB>                 - Shows all methods starting with 'Get'
+        """
+
+# pylint: disable=line-too-long
+CLI_EPILOG = f"""
+Examples:
+  # Product search
+  {colorize('onvif', 'yellow')} --search c210
+  {colorize('onvif', 'yellow')} -s "axis camera"
+  {colorize('onvif', 'yellow')} --search hikvision --page 2 --per-page 5
+
+  # 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
+
+  # Discover with filtering
+  {colorize('onvif', 'yellow')} --discover --filter ptz --interactive
+  {colorize('onvif', 'yellow')} -d -f "C210" -i
+  {colorize('onvif', 'yellow')} -d -f "audio_encoder" -u admin -p admin123 -i
+
+  # Direct command execution
+  {colorize('onvif', 'yellow')} devicemgmt GetCapabilities Category=All --host 192.168.1.17 --port 8000 --username admin --password admin123
+  {colorize('onvif', 'yellow')} ptz ContinuousMove ProfileToken=Profile_1 Velocity={{'PanTilt': {{'x': -0.1, 'y': 0}}}} -H 192.168.1.17 -P 8000 -u admin -p admin123
+
+  # Save output to file
+  {colorize('onvif', 'yellow')} devicemgmt GetDeviceInformation --host 192.168.1.17 --port 8000 --username admin --password admin123 --output device_info.json
+  {colorize('onvif', 'yellow')} media GetProfiles --host 192.168.1.17 --port 8000 --username admin --password admin123 --output profiles.xml
+  {colorize('onvif', 'yellow')} ptz GetConfigurations --host 192.168.1.17 --port 8000 --username admin --password admin123 --output ptz_config.txt --debug
+
+  # Interactive mode
+  {colorize('onvif', 'yellow')} --host 192.168.1.17 --port 8000 --username admin --password admin123 --interactive
+
+  # Prompting for username and password
+  # (if not provided)
+  {colorize('onvif', 'yellow')} -H 192.168.1.17 -P 8000 -i
+
+  # Using HTTPS
+  {colorize('onvif', 'yellow')} media GetProfiles --host camera.example.com --port 443 --username admin --password admin123 --https
+        """