fix: emit DeprecationWarning on current_state setter

docs/releases/3.1.0.md

@@ -165,4 +165,9 @@ machine instance concurrently. This is now documented in the
   [#601](https://github.com/fgmacedo/python-statemachine/pull/601),
   fixes [#600](https://github.com/fgmacedo/python-statemachine/issues/600).
 
+- `current_state` setter now emits `DeprecationWarning` consistently with the getter.
+  Previously only reading `current_state` triggered the warning; assigning to it was silent.
+  The docstring also now includes a `deprecated` directive for Sphinx autodoc.
+  [#604](https://github.com/fgmacedo/python-statemachine/issues/604).
+
 ## Misc in 3.1.0

statemachine/statemachine.py

@@ -395,8 +395,8 @@ def current_state_value(self, value):
     def current_state(self) -> "State | MutableSet[State]":
         """Get/Set the current :ref:`state`.
 
-        This is a low level API, that can be to assign any valid state
-        completely bypassing all the hooks and validations.
+        .. deprecated:: 3.0.0
+            Use :attr:`configuration` / :attr:`configuration_values` instead.
         """
         warnings.warn(
             """Property `current_state` is deprecated in favor of `configuration`.""",
@@ -406,7 +406,12 @@ def current_state(self) -> "State | MutableSet[State]":
         return self._config.current_state
 
     @current_state.setter
-    def current_state(self, value):  # pragma: no cover
+    def current_state(self, value):
+        warnings.warn(
+            """Property `current_state` is deprecated in favor of `configuration`.""",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.current_state_value = value.value
 
     @property

tests/test_statemachine_compat.py

@@ -356,3 +356,28 @@ class SM(StateMachine):
         sm = SM()
         with pytest.warns(DeprecationWarning, match="current_state"):
             _ = sm.current_state  # noqa: F841
+
+    def test_current_state_setter_emits_warning(self):
+        class SM(StateMachine):
+            s1 = State(initial=True)
+            s2 = State(final=True)
+
+            go = s1.to(s2)
+
+        sm = SM()
+        with pytest.warns(DeprecationWarning, match="current_state"):
+            sm.current_state = sm.s2
+        assert sm.s2 in sm.configuration
+
+    def test_current_state_setter_changes_state(self):
+        class SM(StateMachine):
+            s1 = State(initial=True)
+            s2 = State(final=True)
+
+            go = s1.to(s2)
+
+        sm = SM()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            sm.current_state = sm.s2
+        assert sm.s2 in sm.configuration