diff --git a/docs/source/_ext/edit_on_github.py b/docs/source/_ext/edit_on_github.py index 420acbbdde5..ecaea5450c9 100644 --- a/docs/source/_ext/edit_on_github.py +++ b/docs/source/_ext/edit_on_github.py @@ -1,5 +1,4 @@ -""" -Sphinx extension for ReadTheDocs-style "Edit on GitHub" links on the sidebar. +"""Sphinx extension for ReadTheDocs-style "Edit on GitHub" links on the sidebar. Loosely based on https://github.com/astropy/astropy/pull/347 """ diff --git a/homeassistant/auth/providers/legacy_api_password.py b/homeassistant/auth/providers/legacy_api_password.py index 438b2148eb7..72ba3b1ecb3 100644 --- a/homeassistant/auth/providers/legacy_api_password.py +++ b/homeassistant/auth/providers/legacy_api_password.py @@ -1,5 +1,4 @@ -""" -Support Legacy API password auth provider. +"""Support Legacy API password auth provider. It will be removed when auth system production ready """ @@ -71,8 +70,7 @@ class LegacyApiPasswordAuthProvider(AuthProvider): async def async_user_meta_for_credentials( self, credentials: Credentials ) -> UserMeta: - """ - Return info for the user. + """Return info for the user. Will be used to populate info when creating a new user. """ diff --git a/homeassistant/backports/enum.py b/homeassistant/backports/enum.py index 939d6e7669b..bba54c51634 100644 --- a/homeassistant/backports/enum.py +++ b/homeassistant/backports/enum.py @@ -26,8 +26,7 @@ class StrEnum(str, Enum): def _generate_next_value_( name: str, start: int, count: int, last_values: list[Any] ) -> Any: - """ - Make `auto()` explicitly unsupported. + """Make `auto()` explicitly unsupported. We may revisit this when it's very clear that Python 3.11's `StrEnum.auto()` behavior will no longer change. diff --git a/homeassistant/components/__init__.py b/homeassistant/components/__init__.py index 2a062109eaf..d0e631fb04c 100644 --- a/homeassistant/components/__init__.py +++ b/homeassistant/components/__init__.py @@ -1,5 +1,4 @@ -""" -This package contains components that can be plugged into Home Assistant. +"""This package contains components that can be plugged into Home Assistant. Component design guidelines: - Each component defines a constant DOMAIN that is equal to its filename. diff --git a/homeassistant/components/airly/__init__.py b/homeassistant/components/airly/__init__.py index 56ec8eae95b..85b8b22043a 100644 --- a/homeassistant/components/airly/__init__.py +++ b/homeassistant/components/airly/__init__.py @@ -38,8 +38,7 @@ _LOGGER = logging.getLogger(__name__) def set_update_interval(instances_count: int, requests_remaining: int) -> timedelta: - """ - Return data update interval. + """Return data update interval. The number of requests is reset at midnight UTC so we calculate the update interval based on number of minutes until midnight, the number of Airly instances diff --git a/homeassistant/components/airnow/config_flow.py b/homeassistant/components/airnow/config_flow.py index e1828117d5f..39dbef48647 100644 --- a/homeassistant/components/airnow/config_flow.py +++ b/homeassistant/components/airnow/config_flow.py @@ -16,8 +16,7 @@ _LOGGER = logging.getLogger(__name__) async def validate_input(hass: core.HomeAssistant, data): - """ - Validate the user input allows us to connect. + """Validate the user input allows us to connect. Data has the keys from DATA_SCHEMA with values provided by the user. """ diff --git a/homeassistant/components/alexa/intent.py b/homeassistant/components/alexa/intent.py index c18ffd316b1..4c872234746 100644 --- a/homeassistant/components/alexa/intent.py +++ b/homeassistant/components/alexa/intent.py @@ -41,8 +41,7 @@ def async_setup(hass): async def async_setup_intents(hass): - """ - Do intents setup. + """Do intents setup. Right now this module does not expose any, but the intent component breaks without it. diff --git a/homeassistant/components/apple_tv/browse_media.py b/homeassistant/components/apple_tv/browse_media.py index 9944c49a823..d706c9aa7e9 100644 --- a/homeassistant/components/apple_tv/browse_media.py +++ b/homeassistant/components/apple_tv/browse_media.py @@ -24,8 +24,7 @@ def build_app_list(app_list: dict[str, str]) -> BrowseMedia: def item_payload(item: dict[str, Any]) -> BrowseMedia: - """ - Create response payload for a single media item. + """Create response payload for a single media item. Used by async_browse_media. """ diff --git a/homeassistant/components/automation/__init__.py b/homeassistant/components/automation/__init__.py index f005c1dfce2..3cfae999b92 100644 --- a/homeassistant/components/automation/__init__.py +++ b/homeassistant/components/automation/__init__.py @@ -139,8 +139,7 @@ AutomationTriggerInfo = TriggerInfo @bind_hass def is_on(hass: HomeAssistant, entity_id: str) -> bool: - """ - Return true if specified automation entity_id is on. + """Return true if specified automation entity_id is on. Async friendly. """ diff --git a/homeassistant/components/bayesian/binary_sensor.py b/homeassistant/components/bayesian/binary_sensor.py index 5266e310428..77571e1a80f 100644 --- a/homeassistant/components/bayesian/binary_sensor.py +++ b/homeassistant/components/bayesian/binary_sensor.py @@ -217,8 +217,7 @@ class BayesianBinarySensor(BinarySensorEntity): } async def async_added_to_hass(self) -> None: - """ - Call when entity about to be added. + """Call when entity about to be added. All relevant update logic for instance attributes occurs within this closure. Other methods in this class are designed to avoid directly modifying instance @@ -233,8 +232,7 @@ class BayesianBinarySensor(BinarySensorEntity): @callback def async_threshold_sensor_state_listener(event: Event) -> None: - """ - Handle sensor state changes. + """Handle sensor state changes. When a state changes, we must update our list of current observations, then calculate the new probability. @@ -384,8 +382,7 @@ class BayesianBinarySensor(BinarySensorEntity): return prior def _build_observations_by_entity(self) -> dict[str, list[Observation]]: - """ - Build and return data structure of the form below. + """Build and return data structure of the form below. { "sensor.sensor1": [Observation, Observation], @@ -414,8 +411,7 @@ class BayesianBinarySensor(BinarySensorEntity): return observations_by_entity def _build_observations_by_template(self) -> dict[Template, list[Observation]]: - """ - Build and return data structure of the form below. + """Build and return data structure of the form below. { "template": [Observation, Observation], diff --git a/homeassistant/components/bluetooth/active_update_coordinator.py b/homeassistant/components/bluetooth/active_update_coordinator.py index 09567aada05..78e713ce5e6 100644 --- a/homeassistant/components/bluetooth/active_update_coordinator.py +++ b/homeassistant/components/bluetooth/active_update_coordinator.py @@ -26,8 +26,7 @@ _T = TypeVar("_T") class ActiveBluetoothDataUpdateCoordinator( PassiveBluetoothDataUpdateCoordinator, Generic[_T] ): - """ - A coordinator that receives passive data from advertisements but can also poll. + """A coordinator that receives passive data from advertisements but can also poll. Unlike the passive processor coordinator, this coordinator does call a parser method to parse the data from the advertisement. diff --git a/homeassistant/components/bluetooth_tracker/device_tracker.py b/homeassistant/components/bluetooth_tracker/device_tracker.py index c277985782c..659243df733 100644 --- a/homeassistant/components/bluetooth_tracker/device_tracker.py +++ b/homeassistant/components/bluetooth_tracker/device_tracker.py @@ -96,8 +96,7 @@ async def see_device( async def get_tracking_devices(hass: HomeAssistant) -> tuple[set[str], set[str]]: - """ - Load all known devices. + """Load all known devices. We just need the devices so set consider_home and home range to 0 """ diff --git a/homeassistant/components/brunt/cover.py b/homeassistant/components/brunt/cover.py index 36ee89e0395..3fb328ab7fb 100644 --- a/homeassistant/components/brunt/cover.py +++ b/homeassistant/components/brunt/cover.py @@ -55,8 +55,7 @@ async def async_setup_entry( class BruntDevice( CoordinatorEntity[DataUpdateCoordinator[dict[str | None, Thing]]], CoverEntity ): - """ - Representation of a Brunt cover device. + """Representation of a Brunt cover device. Contains the common logic for all Brunt devices. """ @@ -105,8 +104,7 @@ class BruntDevice( @property def current_cover_position(self) -> int | None: - """ - Return current position of cover. + """Return current position of cover. None is unknown, 0 is closed, 100 is fully open. """ @@ -114,8 +112,7 @@ class BruntDevice( @property def request_cover_position(self) -> int | None: - """ - Return request position of cover. + """Return request position of cover. The request position is the position of the last request to Brunt, at times there is a diff of 1 to current @@ -125,8 +122,7 @@ class BruntDevice( @property def move_state(self) -> int | None: - """ - Return current moving state of cover. + """Return current moving state of cover. None is unknown, 0 when stopped, 1 when opening, 2 when closing """ diff --git a/homeassistant/components/buienradar/camera.py b/homeassistant/components/buienradar/camera.py index 265d40ab724..86e650aefed 100644 --- a/homeassistant/components/buienradar/camera.py +++ b/homeassistant/components/buienradar/camera.py @@ -51,8 +51,7 @@ async def async_setup_entry( class BuienradarCam(Camera): - """ - A camera component producing animated buienradar radar-imagery GIFs. + """A camera component producing animated buienradar radar-imagery GIFs. Rain radar imagery camera based on image URL taken from [0]. @@ -62,8 +61,7 @@ class BuienradarCam(Camera): def __init__( self, latitude: float, longitude: float, delta: float, country: str ) -> None: - """ - Initialize the component. + """Initialize the component. This constructor must be run in the event loop. """ @@ -145,8 +143,7 @@ class BuienradarCam(Camera): async def async_camera_image( self, width: int | None = None, height: int | None = None ) -> bytes | None: - """ - Return a still image response from the camera. + """Return a still image response from the camera. Uses asyncio conditions to make sure only one task enters the critical section at the same time. Otherwise, two http requests would start diff --git a/homeassistant/components/camera/img_util.py b/homeassistant/components/camera/img_util.py index cfa8399c4d5..dcb321d5ebb 100644 --- a/homeassistant/components/camera/img_util.py +++ b/homeassistant/components/camera/img_util.py @@ -70,8 +70,7 @@ def scale_jpeg_camera_image(cam_image: Image, width: int, height: int) -> bytes: class TurboJPEGSingleton: - """ - Load TurboJPEG only once. + """Load TurboJPEG only once. Ensures we do not log load failures each snapshot since camera image fetches happen every few diff --git a/homeassistant/components/cast/media_player.py b/homeassistant/components/cast/media_player.py index 5791fb6b8b9..29aab64b714 100644 --- a/homeassistant/components/cast/media_player.py +++ b/homeassistant/components/cast/media_player.py @@ -476,8 +476,7 @@ class CastMediaPlayerEntity(CastDevice, MediaPlayerEntity): # ========== Service Calls ========== def _media_controller(self): - """ - Return media controller. + """Return media controller. First try from our own cast, then groups which our cast is a member in. """ @@ -753,8 +752,7 @@ class CastMediaPlayerEntity(CastDevice, MediaPlayerEntity): ) def _media_status(self): - """ - Return media status. + """Return media status. First try from our own cast, then groups which our cast is a member in. """ diff --git a/homeassistant/components/cisco_ios/device_tracker.py b/homeassistant/components/cisco_ios/device_tracker.py index b8a4d4cd53d..508b2b2d8b3 100644 --- a/homeassistant/components/cisco_ios/device_tracker.py +++ b/homeassistant/components/cisco_ios/device_tracker.py @@ -64,8 +64,7 @@ class CiscoDeviceScanner(DeviceScanner): return self.last_results def _update_info(self): - """ - Ensure the information from the Cisco router is up to date. + """Ensure the information from the Cisco router is up to date. Returns boolean if scanning successful. """ @@ -139,8 +138,7 @@ class CiscoDeviceScanner(DeviceScanner): def _parse_cisco_mac_address(cisco_hardware_addr): - """ - Parse a Cisco formatted HW address to normal MAC. + """Parse a Cisco formatted HW address to normal MAC. e.g. convert 001d.ec02.07ab diff --git a/homeassistant/components/cisco_mobility_express/device_tracker.py b/homeassistant/components/cisco_mobility_express/device_tracker.py index a4dff37705b..9ce98ec4fe8 100644 --- a/homeassistant/components/cisco_mobility_express/device_tracker.py +++ b/homeassistant/components/cisco_mobility_express/device_tracker.py @@ -78,8 +78,7 @@ class CiscoMEDeviceScanner(DeviceScanner): return name def get_extra_attributes(self, device): - """ - Get extra attributes of a device. + """Get extra attributes of a device. Some known extra attributes that may be returned in the device tuple include SSID, PT (eg 802.11ac), devtype (eg iPhone 7) among others. diff --git a/homeassistant/components/cloud/repairs.py b/homeassistant/components/cloud/repairs.py index dbc9b71a990..0864d8b48ad 100644 --- a/homeassistant/components/cloud/repairs.py +++ b/homeassistant/components/cloud/repairs.py @@ -24,8 +24,7 @@ def async_manage_legacy_subscription_issue( hass: HomeAssistant, subscription_info: dict[str, Any], ) -> None: - """ - Manage the legacy subscription issue. + """Manage the legacy subscription issue. If the provider is "legacy" create an issue, in all other cases remove the issue. diff --git a/homeassistant/components/configurator/__init__.py b/homeassistant/components/configurator/__init__.py index 90e8daddb35..ea785b5cdfb 100644 --- a/homeassistant/components/configurator/__init__.py +++ b/homeassistant/components/configurator/__init__.py @@ -1,5 +1,4 @@ -""" -Support to allow pieces of code to request configuration from the user. +"""Support to allow pieces of code to request configuration from the user. Initiate a request by calling the `request_config` method with a callback. This will return a request id that has to be used for future calls. diff --git a/homeassistant/components/crownstone/devices.py b/homeassistant/components/crownstone/devices.py index ead2c54a58e..427f88a1fb9 100644 --- a/homeassistant/components/crownstone/devices.py +++ b/homeassistant/components/crownstone/devices.py @@ -19,8 +19,7 @@ class CrownstoneBaseEntity(Entity): @property def cloud_id(self) -> str: - """ - Return the unique identifier for this device. + """Return the unique identifier for this device. Used as device ID and to generate unique entity ID's. """ diff --git a/homeassistant/components/crownstone/entry_manager.py b/homeassistant/components/crownstone/entry_manager.py index c527e3ba2b9..575a76b45b6 100644 --- a/homeassistant/components/crownstone/entry_manager.py +++ b/homeassistant/components/crownstone/entry_manager.py @@ -52,8 +52,7 @@ class CrownstoneEntryManager: self.usb_sphere_id: str | None = None async def async_setup(self) -> bool: - """ - Set up a Crownstone config entry. + """Set up a Crownstone config entry. Returns True if the setup was successful. """ diff --git a/homeassistant/components/crownstone/helpers.py b/homeassistant/components/crownstone/helpers.py index 58b4dcdba47..94df9b9c5c3 100644 --- a/homeassistant/components/crownstone/helpers.py +++ b/homeassistant/components/crownstone/helpers.py @@ -13,8 +13,7 @@ from .const import DONT_USE_USB, MANUAL_PATH, REFRESH_LIST def list_ports_as_str( serial_ports: list[ListPortInfo], no_usb_option: bool = True ) -> list[str]: - """ - Represent currently available serial ports as string. + """Represent currently available serial ports as string. Adds option to not use usb on top of the list, option to use manual path or refresh list at the end. diff --git a/homeassistant/components/crownstone/light.py b/homeassistant/components/crownstone/light.py index a046a39cd62..c9cbeff90d5 100644 --- a/homeassistant/components/crownstone/light.py +++ b/homeassistant/components/crownstone/light.py @@ -65,8 +65,7 @@ def hass_to_crownstone_state(value: int) -> int: class CrownstoneEntity(CrownstoneBaseEntity, LightEntity): - """ - Representation of a crownstone. + """Representation of a crownstone. Light platform is used to support dimming. """ diff --git a/homeassistant/components/crownstone/listeners.py b/homeassistant/components/crownstone/listeners.py index 63891545cab..6c611e27083 100644 --- a/homeassistant/components/crownstone/listeners.py +++ b/homeassistant/components/crownstone/listeners.py @@ -1,5 +1,4 @@ -""" -Listeners for updating data in the Crownstone integration. +"""Listeners for updating data in the Crownstone integration. For data updates, Cloud Push is used in form of an SSE server that sends out events. For fast device switching Local Push is used in form of a USB dongle that hooks into a BLE mesh. diff --git a/homeassistant/components/darksky/sensor.py b/homeassistant/components/darksky/sensor.py index 24bdd0747c6..e912eb40115 100644 --- a/homeassistant/components/darksky/sensor.py +++ b/homeassistant/components/darksky/sensor.py @@ -747,8 +747,7 @@ class DarkSkySensor(SensorEntity): self._attr_native_value = self.get_state(currently) def get_state(self, data): - """ - Return a new state based on the type. + """Return a new state based on the type. If the sensor type is unknown, the current state is returned. """ @@ -827,8 +826,7 @@ class DarkSkyAlertSensor(SensorEntity): self._attr_native_value = self.get_state(alerts) def get_state(self, data): - """ - Return a new state based on the type. + """Return a new state based on the type. If the sensor type is unknown, the current state is returned. """ @@ -851,8 +849,7 @@ class DarkSkyAlertSensor(SensorEntity): def convert_to_camel(data): - """ - Convert snake case (foo_bar_bat) to camel case (fooBarBat). + """Convert snake case (foo_bar_bat) to camel case (fooBarBat). This is not pythonic, but needed for certain situations. """ diff --git a/homeassistant/components/denonavr/media_player.py b/homeassistant/components/denonavr/media_player.py index c1c5a90dbac..b5d831ad9cc 100644 --- a/homeassistant/components/denonavr/media_player.py +++ b/homeassistant/components/denonavr/media_player.py @@ -139,8 +139,7 @@ async def async_setup_entry( def async_log_errors( func: Callable[Concatenate[_DenonDeviceT, _P], Awaitable[_R]], ) -> Callable[Concatenate[_DenonDeviceT, _P], Coroutine[Any, Any, _R | None]]: - """ - Log errors occurred when calling a Denon AVR receiver. + """Log errors occurred when calling a Denon AVR receiver. Decorates methods of DenonDevice class. Declaration of staticmethod for this method is at the end of this class. diff --git a/homeassistant/components/doorbird/__init__.py b/homeassistant/components/doorbird/__init__.py index f5b2d2aad32..7a675348561 100644 --- a/homeassistant/components/doorbird/__init__.py +++ b/homeassistant/components/doorbird/__init__.py @@ -301,8 +301,7 @@ class ConfiguredDoorBird: return self.get_webhook_id(url, favs) is not None def get_webhook_id(self, url, favs=None) -> str | None: - """ - Return the device favorite ID for the given URL. + """Return the device favorite ID for the given URL. The favorite must exist or there will be problems. """ diff --git a/homeassistant/components/dublin_bus_transport/sensor.py b/homeassistant/components/dublin_bus_transport/sensor.py index 657e3165976..60d058220ab 100644 --- a/homeassistant/components/dublin_bus_transport/sensor.py +++ b/homeassistant/components/dublin_bus_transport/sensor.py @@ -1,5 +1,4 @@ -""" -Support for Dublin RTPI information from data.dublinked.ie. +"""Support for Dublin RTPI information from data.dublinked.ie. For more info on the API see : https://data.gov.ie/dataset/real-time-passenger-information-rtpi-for-dublin-bus-bus-eireann-luas-and-irish-rail/resource/4b9f2c4f-6bf5-4958-a43a-f12dab04cf61 diff --git a/homeassistant/components/dwd_weather_warnings/sensor.py b/homeassistant/components/dwd_weather_warnings/sensor.py index d6b3f6c2a0d..30a258875d5 100644 --- a/homeassistant/components/dwd_weather_warnings/sensor.py +++ b/homeassistant/components/dwd_weather_warnings/sensor.py @@ -1,5 +1,4 @@ -""" -Support for getting statistical data from a DWD Weather Warnings. +"""Support for getting statistical data from a DWD Weather Warnings. Data is fetched from DWD: https://rcccm.dwd.de/DE/wetter/warnungen_aktuell/objekt_einbindung/objekteinbindung.html diff --git a/homeassistant/components/ebox/sensor.py b/homeassistant/components/ebox/sensor.py index ea52b1e422e..91510b3fbc0 100644 --- a/homeassistant/components/ebox/sensor.py +++ b/homeassistant/components/ebox/sensor.py @@ -1,5 +1,4 @@ -""" -Support for EBox. +"""Support for EBox. Get data from 'My Usage Page' page: https://client.ebox.ca/myusage """ diff --git a/homeassistant/components/ecoal_boiler/switch.py b/homeassistant/components/ecoal_boiler/switch.py index 6922a35f5de..b2b46beb26b 100644 --- a/homeassistant/components/ecoal_boiler/switch.py +++ b/homeassistant/components/ecoal_boiler/switch.py @@ -32,8 +32,7 @@ class EcoalSwitch(SwitchEntity): """Representation of Ecoal switch.""" def __init__(self, ecoal_contr, name, state_attr): - """ - Initialize switch. + """Initialize switch. Sets HA switch to state as read from controller. """ diff --git a/homeassistant/components/ecobee/__init__.py b/homeassistant/components/ecobee/__init__.py index 31a1e753fc6..65be0475313 100644 --- a/homeassistant/components/ecobee/__init__.py +++ b/homeassistant/components/ecobee/__init__.py @@ -29,8 +29,7 @@ CONFIG_SCHEMA = vol.Schema( async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool: - """ - Ecobee uses config flow for configuration. + """Ecobee uses config flow for configuration. But, an "ecobee:" entry in configuration.yaml will trigger an import flow if a config entry doesn't already exist. If ecobee.conf exists, the import @@ -87,8 +86,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool: class EcobeeData: - """ - Handle getting the latest data from ecobee.com so platforms can use it. + """Handle getting the latest data from ecobee.com so platforms can use it. Also handle refreshing tokens and updating config entry with refreshed tokens. """ diff --git a/homeassistant/components/ecobee/config_flow.py b/homeassistant/components/ecobee/config_flow.py index 304730e6dbf..ffef5798d1b 100644 --- a/homeassistant/components/ecobee/config_flow.py +++ b/homeassistant/components/ecobee/config_flow.py @@ -76,8 +76,7 @@ class EcobeeFlowHandler(config_entries.ConfigFlow, domain=DOMAIN): ) async def async_step_import(self, import_data): - """ - Import ecobee config from configuration.yaml. + """Import ecobee config from configuration.yaml. Triggered by async_setup only if a config entry doesn't already exist. If ecobee.conf exists, we will attempt to validate the credentials diff --git a/homeassistant/components/eddystone_temperature/sensor.py b/homeassistant/components/eddystone_temperature/sensor.py index d3f70730a48..5a86d45e9f0 100644 --- a/homeassistant/components/eddystone_temperature/sensor.py +++ b/homeassistant/components/eddystone_temperature/sensor.py @@ -1,5 +1,4 @@ -""" -Read temperature information from Eddystone beacons. +"""Read temperature information from Eddystone beacons. Your beacons must be configured to transmit UID (for identification) and TLM (for temperature) frames. diff --git a/homeassistant/components/emby/media_player.py b/homeassistant/components/emby/media_player.py index bc85b983d9d..73593ef09a1 100644 --- a/homeassistant/components/emby/media_player.py +++ b/homeassistant/components/emby/media_player.py @@ -236,8 +236,7 @@ class EmbyDevice(MediaPlayerEntity): @property def media_position_updated_at(self): - """ - When was the position of the current playing media valid. + """When was the position of the current playing media valid. Returns value from homeassistant.util.dt.utcnow(). """ diff --git a/homeassistant/components/fido/sensor.py b/homeassistant/components/fido/sensor.py index e0e6e287508..0d2d6d3a0de 100644 --- a/homeassistant/components/fido/sensor.py +++ b/homeassistant/components/fido/sensor.py @@ -1,5 +1,4 @@ -""" -Support for Fido. +"""Support for Fido. Get data from 'Usage Summary' page: https://www.fido.ca/pages/#/my-account/wireless diff --git a/homeassistant/components/flux/switch.py b/homeassistant/components/flux/switch.py index 6da3f88eedf..d8a58192593 100644 --- a/homeassistant/components/flux/switch.py +++ b/homeassistant/components/flux/switch.py @@ -1,5 +1,4 @@ -""" -Flux for Home-Assistant. +"""Flux for Home-Assistant. The idea was taken from https://github.com/KpaBap/hue-flux/ """ diff --git a/homeassistant/components/fortios/device_tracker.py b/homeassistant/components/fortios/device_tracker.py index d0c08a06441..65f63829c05 100644 --- a/homeassistant/components/fortios/device_tracker.py +++ b/homeassistant/components/fortios/device_tracker.py @@ -1,5 +1,4 @@ -""" -Support to use FortiOS device like FortiGate as device tracker. +"""Support to use FortiOS device like FortiGate as device tracker. This component is part of the device_tracker platform. """ diff --git a/homeassistant/components/fronius/coordinator.py b/homeassistant/components/fronius/coordinator.py index 08779b9b673..16e55f12726 100644 --- a/homeassistant/components/fronius/coordinator.py +++ b/homeassistant/components/fronius/coordinator.py @@ -86,8 +86,7 @@ class FroniusCoordinatorBase( async_add_entities: AddEntitiesCallback, entity_constructor: type[_FroniusEntityT], ) -> None: - """ - Add entities for received keys and registers listener for future seen keys. + """Add entities for received keys and registers listener for future seen keys. Called from a platforms `async_setup_entry`. """ diff --git a/homeassistant/components/frontier_silicon/browse_media.py b/homeassistant/components/frontier_silicon/browse_media.py index 7815b029735..cc4452b2d6b 100644 --- a/homeassistant/components/frontier_silicon/browse_media.py +++ b/homeassistant/components/frontier_silicon/browse_media.py @@ -27,8 +27,7 @@ _LOGGER = logging.getLogger(__name__) def _item_preset_payload(preset: Preset, player_mode: str) -> BrowseMedia: - """ - Create response payload for a single media item. + """Create response payload for a single media item. Used by async_browse_media. """ @@ -47,8 +46,7 @@ def _item_preset_payload(preset: Preset, player_mode: str) -> BrowseMedia: def _item_payload( key, item: dict[str, str], player_mode: str, parent_keys: list[str] ) -> BrowseMedia: - """ - Create response payload for a single media item. + """Create response payload for a single media item. Used by async_browse_media. """ @@ -76,8 +74,7 @@ def _item_payload( async def browse_top_level(current_mode, afsapi: AFSAPI): - """ - Create response payload to describe contents of a specific library. + """Create response payload to describe contents of a specific library. Used by async_browse_media. """ diff --git a/homeassistant/components/fully_kiosk/services.py b/homeassistant/components/fully_kiosk/services.py index de269af891a..3fca9228735 100644 --- a/homeassistant/components/fully_kiosk/services.py +++ b/homeassistant/components/fully_kiosk/services.py @@ -31,8 +31,7 @@ async def async_setup_services(hass: HomeAssistant) -> None: *args: list[str], **kwargs: dict[str, Any], ) -> None: - """ - Execute a Fully service call. + """Execute a Fully service call. :param call: {ServiceCall} HA service call. :param fully_method: {Callable} A method of the FullyKiosk class. diff --git a/homeassistant/components/geo_rss_events/sensor.py b/homeassistant/components/geo_rss_events/sensor.py index 2aade681e29..3e6a0923886 100644 --- a/homeassistant/components/geo_rss_events/sensor.py +++ b/homeassistant/components/geo_rss_events/sensor.py @@ -1,5 +1,4 @@ -""" -Generic GeoRSS events service. +"""Generic GeoRSS events service. Retrieves current events (typically incidents or alerts) in GeoRSS format, and shows information on events filtered by distance to the HA instance's location diff --git a/homeassistant/components/google_assistant_sdk/helpers.py b/homeassistant/components/google_assistant_sdk/helpers.py index 1c85e5b6a4b..1d89e208ced 100644 --- a/homeassistant/components/google_assistant_sdk/helpers.py +++ b/homeassistant/components/google_assistant_sdk/helpers.py @@ -110,8 +110,7 @@ class InMemoryStorage: self.mem: dict[str, bytes] = {} def store_and_get_identifier(self, data: bytes) -> str: - """ - Temporarily store data and return identifier to be able to retrieve it. + """Temporarily store data and return identifier to be able to retrieve it. Data expires after 5 minutes. """ diff --git a/homeassistant/components/google_assistant_sdk/notify.py b/homeassistant/components/google_assistant_sdk/notify.py index 80d0e70f44c..0c0338dd973 100644 --- a/homeassistant/components/google_assistant_sdk/notify.py +++ b/homeassistant/components/google_assistant_sdk/notify.py @@ -25,8 +25,7 @@ LANG_TO_BROADCAST_COMMAND = { def broadcast_commands(language_code: str): - """ - Get the commands for broadcasting a message for the given language code. + """Get the commands for broadcasting a message for the given language code. Return type is a tuple where [0] is for broadcasting to your entire home, while [1] is for broadcasting to a specific target. diff --git a/homeassistant/components/growatt_server/sensor_types/tlx.py b/homeassistant/components/growatt_server/sensor_types/tlx.py index 4703c39a8f9..9c9bbd488d5 100644 --- a/homeassistant/components/growatt_server/sensor_types/tlx.py +++ b/homeassistant/components/growatt_server/sensor_types/tlx.py @@ -1,5 +1,4 @@ -""" -Growatt Sensor definitions for the TLX type. +"""Growatt Sensor definitions for the TLX type. TLX Type is also shown on the UI as: "MIN/MIC/MOD/NEO" """ diff --git a/homeassistant/components/hdmi_cec/__init__.py b/homeassistant/components/hdmi_cec/__init__.py index 18885b81be2..5ad8393726f 100644 --- a/homeassistant/components/hdmi_cec/__init__.py +++ b/homeassistant/components/hdmi_cec/__init__.py @@ -308,8 +308,7 @@ def setup(hass: HomeAssistant, base_config: ConfigType) -> bool: # noqa: C901 _LOGGER.info("Selected %s (%s)", call.data[ATTR_DEVICE], addr) def _update(call: ServiceCall) -> None: - """ - Update if device update is needed. + """Update if device update is needed. Called by service, requests CEC network to update data. """ diff --git a/homeassistant/components/heos/__init__.py b/homeassistant/components/heos/__init__.py index e82873c3c23..26a5e2d5434 100644 --- a/homeassistant/components/heos/__init__.py +++ b/homeassistant/components/heos/__init__.py @@ -458,8 +458,7 @@ class SourceManager: ) def connect_update(self, hass, controller): - """ - Connect listener for when sources change and signal player update. + """Connect listener for when sources change and signal player update. EVENT_SOURCES_CHANGED is often raised multiple times in response to a physical event therefore throttle it. Retrieving sources immediately diff --git a/homeassistant/components/homekit/aidmanager.py b/homeassistant/components/homekit/aidmanager.py index 27bd6234d46..4addbeb1e23 100644 --- a/homeassistant/components/homekit/aidmanager.py +++ b/homeassistant/components/homekit/aidmanager.py @@ -1,5 +1,4 @@ -""" -Manage allocation of accessory ID's. +"""Manage allocation of accessory ID's. HomeKit needs to allocate unique numbers to each accessory. These need to be stable between reboots and upgrades. @@ -60,8 +59,7 @@ def _generate_aids(unique_id: str | None, entity_id: str) -> Generator[int, None class AccessoryAidStorage: - """ - Holds a map of entity ID to HomeKit ID. + """Holds a map of entity ID to HomeKit ID. Will generate new ID's, ensure they are unique and store them to make sure they persist over reboots. diff --git a/homeassistant/components/homekit/iidmanager.py b/homeassistant/components/homekit/iidmanager.py index 8bac268800b..2bd50821138 100644 --- a/homeassistant/components/homekit/iidmanager.py +++ b/homeassistant/components/homekit/iidmanager.py @@ -1,5 +1,4 @@ -""" -Manage allocation of instance ID's. +"""Manage allocation of instance ID's. HomeKit needs to allocate unique numbers to each accessory. These need to be stable between reboots and upgrades. @@ -61,8 +60,7 @@ class IIDStorage(Store): class AccessoryIIDStorage: - """ - Provide stable allocation of IIDs for the lifetime of an accessory. + """Provide stable allocation of IIDs for the lifetime of an accessory. Will generate new ID's, ensure they are unique and store them to make sure they persist over reboots. diff --git a/homeassistant/components/homekit_controller/button.py b/homeassistant/components/homekit_controller/button.py index 11e935df455..34cebb71d6f 100644 --- a/homeassistant/components/homekit_controller/button.py +++ b/homeassistant/components/homekit_controller/button.py @@ -1,5 +1,4 @@ -""" -Support for Homekit buttons. +"""Support for Homekit buttons. These are mostly used where a HomeKit accessory exposes additional non-standard characteristics that don't map to a Home Assistant feature. diff --git a/homeassistant/components/homekit_controller/config_flow.py b/homeassistant/components/homekit_controller/config_flow.py index 71884f25ef4..4f980b9d1c6 100644 --- a/homeassistant/components/homekit_controller/config_flow.py +++ b/homeassistant/components/homekit_controller/config_flow.py @@ -91,8 +91,7 @@ def find_existing_host( def ensure_pin_format(pin: str, allow_insecure_setup_codes: Any = None) -> str: - """ - Ensure a pin code is correctly formatted. + """Ensure a pin code is correctly formatted. Ensures a pin code is in the format 111-11-111. Handles codes with and without dashes. diff --git a/homeassistant/components/homekit_controller/connection.py b/homeassistant/components/homekit_controller/connection.py index f0de7307d7c..37188487746 100644 --- a/homeassistant/components/homekit_controller/connection.py +++ b/homeassistant/components/homekit_controller/connection.py @@ -465,8 +465,7 @@ class HKDevice: @callback def async_create_devices(self) -> None: - """ - Build device registry entries for all accessories paired with the bridge. + """Build device registry entries for all accessories paired with the bridge. This is done as well as by the entities for 2 reasons. First, the bridge might not have any entities attached to it. Secondly there are stateless @@ -536,8 +535,7 @@ class HKDevice: self.unreliable_serial_numbers = unreliable_serial_numbers async def async_process_entity_map(self) -> None: - """ - Process the entity map and load any platforms or entities that need adding. + """Process the entity map and load any platforms or entities that need adding. This is idempotent and will be called at startup and when we detect metadata changes via the c# counter on the zeroconf record. @@ -759,8 +757,7 @@ class HKDevice: @property def unique_id(self) -> str: - """ - Return a unique id for this accessory or bridge. + """Return a unique id for this accessory or bridge. This id is random and will change if a device undergoes a hard reset. """ diff --git a/homeassistant/components/homekit_controller/entity.py b/homeassistant/components/homekit_controller/entity.py index eecf8b9c080..6171e9406a0 100644 --- a/homeassistant/components/homekit_controller/entity.py +++ b/homeassistant/components/homekit_controller/entity.py @@ -72,8 +72,7 @@ class HomeKitEntity(Entity): self._accessory.remove_watchable_characteristics(self._aid) async def async_put_characteristics(self, characteristics: dict[str, Any]) -> None: - """ - Write characteristics to the device. + """Write characteristics to the device. A characteristic type is unique within a service, but in order to write to a named characteristic on a bridge we need to turn its type into @@ -195,8 +194,7 @@ class AccessoryEntity(HomeKitEntity): class CharacteristicEntity(HomeKitEntity): - """ - A HomeKit entity that is related to an single characteristic rather than a whole service. + """A HomeKit entity that is related to an single characteristic rather than a whole service. This is typically used to expose additional sensor, binary_sensor or number entities that don't belong with the service entity. diff --git a/homeassistant/components/homekit_controller/number.py b/homeassistant/components/homekit_controller/number.py index 5d72516bc06..940ea460284 100644 --- a/homeassistant/components/homekit_controller/number.py +++ b/homeassistant/components/homekit_controller/number.py @@ -1,5 +1,4 @@ -""" -Support for Homekit number ranges. +"""Support for Homekit number ranges. These are mostly used where a HomeKit accessory exposes additional non-standard characteristics that don't map to a Home Assistant feature. diff --git a/homeassistant/components/homekit_controller/sensor.py b/homeassistant/components/homekit_controller/sensor.py index 5d3e9669705..543fdb4adaf 100644 --- a/homeassistant/components/homekit_controller/sensor.py +++ b/homeassistant/components/homekit_controller/sensor.py @@ -55,8 +55,7 @@ class HomeKitSensorEntityDescription(SensorEntityDescription): def thread_node_capability_to_str(char: Characteristic) -> str: - """ - Return the thread device type as a string. + """Return the thread device type as a string. The underlying value is a bitmask, but we want to turn that to a human readable string. Some devices will have multiple capabilities. @@ -93,8 +92,7 @@ def thread_node_capability_to_str(char: Characteristic) -> str: def thread_status_to_str(char: Characteristic) -> str: - """ - Return the thread status as a string. + """Return the thread status as a string. The underlying value is a bitmask, but we want to turn that to a human readable string. So we check the flags in order. E.g. BORDER_ROUTER implies @@ -501,8 +499,7 @@ class HomeKitBatterySensor(HomeKitSensor): class SimpleSensor(CharacteristicEntity, SensorEntity): - """ - A simple sensor for a single characteristic. + """A simple sensor for a single characteristic. This may be an additional secondary entity that is part of another service. An example is a switch that has an energy sensor. diff --git a/homeassistant/components/homekit_controller/storage.py b/homeassistant/components/homekit_controller/storage.py index de4f23ad8da..8a73f99b391 100644 --- a/homeassistant/components/homekit_controller/storage.py +++ b/homeassistant/components/homekit_controller/storage.py @@ -19,8 +19,7 @@ _LOGGER = logging.getLogger(__name__) class EntityMapStorage: - """ - Holds a cache of entity structure data from a paired HomeKit device. + """Holds a cache of entity structure data from a paired HomeKit device. HomeKit has a cacheable entity map that describes how an IP or BLE endpoint is structured. This object holds the latest copy of that data. diff --git a/homeassistant/components/homematic/cover.py b/homeassistant/components/homematic/cover.py index d5f1802e774..d9fb44219f6 100644 --- a/homeassistant/components/homematic/cover.py +++ b/homeassistant/components/homematic/cover.py @@ -44,8 +44,7 @@ class HMCover(HMDevice, CoverEntity): @property def current_cover_position(self) -> int | None: - """ - Return current position of cover. + """Return current position of cover. None is unknown, 0 is closed, 100 is fully open. """ @@ -126,8 +125,7 @@ class HMGarage(HMCover): @property def current_cover_position(self) -> None: - """ - Return current position of cover. + """Return current position of cover. None is unknown, 0 is closed, 100 is fully open. """ diff --git a/homeassistant/components/homematicip_cloud/climate.py b/homeassistant/components/homematicip_cloud/climate.py index 6e2ca202fd3..7aa68709040 100644 --- a/homeassistant/components/homematicip_cloud/climate.py +++ b/homeassistant/components/homematicip_cloud/climate.py @@ -131,8 +131,7 @@ class HomematicipHeatingGroup(HomematicipGenericEntity, ClimateEntity): @property def hvac_action(self) -> HVACAction | None: - """ - Return the current hvac_action. + """Return the current hvac_action. This is only relevant for radiator thermostats. """ diff --git a/homeassistant/components/homematicip_cloud/light.py b/homeassistant/components/homematicip_cloud/light.py index 4ad418bc8ad..3000024db43 100644 --- a/homeassistant/components/homematicip_cloud/light.py +++ b/homeassistant/components/homematicip_cloud/light.py @@ -256,8 +256,7 @@ class HomematicipNotificationLight(HomematicipGenericEntity, LightEntity): def _convert_color(color: tuple) -> RGBColorState: - """ - Convert the given color to the reduced RGBColorState color. + """Convert the given color to the reduced RGBColorState color. RGBColorStat contains only 8 colors including white and black, so a conversion is required. diff --git a/homeassistant/components/http/auth.py b/homeassistant/components/http/auth.py index 197c4f34dad..5213cd1b072 100644 --- a/homeassistant/components/http/auth.py +++ b/homeassistant/components/http/auth.py @@ -139,8 +139,7 @@ async def async_setup_auth(hass: HomeAssistant, app: Application) -> None: hass.data[STORAGE_KEY] = refresh_token.id async def async_validate_auth_header(request: Request) -> bool: - """ - Test authorization header against access token. + """Test authorization header against access token. Basic auth_type is legacy code, should be removed with api_password. """ diff --git a/homeassistant/components/huawei_lte/__init__.py b/homeassistant/components/huawei_lte/__init__.py index badf7d0a484..0f661498713 100644 --- a/homeassistant/components/huawei_lte/__init__.py +++ b/homeassistant/components/huawei_lte/__init__.py @@ -456,8 +456,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool: ) def _update_router(*_: Any) -> None: - """ - Update router data. + """Update router data. Separate passthrough function because lambdas don't work with track_time_interval. """ @@ -496,8 +495,7 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool: hass.data[DOMAIN] = HuaweiLteData(hass_config=config, routers={}) def service_handler(service: ServiceCall) -> None: - """ - Apply a service. + """Apply a service. We key this using the router URL instead of its unique id / serial number, because the latter is not available anywhere in the UI. diff --git a/homeassistant/components/huawei_lte/config_flow.py b/homeassistant/components/huawei_lte/config_flow.py index 2319cc9a3ed..d4aa170f70d 100644 --- a/homeassistant/components/huawei_lte/config_flow.py +++ b/homeassistant/components/huawei_lte/config_flow.py @@ -251,8 +251,7 @@ class ConfigFlowHandler(config_entries.ConfigFlow, domain=DOMAIN): self._abort_if_unique_id_configured(updates={CONF_URL: url}) def _is_supported_device() -> bool: - """ - See if we are looking at a possibly supported device. + """See if we are looking at a possibly supported device. Matching solely on SSDP data does not yield reliable enough results. """ diff --git a/homeassistant/components/huisbaasje/__init__.py b/homeassistant/components/huisbaasje/__init__.py index 3952e4a1341..8559156379b 100644 --- a/homeassistant/components/huisbaasje/__init__.py +++ b/homeassistant/components/huisbaasje/__init__.py @@ -122,8 +122,7 @@ def _get_cumulative_value( source_type: str, period_type: str, ): - """ - Get the cumulative energy consumption for a certain period. + """Get the cumulative energy consumption for a certain period. :param current_measurements: The result from the Huisbaasje client :param source_type: The source of energy (electricity or gas) diff --git a/homeassistant/components/imap_email_content/sensor.py b/homeassistant/components/imap_email_content/sensor.py index 216a5a7cfe7..b14de632687 100644 --- a/homeassistant/components/imap_email_content/sensor.py +++ b/homeassistant/components/imap_email_content/sensor.py @@ -219,8 +219,7 @@ class EmailContentSensor(SensorEntity): @staticmethod def get_msg_text(email_message): - """ - Get the message text from the email. + """Get the message text from the email. Will look for text/plain or use text/html if not found. """ diff --git a/homeassistant/components/izone/climate.py b/homeassistant/components/izone/climate.py index 4fb3447488f..9d1db1b2a97 100644 --- a/homeassistant/components/izone/climate.py +++ b/homeassistant/components/izone/climate.py @@ -223,8 +223,7 @@ class ControllerDevice(ClimateEntity): @callback def set_available(self, available: bool, ex: Exception | None = None) -> None: - """ - Set availability for the controller. + """Set availability for the controller. Also sets zone availability as they follow the same availability. """ diff --git a/homeassistant/components/knx/schema.py b/homeassistant/components/knx/schema.py index b1ae55ba9dc..c6206e883e5 100644 --- a/homeassistant/components/knx/schema.py +++ b/homeassistant/components/knx/schema.py @@ -114,8 +114,7 @@ ia_validator = vol.Any( def ip_v4_validator(value: Any, multicast: bool | None = None) -> str: - """ - Validate that value is parsable as IPv4 address. + """Validate that value is parsable as IPv4 address. Optionally check if address is in a reserved multicast block or is explicitly not. """ diff --git a/homeassistant/components/kodi/browse_media.py b/homeassistant/components/kodi/browse_media.py index cfb4fa3caa6..5df714e27da 100644 --- a/homeassistant/components/kodi/browse_media.py +++ b/homeassistant/components/kodi/browse_media.py @@ -84,8 +84,7 @@ async def build_item_response(media_library, payload, get_thumbnail_url=None): async def item_payload(item, get_thumbnail_url=None): - """ - Create response payload for a single media item. + """Create response payload for a single media item. Used by async_browse_media. """ @@ -179,8 +178,7 @@ def media_source_content_filter(item: BrowseMedia) -> bool: async def library_payload(hass): - """ - Create response payload to describe contents of a specific library. + """Create response payload to describe contents of a specific library. Used by async_browse_media. """ diff --git a/homeassistant/components/lirc/__init__.py b/homeassistant/components/lirc/__init__.py index 227d1e7d5a9..c5ebf874681 100644 --- a/homeassistant/components/lirc/__init__.py +++ b/homeassistant/components/lirc/__init__.py @@ -42,8 +42,7 @@ def setup(hass: HomeAssistant, config: ConfigType) -> bool: class LircInterface(threading.Thread): - """ - This interfaces with the lirc daemon to read IR commands. + """This interfaces with the lirc daemon to read IR commands. When using lirc in blocking mode, sometimes repeated commands get produced in the next read of a command so we use a thread here to just wait diff --git a/homeassistant/components/luci/device_tracker.py b/homeassistant/components/luci/device_tracker.py index 82fc51ba5cd..d18ecf8bd4e 100644 --- a/homeassistant/components/luci/device_tracker.py +++ b/homeassistant/components/luci/device_tracker.py @@ -77,8 +77,7 @@ class LuciDeviceScanner(DeviceScanner): return name def get_extra_attributes(self, device): - """ - Get extra attributes of a device. + """Get extra attributes of a device. Some known extra attributes that may be returned in the device tuple include MAC address (mac), network device (dev), IP address diff --git a/homeassistant/components/manual/alarm_control_panel.py b/homeassistant/components/manual/alarm_control_panel.py index 08dcba23272..d35f9b73ef3 100644 --- a/homeassistant/components/manual/alarm_control_panel.py +++ b/homeassistant/components/manual/alarm_control_panel.py @@ -174,8 +174,7 @@ def setup_platform( class ManualAlarm(alarm.AlarmControlPanelEntity, RestoreEntity): - """ - Representation of an alarm status. + """Representation of an alarm status. When armed, will be arming for 'arming_time', after that armed. When triggered, will be pending for the triggering state's 'delay_time'. @@ -339,8 +338,7 @@ class ManualAlarm(alarm.AlarmControlPanelEntity, RestoreEntity): self._async_update_state(STATE_ALARM_ARMED_CUSTOM_BYPASS) async def async_alarm_trigger(self, code: str | None = None) -> None: - """ - Send alarm trigger command. + """Send alarm trigger command. No code needed, a trigger time of zero for the current state disables the alarm. diff --git a/homeassistant/components/manual_mqtt/alarm_control_panel.py b/homeassistant/components/manual_mqtt/alarm_control_panel.py index 93a1eeb2cb6..3857dd19542 100644 --- a/homeassistant/components/manual_mqtt/alarm_control_panel.py +++ b/homeassistant/components/manual_mqtt/alarm_control_panel.py @@ -216,8 +216,7 @@ def setup_platform( class ManualMQTTAlarm(alarm.AlarmControlPanelEntity): - """ - Representation of an alarm status. + """Representation of an alarm status. When armed, will be pending for 'pending_time', after that armed. When triggered, will be pending for the triggering state's 'delay_time' @@ -397,8 +396,7 @@ class ManualMQTTAlarm(alarm.AlarmControlPanelEntity): self._async_update_state(STATE_ALARM_ARMED_CUSTOM_BYPASS) async def async_alarm_trigger(self, code: str | None = None) -> None: - """ - Send alarm trigger command. + """Send alarm trigger command. No code needed, a trigger time of zero for the current state disables the alarm. diff --git a/homeassistant/components/matrix/__init__.py b/homeassistant/components/matrix/__init__.py index 17df46a0849..87e692af3c5 100644 --- a/homeassistant/components/matrix/__init__.py +++ b/homeassistant/components/matrix/__init__.py @@ -276,8 +276,7 @@ class MatrixBot: _LOGGER.error("Could not join room %s: %s", room_id, ex) def _get_auth_tokens(self): - """ - Read sorted authentication tokens from disk. + """Read sorted authentication tokens from disk. Returns the auth_tokens dictionary. """ diff --git a/homeassistant/components/maxcube/climate.py b/homeassistant/components/maxcube/climate.py index 828696a9ff0..2ef451b04a7 100644 --- a/homeassistant/components/maxcube/climate.py +++ b/homeassistant/components/maxcube/climate.py @@ -134,8 +134,7 @@ class MaxCubeClimate(ClimateEntity): raise ValueError(f"unsupported HVAC mode {hvac_mode}") def _set_target(self, mode: int | None, temp: float | None) -> None: - """ - Set the mode and/or temperature of the thermostat. + """Set the mode and/or temperature of the thermostat. @param mode: this is the mode to change to. @param temp: the temperature to target. diff --git a/homeassistant/components/media_player/__init__.py b/homeassistant/components/media_player/__init__.py index 341c9468d11..3938cc64f7b 100644 --- a/homeassistant/components/media_player/__init__.py +++ b/homeassistant/components/media_player/__init__.py @@ -236,8 +236,7 @@ _ENTITY_IMAGE_CACHE = _ImageCache(images=collections.OrderedDict(), maxsize=16) @bind_hass def is_on(hass: HomeAssistant, entity_id: str | None = None) -> bool: - """ - Return true if specified media player entity_id is on. + """Return true if specified media player entity_id is on. Check all media player if no entity_id specified. """ @@ -591,8 +590,7 @@ class MediaPlayerEntity(Entity): media_content_id: str, media_image_id: str | None = None, ) -> tuple[bytes | None, str | None]: - """ - Optionally fetch internally accessible image for media browser. + """Optionally fetch internally accessible image for media browser. Must be implemented by integration. """ @@ -1198,8 +1196,7 @@ async def websocket_browse_media( connection: websocket_api.connection.ActiveConnection, msg: dict[str, Any], ) -> None: - """ - Browse media available to the media_player entity. + """Browse media available to the media_player entity. To use, media_player integrations can implement MediaPlayerEntity.async_browse_media() diff --git a/homeassistant/components/media_source/local_source.py b/homeassistant/components/media_source/local_source.py index 54f82365ffb..d211b878b99 100644 --- a/homeassistant/components/media_source/local_source.py +++ b/homeassistant/components/media_source/local_source.py @@ -192,8 +192,7 @@ class LocalSource(MediaSource): class LocalMediaView(http.HomeAssistantView): - """ - Local Media Finder View. + """Local Media Finder View. Returns media files in config/media. """ diff --git a/homeassistant/components/minio/minio_helper.py b/homeassistant/components/minio/minio_helper.py index 379ff41ae51..6a4c9310853 100644 --- a/homeassistant/components/minio/minio_helper.py +++ b/homeassistant/components/minio/minio_helper.py @@ -187,8 +187,7 @@ class MinioEventThread(threading.Thread): def iterate_objects(event): - """ - Iterate over file records of notification event. + """Iterate over file records of notification event. Most of the time it should still be only one record. """ diff --git a/homeassistant/components/motion_blinds/cover.py b/homeassistant/components/motion_blinds/cover.py index 53ee4f5b561..aaf74a96de0 100644 --- a/homeassistant/components/motion_blinds/cover.py +++ b/homeassistant/components/motion_blinds/cover.py @@ -230,8 +230,7 @@ class MotionPositionDevice(CoordinatorEntity, CoverEntity): @property def current_cover_position(self) -> int | None: - """ - Return current position of cover. + """Return current position of cover. None is unknown, 0 is open, 100 is closed. """ @@ -343,8 +342,7 @@ class MotionTiltDevice(MotionPositionDevice): @property def current_cover_tilt_position(self) -> int | None: - """ - Return current angle of cover. + """Return current angle of cover. None is unknown, 0 is closed/minimum tilt, 100 is fully open/maximum tilt. """ @@ -440,8 +438,7 @@ class MotionTDBUDevice(MotionPositionDevice): @property def current_cover_position(self) -> int | None: - """ - Return current position of cover. + """Return current position of cover. None is unknown, 0 is open, 100 is closed. """ diff --git a/homeassistant/components/mqtt/cover.py b/homeassistant/components/mqtt/cover.py index cf539726741..9b1eb81acc5 100644 --- a/homeassistant/components/mqtt/cover.py +++ b/homeassistant/components/mqtt/cover.py @@ -748,8 +748,7 @@ class MqttCover(MqttEntity, CoverEntity): def find_in_range_from_percent( self, percentage: float, range_type: str = TILT_PAYLOAD ) -> int: - """ - Find the adjusted value for 0-100% within the specified range. + """Find the adjusted value for 0-100% within the specified range. if the range is 80-180 and the percentage is 90 this method would determine the value to send on the topic diff --git a/homeassistant/components/nad/media_player.py b/homeassistant/components/nad/media_player.py index 0e036a8cdfb..fd84668d651 100644 --- a/homeassistant/components/nad/media_player.py +++ b/homeassistant/components/nad/media_player.py @@ -168,8 +168,7 @@ class NAD(MediaPlayerEntity): ) def calc_volume(self, decibel): - """ - Calculate the volume given the decibel. + """Calculate the volume given the decibel. Return the volume (0..1). """ @@ -178,8 +177,7 @@ class NAD(MediaPlayerEntity): ) def calc_db(self, volume): - """ - Calculate the decibel given the volume. + """Calculate the decibel given the volume. Return the dB. """ diff --git a/homeassistant/components/nest/legacy/__init__.py b/homeassistant/components/nest/legacy/__init__.py index 271706b16c0..3c3a10a61bf 100644 --- a/homeassistant/components/nest/legacy/__init__.py +++ b/homeassistant/components/nest/legacy/__init__.py @@ -82,8 +82,7 @@ CANCEL_ETA_SCHEMA = vol.Schema( def nest_update_event_broker(hass, nest): - """ - Dispatch SIGNAL_NEST_UPDATE to devices when nest stream API received data. + """Dispatch SIGNAL_NEST_UPDATE to devices when nest stream API received data. Used for the legacy nest API. diff --git a/homeassistant/components/netatmo/data_handler.py b/homeassistant/components/netatmo/data_handler.py index 1a322f8d8db..80396e8048c 100644 --- a/homeassistant/components/netatmo/data_handler.py +++ b/homeassistant/components/netatmo/data_handler.py @@ -156,8 +156,7 @@ class NetatmoDataHandler: await self.async_dispatch() async def async_update(self, event_time: datetime) -> None: - """ - Update device. + """Update device. We do up to BATCH_SIZE calls in one update in order to minimize the calls on the api service. diff --git a/homeassistant/components/nuki/__init__.py b/homeassistant/components/nuki/__init__.py index 6a3248385ad..3a75c10333b 100644 --- a/homeassistant/components/nuki/__init__.py +++ b/homeassistant/components/nuki/__init__.py @@ -163,8 +163,7 @@ class NukiCoordinator(DataUpdateCoordinator[None]): self.hass.bus.async_fire("nuki_event", event_data) def update_devices(self, devices: list[NukiDevice]) -> dict[str, set[str]]: - """ - Update the Nuki devices. + """Update the Nuki devices. Returns: A dict with the events to be fired. The event type is the key and the device ids are the value diff --git a/homeassistant/components/nws/__init__.py b/homeassistant/components/nws/__init__.py index fb8f9bf0c76..fed7642605d 100644 --- a/homeassistant/components/nws/__init__.py +++ b/homeassistant/components/nws/__init__.py @@ -43,8 +43,7 @@ def base_unique_id(latitude: float, longitude: float) -> str: class NwsDataUpdateCoordinator(DataUpdateCoordinator[None]): - """ - NWS data update coordinator. + """NWS data update coordinator. Implements faster data update intervals for failed updates and exposes a last successful update time. """ diff --git a/homeassistant/components/nws/weather.py b/homeassistant/components/nws/weather.py index b7982247ab2..ecb95a1f9e8 100644 --- a/homeassistant/components/nws/weather.py +++ b/homeassistant/components/nws/weather.py @@ -55,8 +55,7 @@ PARALLEL_UPDATES = 0 def convert_condition( time: str, weather: tuple[tuple[str, int | None], ...] ) -> tuple[str, int | None]: - """ - Convert NWS codes to HA condition. + """Convert NWS codes to HA condition. Choose first condition in CONDITION_CLASSES that exists in weather code. If no match is found, return first condition from NWS diff --git a/homeassistant/components/onkyo/media_player.py b/homeassistant/components/onkyo/media_player.py index 9b41a635fe1..94ee651a168 100644 --- a/homeassistant/components/onkyo/media_player.py +++ b/homeassistant/components/onkyo/media_player.py @@ -355,8 +355,7 @@ class OnkyoDevice(MediaPlayerEntity): self.command("system-power standby") def set_volume_level(self, volume: float) -> None: - """ - Set volume level, input is range 0..1. + """Set volume level, input is range 0..1. However full volume on the amp is usually far too loud so allow the user to specify the upper range with CONF_MAX_VOLUME. we change as per max_volume set by user. This means that if max volume is 80 then full @@ -523,8 +522,7 @@ class OnkyoDeviceZone(OnkyoDevice): self.command(f"zone{self._zone}.power=standby") def set_volume_level(self, volume: float) -> None: - """ - Set volume level, input is range 0..1. + """Set volume level, input is range 0..1. However full volume on the amp is usually far too loud so allow the user to specify the upper range with CONF_MAX_VOLUME. we change as per max_volume set by user. This means that if max volume is 80 then full diff --git a/homeassistant/components/opentherm_gw/config_flow.py b/homeassistant/components/opentherm_gw/config_flow.py index c3a955b2387..ed9b62ff499 100644 --- a/homeassistant/components/opentherm_gw/config_flow.py +++ b/homeassistant/components/opentherm_gw/config_flow.py @@ -86,8 +86,7 @@ class OpenThermGwConfigFlow(config_entries.ConfigFlow, domain=DOMAIN): return await self.async_step_init(user_input) async def async_step_import(self, import_config): - """ - Import an OpenTherm Gateway device as a config entry. + """Import an OpenTherm Gateway device as a config entry. This flow is triggered by `async_setup` for configured devices. """ diff --git a/homeassistant/components/overkiz/cover_entities/awning.py b/homeassistant/components/overkiz/cover_entities/awning.py index a5aee73bf5b..da940d59218 100644 --- a/homeassistant/components/overkiz/cover_entities/awning.py +++ b/homeassistant/components/overkiz/cover_entities/awning.py @@ -45,8 +45,7 @@ class Awning(OverkizGenericCover): @property def current_cover_position(self) -> int | None: - """ - Return current position of cover. + """Return current position of cover. None is unknown, 0 is closed, 100 is fully open. """ diff --git a/homeassistant/components/overkiz/cover_entities/vertical_cover.py b/homeassistant/components/overkiz/cover_entities/vertical_cover.py index 18a9f176593..6e72dacf5c6 100644 --- a/homeassistant/components/overkiz/cover_entities/vertical_cover.py +++ b/homeassistant/components/overkiz/cover_entities/vertical_cover.py @@ -75,8 +75,7 @@ class VerticalCover(OverkizGenericCover): @property def current_cover_position(self) -> int | None: - """ - Return current position of cover. + """Return current position of cover. None is unknown, 0 is closed, 100 is fully open. """ diff --git a/homeassistant/components/overkiz/executor.py b/homeassistant/components/overkiz/executor.py index 7b0f03e446c..9095ec8d38e 100644 --- a/homeassistant/components/overkiz/executor.py +++ b/homeassistant/components/overkiz/executor.py @@ -152,8 +152,7 @@ class OverkizExecutor: await self.coordinator.client.cancel_command(exec_id) def get_gateway_id(self) -> str: - """ - Retrieve gateway id from device url. + """Retrieve gateway id from device url. device URL (:///[#]) """ diff --git a/homeassistant/components/panasonic_bluray/media_player.py b/homeassistant/components/panasonic_bluray/media_player.py index 1e04d5ce53d..ae017e7d72c 100644 --- a/homeassistant/components/panasonic_bluray/media_player.py +++ b/homeassistant/components/panasonic_bluray/media_player.py @@ -91,8 +91,7 @@ class PanasonicBluRay(MediaPlayerEntity): self._attr_media_duration = state[2] def turn_off(self) -> None: - """ - Instruct the device to turn standby. + """Instruct the device to turn standby. Sending the "POWER" button will turn the device to standby - there is no way to turn it completely off remotely. However this works in diff --git a/homeassistant/components/pandora/media_player.py b/homeassistant/components/pandora/media_player.py index b728767cb4e..3a67375ec80 100644 --- a/homeassistant/components/pandora/media_player.py +++ b/homeassistant/components/pandora/media_player.py @@ -255,8 +255,7 @@ class PandoraMediaPlayer(MediaPlayerEntity): @util.Throttle(MIN_TIME_BETWEEN_UPDATES) def _update_song_position(self): - """ - Get the song position and duration. + """Get the song position and duration. It's hard to predict whether or not the music will start during init so we have to detect state by checking the ticker. @@ -312,8 +311,7 @@ class PandoraMediaPlayer(MediaPlayerEntity): self._pianobar.sendcontrol("m") # do it twice in case an 'i' got in def _clear_buffer(self): - """ - Clear buffer from pexpect. + """Clear buffer from pexpect. This is necessary because there are a bunch of 00:00 in the buffer diff --git a/homeassistant/components/plugwise/config_flow.py b/homeassistant/components/plugwise/config_flow.py index 45d83e316b1..d36ae1ba047 100644 --- a/homeassistant/components/plugwise/config_flow.py +++ b/homeassistant/components/plugwise/config_flow.py @@ -62,8 +62,7 @@ def _base_gw_schema(discovery_info: ZeroconfServiceInfo | None) -> vol.Schema: async def validate_gw_input(hass: HomeAssistant, data: dict[str, Any]) -> Smile: - """ - Validate whether the user input allows us to connect to the gateway. + """Validate whether the user input allows us to connect to the gateway. Data has the keys from _base_gw_schema() with values provided by the user. """ diff --git a/homeassistant/components/recorder/history.py b/homeassistant/components/recorder/history.py index e4f5a39f1cc..72ae57dde27 100644 --- a/homeassistant/components/recorder/history.py +++ b/homeassistant/components/recorder/history.py @@ -349,8 +349,7 @@ def get_significant_states_with_session( no_attributes: bool = False, compressed_state_format: bool = False, ) -> MutableMapping[str, list[State | dict[str, Any]]]: - """ - Return states changes during UTC period start_time - end_time. + """Return states changes during UTC period start_time - end_time. entity_ids is an optional iterable of entities to include in the results. diff --git a/homeassistant/components/rejseplanen/sensor.py b/homeassistant/components/rejseplanen/sensor.py index 9ef8b5dc370..9db7c6ff100 100644 --- a/homeassistant/components/rejseplanen/sensor.py +++ b/homeassistant/components/rejseplanen/sensor.py @@ -1,5 +1,4 @@ -""" -Support for Rejseplanen information from rejseplanen.dk. +"""Support for Rejseplanen information from rejseplanen.dk. For more info on the API see: https://help.rejseplanen.dk/hc/en-us/articles/214174465-Rejseplanen-s-API diff --git a/homeassistant/components/roku/browse_media.py b/homeassistant/components/roku/browse_media.py index 07e65ed3891..4173d2f5c6e 100644 --- a/homeassistant/components/roku/browse_media.py +++ b/homeassistant/components/roku/browse_media.py @@ -222,8 +222,7 @@ def item_payload( coordinator: RokuDataUpdateCoordinator, get_browse_image_url: GetBrowseImageUrlType, ) -> BrowseMedia: - """ - Create response payload for a single media item. + """Create response payload for a single media item. Used by async_browse_media. """ diff --git a/homeassistant/components/rpi_power/binary_sensor.py b/homeassistant/components/rpi_power/binary_sensor.py index c0c65e814ea..504bdad0955 100644 --- a/homeassistant/components/rpi_power/binary_sensor.py +++ b/homeassistant/components/rpi_power/binary_sensor.py @@ -1,5 +1,4 @@ -""" -A sensor platform which detects underruns and capped status from the official Raspberry Pi Kernel. +"""A sensor platform which detects underruns and capped status from the official Raspberry Pi Kernel. Minimal Kernel needed is 4.14+ """ diff --git a/homeassistant/components/sabnzbd/__init__.py b/homeassistant/components/sabnzbd/__init__.py index 18f1ce9c451..0b8b6e92eb3 100644 --- a/homeassistant/components/sabnzbd/__init__.py +++ b/homeassistant/components/sabnzbd/__init__.py @@ -145,8 +145,7 @@ async def migrate_unique_id(hass: HomeAssistant, entry: ConfigEntry): @callback def async_migrate_callback(entity_entry: RegistryEntry) -> dict | None: - """ - Define a callback to migrate appropriate SabnzbdSensor entities to new unique IDs. + """Define a callback to migrate appropriate SabnzbdSensor entities to new unique IDs. Old: description.key New: {entry_id}_description.key diff --git a/homeassistant/components/sharkiq/vacuum.py b/homeassistant/components/sharkiq/vacuum.py index 48e82477809..5eafbc1e1e2 100644 --- a/homeassistant/components/sharkiq/vacuum.py +++ b/homeassistant/components/sharkiq/vacuum.py @@ -153,8 +153,7 @@ class SharkVacuumEntity(CoordinatorEntity[SharkIqUpdateCoordinator], StateVacuum @property def state(self) -> str | None: - """ - Get the current vacuum state. + """Get the current vacuum state. NB: Currently, we do not return an error state because they can be very, very stale. In the app, these are (usually) handled by showing the robot as stopped and sending the diff --git a/homeassistant/components/siren/__init__.py b/homeassistant/components/siren/__init__.py index 92d547d5760..0f82918d82a 100644 --- a/homeassistant/components/siren/__init__.py +++ b/homeassistant/components/siren/__init__.py @@ -59,8 +59,7 @@ class SirenTurnOnServiceParameters(TypedDict, total=False): def process_turn_on_params( siren: SirenEntity, params: SirenTurnOnServiceParameters ) -> SirenTurnOnServiceParameters: - """ - Process turn_on service params. + """Process turn_on service params. Filters out unsupported params and validates the rest. """ @@ -178,8 +177,7 @@ class SirenEntity(ToggleEntity): @property def available_tones(self) -> list[int | str] | dict[int, str] | None: - """ - Return a list of available tones. + """Return a list of available tones. Requires SirenEntityFeature.TONES. """ diff --git a/homeassistant/components/smartthings/climate.py b/homeassistant/components/smartthings/climate.py index f311fb2a44d..52a02aca745 100644 --- a/homeassistant/components/smartthings/climate.py +++ b/homeassistant/components/smartthings/climate.py @@ -413,8 +413,7 @@ class SmartThingsAirConditioner(SmartThingsEntity, ClimateEntity): @property def extra_state_attributes(self): - """ - Return device specific state attributes. + """Return device specific state attributes. Include attributes from the Demand Response Load Control (drlc) and Power Consumption capabilities. diff --git a/homeassistant/components/smartthings/smartapp.py b/homeassistant/components/smartthings/smartapp.py index b6bd05740e6..9b17034ab3b 100644 --- a/homeassistant/components/smartthings/smartapp.py +++ b/homeassistant/components/smartthings/smartapp.py @@ -76,8 +76,7 @@ async def find_app(hass: HomeAssistant, api): async def validate_installed_app(api, installed_app_id: str): - """ - Ensure the specified installed SmartApp is valid and functioning. + """Ensure the specified installed SmartApp is valid and functioning. Query the API for the installed SmartApp and validate that it is tied to the specified app_id and is in an authorized state. @@ -104,8 +103,7 @@ def validate_webhook_requirements(hass: HomeAssistant) -> bool: def get_webhook_url(hass: HomeAssistant) -> str: - """ - Get the URL of the webhook. + """Get the URL of the webhook. Return the cloudhook if available, otherwise local webhook. """ @@ -182,8 +180,7 @@ async def update_app(hass: HomeAssistant, app): def setup_smartapp(hass, app): - """ - Configure an individual SmartApp in hass. + """Configure an individual SmartApp in hass. Register the SmartApp with the SmartAppManager so that hass will service lifecycle events (install, event, etc...). A unique SmartApp is created @@ -201,8 +198,7 @@ def setup_smartapp(hass, app): async def setup_smartapp_endpoint(hass: HomeAssistant): - """ - Configure the SmartApp webhook in hass. + """Configure the SmartApp webhook in hass. SmartApps are an extension point within the SmartThings ecosystem and is used to receive push updates (i.e. device updates) from the cloud. @@ -473,8 +469,7 @@ async def smartapp_update(hass: HomeAssistant, req, resp, app): async def smartapp_uninstall(hass: HomeAssistant, req, resp, app): - """ - Handle when a SmartApp is removed from a location by the user. + """Handle when a SmartApp is removed from a location by the user. Find and delete the config entry representing the integration. """ @@ -499,8 +494,7 @@ async def smartapp_uninstall(hass: HomeAssistant, req, resp, app): async def smartapp_webhook(hass: HomeAssistant, webhook_id: str, request): - """ - Handle a smartapp lifecycle event callback from SmartThings. + """Handle a smartapp lifecycle event callback from SmartThings. Requests from SmartThings are digitally signed and the SmartAppManager validates the signature for authenticity. diff --git a/homeassistant/components/smtp/notify.py b/homeassistant/components/smtp/notify.py index 32806889b3d..28c3121a172 100644 --- a/homeassistant/components/smtp/notify.py +++ b/homeassistant/components/smtp/notify.py @@ -183,8 +183,7 @@ class MailNotificationService(BaseNotificationService): return True def send_message(self, message="", **kwargs): - """ - Build and send a message to a user. + """Build and send a message to a user. Will send plain text normally, or will build a multipart HTML message with inline image attachments if images config is defined, or will diff --git a/homeassistant/components/snapcast/media_player.py b/homeassistant/components/snapcast/media_player.py index 2794c350ed4..9e0e10ac0e2 100644 --- a/homeassistant/components/snapcast/media_player.py +++ b/homeassistant/components/snapcast/media_player.py @@ -226,8 +226,7 @@ class SnapcastClientDevice(MediaPlayerEntity): @property def unique_id(self): - """ - Return the ID of this snapcast client. + """Return the ID of this snapcast client. Note: Host part is needed, when using multiple snapservers """ diff --git a/homeassistant/components/sonos/media_browser.py b/homeassistant/components/sonos/media_browser.py index 1f245d23018..1b32cb2473a 100644 --- a/homeassistant/components/sonos/media_browser.py +++ b/homeassistant/components/sonos/media_browser.py @@ -230,8 +230,7 @@ def build_item_response( def item_payload(item: DidlObject, get_thumbnail_url=None) -> BrowseMedia: - """ - Create response payload for a single media item. + """Create response payload for a single media item. Used by async_browse_media. """ @@ -347,8 +346,7 @@ async def root_payload( def library_payload(media_library: MusicLibrary, get_thumbnail_url=None) -> BrowseMedia: - """ - Create response payload to describe contents of a specific library. + """Create response payload to describe contents of a specific library. Used by async_browse_media. """ @@ -369,8 +367,7 @@ def library_payload(media_library: MusicLibrary, get_thumbnail_url=None) -> Brow def favorites_payload(favorites: SonosFavorites) -> BrowseMedia: - """ - Create response payload to describe contents of a specific library. + """Create response payload to describe contents of a specific library. Used by async_browse_media. """ @@ -461,8 +458,7 @@ def get_media_type(item: DidlObject) -> str: def can_play(item: DidlObject) -> bool: - """ - Test if playable. + """Test if playable. Used by async_browse_media. """ @@ -470,8 +466,7 @@ def can_play(item: DidlObject) -> bool: def can_expand(item: DidlObject) -> bool: - """ - Test if expandable. + """Test if expandable. Used by async_browse_media. """ diff --git a/homeassistant/components/sonos/media_player.py b/homeassistant/components/sonos/media_player.py index 90b72a663aa..f2ec967f6d0 100644 --- a/homeassistant/components/sonos/media_player.py +++ b/homeassistant/components/sonos/media_player.py @@ -494,8 +494,7 @@ class SonosMediaPlayerEntity(SonosEntity, MediaPlayerEntity): def play_media( # noqa: C901 self, media_type: str, media_id: str, **kwargs: Any ) -> None: - """ - Send the play_media command to the media player. + """Send the play_media command to the media player. If media_id is a Plex payload, attempt Plex->Sonos playback. diff --git a/homeassistant/components/soundtouch/media_player.py b/homeassistant/components/soundtouch/media_player.py index bb7ad0577ac..7a352145468 100644 --- a/homeassistant/components/soundtouch/media_player.py +++ b/homeassistant/components/soundtouch/media_player.py @@ -329,8 +329,7 @@ class SoundTouchMediaPlayer(MediaPlayerEntity): _LOGGER.warning("Source %s is not supported", source) def create_zone(self, slaves): - """ - Create a zone (multi-room) and play on selected devices. + """Create a zone (multi-room) and play on selected devices. :param slaves: slaves on which to play @@ -342,8 +341,7 @@ class SoundTouchMediaPlayer(MediaPlayerEntity): self._device.create_zone([slave.device for slave in slaves]) def remove_zone_slave(self, slaves): - """ - Remove slave(s) from and existing zone (multi-room). + """Remove slave(s) from and existing zone (multi-room). Zone must already exist and slaves array cannot be empty. Note: If removing last slave, the zone will be deleted and you'll have @@ -367,8 +365,7 @@ class SoundTouchMediaPlayer(MediaPlayerEntity): self._device.remove_zone_slave([slave.device]) def add_zone_slave(self, slaves): - """ - Add slave(s) to and existing zone (multi-room). + """Add slave(s) to and existing zone (multi-room). Zone must already exist and slaves array cannot be empty. diff --git a/homeassistant/components/spotify/browse_media.py b/homeassistant/components/spotify/browse_media.py index 0f72d459b68..98eac019bac 100644 --- a/homeassistant/components/spotify/browse_media.py +++ b/homeassistant/components/spotify/browse_media.py @@ -399,8 +399,7 @@ def build_item_response( # noqa: C901 def item_payload(item: dict[str, Any], *, can_play_artist: bool) -> BrowseMedia: - """ - Create response payload for a single media item. + """Create response payload for a single media item. Used by async_browse_media. """ @@ -445,8 +444,7 @@ def item_payload(item: dict[str, Any], *, can_play_artist: bool) -> BrowseMedia: def library_payload(*, can_play_artist: bool) -> BrowseMedia: - """ - Create response payload to describe contents of a specific library. + """Create response payload to describe contents of a specific library. Used by async_browse_media. """ diff --git a/homeassistant/components/squeezebox/config_flow.py b/homeassistant/components/squeezebox/config_flow.py index a8a1797f3bc..7a5d874c5bb 100644 --- a/homeassistant/components/squeezebox/config_flow.py +++ b/homeassistant/components/squeezebox/config_flow.py @@ -95,8 +95,7 @@ class SqueezeboxConfigFlow(config_entries.ConfigFlow, domain=DOMAIN): self.data_schema = _base_schema(self.discovery_info) async def _validate_input(self, data): - """ - Validate the user input allows us to connect. + """Validate the user input allows us to connect. Retrieve unique id and abort if already configured. """ diff --git a/homeassistant/components/squeezebox/media_player.py b/homeassistant/components/squeezebox/media_player.py index f9d25038674..bd4a7addef2 100644 --- a/homeassistant/components/squeezebox/media_player.py +++ b/homeassistant/components/squeezebox/media_player.py @@ -211,8 +211,7 @@ async def async_setup_entry( class SqueezeBoxEntity(MediaPlayerEntity): - """ - Representation of a SqueezeBox device. + """Representation of a SqueezeBox device. Wraps a pysqueezebox.Player() object. """ @@ -547,8 +546,7 @@ class SqueezeBoxEntity(MediaPlayerEntity): await self._player.async_clear_playlist() async def async_call_method(self, command, parameters=None): - """ - Call Squeezebox JSON/RPC method. + """Call Squeezebox JSON/RPC method. Additional parameters are added to the command to form the list of positional parameters (p0, p1..., pN) passed to JSON/RPC server. @@ -560,8 +558,7 @@ class SqueezeBoxEntity(MediaPlayerEntity): await self._player.async_query(*all_params) async def async_call_query(self, command, parameters=None): - """ - Call Squeezebox JSON/RPC method where we care about the result. + """Call Squeezebox JSON/RPC method where we care about the result. Additional parameters are added to the command to form the list of positional parameters (p0, p1..., pN) passed to JSON/RPC server. @@ -574,8 +571,7 @@ class SqueezeBoxEntity(MediaPlayerEntity): _LOGGER.debug("call_query got result %s", self._query_result) async def async_join_players(self, group_members: list[str]) -> None: - """ - Add other Squeezebox players to this player's sync group. + """Add other Squeezebox players to this player's sync group. If the other player is a member of a sync group, it will leave the current sync group without asking. diff --git a/homeassistant/components/stream/__init__.py b/homeassistant/components/stream/__init__.py index 6073494ae1a..63269401a40 100644 --- a/homeassistant/components/stream/__init__.py +++ b/homeassistant/components/stream/__init__.py @@ -538,8 +538,7 @@ class Stream: width: int | None = None, height: int | None = None, ) -> bytes | None: - """ - Fetch an image from the Stream and return it as a jpeg in bytes. + """Fetch an image from the Stream and return it as a jpeg in bytes. Calls async_get_image from KeyFrameConverter. async_get_image should only be called directly from the main loop and not from an executor thread as it uses diff --git a/homeassistant/components/stream/core.py b/homeassistant/components/stream/core.py index a499d0cc114..ed61342657e 100644 --- a/homeassistant/components/stream/core.py +++ b/homeassistant/components/stream/core.py @@ -366,8 +366,7 @@ class StreamOutput: class StreamView(HomeAssistantView): - """ - Base StreamView. + """Base StreamView. For implementation of a new stream format, define `url` and `name` attributes, and implement `handle` method in a child class. @@ -415,8 +414,7 @@ TRANSFORM_IMAGE_FUNCTION = ( class KeyFrameConverter: - """ - Enables generating and getting an image from the last keyframe seen in the stream. + """Enables generating and getting an image from the last keyframe seen in the stream. An overview of the thread and state interaction: the worker thread sets a packet @@ -450,8 +448,7 @@ class KeyFrameConverter: self._dynamic_stream_settings = dynamic_stream_settings def create_codec_context(self, codec_context: CodecContext) -> None: - """ - Create a codec context to be used for decoding the keyframes. + """Create a codec context to be used for decoding the keyframes. This is run by the worker thread and will only be called once per worker. """ @@ -474,8 +471,7 @@ class KeyFrameConverter: return TRANSFORM_IMAGE_FUNCTION[orientation](image) def _generate_image(self, width: int | None, height: int | None) -> None: - """ - Generate the keyframe image. + """Generate the keyframe image. This is run in an executor thread, but since it is called within an the asyncio lock from the main thread, there will only be one entry diff --git a/homeassistant/components/subaru/__init__.py b/homeassistant/components/subaru/__init__.py index 4829cf72087..3e72b079adf 100644 --- a/homeassistant/components/subaru/__init__.py +++ b/homeassistant/components/subaru/__init__.py @@ -106,8 +106,7 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool: async def refresh_subaru_data(config_entry, vehicle_info, controller): - """ - Refresh local data with data fetched via Subaru API. + """Refresh local data with data fetched via Subaru API. Subaru API calls assume a server side vehicle context Data fetch/update must be done for each vehicle diff --git a/homeassistant/components/subaru/lock.py b/homeassistant/components/subaru/lock.py index bf9d1a8793b..0e57373625a 100644 --- a/homeassistant/components/subaru/lock.py +++ b/homeassistant/components/subaru/lock.py @@ -53,8 +53,7 @@ async def async_setup_entry( class SubaruLock(LockEntity): - """ - Representation of a Subaru door lock. + """Representation of a Subaru door lock. Note that the Subaru API currently does not support returning the status of the locks. Lock status is always unknown. """ diff --git a/homeassistant/components/supla/__init__.py b/homeassistant/components/supla/__init__.py index 02818ccf8d6..72956228948 100644 --- a/homeassistant/components/supla/__init__.py +++ b/homeassistant/components/supla/__init__.py @@ -92,8 +92,7 @@ async def async_setup(hass: HomeAssistant, base_config: ConfigType) -> bool: async def discover_devices(hass, hass_config): - """ - Run periodically to discover new devices. + """Run periodically to discover new devices. Currently it is only run at startup. """ @@ -195,8 +194,7 @@ class SuplaChannel(CoordinatorEntity): return state.get("connected") async def async_action(self, action, **add_pars): - """ - Run server action. + """Run server action. Actions are currently hardcoded in components. Supla's API enables autodiscovery diff --git a/homeassistant/components/syncthru/sensor.py b/homeassistant/components/syncthru/sensor.py index 58f1a5c2b3a..2ec6deccf85 100644 --- a/homeassistant/components/syncthru/sensor.py +++ b/homeassistant/components/syncthru/sensor.py @@ -103,8 +103,7 @@ class SyncThruSensor(CoordinatorEntity[DataUpdateCoordinator[SyncThru]], SensorE class SyncThruMainSensor(SyncThruSensor): - """ - Implementation of the main sensor, conducting the actual polling. + """Implementation of the main sensor, conducting the actual polling. It also shows the detailed state and presents the displayed current status message. diff --git a/homeassistant/components/tado/device_tracker.py b/homeassistant/components/tado/device_tracker.py index 6d6a17b2b16..72eb9c8e289 100644 --- a/homeassistant/components/tado/device_tracker.py +++ b/homeassistant/components/tado/device_tracker.py @@ -95,8 +95,7 @@ class TadoDeviceScanner(DeviceScanner): @Throttle(MIN_TIME_BETWEEN_SCANS) async def _async_update_info(self): - """ - Query Tado for device marked as at home. + """Query Tado for device marked as at home. Returns boolean if scanning successful. """ diff --git a/homeassistant/components/telegram_bot/polling.py b/homeassistant/components/telegram_bot/polling.py index 762ba08ab26..69bb4dc4963 100644 --- a/homeassistant/components/telegram_bot/polling.py +++ b/homeassistant/components/telegram_bot/polling.py @@ -35,8 +35,7 @@ def process_error(update: Update, context: CallbackContext) -> None: class PollBot(BaseTelegramBotEntity): - """ - Controls the Updater object that holds the bot and a dispatcher. + """Controls the Updater object that holds the bot and a dispatcher. The dispatcher is set up by the super class to pass telegram updates to `self.handle_update` """ diff --git a/homeassistant/components/temper/sensor.py b/homeassistant/components/temper/sensor.py index 3b79ed62237..20ad3102a4b 100644 --- a/homeassistant/components/temper/sensor.py +++ b/homeassistant/components/temper/sensor.py @@ -60,8 +60,7 @@ def setup_platform( def reset_devices(): - """ - Re-scan for underlying Temper sensors and assign them to our devices. + """Re-scan for underlying Temper sensors and assign them to our devices. This assumes the same sensor devices are present in the same order. """ diff --git a/homeassistant/components/thermoworks_smoke/sensor.py b/homeassistant/components/thermoworks_smoke/sensor.py index d5621c661d2..fbbfdef6f02 100644 --- a/homeassistant/components/thermoworks_smoke/sensor.py +++ b/homeassistant/components/thermoworks_smoke/sensor.py @@ -1,5 +1,4 @@ -""" -Support for getting the state of a Thermoworks Smoke Thermometer. +"""Support for getting the state of a Thermoworks Smoke Thermometer. Requires Smoke Gateway Wifi with an internet connection. """ diff --git a/homeassistant/components/tile/__init__.py b/homeassistant/components/tile/__init__.py index 3b00ea8421b..29754ffba4b 100644 --- a/homeassistant/components/tile/__init__.py +++ b/homeassistant/components/tile/__init__.py @@ -42,8 +42,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool: @callback def async_migrate_callback(entity_entry: RegistryEntry) -> dict | None: - """ - Define a callback to migrate appropriate Tile entities to new unique IDs. + """Define a callback to migrate appropriate Tile entities to new unique IDs. Old: tile_{uuid} New: {username}_{uuid} diff --git a/homeassistant/components/todoist/calendar.py b/homeassistant/components/todoist/calendar.py index 3e7026970e6..0a822d0515d 100644 --- a/homeassistant/components/todoist/calendar.py +++ b/homeassistant/components/todoist/calendar.py @@ -350,8 +350,7 @@ class TodoistProjectEntity(CalendarEntity): class TodoistProjectData: - """ - Class used by the Task Entity service object to hold all Todoist Tasks. + """Class used by the Task Entity service object to hold all Todoist Tasks. This is analogous to the GoogleCalendarData found in the Google Calendar component. @@ -440,8 +439,7 @@ class TodoistProjectData: ) def create_todoist_task(self, data: Task): - """ - Create a dictionary based on a Task passed from the Todoist API. + """Create a dictionary based on a Task passed from the Todoist API. Will return 'None' if the task is to be filtered out. """ @@ -516,8 +514,7 @@ class TodoistProjectData: @staticmethod def select_best_task(project_tasks: list[TodoistEvent]) -> TodoistEvent: - """ - Search through a list of events for the "best" event to select. + """Search through a list of events for the "best" event to select. The "best" event is determined by the following criteria: * A proposed event must not be completed diff --git a/homeassistant/components/tomorrowio/__init__.py b/homeassistant/components/tomorrowio/__init__.py index bf43b0aa10d..b8a1ba64423 100644 --- a/homeassistant/components/tomorrowio/__init__.py +++ b/homeassistant/components/tomorrowio/__init__.py @@ -223,8 +223,7 @@ class TomorrowioDataUpdateCoordinator(DataUpdateCoordinator[dict[str, Any]]): self._schedule_refresh() async def async_unload_entry(self, entry: ConfigEntry) -> bool | None: - """ - Unload a config entry from coordinator. + """Unload a config entry from coordinator. Returns whether coordinator can be removed as well because there are no config entries tied to it anymore. @@ -341,8 +340,7 @@ class TomorrowioEntity(CoordinatorEntity[TomorrowioDataUpdateCoordinator]): ) def _get_current_property(self, property_name: str) -> int | str | float | None: - """ - Get property from current conditions. + """Get property from current conditions. Used for V4 API. """ diff --git a/homeassistant/components/tomorrowio/config_flow.py b/homeassistant/components/tomorrowio/config_flow.py index 9f512dde4cb..cdb0032431c 100644 --- a/homeassistant/components/tomorrowio/config_flow.py +++ b/homeassistant/components/tomorrowio/config_flow.py @@ -44,8 +44,7 @@ def _get_config_schema( source: str | None, input_dict: dict[str, Any] | None = None, ) -> vol.Schema: - """ - Return schema defaults for init step based on user input/config dict. + """Return schema defaults for init step based on user input/config dict. Retain info already provided for future form views by setting them as defaults in schema. diff --git a/homeassistant/components/tradfri/base_class.py b/homeassistant/components/tradfri/base_class.py index a2b7304cc3e..5a84ad5719c 100644 --- a/homeassistant/components/tradfri/base_class.py +++ b/homeassistant/components/tradfri/base_class.py @@ -63,8 +63,7 @@ class TradfriBaseEntity(CoordinatorEntity[TradfriDeviceDataUpdateCoordinator]): @callback def _handle_coordinator_update(self) -> None: - """ - Handle updated data from the coordinator. + """Handle updated data from the coordinator. Tests fails without this method. """ diff --git a/homeassistant/components/tradfri/fan.py b/homeassistant/components/tradfri/fan.py index 0924da11259..d6bb91a4979 100644 --- a/homeassistant/components/tradfri/fan.py +++ b/homeassistant/components/tradfri/fan.py @@ -78,8 +78,7 @@ class TradfriAirPurifierFan(TradfriBaseEntity, FanEntity): @property def speed_count(self) -> int: - """ - Return the number of speeds the fan supports. + """Return the number of speeds the fan supports. These are the steps: 0 = Off diff --git a/homeassistant/components/ubus/device_tracker.py b/homeassistant/components/ubus/device_tracker.py index 3c4c9fe1b9c..1c16d997d4b 100644 --- a/homeassistant/components/ubus/device_tracker.py +++ b/homeassistant/components/ubus/device_tracker.py @@ -68,8 +68,7 @@ def _refresh_on_access_denied(func): class UbusDeviceScanner(DeviceScanner): - """ - This class queries a wireless router running OpenWrt firmware. + """This class queries a wireless router running OpenWrt firmware. Adapted from Tomato scanner. """ diff --git a/homeassistant/components/uk_transport/sensor.py b/homeassistant/components/uk_transport/sensor.py index d98f9d5011c..3412a004167 100644 --- a/homeassistant/components/uk_transport/sensor.py +++ b/homeassistant/components/uk_transport/sensor.py @@ -97,8 +97,7 @@ def setup_platform( class UkTransportSensor(SensorEntity): - """ - Sensor that reads the UK transport web API. + """Sensor that reads the UK transport web API. transportapi.com provides comprehensive transport data for UK train, tube and bus travel across the UK via simple JSON API. Subclasses of this diff --git a/homeassistant/components/unifiprotect/data.py b/homeassistant/components/unifiprotect/data.py index 518eb623ca1..68d48003ba6 100644 --- a/homeassistant/components/unifiprotect/data.py +++ b/homeassistant/components/unifiprotect/data.py @@ -149,8 +149,7 @@ class ProtectData: @callback def async_add_pending_camera_id(self, camera_id: str) -> None: - """ - Add pending camera. + """Add pending camera. A "pending camera" is one that has been adopted by not had its camera channels initialized yet. Will cause Websocket code to check for channels to be diff --git a/homeassistant/components/unifiprotect/migrate.py b/homeassistant/components/unifiprotect/migrate.py index 308e9903f89..db1e82d9914 100644 --- a/homeassistant/components/unifiprotect/migrate.py +++ b/homeassistant/components/unifiprotect/migrate.py @@ -45,8 +45,7 @@ async def async_get_bootstrap(protect: ProtectApiClient) -> Bootstrap: async def async_migrate_buttons( hass: HomeAssistant, entry: ConfigEntry, protect: ProtectApiClient ) -> None: - """ - Migrate existing Reboot button unique IDs from {device_id} to {deivce_id}_reboot. + """Migrate existing Reboot button unique IDs from {device_id} to {deivce_id}_reboot. This allows for additional types of buttons that are outside of just a reboot button. @@ -97,8 +96,7 @@ async def async_migrate_buttons( async def async_migrate_device_ids( hass: HomeAssistant, entry: ConfigEntry, protect: ProtectApiClient ) -> None: - """ - Migrate unique IDs from {device_id}_{name} format to {mac}_{name} format. + """Migrate unique IDs from {device_id}_{name} format to {mac}_{name} format. This makes devices persist better with in HA. Anything a device is unadopted/readopted or the Protect instance has to rebuild the disk array, the device IDs of Protect devices diff --git a/homeassistant/components/universal/media_player.py b/homeassistant/components/universal/media_player.py index 4f0e17cac9b..c7cc0dd098d 100644 --- a/homeassistant/components/universal/media_player.py +++ b/homeassistant/components/universal/media_player.py @@ -354,8 +354,7 @@ class UniversalMediaPlayer(MediaPlayerEntity): @property def entity_picture(self): - """ - Return image of the media playing. + """Return image of the media playing. The universal media player doesn't use the parent class logic, since the url is coming from child entity pictures which have already been diff --git a/homeassistant/components/vallox/fan.py b/homeassistant/components/vallox/fan.py index 50c30927fde..34eee944114 100644 --- a/homeassistant/components/vallox/fan.py +++ b/homeassistant/components/vallox/fan.py @@ -196,8 +196,7 @@ class ValloxFanEntity(ValloxEntity, FanEntity): return True async def _async_set_preset_mode_internal(self, preset_mode: str) -> bool: - """ - Set new preset mode. + """Set new preset mode. Returns true if the mode has been changed, false otherwise. """ @@ -221,8 +220,7 @@ class ValloxFanEntity(ValloxEntity, FanEntity): return True async def _async_set_percentage_internal(self, percentage: int) -> bool: - """ - Set fan speed percentage for current profile. + """Set fan speed percentage for current profile. Returns true if speed has been changed, false otherwise. """ diff --git a/homeassistant/components/vera/cover.py b/homeassistant/components/vera/cover.py index 5baf495b5fd..25b345b7e31 100644 --- a/homeassistant/components/vera/cover.py +++ b/homeassistant/components/vera/cover.py @@ -43,8 +43,7 @@ class VeraCover(VeraDevice[veraApi.VeraCurtain], CoverEntity): @property def current_cover_position(self) -> int: - """ - Return current position of cover. + """Return current position of cover. 0 is closed, 100 is fully open. """ diff --git a/homeassistant/components/vizio/config_flow.py b/homeassistant/components/vizio/config_flow.py index 4b49d7feed5..014cd3cab0f 100644 --- a/homeassistant/components/vizio/config_flow.py +++ b/homeassistant/components/vizio/config_flow.py @@ -50,8 +50,7 @@ _LOGGER = logging.getLogger(__name__) def _get_config_schema(input_dict: dict[str, Any] | None = None) -> vol.Schema: - """ - Return schema defaults for init step based on user input/config dict. + """Return schema defaults for init step based on user input/config dict. Retain info already provided for future form views by setting them as defaults in schema. @@ -82,8 +81,7 @@ def _get_config_schema(input_dict: dict[str, Any] | None = None) -> vol.Schema: def _get_pairing_schema(input_dict: dict[str, Any] | None = None) -> vol.Schema: - """ - Return schema defaults for pairing data based on user input. + """Return schema defaults for pairing data based on user input. Retain info already provided for future form views by setting them as defaults in schema. @@ -390,8 +388,7 @@ class VizioConfigFlow(config_entries.ConfigFlow, domain=DOMAIN): async def async_step_pair_tv( self, user_input: dict[str, Any] | None = None ) -> FlowResult: - """ - Start pairing process for TV. + """Start pairing process for TV. Ask user for PIN to complete pairing process. """ @@ -470,8 +467,7 @@ class VizioConfigFlow(config_entries.ConfigFlow, domain=DOMAIN): async def async_step_pairing_complete( self, user_input: dict[str, Any] | None = None ) -> FlowResult: - """ - Complete non-import sourced config flow. + """Complete non-import sourced config flow. Display final message to user confirming pairing. """ @@ -480,8 +476,7 @@ class VizioConfigFlow(config_entries.ConfigFlow, domain=DOMAIN): async def async_step_pairing_complete_import( self, user_input: dict[str, Any] | None = None ) -> FlowResult: - """ - Complete import sourced config flow. + """Complete import sourced config flow. Display final message to user confirming pairing and displaying access token. diff --git a/homeassistant/components/volumio/media_player.py b/homeassistant/components/volumio/media_player.py index befe90e1cf4..1d586198c5a 100644 --- a/homeassistant/components/volumio/media_player.py +++ b/homeassistant/components/volumio/media_player.py @@ -1,5 +1,4 @@ -""" -Volumio Platform. +"""Volumio Platform. Volumio rest API: https://volumio.github.io/docs/API/REST_API.html """ diff --git a/homeassistant/components/webostv/helpers.py b/homeassistant/components/webostv/helpers.py index 1de1070a2f1..b61e4af3e6b 100644 --- a/homeassistant/components/webostv/helpers.py +++ b/homeassistant/components/webostv/helpers.py @@ -15,8 +15,7 @@ from .const import DATA_CONFIG_ENTRY, DOMAIN, LIVE_TV_APP_ID, WEBOSTV_EXCEPTIONS def async_get_device_entry_by_device_id( hass: HomeAssistant, device_id: str ) -> DeviceEntry: - """ - Get Device Entry from Device Registry by device ID. + """Get Device Entry from Device Registry by device ID. Raises ValueError if device ID is invalid. """ @@ -29,8 +28,7 @@ def async_get_device_entry_by_device_id( @callback def async_get_device_id_from_entity_id(hass: HomeAssistant, entity_id: str) -> str: - """ - Get device ID from an entity ID. + """Get device ID from an entity ID. Raises ValueError if entity or device ID is invalid. """ @@ -51,8 +49,7 @@ def async_get_device_id_from_entity_id(hass: HomeAssistant, entity_id: str) -> s def async_get_client_by_device_entry( hass: HomeAssistant, device: DeviceEntry ) -> WebOsClient: - """ - Get WebOsClient from Device Registry by device entry. + """Get WebOsClient from Device Registry by device entry. Raises ValueError if client is not found. """ diff --git a/homeassistant/components/withings/__init__.py b/homeassistant/components/withings/__init__.py index 8220bb547c9..94aaa9aa5a6 100644 --- a/homeassistant/components/withings/__init__.py +++ b/homeassistant/components/withings/__init__.py @@ -1,5 +1,4 @@ -""" -Support for the Withings API. +"""Support for the Withings API. For more details about this platform, please refer to the documentation at """ diff --git a/homeassistant/components/wolflink/__init__.py b/homeassistant/components/wolflink/__init__.py index 290e7337617..34df0176e29 100644 --- a/homeassistant/components/wolflink/__init__.py +++ b/homeassistant/components/wolflink/__init__.py @@ -121,8 +121,7 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool: async def fetch_parameters(client: WolfClient, gateway_id: int, device_id: int): - """ - Fetch all available parameters with usage of WolfClient. + """Fetch all available parameters with usage of WolfClient. By default Reglertyp entity is removed because API will not provide value for this parameter. """ diff --git a/homeassistant/components/wsdot/sensor.py b/homeassistant/components/wsdot/sensor.py index b36f598624d..d9df2b7abaf 100644 --- a/homeassistant/components/wsdot/sensor.py +++ b/homeassistant/components/wsdot/sensor.py @@ -68,8 +68,7 @@ def setup_platform( class WashingtonStateTransportSensor(SensorEntity): - """ - Sensor that reads the WSDOT web API. + """Sensor that reads the WSDOT web API. WSDOT provides ferry schedules, toll rates, weather conditions, mountain pass conditions, and more. Subclasses of this diff --git a/homeassistant/components/xiaomi_miio/__init__.py b/homeassistant/components/xiaomi_miio/__init__.py index d5d6fbf6e0b..4975edf8748 100644 --- a/homeassistant/components/xiaomi_miio/__init__.py +++ b/homeassistant/components/xiaomi_miio/__init__.py @@ -207,8 +207,7 @@ class VacuumCoordinatorData: @dataclass(init=False, frozen=True) class VacuumCoordinatorDataAttributes: - """ - A class that holds attribute names for VacuumCoordinatorData. + """A class that holds attribute names for VacuumCoordinatorData. These attributes can be used in methods like `getattr` when a generic solutions is needed. diff --git a/homeassistant/components/xiaomi_tv/media_player.py b/homeassistant/components/xiaomi_tv/media_player.py index 5e045d1404a..82444c26f65 100644 --- a/homeassistant/components/xiaomi_tv/media_player.py +++ b/homeassistant/components/xiaomi_tv/media_player.py @@ -75,8 +75,7 @@ class XiaomiTV(MediaPlayerEntity): self._attr_state = MediaPlayerState.OFF def turn_off(self) -> None: - """ - Instruct the TV to turn sleep. + """Instruct the TV to turn sleep. This is done instead of turning off, because the TV won't accept any input when turned off. Thus, the user diff --git a/homeassistant/components/yeelight/device.py b/homeassistant/components/yeelight/device.py index 6737f96c169..1455e168a23 100644 --- a/homeassistant/components/yeelight/device.py +++ b/homeassistant/components/yeelight/device.py @@ -117,8 +117,7 @@ class YeelightDevice: @property def is_nightlight_supported(self) -> bool: - """ - Return true / false if nightlight is supported. + """Return true / false if nightlight is supported. Uses brightness as it appears to be supported in both ceiling and other lights. """ diff --git a/homeassistant/components/yeelight/light.py b/homeassistant/components/yeelight/light.py index da79a1eb2d6..67a69e1aa89 100644 --- a/homeassistant/components/yeelight/light.py +++ b/homeassistant/components/yeelight/light.py @@ -859,8 +859,7 @@ class YeelightGenericLight(YeelightEntity, LightEntity): @_async_cmd async def async_set_scene(self, scene_class, *args): - """ - Set the light directly to the specified state. + """Set the light directly to the specified state. If the light is off, it will first be turned on. """ diff --git a/homeassistant/components/zha/climate.py b/homeassistant/components/zha/climate.py index 05b0528b330..022be309c45 100644 --- a/homeassistant/components/zha/climate.py +++ b/homeassistant/components/zha/climate.py @@ -1,5 +1,4 @@ -""" -Climate on Zigbee Home Automation networks. +"""Climate on Zigbee Home Automation networks. For more details on this platform, please refer to the documentation at https://home-assistant.io/components/zha.climate/ @@ -772,8 +771,7 @@ class StelproFanHeater(Thermostat): }, ) class ZONNSMARTThermostat(Thermostat): - """ - ZONNSMART Thermostat implementation. + """ZONNSMART Thermostat implementation. Notice that this device uses two holiday presets (2: HolidayMode, 3: HolidayModeTemp), but only one of them can be set. diff --git a/homeassistant/components/zha/core/channels/hvac.py b/homeassistant/components/zha/core/channels/hvac.py index 4b4909299b1..4a73a643b75 100644 --- a/homeassistant/components/zha/core/channels/hvac.py +++ b/homeassistant/components/zha/core/channels/hvac.py @@ -1,5 +1,4 @@ -""" -HVAC channels module for Zigbee Home Automation. +"""HVAC channels module for Zigbee Home Automation. For more details about this component, please refer to the documentation at https://home-assistant.io/integrations/zha/ diff --git a/homeassistant/components/zha/core/channels/security.py b/homeassistant/components/zha/core/channels/security.py index a2e9d19818b..d6a338679f0 100644 --- a/homeassistant/components/zha/core/channels/security.py +++ b/homeassistant/components/zha/core/channels/security.py @@ -1,5 +1,4 @@ -""" -Security channels module for Zigbee Home Automation. +"""Security channels module for Zigbee Home Automation. For more details about this component, please refer to the documentation at https://home-assistant.io/integrations/zha/ diff --git a/homeassistant/components/zha/core/helpers.py b/homeassistant/components/zha/core/helpers.py index 34b484cc21d..526af1a7e49 100644 --- a/homeassistant/components/zha/core/helpers.py +++ b/homeassistant/components/zha/core/helpers.py @@ -1,5 +1,4 @@ -""" -Helpers for Zigbee Home Automation. +"""Helpers for Zigbee Home Automation. For more details about this component, please refer to the documentation at https://home-assistant.io/integrations/zha/ diff --git a/homeassistant/components/zwave_js/discovery.py b/homeassistant/components/zwave_js/discovery.py index a30731b1ce8..6f9f1896fba 100644 --- a/homeassistant/components/zwave_js/discovery.py +++ b/homeassistant/components/zwave_js/discovery.py @@ -198,8 +198,7 @@ def get_config_parameter_discovery_schema( property_key_name: set[str | None] | None = None, **kwargs: Any, ) -> ZWaveDiscoverySchema: - """ - Return a discovery schema for a config parameter. + """Return a discovery schema for a config parameter. Supports all keyword arguments to ZWaveValueDiscoverySchema except platform, hint, and primary_value. diff --git a/homeassistant/components/zwave_js/discovery_data_template.py b/homeassistant/components/zwave_js/discovery_data_template.py index 82d2b9ffc44..249a175d4d2 100644 --- a/homeassistant/components/zwave_js/discovery_data_template.py +++ b/homeassistant/components/zwave_js/discovery_data_template.py @@ -225,8 +225,7 @@ class BaseDiscoverySchemaDataTemplate: static_data: Any | None = None def resolve_data(self, value: ZwaveValue) -> Any: - """ - Resolve helper class data for a discovered value. + """Resolve helper class data for a discovered value. Can optionally be implemented by subclasses if input data needs to be transformed once discovered Value is available. @@ -234,16 +233,14 @@ class BaseDiscoverySchemaDataTemplate: return {} def values_to_watch(self, resolved_data: Any) -> Iterable[ZwaveValue | None]: - """ - Return list of all ZwaveValues resolved by helper that should be watched. + """Return list of all ZwaveValues resolved by helper that should be watched. Should be implemented by subclasses only if there are values to watch. """ return [] def value_ids_to_watch(self, resolved_data: Any) -> set[str]: - """ - Return list of all Value IDs resolved by helper that should be watched. + """Return list of all Value IDs resolved by helper that should be watched. Not to be overwritten by subclasses. """ @@ -430,8 +427,7 @@ class FanValueMapping: speeds: list[tuple[int, int]] = field(default_factory=list) def __post_init__(self) -> None: - """ - Validate inputs. + """Validate inputs. These inputs are hardcoded in `discovery.py`, so these checks should only fail due to developer error. @@ -467,8 +463,7 @@ class ConfigurableFanValueMappingDataTemplate( FanValueMappingDataTemplate, ConfigurableFanValueMappingValueMix, ): - """ - Gets fan speeds based on a configuration value. + """Gets fan speeds based on a configuration value. Example: ZWaveDiscoverySchema( @@ -547,8 +542,7 @@ class FixedFanValueMappingDataTemplate( FanValueMappingDataTemplate, FixedFanValueMappingValueMix, ): - """ - Specifies a fixed set of properties for a fan. + """Specifies a fixed set of properties for a fan. Example: ZWaveDiscoverySchema( diff --git a/homeassistant/components/zwave_js/entity.py b/homeassistant/components/zwave_js/entity.py index 53946a07982..2a57257ffbf 100644 --- a/homeassistant/components/zwave_js/entity.py +++ b/homeassistant/components/zwave_js/entity.py @@ -173,8 +173,7 @@ class ZWaveBaseEntity(Entity): @callback def _node_status_alive_or_dead(self, event_data: dict) -> None: - """ - Call when node status changes to alive or dead. + """Call when node status changes to alive or dead. Should not be overridden by subclasses. """ diff --git a/homeassistant/components/zwave_js/fan.py b/homeassistant/components/zwave_js/fan.py index 093f117c6a0..224921b1b78 100644 --- a/homeassistant/components/zwave_js/fan.py +++ b/homeassistant/components/zwave_js/fan.py @@ -285,8 +285,7 @@ class ValueMappingZwaveFan(ZwaveFan): return last_max_speed def zwave_speed_to_percentage(self, zwave_speed: int) -> int | None: - """ - Convert a Zwave speed to a percentage. + """Convert a Zwave speed to a percentage. This method may return None if the device's value mapping doesn't cover the specified Z-Wave speed. diff --git a/homeassistant/components/zwave_js/helpers.py b/homeassistant/components/zwave_js/helpers.py index 792bd4fc1b1..d856e987af7 100644 --- a/homeassistant/components/zwave_js/helpers.py +++ b/homeassistant/components/zwave_js/helpers.py @@ -94,8 +94,7 @@ def value_matches_matcher( @callback def get_value_id_from_unique_id(unique_id: str) -> str | None: - """ - Get the value ID and optional state key from a unique ID. + """Get the value ID and optional state key from a unique ID. Raises ValueError """ @@ -176,8 +175,7 @@ def get_device_id_ext(driver: Driver, node: ZwaveNode) -> tuple[str, str] | None def get_home_and_node_id_from_device_entry( device_entry: dr.DeviceEntry, ) -> tuple[str, int] | None: - """ - Get home ID and node ID for Z-Wave device registry entry. + """Get home ID and node ID for Z-Wave device registry entry. Returns (home_id, node_id) or None if not found. """ @@ -199,8 +197,7 @@ def get_home_and_node_id_from_device_entry( def async_get_node_from_device_id( hass: HomeAssistant, device_id: str, dev_reg: dr.DeviceRegistry | None = None ) -> ZwaveNode: - """ - Get node from a device ID. + """Get node from a device ID. Raises ValueError if device is invalid or node can't be found. """ @@ -253,8 +250,7 @@ def async_get_node_from_entity_id( ent_reg: er.EntityRegistry | None = None, dev_reg: dr.DeviceRegistry | None = None, ) -> ZwaveNode: - """ - Get node from an entity ID. + """Get node from an entity ID. Raises ValueError if entity is invalid. """ @@ -319,8 +315,7 @@ def async_get_nodes_from_targets( dev_reg: dr.DeviceRegistry | None = None, logger: logging.Logger = LOGGER, ) -> set[ZwaveNode]: - """ - Get nodes for all targets. + """Get nodes for all targets. Supports entity_id with group expansion, area_id, and device_id. """ diff --git a/homeassistant/components/zwave_js/light.py b/homeassistant/components/zwave_js/light.py index 70434290d54..2746cce456d 100644 --- a/homeassistant/components/zwave_js/light.py +++ b/homeassistant/components/zwave_js/light.py @@ -442,8 +442,7 @@ class ZwaveLight(ZWaveBaseEntity, LightEntity): class ZwaveBlackIsOffLight(ZwaveLight): - """ - Representation of a Z-Wave light where setting the color to black turns it off. + """Representation of a Z-Wave light where setting the color to black turns it off. Currently only supports lights with RGB, no color temperature, and no white channels. """ diff --git a/homeassistant/components/zwave_js/migrate.py b/homeassistant/components/zwave_js/migrate.py index 400c2b3cffe..a01b974854d 100644 --- a/homeassistant/components/zwave_js/migrate.py +++ b/homeassistant/components/zwave_js/migrate.py @@ -34,8 +34,7 @@ class ValueID: @staticmethod def from_unique_id(unique_id: str) -> ValueID: - """ - Get a ValueID from a unique ID. + """Get a ValueID from a unique ID. This also works for Notification CC Binary Sensors which have their own unique ID format. diff --git a/homeassistant/components/zwave_me/config_flow.py b/homeassistant/components/zwave_me/config_flow.py index ea71506fb90..864f849176f 100644 --- a/homeassistant/components/zwave_me/config_flow.py +++ b/homeassistant/components/zwave_me/config_flow.py @@ -86,8 +86,7 @@ class ZWaveMeConfigFlow(config_entries.ConfigFlow, domain=DOMAIN): async def async_step_zeroconf( self, discovery_info: ZeroconfServiceInfo ) -> FlowResult: - """ - Handle a discovered Z-Wave accessory - get url to pass into user step. + """Handle a discovered Z-Wave accessory - get url to pass into user step. This flow is triggered by the discovery component. """ diff --git a/homeassistant/core.py b/homeassistant/core.py index 57b37af3904..ea3a57afe59 100644 --- a/homeassistant/core.py +++ b/homeassistant/core.py @@ -1,5 +1,4 @@ -""" -Core components of Home Assistant. +"""Core components of Home Assistant. Home Assistant is a Home Automation framework for observing the state of entities and react to changes. @@ -1577,8 +1576,7 @@ class ServiceRegistry: service_func: Callable[[ServiceCall], Coroutine[Any, Any, None] | None], schema: vol.Schema | None = None, ) -> None: - """ - Register a service. + """Register a service. Schema is called to coerce and validate the service data. """ @@ -1594,8 +1592,7 @@ class ServiceRegistry: service_func: Callable[[ServiceCall], Coroutine[Any, Any, None] | None], schema: vol.Schema | None = None, ) -> None: - """ - Register a service. + """Register a service. Schema is called to coerce and validate the service data. @@ -1652,8 +1649,7 @@ class ServiceRegistry: limit: float | None = SERVICE_CALL_LIMIT, target: dict[str, Any] | None = None, ) -> bool | None: - """ - Call a service. + """Call a service. See description of async_call for details. """ @@ -1674,8 +1670,7 @@ class ServiceRegistry: limit: float | None = SERVICE_CALL_LIMIT, target: dict[str, Any] | None = None, ) -> bool | None: - """ - Call a service. + """Call a service. Specify blocking=True to wait until service is executed. Waits a maximum of limit, which may be None for no timeout. diff --git a/homeassistant/loader.py b/homeassistant/loader.py index ef44f43f818..433206397f3 100644 --- a/homeassistant/loader.py +++ b/homeassistant/loader.py @@ -1,5 +1,4 @@ -""" -The methods for loading Home Assistant integrations. +"""The methods for loading Home Assistant integrations. This module has quite some complex parts. I have tried to add as much documentation as possible to keep it understandable. @@ -120,8 +119,7 @@ class USBMatcher(USBMatcherRequired, USBMatcherOptional): class Manifest(TypedDict, total=False): - """ - Integration manifest. + """Integration manifest. Note that none of the attributes are marked Optional here. However, some of them may be optional in manifest.json in the sense that they can be omitted diff --git a/homeassistant/util/location.py b/homeassistant/util/location.py index 407ad3881cd..a251aec268e 100644 --- a/homeassistant/util/location.py +++ b/homeassistant/util/location.py @@ -1,5 +1,4 @@ -""" -Module with location helpers. +"""Module with location helpers. detect_location_info and elevation are mocked by default during tests. """ diff --git a/homeassistant/util/logging.py b/homeassistant/util/logging.py index 9bcae1e7c74..1db30a6bdfa 100644 --- a/homeassistant/util/logging.py +++ b/homeassistant/util/logging.py @@ -46,8 +46,7 @@ class HomeAssistantQueueHandler(logging.handlers.QueueHandler): return record def handle(self, record: logging.LogRecord) -> Any: - """ - Conditionally emit the specified logging record. + """Conditionally emit the specified logging record. Depending on which filters have been added to the handler, push the new records onto the backing Queue. @@ -64,8 +63,7 @@ class HomeAssistantQueueHandler(logging.handlers.QueueHandler): return return_value def close(self) -> None: - """ - Tidy up any resources used by the handler. + """Tidy up any resources used by the handler. This adds shutdown of the QueueListener """ @@ -78,8 +76,7 @@ class HomeAssistantQueueHandler(logging.handlers.QueueHandler): @callback def async_activate_log_queue_handler(hass: HomeAssistant) -> None: - """ - Migrate the existing log handlers to use the queue. + """Migrate the existing log handlers to use the queue. This allows us to avoid blocking I/O and formatting messages in the event loop as log messages are written in another thread. diff --git a/pyproject.toml b/pyproject.toml index 04d1188c1de..c2caf3df8bb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -264,7 +264,6 @@ select = [ ignore = [ "D202", # No blank lines allowed after function docstring "D203", # 1 blank line required before class docstring - "D212", # Multi-line docstring summary should start at the first line "D213", # Multi-line docstring summary should start at the second line "D404", # First word of the docstring should not be This "D406", # Section name should end with a newline diff --git a/script/hassfest/manifest.py b/script/hassfest/manifest.py index 6f41b02878c..6774e909140 100644 --- a/script/hassfest/manifest.py +++ b/script/hassfest/manifest.py @@ -298,8 +298,7 @@ CUSTOM_INTEGRATION_MANIFEST_SCHEMA = INTEGRATION_MANIFEST_SCHEMA.extend( def validate_version(integration: Integration) -> None: - """ - Validate the version of the integration. + """Validate the version of the integration. Will be removed when the version key is no longer optional for custom integrations. """ diff --git a/script/hassfest/mypy_config.py b/script/hassfest/mypy_config.py index e6886f2f79f..a97efa10d99 100644 --- a/script/hassfest/mypy_config.py +++ b/script/hassfest/mypy_config.py @@ -92,8 +92,7 @@ def _strict_module_in_ignore_list( def _sort_within_sections(line_iter: Iterable[str]) -> Iterable[str]: - """ - Sort lines within sections. + """Sort lines within sections. Sections are defined as anything not delimited by a blank line or an octothorpe-prefixed comment line. diff --git a/script/lint_and_test.py b/script/lint_and_test.py index fbb837132ee..630e0eb996e 100755 --- a/script/lint_and_test.py +++ b/script/lint_and_test.py @@ -1,6 +1,5 @@ #!/usr/bin/env python3 -""" -Quickly check if branch is up to PR standards. +"""Quickly check if branch is up to PR standards. This is NOT a full CI/linting replacement, only a quick check during development. """ diff --git a/tests/components/bayesian/test_binary_sensor.py b/tests/components/bayesian/test_binary_sensor.py index 8a29ba1036f..66c721bd11f 100644 --- a/tests/components/bayesian/test_binary_sensor.py +++ b/tests/components/bayesian/test_binary_sensor.py @@ -358,8 +358,7 @@ async def test_threshold(hass): async def test_multiple_observations(hass): - """ - Test sensor with multiple observations of same entity. + """Test sensor with multiple observations of same entity. these entries should be labelled as 'multi_state' and negative observations ignored - as the outcome is not known to be binary. Before the merge of #67631 this practice was a common work-around for bayesian's ignoring of negative observations, diff --git a/tests/components/bthome/test_config_flow.py b/tests/components/bthome/test_config_flow.py index 64a298e3460..ee2f28aaf6c 100644 --- a/tests/components/bthome/test_config_flow.py +++ b/tests/components/bthome/test_config_flow.py @@ -164,8 +164,7 @@ async def test_async_step_user_no_devices_found(hass): async def test_async_step_user_no_devices_found_2(hass): - """ - Test setup from service info cache with no devices found. + """Test setup from service info cache with no devices found. This variant tests with a non-BTHome device known to us. """ @@ -532,8 +531,7 @@ async def test_async_step_reauth_wrong_key(hass): async def test_async_step_reauth_abort_early(hass): - """ - Test we can abort the reauth if there is no encryption. + """Test we can abort the reauth if there is no encryption. (This can't currently happen in practice). """ diff --git a/tests/components/denonavr/test_config_flow.py b/tests/components/denonavr/test_config_flow.py index 39127f972fe..140fccc95e4 100644 --- a/tests/components/denonavr/test_config_flow.py +++ b/tests/components/denonavr/test_config_flow.py @@ -69,8 +69,7 @@ def denonavr_connect_fixture(): async def test_config_flow_manual_host_success(hass): - """ - Successful flow manually initialized by the user. + """Successful flow manually initialized by the user. Host specified. """ @@ -99,8 +98,7 @@ async def test_config_flow_manual_host_success(hass): async def test_config_flow_manual_discover_1_success(hass): - """ - Successful flow manually initialized by the user. + """Successful flow manually initialized by the user. Without the host specified and 1 receiver discovered. """ @@ -133,8 +131,7 @@ async def test_config_flow_manual_discover_1_success(hass): async def test_config_flow_manual_discover_2_success(hass): - """ - Successful flow manually initialized by the user. + """Successful flow manually initialized by the user. Without the host specified and 2 receiver discovered. """ @@ -176,8 +173,7 @@ async def test_config_flow_manual_discover_2_success(hass): async def test_config_flow_manual_discover_error(hass): - """ - Failed flow manually initialized by the user. + """Failed flow manually initialized by the user. Without the host specified and no receiver discovered. """ @@ -204,8 +200,7 @@ async def test_config_flow_manual_discover_error(hass): async def test_config_flow_manual_host_no_serial(hass): - """ - Successful flow manually initialized by the user. + """Successful flow manually initialized by the user. Host specified and an error getting the serial number. """ @@ -238,8 +233,7 @@ async def test_config_flow_manual_host_no_serial(hass): async def test_config_flow_manual_host_connection_error(hass): - """ - Failed flow manually initialized by the user. + """Failed flow manually initialized by the user. Host specified and a connection error. """ @@ -268,8 +262,7 @@ async def test_config_flow_manual_host_connection_error(hass): async def test_config_flow_manual_host_no_device_info(hass): - """ - Failed flow manually initialized by the user. + """Failed flow manually initialized by the user. Host specified and no device info (due to receiver power off). """ @@ -331,8 +324,7 @@ async def test_config_flow_ssdp(hass): async def test_config_flow_ssdp_not_denon(hass): - """ - Failed flow initialized by ssdp discovery. + """Failed flow initialized by ssdp discovery. Not supported manufacturer. """ @@ -356,8 +348,7 @@ async def test_config_flow_ssdp_not_denon(hass): async def test_config_flow_ssdp_missing_info(hass): - """ - Failed flow initialized by ssdp discovery. + """Failed flow initialized by ssdp discovery. Missing information. """ @@ -379,8 +370,7 @@ async def test_config_flow_ssdp_missing_info(hass): async def test_config_flow_ssdp_ignored_model(hass): - """ - Failed flow initialized by ssdp discovery. + """Failed flow initialized by ssdp discovery. Model in the ignored models list. """ @@ -443,8 +433,7 @@ async def test_options_flow(hass): async def test_config_flow_manual_host_no_serial_double_config(hass): - """ - Failed flow manually initialized by the user twice. + """Failed flow manually initialized by the user twice. Host specified and an error getting the serial number. """ diff --git a/tests/components/eafm/test_sensor.py b/tests/components/eafm/test_sensor.py index d8d48367a64..4caaf9d78c7 100644 --- a/tests/components/eafm/test_sensor.py +++ b/tests/components/eafm/test_sensor.py @@ -54,8 +54,7 @@ async def async_setup_test_fixture(hass, mock_get_station, initial_value): async def test_reading_measures_not_list(hass, mock_get_station): - """ - Test that a measure can be a dict not a list. + """Test that a measure can be a dict not a list. E.g. https://environment.data.gov.uk/flood-monitoring/id/stations/751110 """ @@ -80,8 +79,7 @@ async def test_reading_measures_not_list(hass, mock_get_station): async def test_reading_no_unit(hass, mock_get_station): - """ - Test that a sensor functions even if its unit is not known. + """Test that a sensor functions even if its unit is not known. E.g. https://environment.data.gov.uk/flood-monitoring/id/stations/L0410 """ @@ -108,8 +106,7 @@ async def test_reading_no_unit(hass, mock_get_station): async def test_ignore_invalid_latest_reading(hass, mock_get_station): - """ - Test that a sensor functions even if its unit is not known. + """Test that a sensor functions even if its unit is not known. E.g. https://environment.data.gov.uk/flood-monitoring/id/stations/L0410 """ diff --git a/tests/components/filter/test_sensor.py b/tests/components/filter/test_sensor.py index 054b4cbc0dc..5ac03aea13d 100644 --- a/tests/components/filter/test_sensor.py +++ b/tests/components/filter/test_sensor.py @@ -359,8 +359,7 @@ async def test_outlier(values: list[State]) -> None: def test_outlier_step(values: list[State]) -> None: - """ - Test step-change handling in outlier. + """Test step-change handling in outlier. Test if outlier filter handles long-running step-changes correctly. It should converge to no longer filter once just over half the diff --git a/tests/components/flux/test_switch.py b/tests/components/flux/test_switch.py index e6d25ef57b1..d79b920db5f 100644 --- a/tests/components/flux/test_switch.py +++ b/tests/components/flux/test_switch.py @@ -591,8 +591,7 @@ async def test_flux_before_sunrise_stop_next_day(hass, enable_custom_integration async def test_flux_after_sunrise_before_sunset_stop_next_day( hass, enable_custom_integrations ): - """ - Test the flux switch after sunrise and before sunset. + """Test the flux switch after sunrise and before sunset. This test has the stop_time on the next day (after midnight). """ diff --git a/tests/components/generic/test_config_flow.py b/tests/components/generic/test_config_flow.py index ba4ff4dbd0c..5617f09a33f 100644 --- a/tests/components/generic/test_config_flow.py +++ b/tests/components/generic/test_config_flow.py @@ -650,8 +650,7 @@ async def test_options_template_error(hass, fakeimgbytes_png, mock_create_stream async def test_slug(hass, caplog): - """ - Test that the slug function generates an error in case of invalid template. + """Test that the slug function generates an error in case of invalid template. Other paths in the slug function are already tested by other tests. """ diff --git a/tests/components/generic_hygrostat/test_humidifier.py b/tests/components/generic_hygrostat/test_humidifier.py index 4b6b9e4bb2a..d93fa605397 100644 --- a/tests/components/generic_hygrostat/test_humidifier.py +++ b/tests/components/generic_hygrostat/test_humidifier.py @@ -1441,8 +1441,7 @@ async def test_no_restore_state(hass): async def test_restore_state_uncoherence_case(hass): - """ - Test restore from a strange state. + """Test restore from a strange state. - Turn the generic hygrostat off - Restart HA and restore state from DB diff --git a/tests/components/generic_thermostat/test_climate.py b/tests/components/generic_thermostat/test_climate.py index 4c1ed8ad8c2..d45c0b248ef 100644 --- a/tests/components/generic_thermostat/test_climate.py +++ b/tests/components/generic_thermostat/test_climate.py @@ -1456,8 +1456,7 @@ async def test_restore_will_turn_off_when_loaded_second(hass): async def test_restore_state_uncoherence_case(hass): - """ - Test restore from a strange state. + """Test restore from a strange state. - Turn the generic thermostat off - Restart HA and restore state from DB diff --git a/tests/components/google_assistant/test_trait.py b/tests/components/google_assistant/test_trait.py index 992865c04f8..b528dc3e2f8 100644 --- a/tests/components/google_assistant/test_trait.py +++ b/tests/components/google_assistant/test_trait.py @@ -1035,8 +1035,7 @@ async def test_temperature_setting_climate_setpoint(hass): async def test_temperature_setting_climate_setpoint_auto(hass): - """ - Test TemperatureSetting trait support for climate domain. + """Test TemperatureSetting trait support for climate domain. Setpoint in auto mode. """ diff --git a/tests/components/homekit_controller/common.py b/tests/components/homekit_controller/common.py index ec30d541a93..8b9216030b1 100644 --- a/tests/components/homekit_controller/common.py +++ b/tests/components/homekit_controller/common.py @@ -78,8 +78,7 @@ class EntityTestInfo: @dataclass class DeviceTriggerInfo: - """ - Describe a automation trigger we expect to be created. + """Describe a automation trigger we expect to be created. We only use these for a stateless characteristic like a doorbell. """ diff --git a/tests/components/homekit_controller/specific_devices/test_aqara_gateway.py b/tests/components/homekit_controller/specific_devices/test_aqara_gateway.py index 7df51316ceb..16953fa1662 100644 --- a/tests/components/homekit_controller/specific_devices/test_aqara_gateway.py +++ b/tests/components/homekit_controller/specific_devices/test_aqara_gateway.py @@ -1,5 +1,4 @@ -""" -Regression tests for Aqara Gateway V3. +"""Regression tests for Aqara Gateway V3. https://github.com/home-assistant/core/issues/20957 """ diff --git a/tests/components/homekit_controller/specific_devices/test_aqara_switch.py b/tests/components/homekit_controller/specific_devices/test_aqara_switch.py index 6472d993974..ec29de885de 100644 --- a/tests/components/homekit_controller/specific_devices/test_aqara_switch.py +++ b/tests/components/homekit_controller/specific_devices/test_aqara_switch.py @@ -1,5 +1,4 @@ -""" -Regression tests for Aqara AR004. +"""Regression tests for Aqara AR004. This device has a non-standard programmable stateless switch service that has a service-label-index despite not being linked to a service-label. diff --git a/tests/components/homekit_controller/specific_devices/test_ecobee3.py b/tests/components/homekit_controller/specific_devices/test_ecobee3.py index 299b8d24a9b..c203883d4ac 100644 --- a/tests/components/homekit_controller/specific_devices/test_ecobee3.py +++ b/tests/components/homekit_controller/specific_devices/test_ecobee3.py @@ -1,5 +1,4 @@ -""" -Regression tests for Ecobee 3. +"""Regression tests for Ecobee 3. https://github.com/home-assistant/core/issues/15336 """ diff --git a/tests/components/homekit_controller/specific_devices/test_ecobee_occupancy.py b/tests/components/homekit_controller/specific_devices/test_ecobee_occupancy.py index 88220279b0c..4018701cfe5 100644 --- a/tests/components/homekit_controller/specific_devices/test_ecobee_occupancy.py +++ b/tests/components/homekit_controller/specific_devices/test_ecobee_occupancy.py @@ -1,5 +1,4 @@ -""" -Regression tests for Ecobee occupancy. +"""Regression tests for Ecobee occupancy. https://github.com/home-assistant/core/issues/31827 """ diff --git a/tests/components/homekit_controller/specific_devices/test_koogeek_ls1.py b/tests/components/homekit_controller/specific_devices/test_koogeek_ls1.py index 2e3102d8f13..fe00898b066 100644 --- a/tests/components/homekit_controller/specific_devices/test_koogeek_ls1.py +++ b/tests/components/homekit_controller/specific_devices/test_koogeek_ls1.py @@ -65,8 +65,7 @@ async def test_koogeek_ls1_setup(hass): @pytest.mark.parametrize("failure_cls", [AccessoryDisconnectedError, EncryptionError]) async def test_recover_from_failure(hass, utcnow, failure_cls): - """ - Test that entity actually recovers from a network connection drop. + """Test that entity actually recovers from a network connection drop. See https://github.com/home-assistant/core/issues/18949 """ diff --git a/tests/components/homekit_controller/specific_devices/test_koogeek_sw2.py b/tests/components/homekit_controller/specific_devices/test_koogeek_sw2.py index 91edf91156a..21c434266ab 100644 --- a/tests/components/homekit_controller/specific_devices/test_koogeek_sw2.py +++ b/tests/components/homekit_controller/specific_devices/test_koogeek_sw2.py @@ -1,5 +1,4 @@ -""" -Make sure that existing Koogeek SW2 is enumerated correctly. +"""Make sure that existing Koogeek SW2 is enumerated correctly. This Koogeek device has a custom power sensor that extra handling. diff --git a/tests/components/homekit_controller/specific_devices/test_lennox_e30.py b/tests/components/homekit_controller/specific_devices/test_lennox_e30.py index fb1c0d183d3..9d37c1d4b7b 100644 --- a/tests/components/homekit_controller/specific_devices/test_lennox_e30.py +++ b/tests/components/homekit_controller/specific_devices/test_lennox_e30.py @@ -1,5 +1,4 @@ -""" -Regression tests for Aqara Gateway V3. +"""Regression tests for Aqara Gateway V3. https://github.com/home-assistant/core/issues/20885 """ diff --git a/tests/components/homekit_controller/specific_devices/test_netamo_doorbell.py b/tests/components/homekit_controller/specific_devices/test_netamo_doorbell.py index 9ff84c45701..0ebd38b9baf 100644 --- a/tests/components/homekit_controller/specific_devices/test_netamo_doorbell.py +++ b/tests/components/homekit_controller/specific_devices/test_netamo_doorbell.py @@ -1,5 +1,4 @@ -""" -Regression tests for Netamo Doorbell. +"""Regression tests for Netamo Doorbell. https://github.com/home-assistant/core/issues/44596 """ diff --git a/tests/components/homekit_controller/specific_devices/test_netamo_smart_co_alarm.py b/tests/components/homekit_controller/specific_devices/test_netamo_smart_co_alarm.py index 3f46ffdc9fa..34f161953e6 100644 --- a/tests/components/homekit_controller/specific_devices/test_netamo_smart_co_alarm.py +++ b/tests/components/homekit_controller/specific_devices/test_netamo_smart_co_alarm.py @@ -1,5 +1,4 @@ -""" -Regression tests for Netamo Smart CO Alarm. +"""Regression tests for Netamo Smart CO Alarm. https://github.com/home-assistant/core/issues/78903 """ diff --git a/tests/components/homekit_controller/specific_devices/test_netatmo_home_coach.py b/tests/components/homekit_controller/specific_devices/test_netatmo_home_coach.py index 5769cc81129..34270cd5559 100644 --- a/tests/components/homekit_controller/specific_devices/test_netatmo_home_coach.py +++ b/tests/components/homekit_controller/specific_devices/test_netatmo_home_coach.py @@ -1,5 +1,4 @@ -""" -Regression tests for Netamo Healthy Home Coach. +"""Regression tests for Netamo Healthy Home Coach. https://github.com/home-assistant/core/issues/73360 """ diff --git a/tests/components/homekit_controller/specific_devices/test_rainmachine_pro_8.py b/tests/components/homekit_controller/specific_devices/test_rainmachine_pro_8.py index c93493f38b5..42696eb0713 100644 --- a/tests/components/homekit_controller/specific_devices/test_rainmachine_pro_8.py +++ b/tests/components/homekit_controller/specific_devices/test_rainmachine_pro_8.py @@ -1,5 +1,4 @@ -""" -Make sure that existing RainMachine support isn't broken. +"""Make sure that existing RainMachine support isn't broken. https://github.com/home-assistant/core/issues/31745 """ diff --git a/tests/components/homekit_controller/specific_devices/test_simpleconnect_fan.py b/tests/components/homekit_controller/specific_devices/test_simpleconnect_fan.py index 9a5edeb45b2..3918f30ecdb 100644 --- a/tests/components/homekit_controller/specific_devices/test_simpleconnect_fan.py +++ b/tests/components/homekit_controller/specific_devices/test_simpleconnect_fan.py @@ -1,5 +1,4 @@ -""" -Test against characteristics captured from a SIMPLEconnect Fan. +"""Test against characteristics captured from a SIMPLEconnect Fan. https://github.com/home-assistant/core/issues/26180 """ diff --git a/tests/components/homekit_controller/specific_devices/test_velux_gateway.py b/tests/components/homekit_controller/specific_devices/test_velux_gateway.py index a82d995d4d1..213a89be7b5 100644 --- a/tests/components/homekit_controller/specific_devices/test_velux_gateway.py +++ b/tests/components/homekit_controller/specific_devices/test_velux_gateway.py @@ -1,5 +1,4 @@ -""" -Test against characteristics captured from a Velux Gateway. +"""Test against characteristics captured from a Velux Gateway. https://github.com/home-assistant/core/issues/44314 """ diff --git a/tests/components/homekit_controller/test_climate.py b/tests/components/homekit_controller/test_climate.py index bf544c5aff4..1d436381027 100644 --- a/tests/components/homekit_controller/test_climate.py +++ b/tests/components/homekit_controller/test_climate.py @@ -761,8 +761,7 @@ async def test_heater_cooler_change_thermostat_state(hass, utcnow): async def test_can_turn_on_after_off(hass, utcnow): - """ - Test that we always force device from inactive to active when setting mode. + """Test that we always force device from inactive to active when setting mode. This is a regression test for #81863. """ diff --git a/tests/components/homekit_controller/test_config_flow.py b/tests/components/homekit_controller/test_config_flow.py index 86af49a96c4..9aab999526d 100644 --- a/tests/components/homekit_controller/test_config_flow.py +++ b/tests/components/homekit_controller/test_config_flow.py @@ -405,8 +405,7 @@ async def test_discovery_does_not_ignore_non_homekit(hass, controller): async def test_discovery_broken_pairing_flag(hass, controller): - """ - There is already a config entry for the pairing and its pairing flag is wrong in zeroconf. + """There is already a config entry for the pairing and its pairing flag is wrong in zeroconf. We have seen this particular implementation error in 2 different devices. """ diff --git a/tests/components/homekit_controller/test_connection.py b/tests/components/homekit_controller/test_connection.py index b853989ab15..d21aedd6cb8 100644 --- a/tests/components/homekit_controller/test_connection.py +++ b/tests/components/homekit_controller/test_connection.py @@ -89,8 +89,7 @@ DEVICE_MIGRATION_TESTS = [ async def test_migrate_device_id_no_serial_skip_if_other_owner( hass: HomeAssistant, variant: DeviceMigrationTest ): - """ - Don't migrate unrelated devices. + """Don't migrate unrelated devices. Create a device registry entry that needs migrate, but belongs to a different config entry. It should be ignored. diff --git a/tests/components/homekit_controller/test_fan.py b/tests/components/homekit_controller/test_fan.py index 855f426da13..59f8d433aeb 100644 --- a/tests/components/homekit_controller/test_fan.py +++ b/tests/components/homekit_controller/test_fan.py @@ -8,8 +8,7 @@ from .common import get_next_aid, setup_test_component def create_fan_service(accessory): - """ - Define fan v1 characteristics as per HAP spec. + """Define fan v1 characteristics as per HAP spec. This service is no longer documented in R2 of the public HAP spec but existing devices out there use it (like the SIMPLEconnect fan) diff --git a/tests/components/homekit_controller/test_media_player.py b/tests/components/homekit_controller/test_media_player.py index 829f28cf341..c953eac1810 100644 --- a/tests/components/homekit_controller/test_media_player.py +++ b/tests/components/homekit_controller/test_media_player.py @@ -12,8 +12,7 @@ from .common import get_next_aid, setup_test_component def create_tv_service(accessory): - """ - Define tv characteristics. + """Define tv characteristics. The TV is not currently documented publicly - this is based on observing really TV's that have HomeKit support. """ diff --git a/tests/components/homematicip_cloud/helper.py b/tests/components/homematicip_cloud/helper.py index 8e9b27d59ba..7b4071e9808 100644 --- a/tests/components/homematicip_cloud/helper.py +++ b/tests/components/homematicip_cloud/helper.py @@ -115,8 +115,7 @@ class HomeFactory: class HomeTemplate(Home): - """ - Home template as builder for home mock. + """Home template as builder for home mock. It is based on the upstream libs home class to generate hmip devices and groups based on the given homematicip_cloud.json. @@ -187,8 +186,7 @@ class HomeTemplate(Home): return self.init_json_state def get_async_home_mock(self): - """ - Create Mock for Async_Home. based on template to be used for testing. + """Create Mock for Async_Home. based on template to be used for testing. It adds collections of mocked devices and groups to the home objects, and sets required attributes. diff --git a/tests/components/influxdb/test_init.py b/tests/components/influxdb/test_init.py index cd3bd283e2b..a31d008fa68 100644 --- a/tests/components/influxdb/test_init.py +++ b/tests/components/influxdb/test_init.py @@ -1658,8 +1658,7 @@ async def test_connection_failure_on_startup( async def test_invalid_inputs_error( hass, caplog, mock_client, config_ext, get_write_api, get_mock_call, test_exception ): - """ - Test the event listener when influx returns invalid inputs on write. + """Test the event listener when influx returns invalid inputs on write. The difference in error handling in this case is that we do not sleep and try again, if an input is invalid it is logged and dropped. diff --git a/tests/components/lutron_caseta/__init__.py b/tests/components/lutron_caseta/__init__.py index 5e3db30ad5b..4e8e2d9a504 100644 --- a/tests/components/lutron_caseta/__init__.py +++ b/tests/components/lutron_caseta/__init__.py @@ -279,8 +279,7 @@ class MockBridge: return self.devices def get_devices_by_domain(self, domain: str) -> list[dict]: - """ - Return a list of devices for the given domain. + """Return a list of devices for the given domain. :param domain: one of 'light', 'switch', 'cover', 'fan' or 'sensor' :returns list of zero or more of the devices @@ -294,16 +293,14 @@ class MockBridge: return self.get_devices_by_types(types) def get_devices_by_type(self, type_: str) -> list[dict]: - """ - Will return all devices of a given device type. + """Will return all devices of a given device type. :param type_: LEAP device type, e.g. WallSwitch """ return [device for device in self.devices.values() if device["type"] == type_] def get_devices_by_types(self, types: list[str]) -> list[dict]: - """ - Will return all devices for a list of given device types. + """Will return all devices for a list of given device types. :param types: list of LEAP device types such as WallSwitch, WallDimmer """ diff --git a/tests/components/mqtt/test_init.py b/tests/components/mqtt/test_init.py index 337407d6c6b..68a653552a1 100644 --- a/tests/components/mqtt/test_init.py +++ b/tests/components/mqtt/test_init.py @@ -1197,8 +1197,7 @@ async def test_subscribe_special_characters( async def test_subscribe_same_topic( hass, mqtt_client_mock, mqtt_mock_entry_no_yaml_config ): - """ - Test subscring to same topic twice and simulate retained messages. + """Test subscring to same topic twice and simulate retained messages. When subscribing to the same topic again, SUBSCRIBE must be sent to the broker again for it to resend any retained messages. diff --git a/tests/components/nanoleaf/test_config_flow.py b/tests/components/nanoleaf/test_config_flow.py index 0a2a262ce6f..a3d0e2852a5 100644 --- a/tests/components/nanoleaf/test_config_flow.py +++ b/tests/components/nanoleaf/test_config_flow.py @@ -345,8 +345,7 @@ async def test_import_discovery_integration( nanoleaf_conf_file: dict[str, dict[str, str]], remove_config: bool, ) -> None: - """ - Test discovery integration import. + """Test discovery integration import. Test with different discovery flow sources and corresponding types. Test with different .nanoleaf_conf files with device_id (>= 2021.4), host (< 2021.4) and combination. diff --git a/tests/components/nest/test_camera_sdm.py b/tests/components/nest/test_camera_sdm.py index 86f05c613ed..052fdc5af0e 100644 --- a/tests/components/nest/test_camera_sdm.py +++ b/tests/components/nest/test_camera_sdm.py @@ -1,5 +1,4 @@ -""" -Test for Nest cameras platform for the Smart Device Management API. +"""Test for Nest cameras platform for the Smart Device Management API. These tests fake out the subscriber/devicemanager, and are not using a real pubsub subscriber. diff --git a/tests/components/nest/test_climate_sdm.py b/tests/components/nest/test_climate_sdm.py index 0c25669963b..748bf091184 100644 --- a/tests/components/nest/test_climate_sdm.py +++ b/tests/components/nest/test_climate_sdm.py @@ -1,5 +1,4 @@ -""" -Test for Nest climate platform for the Smart Device Management API. +"""Test for Nest climate platform for the Smart Device Management API. These tests fake out the subscriber/devicemanager, and are not using a real pubsub subscriber. diff --git a/tests/components/nest/test_init_sdm.py b/tests/components/nest/test_init_sdm.py index d7c82609c60..326d5dc2aef 100644 --- a/tests/components/nest/test_init_sdm.py +++ b/tests/components/nest/test_init_sdm.py @@ -1,5 +1,4 @@ -""" -Test for setup methods for the SDM API. +"""Test for setup methods for the SDM API. The tests fake out the subscriber/devicemanager and simulate setup behavior and failure modes. diff --git a/tests/components/nest/test_sensor_sdm.py b/tests/components/nest/test_sensor_sdm.py index b1dddcd9494..c33b4ebe06e 100644 --- a/tests/components/nest/test_sensor_sdm.py +++ b/tests/components/nest/test_sensor_sdm.py @@ -1,5 +1,4 @@ -""" -Test for Nest sensors platform for the Smart Device Management API. +"""Test for Nest sensors platform for the Smart Device Management API. These tests fake out the subscriber/devicemanager, and are not using a real pubsub subscriber. diff --git a/tests/components/pvpc_hourly_pricing/test_config_flow.py b/tests/components/pvpc_hourly_pricing/test_config_flow.py index 125214066a5..beaeb71c70b 100644 --- a/tests/components/pvpc_hourly_pricing/test_config_flow.py +++ b/tests/components/pvpc_hourly_pricing/test_config_flow.py @@ -23,8 +23,7 @@ _MOCK_TIME_VALID_RESPONSES = datetime(2023, 1, 6, 12, 0, tzinfo=date_util.UTC) async def test_config_flow(hass, pvpc_aioclient_mock: AiohttpClientMocker): - """ - Test config flow for pvpc_hourly_pricing. + """Test config flow for pvpc_hourly_pricing. - Create a new entry with tariff "2.0TD (Ceuta/Melilla)" - Check state and attributes diff --git a/tests/components/rflink/test_binary_sensor.py b/tests/components/rflink/test_binary_sensor.py index d806e51a833..4d37ff8fb8e 100644 --- a/tests/components/rflink/test_binary_sensor.py +++ b/tests/components/rflink/test_binary_sensor.py @@ -1,5 +1,4 @@ -""" -Test for RFlink sensor components. +"""Test for RFlink sensor components. Test setup of rflink sensor component/platform. Verify manual and automatic sensor creation. diff --git a/tests/components/smartthings/test_binary_sensor.py b/tests/components/smartthings/test_binary_sensor.py index b636cffbc2e..3671a0bbb7c 100644 --- a/tests/components/smartthings/test_binary_sensor.py +++ b/tests/components/smartthings/test_binary_sensor.py @@ -1,5 +1,4 @@ -""" -Test for the SmartThings binary_sensor platform. +"""Test for the SmartThings binary_sensor platform. The only mocking required is of the underlying SmartThings API object so real HTTP calls are not initiated during testing. diff --git a/tests/components/smartthings/test_climate.py b/tests/components/smartthings/test_climate.py index 22532139dde..1f952d8ca59 100644 --- a/tests/components/smartthings/test_climate.py +++ b/tests/components/smartthings/test_climate.py @@ -1,5 +1,4 @@ -""" -Test for the SmartThings climate platform. +"""Test for the SmartThings climate platform. The only mocking required is of the underlying SmartThings API object so real HTTP calls are not initiated during testing. diff --git a/tests/components/smartthings/test_cover.py b/tests/components/smartthings/test_cover.py index 1e3b084877a..34461b8319b 100644 --- a/tests/components/smartthings/test_cover.py +++ b/tests/components/smartthings/test_cover.py @@ -1,5 +1,4 @@ -""" -Test for the SmartThings cover platform. +"""Test for the SmartThings cover platform. The only mocking required is of the underlying SmartThings API object so real HTTP calls are not initiated during testing. diff --git a/tests/components/smartthings/test_fan.py b/tests/components/smartthings/test_fan.py index 9bf810b0712..05e73e84744 100644 --- a/tests/components/smartthings/test_fan.py +++ b/tests/components/smartthings/test_fan.py @@ -1,5 +1,4 @@ -""" -Test for the SmartThings fan platform. +"""Test for the SmartThings fan platform. The only mocking required is of the underlying SmartThings API object so real HTTP calls are not initiated during testing. diff --git a/tests/components/smartthings/test_init.py b/tests/components/smartthings/test_init.py index 9987d53a6b2..dedf715db1a 100644 --- a/tests/components/smartthings/test_init.py +++ b/tests/components/smartthings/test_init.py @@ -47,8 +47,7 @@ async def test_migration_creates_new_flow(hass, smartthings_mock, config_entry): async def test_unrecoverable_api_errors_create_new_flow( hass, config_entry, smartthings_mock ): - """ - Test a new config flow is initiated when there are API errors. + """Test a new config flow is initiated when there are API errors. 401 (unauthorized): Occurs when the access token is no longer valid. 403 (forbidden/not found): Occurs when the app or installed app could diff --git a/tests/components/smartthings/test_light.py b/tests/components/smartthings/test_light.py index 4bff370fb60..3593da1250f 100644 --- a/tests/components/smartthings/test_light.py +++ b/tests/components/smartthings/test_light.py @@ -1,5 +1,4 @@ -""" -Test for the SmartThings light platform. +"""Test for the SmartThings light platform. The only mocking required is of the underlying SmartThings API object so real HTTP calls are not initiated during testing. @@ -195,8 +194,7 @@ async def test_turn_on_with_brightness(hass, light_devices): async def test_turn_on_with_minimal_brightness(hass, light_devices): - """ - Test lights set to lowest brightness when converted scale would be zero. + """Test lights set to lowest brightness when converted scale would be zero. SmartThings light brightness is a percentage (0-100), but Home Assistant uses a 0-255 scale. This tests if a really low value (1-2) is passed, we don't diff --git a/tests/components/smartthings/test_lock.py b/tests/components/smartthings/test_lock.py index f1ab6640058..5f1ccf0a570 100644 --- a/tests/components/smartthings/test_lock.py +++ b/tests/components/smartthings/test_lock.py @@ -1,5 +1,4 @@ -""" -Test for the SmartThings lock platform. +"""Test for the SmartThings lock platform. The only mocking required is of the underlying SmartThings API object so real HTTP calls are not initiated during testing. diff --git a/tests/components/smartthings/test_scene.py b/tests/components/smartthings/test_scene.py index ccb47144676..a799f7a1400 100644 --- a/tests/components/smartthings/test_scene.py +++ b/tests/components/smartthings/test_scene.py @@ -1,5 +1,4 @@ -""" -Test for the SmartThings scene platform. +"""Test for the SmartThings scene platform. The only mocking required is of the underlying SmartThings API object so real HTTP calls are not initiated during testing. diff --git a/tests/components/smartthings/test_sensor.py b/tests/components/smartthings/test_sensor.py index a4e89ebe5c7..04379ceef56 100644 --- a/tests/components/smartthings/test_sensor.py +++ b/tests/components/smartthings/test_sensor.py @@ -1,5 +1,4 @@ -""" -Test for the SmartThings sensors platform. +"""Test for the SmartThings sensors platform. The only mocking required is of the underlying SmartThings API object so real HTTP calls are not initiated during testing. diff --git a/tests/components/smartthings/test_switch.py b/tests/components/smartthings/test_switch.py index 77c7f4d2c7e..3308bc93410 100644 --- a/tests/components/smartthings/test_switch.py +++ b/tests/components/smartthings/test_switch.py @@ -1,5 +1,4 @@ -""" -Test for the SmartThings switch platform. +"""Test for the SmartThings switch platform. The only mocking required is of the underlying SmartThings API object so real HTTP calls are not initiated during testing. diff --git a/tests/components/stream/common.py b/tests/components/stream/common.py index ff98d90ea8d..c75525c6061 100644 --- a/tests/components/stream/common.py +++ b/tests/components/stream/common.py @@ -63,8 +63,7 @@ def frame_image_data(frame_i, total_frames): def generate_video(encoder, container_format, duration): - """ - Generate a test video. + """Generate a test video. See: http://docs.mikeboers.com/pyav/develop/cookbook/numpy.html """ diff --git a/tests/components/stream/test_hls.py b/tests/components/stream/test_hls.py index cd4f5796938..e896f382ebb 100644 --- a/tests/components/stream/test_hls.py +++ b/tests/components/stream/test_hls.py @@ -136,8 +136,7 @@ def make_playlist( async def test_hls_stream( hass, setup_component, hls_stream, stream_worker_sync, h264_video ): - """ - Test hls stream. + """Test hls stream. Purposefully not mocking anything here to test full integration with the stream component. @@ -527,8 +526,7 @@ async def test_remove_incomplete_segment_on_exit( async def test_hls_stream_rotate( hass, setup_component, hls_stream, stream_worker_sync, h264_video ): - """ - Test hls stream with rotation applied. + """Test hls stream with rotation applied. Purposefully not mocking anything here to test full integration with the stream component. diff --git a/tests/components/stream/test_ll_hls.py b/tests/components/stream/test_ll_hls.py index 448c3593d68..2771e0dd803 100644 --- a/tests/components/stream/test_ll_hls.py +++ b/tests/components/stream/test_ll_hls.py @@ -115,8 +115,7 @@ def make_hint(segment, part): async def test_ll_hls_stream(hass, hls_stream, stream_worker_sync): - """ - Test hls stream. + """Test hls stream. Purposefully not mocking anything here to test full integration with the stream component. diff --git a/tests/components/stream/test_recorder.py b/tests/components/stream/test_recorder.py index 1e941dd5d81..00bdd80cb11 100644 --- a/tests/components/stream/test_recorder.py +++ b/tests/components/stream/test_recorder.py @@ -199,8 +199,7 @@ async def test_record_stream_audio( expected_audio_streams, h264_mov_video, ): - """ - Test treatment of different audio inputs. + """Test treatment of different audio inputs. Record stream output should have an audio channel when input has a valid codec and audio packets and no audio channel otherwise. diff --git a/tests/components/tradfri/conftest.py b/tests/components/tradfri/conftest.py index 4b41c9cc773..e474765f60a 100644 --- a/tests/components/tradfri/conftest.py +++ b/tests/components/tradfri/conftest.py @@ -78,8 +78,7 @@ def mock_api_factory(mock_api): @pytest.fixture(autouse=True) def setup(request): - """ - Set up patches for pytradfri methods for the fan platform. + """Set up patches for pytradfri methods for the fan platform. This is used in test_fan as well as in test_sensor. """ diff --git a/tests/components/twinkly/test_light.py b/tests/components/twinkly/test_light.py index d5da88cda11..d5b2e4e6848 100644 --- a/tests/components/twinkly/test_light.py +++ b/tests/components/twinkly/test_light.py @@ -289,8 +289,7 @@ async def test_turn_off(hass: HomeAssistant): async def test_update_name(hass: HomeAssistant): - """ - Validate device's name update behavior. + """Validate device's name update behavior. Validate that if device name is changed from the Twinkly app, then the name of the entity is updated and it's also persisted, diff --git a/tests/components/xiaomi_ble/test_config_flow.py b/tests/components/xiaomi_ble/test_config_flow.py index cd6fa42fc49..9d49abf1a00 100644 --- a/tests/components/xiaomi_ble/test_config_flow.py +++ b/tests/components/xiaomi_ble/test_config_flow.py @@ -333,8 +333,7 @@ async def test_async_step_user_no_devices_found(hass): async def test_async_step_user_no_devices_found_2(hass): - """ - Test setup from service info cache with no devices found. + """Test setup from service info cache with no devices found. This variant tests with a non-Xiaomi device known to us. """ @@ -1043,8 +1042,7 @@ async def test_async_step_reauth_v4_wrong_key(hass): async def test_async_step_reauth_abort_early(hass): - """ - Test we can abort the reauth if there is no encryption. + """Test we can abort the reauth if there is no encryption. (This can't currently happen in practice). """ diff --git a/tests/helpers/test_condition.py b/tests/helpers/test_condition.py index 31ca77a0bd1..225982b4140 100644 --- a/tests/helpers/test_condition.py +++ b/tests/helpers/test_condition.py @@ -2141,8 +2141,7 @@ async def assert_automation_condition_trace(hass_ws_client, automation_id, expec async def test_if_action_before_sunrise_no_offset(hass, hass_ws_client, calls): - """ - Test if action was before sunrise. + """Test if action was before sunrise. Before sunrise is true from midnight until sunset, local time. """ @@ -2211,8 +2210,7 @@ async def test_if_action_before_sunrise_no_offset(hass, hass_ws_client, calls): async def test_if_action_after_sunrise_no_offset(hass, hass_ws_client, calls): - """ - Test if action was after sunrise. + """Test if action was after sunrise. After sunrise is true from sunrise until midnight, local time. """ @@ -2281,8 +2279,7 @@ async def test_if_action_after_sunrise_no_offset(hass, hass_ws_client, calls): async def test_if_action_before_sunrise_with_offset(hass, hass_ws_client, calls): - """ - Test if action was before sunrise with offset. + """Test if action was before sunrise with offset. Before sunrise is true from midnight until sunset, local time. """ @@ -2403,8 +2400,7 @@ async def test_if_action_before_sunrise_with_offset(hass, hass_ws_client, calls) async def test_if_action_before_sunset_with_offset(hass, hass_ws_client, calls): - """ - Test if action was before sunset with offset. + """Test if action was before sunset with offset. Before sunset is true from midnight until sunset, local time. """ @@ -2525,8 +2521,7 @@ async def test_if_action_before_sunset_with_offset(hass, hass_ws_client, calls): async def test_if_action_after_sunrise_with_offset(hass, hass_ws_client, calls): - """ - Test if action was after sunrise with offset. + """Test if action was after sunrise with offset. After sunrise is true from sunrise until midnight, local time. """ @@ -2671,8 +2666,7 @@ async def test_if_action_after_sunrise_with_offset(hass, hass_ws_client, calls): async def test_if_action_after_sunset_with_offset(hass, hass_ws_client, calls): - """ - Test if action was after sunset with offset. + """Test if action was after sunset with offset. After sunset is true from sunset until midnight, local time. """ @@ -2745,8 +2739,7 @@ async def test_if_action_after_sunset_with_offset(hass, hass_ws_client, calls): async def test_if_action_after_and_before_during(hass, hass_ws_client, calls): - """ - Test if action was after sunrise and before sunset. + """Test if action was after sunrise and before sunset. This is true from sunrise until sunset. """ @@ -2847,8 +2840,7 @@ async def test_if_action_after_and_before_during(hass, hass_ws_client, calls): async def test_if_action_before_or_after_during(hass, hass_ws_client, calls): - """ - Test if action was before sunrise or after sunset. + """Test if action was before sunrise or after sunset. This is true from midnight until sunrise and from sunset until midnight """ @@ -2969,8 +2961,7 @@ async def test_if_action_before_or_after_during(hass, hass_ws_client, calls): async def test_if_action_before_sunrise_no_offset_kotzebue(hass, hass_ws_client, calls): - """ - Test if action was before sunrise. + """Test if action was before sunrise. Local timezone: Alaska time Location: Kotzebue, which has a very skewed local timezone with sunrise @@ -3045,8 +3036,7 @@ async def test_if_action_before_sunrise_no_offset_kotzebue(hass, hass_ws_client, async def test_if_action_after_sunrise_no_offset_kotzebue(hass, hass_ws_client, calls): - """ - Test if action was after sunrise. + """Test if action was after sunrise. Local timezone: Alaska time Location: Kotzebue, which has a very skewed local timezone with sunrise @@ -3121,8 +3111,7 @@ async def test_if_action_after_sunrise_no_offset_kotzebue(hass, hass_ws_client, async def test_if_action_before_sunset_no_offset_kotzebue(hass, hass_ws_client, calls): - """ - Test if action was before sunrise. + """Test if action was before sunrise. Local timezone: Alaska time Location: Kotzebue, which has a very skewed local timezone with sunrise @@ -3197,8 +3186,7 @@ async def test_if_action_before_sunset_no_offset_kotzebue(hass, hass_ws_client, async def test_if_action_after_sunset_no_offset_kotzebue(hass, hass_ws_client, calls): - """ - Test if action was after sunrise. + """Test if action was after sunrise. Local timezone: Alaska time Location: Kotzebue, which has a very skewed local timezone with sunrise diff --git a/tests/helpers/test_config_validation.py b/tests/helpers/test_config_validation.py index 3b087b6a40b..0e9fe555daf 100644 --- a/tests/helpers/test_config_validation.py +++ b/tests/helpers/test_config_validation.py @@ -751,8 +751,7 @@ def version(monkeypatch): def test_deprecated_with_no_optionals(caplog, schema): - """ - Test deprecation behaves correctly when optional params are None. + """Test deprecation behaves correctly when optional params are None. Expected behavior: - Outputs the appropriate deprecation warning if key is detected @@ -783,8 +782,7 @@ def test_deprecated_with_no_optionals(caplog, schema): def test_deprecated_or_removed_param_and_raise(caplog, schema): - """ - Test removed or deprecation options and fail the config validation by raising an exception. + """Test removed or deprecation options and fail the config validation by raising an exception. Expected behavior: - Outputs the appropriate deprecation or removed from support error if key is detected @@ -823,8 +821,7 @@ def test_deprecated_or_removed_param_and_raise(caplog, schema): def test_deprecated_with_replacement_key(caplog, schema): - """ - Test deprecation behaves correctly when only a replacement key is provided. + """Test deprecation behaves correctly when only a replacement key is provided. Expected behavior: - Outputs the appropriate deprecation warning if key is detected @@ -861,8 +858,7 @@ def test_deprecated_with_replacement_key(caplog, schema): def test_deprecated_with_default(caplog, schema): - """ - Test deprecation behaves correctly with a default value. + """Test deprecation behaves correctly with a default value. This is likely a scenario that would never occur. @@ -890,8 +886,7 @@ def test_deprecated_with_default(caplog, schema): def test_deprecated_with_replacement_key_and_default(caplog, schema): - """ - Test deprecation with a replacement key and default. + """Test deprecation with a replacement key and default. Expected behavior: - Outputs the appropriate deprecation warning if key is detected diff --git a/tests/testing_config/custom_components/test/alarm_control_panel.py b/tests/testing_config/custom_components/test/alarm_control_panel.py index f38bf48fc94..b39c2c71eda 100644 --- a/tests/testing_config/custom_components/test/alarm_control_panel.py +++ b/tests/testing_config/custom_components/test/alarm_control_panel.py @@ -1,5 +1,4 @@ -""" -Provide a mock alarm_control_panel platform. +"""Provide a mock alarm_control_panel platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/binary_sensor.py b/tests/testing_config/custom_components/test/binary_sensor.py index 13a877f7e8c..6deaad22b30 100644 --- a/tests/testing_config/custom_components/test/binary_sensor.py +++ b/tests/testing_config/custom_components/test/binary_sensor.py @@ -1,5 +1,4 @@ -""" -Provide a mock binary sensor platform. +"""Provide a mock binary sensor platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/button.py b/tests/testing_config/custom_components/test/button.py index 471e0f42a39..99c6868f834 100644 --- a/tests/testing_config/custom_components/test/button.py +++ b/tests/testing_config/custom_components/test/button.py @@ -1,5 +1,4 @@ -""" -Provide a mock button platform. +"""Provide a mock button platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/cover.py b/tests/testing_config/custom_components/test/cover.py index 98d59a473b1..51a4a9dc83b 100644 --- a/tests/testing_config/custom_components/test/cover.py +++ b/tests/testing_config/custom_components/test/cover.py @@ -1,5 +1,4 @@ -""" -Provide a mock cover platform. +"""Provide a mock cover platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/light.py b/tests/testing_config/custom_components/test/light.py index 3c78e7acce3..e84e8cbe390 100644 --- a/tests/testing_config/custom_components/test/light.py +++ b/tests/testing_config/custom_components/test/light.py @@ -1,5 +1,4 @@ -""" -Provide a mock light platform. +"""Provide a mock light platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/lock.py b/tests/testing_config/custom_components/test/lock.py index a6ce9e102d5..f98cc3fa671 100644 --- a/tests/testing_config/custom_components/test/lock.py +++ b/tests/testing_config/custom_components/test/lock.py @@ -1,5 +1,4 @@ -""" -Provide a mock lock platform. +"""Provide a mock lock platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/number.py b/tests/testing_config/custom_components/test/number.py index 094698923f4..3d9a7f4a8c7 100644 --- a/tests/testing_config/custom_components/test/number.py +++ b/tests/testing_config/custom_components/test/number.py @@ -1,5 +1,4 @@ -""" -Provide a mock number platform. +"""Provide a mock number platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/remote.py b/tests/testing_config/custom_components/test/remote.py index c6f05b156f3..6c5242a739e 100644 --- a/tests/testing_config/custom_components/test/remote.py +++ b/tests/testing_config/custom_components/test/remote.py @@ -1,5 +1,4 @@ -""" -Provide a mock remote platform. +"""Provide a mock remote platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/select.py b/tests/testing_config/custom_components/test/select.py index 375191983b5..d68b3008a50 100644 --- a/tests/testing_config/custom_components/test/select.py +++ b/tests/testing_config/custom_components/test/select.py @@ -1,5 +1,4 @@ -""" -Provide a mock select platform. +"""Provide a mock select platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/sensor.py b/tests/testing_config/custom_components/test/sensor.py index 2b516dbcc41..6594d9bbfae 100644 --- a/tests/testing_config/custom_components/test/sensor.py +++ b/tests/testing_config/custom_components/test/sensor.py @@ -1,5 +1,4 @@ -""" -Provide a mock sensor platform. +"""Provide a mock sensor platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/switch.py b/tests/testing_config/custom_components/test/switch.py index 7dd1862d88f..6f132b85a3a 100644 --- a/tests/testing_config/custom_components/test/switch.py +++ b/tests/testing_config/custom_components/test/switch.py @@ -1,5 +1,4 @@ -""" -Provide a mock switch platform. +"""Provide a mock switch platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/text.py b/tests/testing_config/custom_components/test/text.py index 1430259e2e8..b113423b4e3 100644 --- a/tests/testing_config/custom_components/test/text.py +++ b/tests/testing_config/custom_components/test/text.py @@ -1,5 +1,4 @@ -""" -Provide a mock text platform. +"""Provide a mock text platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/update.py b/tests/testing_config/custom_components/test/update.py index 1840f076407..5d2292e9249 100644 --- a/tests/testing_config/custom_components/test/update.py +++ b/tests/testing_config/custom_components/test/update.py @@ -1,5 +1,4 @@ -""" -Provide a mock update platform. +"""Provide a mock update platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/testing_config/custom_components/test/weather.py b/tests/testing_config/custom_components/test/weather.py index 23a9569c785..a2977e114e4 100644 --- a/tests/testing_config/custom_components/test/weather.py +++ b/tests/testing_config/custom_components/test/weather.py @@ -1,5 +1,4 @@ -""" -Provide a mock weather platform. +"""Provide a mock weather platform. Call init before using it in your tests to ensure clean test data. """ diff --git a/tests/util/test_color.py b/tests/util/test_color.py index ad4b73274e8..9c85e143d7e 100644 --- a/tests/util/test_color.py +++ b/tests/util/test_color.py @@ -333,8 +333,7 @@ def test_returns_same_value_for_any_two_temperatures_above_40000(): def test_should_return_pure_white_at_6600(): - """ - Function should return red=255, blue=255, green=255 when given 6600K. + """Function should return red=255, blue=255, green=255 when given 6600K. 6600K is considered "pure white" light. This is just a rough estimate because the formula itself is a "best