Skip to content

Release v0.2.0 - Major Modernization and Feature Expansion #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
Luminger merged 13 commits into from
Oct 18, 2025
Merged

Release v0.2.0 - Major Modernization and Feature Expansion #1

Luminger merged 13 commits into from
Oct 18, 2025

Conversation

@Luminger
Copy link
Owner

@Luminger Luminger commented Oct 17, 2025 •
edited
Loading

Release v0.2.0 - Major Modernization and Feature Expansion

This PR introduces significant improvements to ezcoo-cli, transforming it from a basic CLI tool into a comprehensive, type-safe library with extensive testing and modern Python tooling.

Important: License Change

This release changes the project license from Apache-2.0 to GPL-3.0-or-later. This means all derivative works must also be licensed under GPL-3.0-or-later and remain open source. If you were using this project under Apache-2.0, you may continue to use versions ≤0.1.1 under that license, but v0.2.0 and later are GPL-licensed.

Overview

This release represents a complete modernization of the project with breaking changes to improve maintainability, type safety, and usability both as a CLI tool and as a Python library.

Added

High-Level KVM Interface

  • New KVM class in kvm.py providing type-safe, structured interface for library usage
  • Comprehensive data models using dataclasses for all KVM responses
  • Generic KVMResponse[T] wrapper ensuring type safety for all operations

Multi-Device Support

  • Support for controlling multiple KVM switches on the same serial bus (addresses 0-99)
  • New discover command to find all devices with their firmware versions

Enhanced CLI Commands

Complete rewrite replacing simple console.py:

  • status: Show system status with firmware version and address
  • help: Display device help information
  • input switch: Switch inputs with output selection
  • output routing: Query current input-to-output routing
  • output stream: Check output stream status
  • edid get/set: Manage EDID data for inputs
  • discover: Find all devices on the serial bus
  • Multiple output formats: --format raw|json|pretty

Comprehensive Testing

  • Full test suite with pytest achieving high code coverage
  • Unit tests for Device, KVM, and CLI commands
  • Integration tests for end-to-end workflows
  • Hardware replay tests using pytest-reserial (no hardware needed for CI)
  • Test scripts: test-record.sh, test-replay.sh, test-with-hardware.sh

Documentation & CI/CD

  • Extensive README with installation, usage examples, and library usage guide
  • Official EZCOO KVM switch manual (PDF) in docs/
  • GitHub Actions workflows for automated testing and building on PRs
  • RELEASING.md with complete manual release process (GitHub, PyPI, AUR)

Breaking Changes

Build System & Tooling

  • Poetry → uv: Faster dependency management with uv.lock and PEP 621 format
  • flake8 → ruff: Modern linting and formatting with comprehensive rules
  • Build backend: poetry-core → hatchling

CLI Changes

  • Complete rewrite: cli.py replaces console.py
  • New command structure: Organized subcommands and groups
  • Default output format: Changed from raw device response to human-readable pretty format
  • New options: --address for multi-device support, --format for output control
  • All commands now use high-level KVM interface instead of direct device commands

API Changes

  • Device class: Enhanced with DeviceError and DeviceConnectionError exceptions
  • Command validation: Prevents injection attacks
  • Response types: Returns structured KVMResponse[T] objects instead of raw strings
  • Type hints: Updated to modern Python 3.10+ syntax (Self, type[])

Dependencies

  • Removed: attrs, mypy, flake8, flake8-black, flake8-import-order
  • Added: pytest, pytest-cov, pytest-reserial, ruff
  • Updated: click ≥8.1.3, pyserial ≥3.5
  • Minimum Python: 3.10+

Fixed

  • Improved error handling with specific exception types
  • Better validation of command responses with structured parsing
  • More reliable serial port handling with proper connection error handling
  • Command injection prevention through input validation

Testing

All tests pass with hardware replay:

./scripts/test-replay.sh

CI workflow validates:

  • Ruff linting and formatting
  • Type safety
  • Test suite with coverage reporting
  • Package building

Checklist

  • All tests passing
  • Documentation updated
  • CHANGELOG.md updated
  • Version bumped to 0.2.0
  • CI/CD workflows added
  • Breaking changes documented

Migration Guide: Users upgrading from v0.1.x should:

  1. Update command syntax to new structure (see README.md)
  2. Note default output is now pretty-formatted (use --format raw for old behavior)
  3. Update any code using the library to use new KVM class instead of direct Device access
  4. Review CHANGELOG.md for complete list of breaking changes

@Luminger
chore: change license from Apache-2.0 to GPL-3.0-or-later
29f28f6 
Switch to GPL-3.0-or-later to ensure all derivative works remain
open source and contribute back to the community.
@Luminger
feat!: migrate from poetry to uv and flake8 to ruff
6c8433e 
- Remove poetry.lock and poetry.toml
- Add uv.lock for dependency management
- Replace flake8 with ruff for linting
- Update pyproject.toml with ruff configuration
- Update VSCode settings to use ruff instead of flake8

BREAKING CHANGE: Requires uv instead of poetry for dependency management
Luminger added 11 commits October 18, 2025 19:31
@Luminger
feat: implement high-level KVM interface with dataclasses and refacto…
20e8c66 
…r CLI

- Add dataclasses for structured data (SystemStatus, HelpInfo, OutputRouting, StreamStatus)
- Implement high-level KVM class with type-safe methods for device operations
- Refactor CLI to use KVM class instead of direct Device access
- Add helper method for raw output to eliminate code duplication
- Rename console.py to cli.py and update pyproject.toml entrypoint
- Update README.md with comprehensive library usage examples
- Document tested device models (EZ-SW41HA-KVMU3L and EZ-SW41HA-KVMU3P)
- Maintain backward compatibility with raw, pretty, and JSON output formats
@Luminger
feat: add multi-device addressing support and comprehensive test suite
aac7502 
BREAKING CHANGES:
- Require Python 3.10+ (was 3.8+)
- Change SystemStatus.system_address from string to int
- Remove KVMCommandNotSupportedError exception class
- Remove unsupported CLI commands (input edid, input signal, system address, system auto-mode)
- Remove unsupported KVM methods (get_input_signal_status, get_edid_info)

Features:
- Add device address support (0-99) for multi-device setups on same serial port
- Add device discovery command to scan for devices on address range
- Add set-address command to change device addresses
- Add unified --format flag (raw/json/pretty) for all query commands
- Add raw_response and command fields to all response models
- Add comprehensive pytest test suite with pytest-reserial for recording/replaying serial traffic
- Add test helper scripts (test-record.sh, test-replay.sh, test-with-hardware.sh)
- Add command validation to prevent injection attacks

Improvements:
- Refactor CLI to use match statements for format handling
- Add address prefix support (Axx) for commands to addressed devices
- Add DeviceResponse base class for all response models
- Improve error handling and validation
- Add extensive documentation for testing, address management, and command support status

Documentation:
- Document all working and unsupported commands based on firmware 2.03 testing
- Add comprehensive testing guide with three modes (replay/hardware/record)
- Add device chaining and multi-device setup documentation
- Add output format documentation with examples
- Document command support status and firmware limitations

Configuration:
- Add pytest configuration with coverage settings
- Add dev dependencies: pytest, pytest-cov, pytest-reserial
- Update .gitignore for devenv, direnv, and pre-commit files
@Luminger
refactor(cli): inline formatting functions into command handlers
dd3e85e 
Remove separate format_pretty_* helper functions and inline their logic
directly into the command handlers to simplify code structure.
@Luminger
refactor(core)!: improve response parsing and type safety
012ef2b 
BREAKING CHANGE: raw_response field changed from str to list[str] in all response models

- Move DiscoveredDevice model from cli.py to models.py for better organization
- Change raw_response type from str to list[str] across all DeviceResponse models
- Replace string manipulation with regex patterns for robust parsing in KVM class
- Add comprehensive docstrings to parsing methods explaining expected formats
- Fix raw_response output by joining list elements in CLI echo statements
- Update all tests to reflect new list[str] type for raw_response
- Improve code formatting for long parameter lists and click options
- Add detailed docstring to KVM.__init__ method
@Luminger
refactor: remove redundant RS232 serial config parsing
247a087 
Remove SerialConfig dataclass and parsing logic as RS232 settings
are hardcoded and provide no value to users.
@Luminger
refactor(kvm)!: improve type safety with generic responses and enums
4feeab5 
BREAKING CHANGE: KVM methods now return KVMResponse[T] wrapper instead of direct model types

- Add generic KVMResponse[T] wrapper for type-safe response handling
- Replace string stream status with StreamState enum (ON/OFF)
- Refactor _execute_command to accept parser function instead of boolean
- Remove unused DeviceResponse base class and SerialConfig
- Simplify data models to contain only parsed data
- Update CLI and tests for new response structure
@Luminger
chore(release): bump version to 0.2.0
ce62701
@Luminger
test: remove incomplete comment and optimize fixture usage
ff24989 
- Remove incomplete 'Performance tests' comment from test_integration.py
- Remove unnecessary reserial fixture from test_kvm_error_handling()
  since it only validates parameters without device interaction
- Remove empty test entry from test_integration.jsonl
@Luminger
docs: improve documentation for release readiness
9868044 
- Add AUR installation method
- Fix repository URL placeholder
- Reorganize CLI sections for better UX (KVM switching first)
- Simplify Output Formats and Multi-Device Setup sections
- Remove redundant Error Handling and Data Models sections
- Streamline testing documentation
- Reorganize Command Support Status (working commands first)
- Fix command categorization (GET vs SET)
- Remove PROTOCOL.md (documents different device)
- Remove docs/ezcoo1.docx (V1 protocol for different device)
@Luminger
ci: add GitHub Actions workflows and release documentation
d0d5c88 
- Add check/build composite actions for linting and packaging
- Add CI workflow for PR validation
- Document release process for GitHub, PyPI, and AUR
@Luminger
docs: add changelog for v0.2.0 release
39d24f0 
Document breaking changes, new features, and improvements
including KVM interface, multi-device support, CLI rewrite,
tooling migration (Poetry→uv, flake8→ruff), and test suite.
@Luminger Luminger merged commit f41fe75 into main Oct 18, 2025
2 checks passed
@Luminger Luminger deleted the modernize branch October 18, 2025 17:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Luminger