Add dev blog about deprecating @bind_hass and hass.components (#2093)

* Add dev blog about deprecating `@bind_hass` and `hass.components`

* Add note about logging

* Clarify that we start removing @bind_hass in core

* Change version

* Add note about manifest.json

* Apply suggestion

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* Update message

* Adjust language

---------

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
Jan-Philipp Benecke 2024-03-04 10:14:47 +01:00 committed by GitHub
parent cdcf0a1fe2
commit a6a6b40cce
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 98 additions and 3 deletions

View File

@ -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'
)
```

View File

@ -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

View File

@ -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)