Add open / opening state to LockEntity (#2100)

* Add open / opening state to LockEntity

* Fix link

* Fix comments

* New date

* Change date

* Change wording

blog/2024-05-10-lock supports open state.md

@@ -0,0 +1,33 @@
+---
+author: G Johansson
+authorURL: https://github.com/gjohansson-ST
+title: "LockEntity supports open/opening state"
+---
+
+Recently we have added a `open` and `opening` state to `LockEntity`
+
+This is useful if you have locks which can differentiate between `unlocked` (not locked but latched) state and `open` (unlocked and latch withdrawn) state.
+
+`LockEntity` already supports the [`open` method](/docs/core/entity/lock#open) by implementing the feature flag `LockEntityFeature.OPEN`
+
+Example (default implementation):
+
+```python
+class MyLock(LockEntity):
+
+    @property
+    def is_opening(self) -> bool:
+        """Return true if lock is open."""
+        return self._state == STATE_OPENING
+
+    @property
+    def is_open(self) -> bool:
+        """Return true if lock is open."""
+        return self._state == STATE_OPEN
+
+    async def async_open(self, **kwargs: Any) -> None:
+        """Open the door latch."""
+        self._state = STATE_OPEN
+        self.async_write_ha_state()
+
+```

docs/core/entity/lock.md

@@ -19,6 +19,8 @@ Properties should always only return information from memory and not do I/O (lik
 | is_locking | bool | None | Indication of whether the lock is currently locking. Used to determine `state`.
 | is_unlocking | bool | None | Indication of whether the lock is currently unlocking. Used to determine `state`.
 | is_jammed | bool | None | Indication of whether the lock is currently jammed. Used to determine `state`.
+| is_opening | bool | None | Indication of whether the lock is currently opening. Used to determine `state`.
+| is_open | bool | None | Indication of whether the lock is currently open. Used to determine `state`.
 
 ## Supported Features