Home Assistant Core

The Z-Wave integration follows a layered architecture to connect Home Assistant to the physical Z-Wave hardware:

1. Z-Wave USB stick: Communicates via radio and handles device pairing.
2. Z-Wave JS: Translates the USB stick's serial protocol into device representations.
3. Z-Wave JS Server: Forwards the state of Z-Wave JS over a WebSocket connection.
4. Z-Wave JS Server Python: Consumes the WebSocket connection to make the state available to Python.
5. Z-Wave integration: Represents the devices within Home Assistant for user control.
6. Home Assistant: The top-level automation platform.

To prevent duplication in the entity registry, unique IDs should not include the integration's domain or the entity's platform name.

• W7425: home-assistant-entity-unique-id-redundant-domain: Do not include the integration's name (from manifest.json) as a delimited segment in the unique_id. For example, if the domain is myhub, avoid f"myhub-{device_id}". This applies to _attr_unique_id assignments and unique_id property returns.
• W7427: home-assistant-entity-unique-id-redundant-platform: Do not include the platform name (e.g., sensor, light) as a delimited segment in the unique_id. This check is scoped to platform modules like sensor.py or light/__init__.py.

Using if or match statements inside test functions can create non-deterministic execution paths where some branches may never run, hiding failures.

To fix W7409: home-assistant-test-non-deterministic:

• Use @pytest.mark.parametrize to cover different cases explicitly.
• Split the logic into separate test functions.

Exemptions for if statements:

• Guard clauses (return, raise, pytest.skip, pytest.xfail, pytest.fail).
• Conditions referencing a function parameter.
• Branches that contain no assert statements.

Note: match statements have no exemptions.

To maintain consistency and ensure correct time zone handling, use Home Assistant's dt utility instead of standard datetime methods.

• For aware local time: Use homeassistant.util.dt.now() instead of datetime.datetime.now(<tz>) when a non-UTC time zone is provided. This returns an aware datetime in the given time zone (defaulting to DEFAULT_TIME_ZONE).
• For naive local time: Use homeassistant.util.dt.naive_now() instead of datetime.datetime.now() (called without a time zone argument). This returns a naive datetime in system local time.
• For UTC: Use the home-assistant-enforce-utcnow checker (C7414) for datetime.now(UTC) cases.

# Instead of:
import datetime
now = datetime.datetime.now(timezone.utc)

# Use:
from homeassistant.util import dt
now = dt.now()

Autonomous agents are not allowed to contribute to OHF projects.

Any pull requests or issues believed to be created autonomously will be closed. Automated comments may be marked as spam. This includes any contribution that bypasses the provided issue or pull request templates.

To support multi-language support, HomeAssistantError and its subclasses must use the translation system instead of hardcoded English strings.

Requirements

• Use translation_domain and translation_key instead of a positional message argument (W7417).
• Do not provide both a positional message and a translation_key (W7419).
• Ensure translation_key and translation_domain are both provided (E7408).
• The referenced key must exist in the integration's strings.json under the exceptions section (E7406).
• Placeholders passed in code (via translation_placeholders) must match the {placeholder} slots in the strings.json message (E7418).

The Home Assistant Pylint plugin uses a specific numbering convention for its automated checks. Every check follows the standard Pylint format {C,W,E,R}74{00-99}, where 74 is the base ID for Home Assistant. The prefix indicates the type of issue:

• C: Convention
• W: Warning
• E: Error
• R: Refactor

The home_assistant_mdi_icons checker ensures that Material Design Icon (MDI) references are valid.

• E7409: home-assistant-mdi-icon-not-found: Triggered when an mdi: icon reference in Python code does not exist in the MDI set.
• E7410: home-assistant-mdi-icon-json-not-found: Triggered when an mdi: icon reference in icons.json does not exist in the MDI set.

When defining custom metrics for the Prometheus integration, adhere to the following rules to ensure compatibility and consistency:

1. Standard Compliance: Metric and label names must follow the official Prometheus naming guidelines.
2. Domain Prefixing: For domain-specific metrics, use the domain name (e.g., sensor, switch, climate) as a prefix in the metric name.
3. Handling Enum-like Values: Do not export state strings directly as metric values. Instead, use a "boolean" metric approach where the value is either 0 or 1, and use the specific state or mode as a metric label.

The home_assistant_logger checker ensures consistent formatting for logger messages across the codebase. It enforces two main rules:

C7401: home-assistant-logger-period

User-visible logger messages must not end with a period. Home Assistant follows a convention of avoiding trailing punctuation in log messages.

C7402: home-assistant-logger-capital

Logger messages must start with a capital letter. If a message does not warrant capitalization, it should be downgraded to the debug level.