pytvt 0.5.1__tar.gz

pytvt-0.5.1/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+
+# pypi
+.pypirc
+
+# Build / publish artefacts
+*.whl
+*.tar.gz
+
+# Proprietary/native SDK artefacts
+*.so
+*.so.*
+*.dll
+*.dylib
+*.lib
+*.a
+*.h
+
+# Local vendor SDK checkouts/extractions
+bridges/sdk_local/tvt/
+tvt-api/tvt/
+
+# Node (bridges/sdk_local)
+bridges/sdk_local/node_modules/
+
+# Environment / secrets
+.env
+
+# OS
+.DS_Store
+
+# Device inventory (contains site-specific data)
+files/
+
+# Debug/development scripts (not in tools/)
+debug_*.py
+parse_init.py
+
+# Logs and dumps
+*.log
+*.dump
+*.pcap
+*.cap
+
+# Scan output artifacts
+output/
+*.csv
+*.json.bak
+*.xlsx
+failed_devices.json
+
+# Docker (Dockerfile lives in tvt-api repo now)
+Dockerfile
+.dockerignore
+
+# Legacy
+Pipfile.lock
+

pytvt-0.5.1/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.1] — 2026-04-14
+
+### Changed
+
+- **Release hardening for PyPI** — native TVT SDK components are now loaded only
+  at runtime from explicit user-provided paths or environment variables.
+- **SDK path configuration** — added `TVT_SDK_PATH` and `TVT_SCAN_SCRIPT`
+  support across config loading, `DeviceManager`, `NetSdkClient`, and the
+  local Node.js bridge, while preserving legacy env vars for local workflows.
+- **Packaging safety** — expanded build exclusions, MANIFEST rules, and
+  `.gitignore` patterns to prevent native SDK binaries, headers, and local SDK
+  workspaces from being published or accidentally committed.
+- **Documentation** — clarified that the proprietary TVT SDK is never
+  redistributed, documented runtime SDK setup, and separated SDK-backed
+  features from SDK-free features.
+
+## [0.5.0] — 2026-04-09
+
+### Added
+
+- **`DeviceManager` unified facade** — single API for TVT device operations with
+  automatic backend selection. Probes native SDK availability first, then falls
+  back to an SDK bridge service. Supports forced backend selection.
+  - `device_info()`, `device_time()`, `snapshot()`, `rtsp_url()`, `ptz()`,
+    `ptz_preset()`, `reboot()` — all return the same result types regardless
+    of backend.
+  - `available_backends()` — probe what's available on the current platform.
+  - `Backend` enum, `NoBackendAvailable` exception.
+- **`is_netsdk_available()` probe** — check if the native SDK is loadable without
+  actually loading it (platform + architecture + file existence check).
+- **Expanded netsdk loader** — searches explicit path/env var → SDK root →
+  system. Added `_arch_dir()` for platform-specific directory selection,
+  pre-loading of companion `.so` dependencies.
+- **aarch64 support** — loader recognizes `linux-arm64` bin directory for ARM64 Linux.
+
+### Changed
+
+- `netsdk/__init__.py` now exports `is_netsdk_available` and `NetSdkUnavailable`.
+- Public `__init__.py` exports `DeviceManager`, `Backend`, `NoBackendAvailable`,
+  `available_backends`.
+
+## [0.4.0] — 2026-04-08
+
+### Added
+
+- **`pytvt.netsdk` package** — ctypes bindings for the TVT NetSDK C++ library
+  (`libdvrnetsdk.so`). `NetSdkClient` + `DeviceSession` with 25+ methods covering
+  device info, PTZ, snapshots, RTSP URLs, alarms, recording, firmware, disks,
+  users, time sync, and more.
+- **`SdkHttpClient`** — typed Python client for an SDK bridge service with
+  10 methods: `health()`, `scan()`, `device_info()`, `device_time()`, `snapshot()`,
+  `rtsp_url()`, `ptz()`, `ptz_preset()`, `reboot()`.
+- **Result dataclasses** — `DeviceInfoResult`, `DeviceTimeResult`, `RtspUrlResult`,
+  `CommandResult` for SDK HTTP responses.
+- **135 netsdk tests** + **26 SdkHttpClient tests** (161 new tests).
+
+## [0.3.0] — 2026-04-07
+
+### Added
+
+- **`WebApiClient`** — TVT HTTP API (LAPI protocol) client with HTTP Basic auth.
+  Per-device management: capability detection, device info, channels, disks,
+  date/time, password management, image/stream/audio/OSD configuration, snapshots
+  with RTSP fallback, recording status and search.
+- **66 new tests** for the Web API client.
+
+## [0.2.0] — 2026-04-06
+
+First packaged release. Restructured from flat scripts into an installable Python
+package with formalized architecture, new operator-facing features, and
+comprehensive test coverage.
+
+### Added
+
+- **Scan diffing / change detection** — compare two JSON scan result files to detect
+  device and camera changes between runs. New `pytvt-diff` CLI command with
+  human-readable, JSON, and summary output modes. New library API:
+  `diff_scans()`, `load_scan_file()`, `ScanDiff`, `DeviceDiff`.
+- **Backend family / integration mode architecture** — formalized `BackendFamily`
+  (protocol, sdk) and `IntegrationMode` (compat_bridge, direct_sdk) enums with
+  `CompositeStrategy` for multi-backend fallback.
+- **Execution plan layer** — `ExecutionPlan` dataclass and `resolve_execution_plan()`
+  resolver that makes "what will be executed" explicit and inspectable before a
+  scan runs.
+- **Backend registry** — `register()` / `get()` / `dispatch()` dispatch table
+  mapping (family, mode) tuples to scan callables, with default wiring at import time.
+- **Research / reference isolation** — protocol reverse-engineering scripts moved to
+  `research/` with clear warning headers. Import boundary enforced by test.
+- **Typed exception hierarchy** — `PytvtError`, `BackendError`, `RegistryError`.
+- **Comprehensive test suite** — 237 tests across 13 files covering protocol
+  encryption, config precedence, models, scanner dispatch, CLI parsing, output
+  formatting, discovery, SDK backends, architecture invariants, and scan diffing.
+- **CI pipeline** — GitHub Actions running pytest + ruff on Python 3.10–3.13.
+- **Contributor docs** — CONTRIBUTING.md with code tier guidance, PR template,
+  issue templates.
+- **`pytvt-diff` console script** — registered in pyproject.toml alongside the
+  existing four CLI entry points.
+
+### Changed
+
+- **Package layout** — migrated from flat scripts to `src/pytvt/` installable
+  package with hatchling build backend.
+- **CLI decomposition** — split monolithic main.py into focused modules: cli.py,
+  config.py, models.py, scanner.py, protocol.py, discovery.py, output.py,
+  sdk_http.py, sdk_local.py, nvr_api.py, snapshot.py.
+- **Data models** — replaced raw dicts with typed dataclasses (`ScannerConfig`,
+  `DeviceEntry`, `CameraInfo`, `ScanResult`) with factory methods and serialization.
+- **Backend normalization** — CLI backend strings (`protocol`, `sdk`, `sdk-local`,
+  `both`) are normalized via `resolve_backend()` with backward-compatible aliases
+  (`sdk_local` → `sdk-local`, `compat_bridge` → `sdk`, `direct_sdk` → `sdk-local`).
+- **Node.js bridge** — moved `scan_nvr.mjs` to `bridges/sdk_local/` with its own
+  `package.json`, isolated from the Python package.
+- **README** — complete rewrite with architecture diagram, backend comparison table,
+  integration mode explanations, full CLI reference, and project structure tree.
+
+### Licensing
+
+- Licensed under MIT starting from 1.0.0. Previous versions were AGPLv3.
+
+[0.5.1]: https://github.com/dannielperez/pytvt/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/dannielperez/pytvt/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/dannielperez/pytvt/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/dannielperez/pytvt/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/dannielperez/pytvt/releases/tag/v0.2.0

pytvt-0.5.1/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing to pytvt
+
+Thanks for your interest in contributing. This is a solo-maintained project, but bug reports, fixes, and well-scoped improvements are welcome.
+
+## Getting Started
+
+```bash
+git clone https://github.com/dannielperez/pytvt.git
+cd pytvt
+pip install -e ".[dev]"
+```
+
+## Development
+
+### Running tests
+
+```bash
+pytest
+```
+
+### Linting + formatting
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+### Type checking (optional)
+
+```bash
+mypy src/pytvt/
+```
+
+## Releases
+
+Releases should use GitHub Actions OIDC trusted publishing, not manual `twine upload` tokens.
+
+Configure trusted publishers on both TestPyPI and PyPI with these values:
+
+- Owner: `dannielperez`
+- Repository: `pytvt`
+- Workflow: `publish.yml`
+- Environment: `testpypi` for TestPyPI, `pypi` for production PyPI
+
+The publish workflow is designed to:
+
+- run CI and build validation
+- publish to TestPyPI via OIDC
+- install and smoke-test the TestPyPI package
+- publish to PyPI via OIDC only after TestPyPI validation succeeds
+
+## Code Style
+
+- Python 3.10+ — use modern syntax (`X | Y` unions, etc.)
+- Formatting and linting handled by [Ruff](https://docs.astral.sh/ruff/)
+- Prefer stdlib `dataclasses` for data models
+- Keep functions small and testable — avoid side effects in library code
+- Include type annotations on public APIs
+
+## Pull Requests
+
+1. Fork the repo and create a feature branch
+2. Keep changes focused — one concern per PR
+3. Add or update tests for changed behavior
+4. Run `ruff check` and `pytest` before submitting
+5. Fill out the PR template
+
+## Code Tiers
+
+pytvt separates code into three tiers. Understand which tier you are working in:
+
+| Tier | Location | CI-gated | Imported at runtime |
+|---|---|---|---|
+| **Published package** | `src/pytvt/` | Yes | Yes |
+| **Local helper runtimes** | `bridges/`, `tvt-api/` | No | Optional, developer-managed |
+| **Research / reference** | `research/` | No | **No** — never import |
+| **Operational tools** | `tools/` | No | Imports *from* pytvt |
+
+**Key rule:** code in `src/pytvt/` must never import from `research/` or `tools/`. This boundary is enforced by `tests/test_architecture.py::TestImportBoundary`.
+
+If you are adding protocol research scripts, put them in `research/` with the standard header:
+
+```python
+#!/usr/bin/env python3
+"""
+RESEARCH / REFERENCE ONLY — not part of the pytvt runtime.
+
+<description>
+
+See research/README.md for context.
+"""
+```
+
+## Bug Reports
+
+Use the GitHub issue templates. Include:
+
+- Python version and OS
+- Steps to reproduce
+- Expected vs actual behavior
+- Full error output / traceback
+
+## Scope
+
+This project focuses on TVT NVR device management. Out-of-scope:
+
+- Support for non-TVT vendors (see related repos)
+- Features requiring always-on infrastructure
+- GUI / web interface
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

pytvt-0.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danniel Perez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytvt-0.5.1/MANIFEST.in

@@ -0,0 +1,41 @@
+# MANIFEST.in — controls source distribution (sdist) contents.
+#
+# Hatchling does not use MANIFEST.in directly, but this file serves as an
+# explicit record of what is intentionally excluded from the published package
+# and acts as a safety net for other build tools.
+#
+# The published pytvt sdist ships only:
+#   - src/pytvt/**     (pure-Python package)
+#   - tests/**         (test suite)
+#   - pyproject.toml
+#   - README.md
+#   - CHANGELOG.md
+#   - LICENSE
+#
+# Explicitly excluded (not redistributed):
+#   - bridges/         Local Node.js bridge scripts
+#   - tvt-api/         Local SDK helper workspace
+#   - research/        Reverse-engineering research scripts
+#   - tools/           Maintenance utilities
+#   - files/           Sample and local scan outputs
+#   - config.json      Local device inventory example (site-specific)
+#   - .env.example     Local secrets template
+
+include pyproject.toml
+include README.md
+include CHANGELOG.md
+include LICENSE
+
+recursive-include src/pytvt *.py
+recursive-include tests *.py
+global-exclude *.so *.so.* *.dll *.dylib *.lib *.a *.h
+
+prune bridges
+prune files
+prune tvt-api
+prune research
+prune tools
+exclude config.json
+exclude .env.example
+exclude .editorconfig
+exclude .gitmodules