Skip to content

Commit 671992a

Browse files
kaburagiseckaburagisec
committed
docs(readme): Bump version to v0.0.7
1 parent d64ccc0 commit 671992a

File tree

2 files changed

+374
-4
lines changed

2 files changed

+374
-4
lines changed

‎README.md‎

Lines changed: 187 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
[![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/nirsimetri/onvif-python?tab=MIT-1-ov-file)
44
[![DeepWiki](https://img.shields.io/badge/DeepWiki-AI%20Wiki-orange)](https://deepwiki.com/nirsimetri/onvif-python)
5-
[![Release](https://img.shields.io/badge/Release-v0.0.6-red?logo=archive)](https://github.com/nirsimetri/onvif-python/releases)
5+
[![Release](https://img.shields.io/badge/Release-v0.0.7-red?logo=archive)](https://github.com/nirsimetri/onvif-python/releases)
66
<br>
7-
[![PyPI](https://img.shields.io/badge/PyPI-0.0.6-yellow?logo=archive)](https://pypi.org/project/onvif-python/)
7+
[![PyPI](https://img.shields.io/badge/PyPI-0.0.7-yellow?logo=archive)](https://pypi.org/project/onvif-python/)
88
[![Downloads](https://img.shields.io/pypi/dm/onvif-python?label=PyPI%20Downloads)](https://clickpy.clickhouse.com/dashboard/onvif-python)
99

1010
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/`]
109109
> [!IMPORTANT]
110110
> 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.
111111
112+
## ONVIFClient Parameters
113+
114+
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:
115+
116+
### Basic Parameters
117+
118+
| Parameter | Type | Required | Default | Description |
119+
|-----------|------|----------|---------|-------------|
120+
| `host` | `str` | ✅ Yes | - | IP address or hostname of the ONVIF device (e.g., `"192.168.1.17"`) |
121+
| `port` | `int` | ✅ Yes | - | Port number for ONVIF service (common ports: `80`, `8000`, `8080`) |
122+
| `username` | `str` | ✅ Yes | - | Username for device authentication (use digest authentication) |
123+
| `password` | `str` | ✅ Yes | - | Password for device authentication |
124+
125+
### Connection Parameters
126+
127+
| Parameter | Type | Required | Default | Description |
128+
|-----------|------|----------|---------|-------------|
129+
| `timeout` | `int` | ❌ No | `10` | Connection timeout in seconds for SOAP requests |
130+
| `use_https` | `bool` | ❌ No | `False` | Use HTTPS instead of HTTP for secure communication |
131+
| `verify_ssl` | `bool` | ❌ No | `True` | Verify SSL certificates when using HTTPS (set to `False` for self-signed certificates) |
132+
133+
### Caching Parameters
134+
135+
| Parameter | Type | Required | Default | Description |
136+
|-----------|------|----------|---------|-------------|
137+
| `cache` | `CacheMode` | ❌ No | `CacheMode.ALL` | WSDL caching strategy (see [Cache Modes](#cache-modes) below) |
138+
139+
### Feature Parameters
140+
141+
| Parameter | Type | Required | Default | Description |
142+
|-----------|------|----------|---------|-------------|
143+
| `apply_patch` | `bool` | ❌ No | `True` | Enable zeep patching for better xsd:any field parsing and automatic flattening |
144+
| `capture_xml` | `bool` | ❌ No | `False` | Enable XML capture plugin for debugging SOAP requests/responses |
145+
146+
### Cache Modes
147+
148+
The library provides four caching strategies via the `CacheMode` enum:
149+
150+
| Mode | Description | Best For | Startup Speed | Disk Usage | Memory Usage |
151+
|------|-------------|----------|---------------|------------|--------------|
152+
| `CacheMode.ALL` | In-memory + disk cache (SQLite) | Production servers, multi-device apps | ⚡⚡⚡ Fast | 💾 High | 🧠 High |
153+
| `CacheMode.DB` | Disk cache only (SQLite) | Batch jobs, CLI tools | ⚡⚡ Medium | 💾 Medium | 🧠 Low |
154+
| `CacheMode.MEM` | In-memory cache only | Short-lived scripts, demos | ⚡⚡ Medium | 💾 None | 🧠 Medium |
155+
| `CacheMode.NONE` | No caching | Testing, debugging | ⚡ Slow | 💾 None | 🧠 Low |
156+
157+
**Recommendation:** Use `CacheMode.ALL` (default) for production applications to maximize performance.
158+
159+
### Usage Examples
160+
161+
**Basic Connection:**
162+
```python
163+
from onvif import ONVIFClient
164+
165+
# Minimal configuration
166+
client = ONVIFClient("192.168.1.17", 80, "admin", "password")
167+
```
168+
169+
**Secure Connection (HTTPS):**
170+
```python
171+
from onvif import ONVIFClient
172+
173+
# Connect via HTTPS with custom timeout
174+
client = ONVIFClient(
175+
"your-cctv-node.viewplexus.com",
176+
443, # HTTPS port
177+
"admin",
178+
"password",
179+
timeout=30,
180+
use_https=True,
181+
verify_ssl=False # For self-signed certificates
182+
)
183+
```
184+
185+
**Performance Optimized (Memory Cache):**
186+
```python
187+
from onvif import ONVIFClient, CacheMode
188+
189+
# Use memory-only cache for quick scripts
190+
client = ONVIFClient(
191+
"192.168.1.17",
192+
80,
193+
"admin",
194+
"password",
195+
cache=CacheMode.MEM
196+
)
197+
```
198+
199+
**No Caching (Testing):**
200+
```python
201+
from onvif import ONVIFClient, CacheMode
202+
203+
# Disable all caching for testing
204+
client = ONVIFClient(
205+
"192.168.1.17",
206+
80,
207+
"admin",
208+
"password",
209+
cache=CacheMode.NONE,
210+
apply_patch=False # Use original zeep behavior
211+
)
212+
```
213+
214+
**Debugging Mode (XML Capture):**
215+
```python
216+
from onvif import ONVIFClient
217+
218+
# Enable XML capture for debugging
219+
client = ONVIFClient(
220+
"192.168.1.17",
221+
80,
222+
"admin",
223+
"password",
224+
capture_xml=True # Captures all SOAP requests/responses
225+
)
226+
227+
# Make some ONVIF calls
228+
device = client.devicemgmt()
229+
info = device.GetDeviceInformation()
230+
services = device.GetCapabilities()
231+
232+
# Access the XML capture plugin
233+
if client.xml_plugin:
234+
# Get last captured request/response
235+
print("Last Request XML:")
236+
print(client.xml_plugin.last_sent_xml)
237+
238+
print("\nLast Response XML:")
239+
print(client.xml_plugin.last_received_xml)
240+
241+
print(f"\nLast Operation: {client.xml_plugin.last_operation}")
242+
243+
# Get complete history of all requests/responses
244+
print(f"\nTotal captured operations: {len(client.xml_plugin.history)}")
245+
for item in client.xml_plugin.history:
246+
print(f" - {item['operation']} ({item['type']})")
247+
248+
# Save captured XML to files
249+
client.xml_plugin.save_to_file(
250+
request_file="last_request.xml",
251+
response_file="last_response.xml"
252+
)
253+
254+
# Clear history when done
255+
client.xml_plugin.clear_history()
256+
```
257+
258+
> [!NOTE]
259+
> **XML Capture Plugin Methods:**
260+
> - `last_sent_xml` - Get the last SOAP request XML
261+
> - `last_received_xml` - Get the last SOAP response XML
262+
> - `last_operation` - Get the name of the last operation
263+
> - `history` - List of all captured requests/responses with metadata
264+
> - `get_last_request()` - Method to get last request
265+
> - `get_last_response()` - Method to get last response
266+
> - `get_history()` - Method to get all history
267+
> - `save_to_file(request_file, response_file)` - Save XML to files
268+
> - `clear_history()` - Clear captured history
269+
270+
271+
**Production Configuration:**
272+
```python
273+
from onvif import ONVIFClient, CacheMode
274+
275+
# Recommended production settings
276+
client = ONVIFClient(
277+
host="your-cctv-node.viewplexus.com",
278+
port=443,
279+
username="admin",
280+
password="secure_password",
281+
timeout=15,
282+
cache=CacheMode.ALL, # Maximum performance
283+
use_https=True, # Secure communication
284+
verify_ssl=True, # Verify certificates (default)
285+
apply_patch=True, # Enhanced parsing (default)
286+
capture_xml=False # Disable debug mode (default)
287+
)
288+
```
289+
290+
### Notes
291+
292+
- **Authentication:** This library uses **WS-UsernameToken with Digest** authentication by default, which is the standard for ONVIF devices.
293+
- **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.
294+
- **XML Capture:** Only use `capture_xml=True` during development/debugging as it increases memory usage and may expose sensitive data in logs.
295+
- **Cache Location:** Disk cache (when using `CacheMode.DB` or `CacheMode.ALL`) is stored in `~/.onvif-python/onvif_zeep_cache.sqlite`.
296+
112297
## Service Discovery: Understanding Device Capabilities
113298

114299
> [!WARNING]

0 commit comments

Comments
 (0)