diff --git a/blog/2024-02-27-deprecate-bind-hass-and-hass-components.md b/blog/2024-02-27-deprecate-bind-hass-and-hass-components.md new file mode 100644 index 00000000..0562a609 --- /dev/null +++ b/blog/2024-02-27-deprecate-bind-hass-and-hass-components.md @@ -0,0 +1,93 @@ +--- +author: Jan-Philipp Benecke +authorURL: https://github.com/jpbede +authorImageURL: https://avatars.githubusercontent.com/u/3989428?s=96&v=4 +title: "Deprecate use of @bind_hass and hass.components" +--- + +As of Home Assistant 2024.3, we deprecate the use of the `@bind_hass` decorator +and thus also the use of `hass.components`. +Using `hass.components` will issue a warning in the logs. +Authors of custom integrations are encouraged to update their code +to prevent any issues before Home Assistant 2024.9. + +Starting from Home Assistant 2024.9, the `@bind_hass` decorator and +`hass.components` will be removed and will no longer work. + +## Use of `@bind_hass` decorator + +Integrations that use the `@bind_hass` decorator should be updated to remove them and pass the `hass` object as first parameter to the function instead: + +### New example + +```python +from homeassistant.core import HomeAssistant +from homeassistant.components.persistent_notification import async_create + +def create_notification(hass: HomeAssistant, message: str): + """Create a notification.""" + async_create( + hass, + message, + title='Important notification' + ) + +async def async_setup(hass: HomeAssistant, config): + """Set up the component.""" + create_notification(hass, "You're already using the latest version!") +``` + +### Old example + +```python +from homeassistant.core import HomeAssistant +from homeassistant.loader import bind_hass +from homeassistant.components.persistent_notification import async_create + +@bind_hass +def create_notification(hass: HomeAssistant, message: str): + """Create a notification.""" + async_create( + hass, + message, + title='Important notification' + ) + +async def async_setup(hass: HomeAssistant, config): + """Set up the component.""" + create_notification("You're already using the latest version!") +``` + +## Use of `hass.components` + +Integrations that use `hass.components` should be updated to import the functions and classes directly +from the integration package and pass the `hass` object as first parameter. +Remember to include the imported components under `dependencies` in your `manifest.json`. + +### New example + +```python +from homeassistant.core import HomeAssistant +from homeassistant.components.persistent_notification import async_create + +async def async_setup(hass: HomeAssistant, config): + """Set up the component.""" + async_create( + hass, + "You're already using the latest version!", + title='Important notification' + ) +``` + +### Old example + +```python +from homeassistant.core import HomeAssistant + +async def async_setup(hass: HomeAssistant, config): + """Set up the component.""" + hass.components.persistent_notification.async_create( + "You're already using the latest version!", + title='Important notification' + ) +``` diff --git a/docs/auth_permissions.md b/docs/auth_permissions.md index 29402b49..e76da25c 100644 --- a/docs/auth_permissions.md +++ b/docs/auth_permissions.md @@ -262,7 +262,7 @@ from homeassistant.components import websocket_api async def async_setup(hass, config): - hass.components.websocket_api.async_register_command(websocket_create) + websocket_api.async_register_command(hass, websocket_create) return True diff --git a/docs/frontend/extending/websocket-api.md b/docs/frontend/extending/websocket-api.md index 9a2533fe..b81c8de7 100644 --- a/docs/frontend/extending/websocket-api.md +++ b/docs/frontend/extending/websocket-api.md @@ -81,10 +81,12 @@ async def ws_handle_thumbnail( With all pieces defined, it's time to register the command. This is done inside your setup method. ```python +from homeassistant.components import websocket_api + async def async_setup(hass, config): """Setup of your component.""" - hass.components.websocket_api.async_register_command(ws_get_panels) - hass.components.websocket_api.async_register_command(ws_handle_thumbnail) + websocket_api.async_register_command(hass, ws_get_panels) + websocket_api.async_register_command(hass, ws_handle_thumbnail) ``` ## Calling the command from the frontend (JavaScript)