feat: add Field descriptions and metadata to models#42
Merged
Conversation
…eature Add comprehensive Field() definitions with: - Descriptive help text for each field - Unit of measurement metadata (°F, GPM, %, W, Wh, etc.) - Device class hints for Home Assistant integration (temperature, power, energy, signal_strength) This enables better documentation generation and improves integration with home automation systems.
eman
force-pushed
the
feat/add-field-descriptions
branch
from
cd6f4ea to
39b46f1
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive Field() metadata and descriptive help text to the DeviceStatus and DeviceFeature models, which will improve code documentation, support home automation system integrations like Home Assistant, and provide clearer API semantics for consumers.
Key changes:
- Added descriptive help text to all model fields for improved documentation clarity
- Added unit_of_measurement metadata (°F, GPM, %, W, Wh, days, hours, RPM, etc.) to enable proper value interpretation
- Added device_class hints (temperature, power, energy, signal_strength) specifically for Home Assistant integration
src/nwp500/models.py
Outdated
| }, | ||
| ) | ||
| freeze_protection_temp_min: HalfCelsiusToF = Field( | ||
| description="Minimum freeze protection threshold", |
There was a problem hiding this comment.
The description for freeze_protection_temp_min in DeviceFeature (line 776) is identical to the description in DeviceStatus (line 673). However, the DeviceFeature field represents a device capability limit, not an active setting. Consider distinguishing the descriptions - for example, 'Minimum configurable freeze protection temperature' in DeviceFeature vs. 'Minimum freeze protection threshold' in DeviceStatus.
Suggested change
| description="Minimum freeze protection threshold", | |
| description="Minimum configurable freeze protection temperature", |
…g descriptions - dhw_temperature_setting: user-configured target with range info - dhw_target_temperature_setting: documented as legacy API duplicate
…atus and DeviceFeature DeviceStatus: Active thresholds (current settings) DeviceFeature: Configurable limits (capability boundaries)
DeviceStatus: Whether ECO high-temp safety limit is triggered (status) DeviceFeature: ECO safety switch capability (feature availability)
Updated all DeviceStatus and DeviceFeature field descriptions to match the comprehensive documentation in docs/protocol/*.rst files. Added: - Detailed functional descriptions - Operating ranges and default values - Technical specifications (power ratings, limits) - Cross-references to related fields and error codes - Context about how components work together
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds comprehensive Field() definitions to DeviceStatus and DeviceFeature models.
Changes
Benefits