refactor: rename module `switchbot_mqtt/_actors/{_base->base}` (cause accessed by outer `switchbot_mqtt` & `switchbot_mqtt._cli`)

switchbot_mqtt/__init__.py

@@ -22,7 +22,7 @@ import typing
 import paho.mqtt.client
 
 from switchbot_mqtt._actors import _ButtonAutomator, _CurtainMotor
-from switchbot_mqtt._actors._base import _MQTTCallbackUserdata
+from switchbot_mqtt._actors.base import _MQTTCallbackUserdata
 
 _LOGGER = logging.getLogger(__name__)
 

switchbot_mqtt/_actors/__init__.py

@@ -23,7 +23,7 @@ import bluepy.btle
 import paho.mqtt.client
 import switchbot
 
-from switchbot_mqtt._actors._base import _MQTTCallbackUserdata, _MQTTControlledActor
+from switchbot_mqtt._actors.base import _MQTTCallbackUserdata, _MQTTControlledActor
 from switchbot_mqtt._utils import (
     _join_mqtt_topic_levels,
     _MQTTTopicLevel,

switchbot_mqtt/_actors/_base.py → switchbot_mqtt/_actors/base.py

@@ -16,6 +16,13 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
+# > Even with __all__ set appropriately, internal interfaces (packages,
+# > modules, classes, functions, attributes or other names) should still be
+# > prefixed with a single leading underscore. An interface is also considered
+# > internal if any containing namespace (package, module or class) is
+# > considered internal.
+# https://peps.python.org/pep-0008/#public-and-internal-interfaces
+
 from __future__ import annotations  # PEP563 (default in python>=3.10)
 
 import abc

switchbot_mqtt/_cli.py

@@ -26,8 +26,8 @@ import warnings
 import switchbot
 
 import switchbot_mqtt
-import switchbot_mqtt._actors._base  # rename {_->}base ?
 from switchbot_mqtt._actors import _ButtonAutomator, _CurtainMotor
+from switchbot_mqtt._actors.base import _MQTTCallbackUserdata
 
 _MQTT_DEFAULT_PORT = 1883
 _MQTT_DEFAULT_TLS_PORT = 8883
@@ -81,35 +81,30 @@ def _main() -> None:
         help="Maximum number of attempts to send a command to a SwitchBot device"
         " (default: %(default)d)",
     )
-    _MQTTCallbackUserdata = (
-        switchbot_mqtt._actors._base._MQTTCallbackUserdata  # pylint: disable=protected-access; internal module & class
-    )
-    mqtt_topic_prefix = _MQTTCallbackUserdata.mqtt_topic_prefix
     argparser.add_argument(
         "--fetch-device-info",
         action="store_true",
         help="Report devices' battery level on topic "
-        # pylint: disable=protected-access; internal
         + _ButtonAutomator.get_mqtt_battery_percentage_topic(
-            prefix=mqtt_topic_prefix, mac_address="MAC_ADDRESS"
+            prefix=_MQTTCallbackUserdata.mqtt_topic_prefix, mac_address="MAC_ADDRESS"
         )
         + " or, respectively,"
         + _CurtainMotor.get_mqtt_battery_percentage_topic(
-            prefix=mqtt_topic_prefix, mac_address="MAC_ADDRESS"
+            prefix=_MQTTCallbackUserdata.mqtt_topic_prefix, mac_address="MAC_ADDRESS"
         )
         + " after every command. Additionally report curtain motors' position on topic "
         + _CurtainMotor.get_mqtt_position_topic(
-            prefix=mqtt_topic_prefix, mac_address="MAC_ADDRESS"
+            prefix=_MQTTCallbackUserdata.mqtt_topic_prefix, mac_address="MAC_ADDRESS"
         )
         + " after executing stop commands."
         " When this option is enabled, the mentioned reports may also be requested"
         " by sending a MQTT message to the topic "
         + _ButtonAutomator.get_mqtt_update_device_info_topic(
-            prefix=mqtt_topic_prefix, mac_address="MAC_ADDRESS"
+            prefix=_MQTTCallbackUserdata.mqtt_topic_prefix, mac_address="MAC_ADDRESS"
         )
         + " or "
         + _CurtainMotor.get_mqtt_update_device_info_topic(
-            prefix=mqtt_topic_prefix, mac_address="MAC_ADDRESS"
+            prefix=_MQTTCallbackUserdata.mqtt_topic_prefix, mac_address="MAC_ADDRESS"
         )
         + ". This option can also be enabled by assigning a non-empty value to the"
         " environment variable FETCH_DEVICE_INFO.",

tests/test_actor_base.py

@@ -22,7 +22,7 @@ import paho.mqtt.client
 import pytest
 import switchbot
 
-import switchbot_mqtt._actors._base
+import switchbot_mqtt._actors.base
 
 # pylint: disable=protected-access
 
@@ -30,13 +30,13 @@ import switchbot_mqtt._actors._base
 def test_abstract() -> None:
     with pytest.raises(TypeError, match=r"\babstract class\b"):
         # pylint: disable=abstract-class-instantiated
-        switchbot_mqtt._actors._base._MQTTControlledActor(  # type: ignore
+        switchbot_mqtt._actors.base._MQTTControlledActor(  # type: ignore
             mac_address="dummy", retry_count=21, password=None
         )
 
 
 def test_execute_command_abstract() -> None:
-    class _ActorMock(switchbot_mqtt._actors._base._MQTTControlledActor):
+    class _ActorMock(switchbot_mqtt._actors.base._MQTTControlledActor):
         def __init__(
             self, mac_address: str, retry_count: int, password: typing.Optional[str]
         ) -> None:

tests/test_actor_base_device_info.py

@@ -25,7 +25,7 @@ import bluepy.btle
 import pytest
 
 from switchbot_mqtt._actors import _ButtonAutomator, _CurtainMotor
-from switchbot_mqtt._actors._base import _MQTTControlledActor
+from switchbot_mqtt._actors.base import _MQTTControlledActor
 
 # pylint: disable=protected-access
 

tests/test_mqtt.py

@@ -27,7 +27,7 @@ from paho.mqtt.client import MQTT_ERR_QUEUE_SIZE, MQTT_ERR_SUCCESS, MQTTMessage,
 import switchbot_mqtt
 import switchbot_mqtt._actors
 from switchbot_mqtt._actors import _ButtonAutomator, _CurtainMotor
-from switchbot_mqtt._actors._base import _MQTTCallbackUserdata, _MQTTControlledActor
+from switchbot_mqtt._actors.base import _MQTTCallbackUserdata, _MQTTControlledActor
 from switchbot_mqtt._utils import _MQTTTopicLevel, _MQTTTopicPlaceholder
 
 # pylint: disable=protected-access
@@ -116,12 +116,12 @@ def test__run(
     ]
     assert len(caplog.record_tuples) == (7 if fetch_device_info else 5)
     assert (
-        "switchbot_mqtt._actors._base",
+        "switchbot_mqtt._actors.base",
         logging.INFO,
         "subscribing to MQTT topic 'homeassistant/switch/switchbot/+/set'",
     ) in caplog.record_tuples
     assert (
-        "switchbot_mqtt._actors._base",
+        "switchbot_mqtt._actors.base",
         logging.INFO,
         "subscribing to MQTT topic 'homeassistant/cover/switchbot-curtain/+/set'",
     ) in caplog.record_tuples
@@ -281,7 +281,7 @@ def test__mqtt_update_device_info_callback(
     )
     assert caplog.record_tuples == [
         (
-            "switchbot_mqtt._actors._base",
+            "switchbot_mqtt._actors.base",
             logging.DEBUG,
             f"received topic={topic.decode()} payload={payload!r}",
         )
@@ -315,11 +315,11 @@ def test__mqtt_update_device_info_callback_ignore_retained(
     execute_command_mock.assert_not_called()
     assert caplog.record_tuples == [
         (
-            "switchbot_mqtt._actors._base",
+            "switchbot_mqtt._actors.base",
             logging.DEBUG,
             "received topic=aa:bb:cc:dd:ee:ff/request payload=b''",
         ),
-        ("switchbot_mqtt._actors._base", logging.INFO, "ignoring retained message"),
+        ("switchbot_mqtt._actors.base", logging.INFO, "ignoring retained message"),
     ]
 
 
@@ -423,7 +423,7 @@ def test__mqtt_command_callback(
     )
     assert caplog.record_tuples == [
         (
-            "switchbot_mqtt._actors._base",
+            "switchbot_mqtt._actors.base",
             logging.DEBUG,
             f"received topic={topic.decode()} payload={payload!r}",
         )
@@ -507,12 +507,12 @@ def test__mqtt_command_callback_unexpected_topic(
     execute_command_mock.assert_not_called()
     assert caplog.record_tuples == [
         (
-            "switchbot_mqtt._actors._base",
+            "switchbot_mqtt._actors.base",
             logging.DEBUG,
             f"received topic={topic.decode()} payload={payload!r}",
         ),
         (
-            "switchbot_mqtt._actors._base",
+            "switchbot_mqtt._actors.base",
             logging.WARNING,
             f"unexpected topic {topic.decode()}",
         ),
@@ -547,12 +547,12 @@ def test__mqtt_command_callback_invalid_mac_address(
     execute_command_mock.assert_not_called()
     assert caplog.record_tuples == [
         (
-            "switchbot_mqtt._actors._base",
+            "switchbot_mqtt._actors.base",
             logging.DEBUG,
             f"received topic={topic.decode()} payload={payload!r}",
         ),
         (
-            "switchbot_mqtt._actors._base",
+            "switchbot_mqtt._actors.base",
             logging.WARNING,
             f"invalid mac address {mac_address}",
         ),
@@ -590,11 +590,11 @@ def test__mqtt_command_callback_ignore_retained(
     execute_command_mock.assert_not_called()
     assert caplog.record_tuples == [
         (
-            "switchbot_mqtt._actors._base",
+            "switchbot_mqtt._actors.base",
             logging.DEBUG,
             f"received topic={topic.decode()} payload={payload!r}",
         ),
-        ("switchbot_mqtt._actors._base", logging.INFO, "ignoring retained message"),
+        ("switchbot_mqtt._actors.base", logging.INFO, "ignoring retained message"),
     ]
 
 
@@ -664,7 +664,7 @@ def test__report_state(
         topic=expected_topic, payload=state, retain=True
     )
     assert caplog.record_tuples[0] == (
-        "switchbot_mqtt._actors._base",
+        "switchbot_mqtt._actors.base",
         logging.DEBUG,
         f"publishing topic={expected_topic} payload={state!r}",
     )
@@ -673,7 +673,7 @@ def test__report_state(
     else:
         assert caplog.record_tuples[1:] == [
             (
-                "switchbot_mqtt._actors._base",
+                "switchbot_mqtt._actors.base",
                 logging.ERROR,
                 f"Failed to publish MQTT message on topic {expected_topic} (rc={return_code})",
             )

tests/test_switchbot_curtain_motor_position.py

@@ -24,7 +24,7 @@ import pytest
 from paho.mqtt.client import MQTTMessage
 
 from switchbot_mqtt._actors import _CurtainMotor
-from switchbot_mqtt._actors._base import _MQTTCallbackUserdata
+from switchbot_mqtt._actors.base import _MQTTCallbackUserdata
 
 # pylint: disable=protected-access
 
@@ -147,7 +147,7 @@ def test__mqtt_set_position_callback_unexpected_topic(
     device_init_mock.assert_not_called()
     assert caplog.record_tuples == [
         (
-            "switchbot_mqtt._actors._base",
+            "switchbot_mqtt._actors.base",
             logging.WARN,
             "unexpected topic switchbot-curtain/aa:bb:cc:dd:ee:ff/position/set",
         ),
@@ -175,7 +175,7 @@ def test__mqtt_set_position_callback_invalid_mac_address(
     device_init_mock.assert_not_called()
     assert caplog.record_tuples == [
         (
-            "switchbot_mqtt._actors._base",
+            "switchbot_mqtt._actors.base",
             logging.WARN,
             "invalid mac address aa:bb:cc:dd:ee",
         ),