onvif-python 0.1.0__tar.gz → 0.1.2__tar.gz

{onvif_python-0.1.0/onvif_python.egg-info → onvif_python-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onvif-python
-Version: 0.1.0
+Version: 0.1.2
 Summary: A comprehensive and developer-friendly Python library for working with ONVIF-compliant devices
 Author-email: Nirsimetri Technologies® <open@nirsimetri.com>
 Maintainer: Kaburagi
@@ -40,10 +40,11 @@ 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.1.0-red?logo=archive)](https://github.com/nirsimetri/onvif-python/releases)
-<br>
-[![PyPI](https://img.shields.io/badge/PyPI-0.1.0-yellow?logo=archive)](https://pypi.org/project/onvif-python/)
+[![PyPI](https://img.shields.io/badge/PyPI-0.1.2-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)
+<br>
+[![Build](https://github.com/nirsimetri/onvif-python/actions/workflows/python-app.yml/badge.svg?branch=main)](https://github.com/nirsimetri/onvif-python/actions/workflows/python-app.yml)
+[![Upload Python Package](https://github.com/nirsimetri/onvif-python/actions/workflows/python-publish.yml/badge.svg)](https://github.com/nirsimetri/onvif-python/actions/workflows/python-publish.yml)
 
 **This project provides a comprehensive and developer-friendly Python library for working with ONVIF-compliant devices.** It is designed to be reliable, easy to integrate, and flexible enough to support a wide range of ONVIF profiles and services.  
 
@@ -66,6 +67,13 @@ This library simplifies that process by wrapping SOAP communication into a clean
 - **Companies** building video intelligence, analytics, or VMS platforms  
 - **Security integrators** who need reliable ONVIF interoperability across devices
 
+## Requirements
+
+- **Python**: 3.9 or higher
+- **Dependencies**:
+  - [`zeep>=4.3.0`](https://github.com/mvantellingen/python-zeep) - SOAP client for ONVIF communication
+  - [`requests>=2.32.0`](https://github.com/psf/requests) - HTTP library for network requests
+
 ## Installation
 
 From official [PyPI](https://pypi.org/project/onvif-python/):
@@ -151,6 +159,297 @@ 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.
 
+## ONVIF CLI
+
+> [!NOTE]
+> The CLI is automatically installed when you install the `onvif-python` see [Installation](#installation). This feature has been available since `onvif-python` version [`0.1.1`](https://github.com/nirsimetri/onvif-python/releases/tag/v0.1.1).
+
+![Windows](https://img.shields.io/badge/Windows-0078D6?style=plastic&logo=gitforwindows&logoColor=white)
+![Linux](https://img.shields.io/badge/Linux-FCC624?style=plastic&logo=linux&logoColor=black)
+![macOS](https://img.shields.io/badge/macOS-1A9FEE?style=plastic&logo=apple&logoColor=black)
+![Raspberry Pi](https://img.shields.io/badge/Raspberry%20Pi-A22846?style=plastic&logo=raspberrypi&logoColor=black)
+
+This library includes a powerful command-line interface (CLI) for interacting with ONVIF devices directly from your terminal. It supports both direct command execution and an interactive shell mode, providing a flexible and efficient way to manage and debug ONVIF devices.
+
+### Features
+
+- **Interactive Shell:** A user-friendly shell with tab completion, command history, and colorized output.
+- **Direct Command Execution:** Run ONVIF commands directly from the terminal for scripting and automation.
+- **Automatic Discovery:** Automatically detects available services on the device.
+- **Connection Management:** Supports HTTP/HTTPS, custom timeouts, and SSL verification.
+- **Data Management:** Store results from commands and use them as parameters in subsequent commands.
+- **Cross-Platform:** Works on Windows, macOS, Linux, and Raspberry Pi.
+
+### Screenshoot
+
+<table>
+  <tr>
+    <td width="34.2%">
+      <a href="https://github.com/nirsimetri/onvif-python">
+        <img src="./assets/onvif_cli.png" />
+      </a>
+    </td>
+    <td width="65.8%">
+        <a href="https://github.com/nirsimetri/onvif-python">
+        <img src="./assets/onvif_operations.png" />
+        </a>
+    </td>
+  </tr>
+  <tr>
+    <th align="center">
+      Onboarding
+    </th>
+    <th align="center">
+      List available operations
+    </th>
+  </tr>
+</table>
+
+### Help Command
+
+<details>
+<summary><b>1. Direct CLI</b></summary> 
+
+```bash
+usage: onvif [-h] [--host HOST] [--port PORT] [--username USERNAME] [--password PASSWORD] [--discover] [--timeout TIMEOUT] [--https] [--no-verify]
+             [--no-patch] [--interactive] [--debug] [--wsdl WSDL] [--cache {all,db,mem,none}]
+             [service] [method] [params ...]
+
+ONVIF Terminal Client —
+https://github.com/nirsimetri/onvif-python
+
+positional arguments:
+  service               ONVIF service name (e.g., devicemgmt, media, ptz)
+  method                Service method name (e.g., GetCapabilities, GetProfiles)
+  params                Method parameters as Simple Parameter or JSON string
+
+options:
+  -h, --help            show this help message and exit
+  --host HOST, -H HOST  ONVIF device IP address or hostname
+  --port PORT, -P PORT  ONVIF device port (default: 80)
+  --username USERNAME, -u USERNAME
+                        Username for authentication
+  --password PASSWORD, -p PASSWORD
+                        Password for authentication
+  --discover, -d        Discover ONVIF devices on the network using WS-Discovery
+  --timeout TIMEOUT     Connection timeout in seconds (default: 10)
+  --https               Use HTTPS instead of HTTP
+  --no-verify           Disable SSL certificate verification
+  --no-patch            Disable ZeepPatcher
+  --interactive, -i     Start interactive mode
+  --debug               Enable debug mode with XML capture
+  --wsdl WSDL           Custom WSDL directory path
+  --cache {all,db,mem,none}
+                        Caching mode for ONVIFClient (default: all). 'all': memory+disk, 'db': disk-only, 'mem': memory-only, 'none': disabled.
+
+Examples:
+  # Discover ONVIF devices on network
+  onvif --discover --username admin --password admin123 --interactive
+  onvif media GetProfiles --discover --username admin
+  onvif -d -i
+
+  # Direct command execution
+  onvif devicemgmt GetCapabilities Category=All --host 192.168.1.17 --port 8000 --username admin --password admin123
+  onvif ptz ContinuousMove ProfileToken=Profile_1 Velocity={"PanTilt": {"x": -0.1, "y": 0}} --host 192.168.1.17 --port 8000 --username admin --password admin123
+
+  # Interactive mode
+  onvif --host 192.168.1.17 --port 8000 --username admin --password admin123 --interactive
+
+  # Prompting for username and password
+  # (if not provided)
+  onvif -H 192.168.1.17 -P 8000 -i
+
+  # Using HTTPS
+  onvif media GetProfiles --host camera.example.com --port 443 --username admin --password admin123 --https
+```
+
+</details>
+
+<details>
+<summary><b>2. Interactive Shell</b></summary> 
+
+```bash
+ONVIF Interactive Shell Commands -
+https://github.com/nirsimetri/onvif-python
+
+Basic Commands:
+  capabilities, caps       - Show device capabilities
+  services                 - Show available services with details
+  info                     - Show connection and device information
+  exit, quit               - Exit the shell
+  shortcuts                - Show available shortcuts
+
+Navigation Commands:
+  <service>                - Enter service mode (e.g., devicemgmt, media)
+  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
+  desc <method>            - Show method documentation in service mode
+
+Method Execution:
+  <method>                 - Execute method without parameters
+  <method> {"param": "value"}  - Execute method with JSON parameters
+  <method> param=value     - Execute method with simple parameters
+
+Data Management:
+  store <name>             - Store last result with a name
+  show <name>              - Show stored data
+  show <name>.attribute    - Show specific attribute
+  show                     - List all stored data
+  rm <name>                - Remove stored data by name
+  cls                      - Clear all stored data
+
+Using Stored Data in Methods:
+  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
+
+Debug Commands:
+  debug                    - Show last SOAP request & response (if --debug enabled)
+
+Tab Completion:
+  Use TAB key for auto-completion of commands, services, and methods
+  Type partial commands to see suggestions
+
+Examples:
+  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
+```
+
+</details>
+
+### Usage
+
+**1. Interactive Mode**
+
+The interactive shell is recommended for exploration and debugging. It provides an intuitive way to navigate services, call methods, and view results.
+
+To start the interactive shell, provide the connection details:
+
+```bash
+onvif --host 192.168.1.17 --port 8000 --username admin --password admin123 -i
+```
+
+If you omit the username or password, you will be prompted to enter them securely.
+
+**Interactive Shell Commands:**
+| Command | Description |
+|---|---|
+| `help` | Show help information |
+| `ls` | List available services or methods in the current context |
+| `cd <service>` | Enter a service mode (e.g., `cd devicemgmt`) |
+| `up` | Go back to the root context |
+| `pwd` | Show the current service context |
+| `desc <method>` | Show documentation for a method |
+| `store <name>` | Store the last result with a variable name |
+| `show <name>` | Display a stored variable |
+| `exit` / `quit` | Exit the shell |
+
+> [!IMPORTANT]
+> You can see all the other commands available in the interactive shell by trying it out directly. The interactive shell runs periodic background health checks to detect connection loss. It uses silent TCP pings to avoid interrupting your work and will automatically exit if the device is unreachable, similar to an SSH session.
+
+**2. Device Discovery (WS-Discovery)**
+
+The CLI includes automatic ONVIF device discovery using the WS-Discovery protocol. This feature allows you to find all ONVIF-compliant devices on your local network without knowing their IP addresses beforehand.
+
+**Discover and Connect Interactively:**
+```bash
+# Discover devices and enter interactive mode
+onvif --discover --username admin --password admin123 --interactive
+
+# Short form
+onvif -d -u admin -p admin123 -i
+```
+
+**Discover and Execute Command:**
+```bash
+# Discover devices and execute a command on the selected device
+onvif media GetProfiles --discover --username admin --password admin123
+
+# Short form
+onvif media GetProfiles -d -u admin -p admin123
+```
+
+**How Device Discovery Works:**
+
+1. **Automatic Network Scanning**: Sends a WS-Discovery Probe message to the multicast address `239.255.255.250:3702`
+2. **Device Detection**: Listens for ProbeMatch responses from ONVIF devices (default timeout: 4 seconds)
+3. **Interactive Selection**: Displays a numbered list of discovered devices with their details:
+   - Device UUID (Endpoint Reference)
+   - XAddrs (ONVIF service URLs)
+   - Device Types (e.g., NetworkVideoTransmitter)
+   - Scopes (name, location, hardware, profile information)
+4. **Connection**: Once you select a device, the CLI automatically connects using the discovered host and port
+
+**Example Discovery Output:**
+```
+Discovering ONVIF devices on network...
+Network interface: 192.168.1.100
+Timeout: 4s
+
+Found 2 ONVIF device(s):
+
+[1] 192.168.1.14:2020
+    [id] uuid:3fa1fe68-b915-4053-a3e1-a8294833fe3c
+    [xaddrs] http://192.168.1.14:2020/onvif/device_service
+    [types] tdn:NetworkVideoTransmitter
+    [scopes] [name/C210] [hardware/C210] [Profile/Streaming] [location/Hong Kong]
+
+[2] 192.168.1.17:8000
+    [id] urn:uuid:7d04ff31-61e6-11f0-a00c-6056eef47207
+    [xaddrs] http://192.168.1.17:8000/onvif/device_service
+    [types] dn:NetworkVideoTransmitter tds:Device
+    [scopes] [type/NetworkVideoTransmitter] [location/unknown] [name/IPC_123465959]
+
+Select device number 1-2 or q to quit: 1
+
+Selected: 192.168.1.14:2020
+```
+
+**Notes:**
+
+- Discovery only works on the local network (same subnet)
+- Some networks may block multicast traffic (check firewall settings)
+- The `--host` and `--port` arguments are not required when using `--discover`
+- You can still provide `--username` and `--password` upfront to avoid prompts
+
+**3. Direct Command Execution**
+
+You can also execute a single ONVIF command directly. This is useful for scripting or quick checks.
+
+**Syntax:**
+```bash
+onvif <service> <method> [parameters...] -H <host> -P <port> -u <user> -p <pass>
+```
+
+**Example:**
+```bash
+# Get device capabilities
+onvif devicemgmt GetCapabilities Category=All -H 192.168.1.17 -P 8000 -u admin -p admin123
+
+# Move a PTZ camera
+onvif ptz ContinuousMove ProfileToken=Profile_1 Velocity='{"PanTilt": {"x": 0.1}}' -H 192.168.1.17 -P 8000 -u admin -p admin123
+```
+
+### CLI Parameters
+
+All `ONVIFClient` parameters (like `--timeout`, `--https`, `--cache`, etc.) are available as command-line arguments. Use `onvif --help` to see all available options.
+
 ## 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:
@@ -193,9 +492,9 @@ The `ONVIFClient` class provides various configuration options to customize the
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| `apply_patch` | `bool` | ❌ No | `True` | Enable zeep patching for better `xsd:any` field parsing and automatic flattening, applied at (>= [`v0.0.4`](https://github.com/nirsimetri/onvif-python/releases/tag/v0.0.4)) |
-| `capture_xml` | `bool` | ❌ No | `False` | Enable XML capture plugin for debugging SOAP requests/responses, applied at (>= [`v0.0.6`](https://github.com/nirsimetri/onvif-python/releases/tag/v0.0.6)) |
-| `wsdl_dir`    | `str`  | ❌ No | `None` | Custom WSDL directory path for using external WSDL files instead of built-in ones (e.g., `/path/to/custom/wsdl`), applied at (>= [`v0.1.0`](https://github.com/nirsimetri/onvif-python/releases/tag/v0.1.0)) |
+| `apply_patch` | `bool` | ❌ No | `True` | Enable zeep patching for better `xsd:any` field parsing and automatic flattening, applied at ([`>=v0.0.4`](https://github.com/nirsimetri/onvif-python/releases/tag/v0.0.4)) |
+| `capture_xml` | `bool` | ❌ No | `False` | Enable XML capture plugin for debugging SOAP requests/responses, applied at ([`>=v0.0.6`](https://github.com/nirsimetri/onvif-python/releases/tag/v0.0.6)) |
+| `wsdl_dir`    | `str`  | ❌ No | `None` | Custom WSDL directory path for using external WSDL files instead of built-in ones (e.g., `/path/to/custom/wsdl`), applied at ([`>=v0.1.0`](https://github.com/nirsimetri/onvif-python/releases/tag/v0.1.0)) |
 
 </details>
 
@@ -428,53 +727,6 @@ else:
 - **GetCapabilities** is **mandatory** for all ONVIF-compliant devices, ensuring broader compatibility
 - **Default URLs** guarantee basic connectivity even with non-compliant devices
 
-**Get detailed service information:**
-
-If you need comprehensive service details, you can manually call `GetServices` with capabilities:
-
-```python
-device = client.devicemgmt()
-
-try:
-    # Try to get detailed service information
-    services = device.GetServices(IncludeCapability=True)
-    for service in services:
-        print(f"Service: {service.Namespace}")
-        print(f"XAddr: {service.XAddr}")
-        if hasattr(service, 'Capabilities'):
-            print(f"Capabilities: {service.Capabilities}")
-except Exception:
-    # Fallback to GetCapabilities for legacy devices
-    capabilities = device.GetCapabilities()
-    print("Capabilities:", capabilities)
-```
-
-**Access capabilities information:**
-
-When using `GetCapabilities` fallback, you can access capability information:
-
-```python
-device = client.devicemgmt()
-
-try:
-    # Get capabilities information from device
-    capabilities = device.GetCapabilities()
-    
-    # Main services (always available)
-    print("Media XAddr:", getattr(capabilities.Media, 'XAddr', 'Not available'))
-    print("PTZ XAddr:", getattr(capabilities.PTZ, 'XAddr', 'Not available'))
-    
-    # Extension services (device-dependent)
-    ext = getattr(capabilities, 'Extension', None)
-    if ext:
-        print("DeviceIO XAddr:", getattr(ext.DeviceIO, 'XAddr', 'Not available'))
-        print("Recording XAddr:", getattr(ext.Recording, 'XAddr', 'Not available'))
-        print("Search XAddr:", getattr(ext.Search, 'XAddr', 'Not available'))
-        print("Replay XAddr:", getattr(ext.Replay, 'XAddr', 'Not available'))
-except Exception as e:
-    print(f"Error getting capabilities: {e}")
-```
-
 > [!TIP]
 > The library handles service discovery automatically with intelligent fallback. You typically don't need to call discovery methods manually unless you need detailed capability information or want to refresh the service list after device configuration changes.
 
@@ -630,8 +882,8 @@ Some ONVIF services have multiple bindings in the same WSDL. These typically inc
 ## Future Improvements (Stay tuned and star ⭐ this repo)
 
 - [x] ~~Add debugging mode with raw xml on SOAP requests and responses.~~ ([c258162](https://github.com/nirsimetri/onvif-python/commit/c258162))
-- [x] ~~Add functionality for `ONVIFClient` to accept a custom `wsdl_dir` service.~~ ([65f2570](https://github.com/nirsimetri/onvif-python/commit/65f257092e4c9daa23dd0d00825ed38a45d23b70))
-- [ ] Add `ONVIF CLI` program to interact directly with ONVIF devices via terminal.
+- [x] ~~Add functionality for `ONVIFClient` to accept a custom `wsdl_dir` service.~~ ([65f2570](https://github.com/nirsimetri/onvif-python/commit/65f2570))
+- [x] ~~Add `ONVIF CLI` program to interact directly with ONVIF devices via terminal.~~ ([645be01](https://github.com/nirsimetri/onvif-python/commit/645be01))
 - [ ] Add asynchronous (async/await) support for non-blocking ONVIF operations and concurrent device communication.
 - [ ] Implement structured data models for ONVIF Schemas using [xsdata](https://github.com/tefra/xsdata).
 - [ ] Integrate [xmltodict](https://github.com/martinblech/xmltodict) for simplified XML parsing and conversion.