Rename some constants; improve documentation

JeffLIrion · Sep 7, 2019 · 4483cc6 · 4483cc6
1 parent 3e8d4ca
commit 4483cc6
Show file tree

Hide file tree

Showing 5 changed files with 36 additions and 14 deletions.
diff --git a/Makefile b/Makefile
@@ -4,9 +4,13 @@ release:
 	scripts/git_tag.sh
 	python setup.py sdist bdist_wheel
 	twine upload dist/*
-	
+
 .PHONY: docs
 docs:
 	@cd docs/source && rm -f androidtv*.rst
 	@cd docs && sphinx-apidoc -f -e -o source/ ../androidtv/
 	@cd docs && make html && make html
+
+.PHONY: coverage
+coverage:
+	coverage run --source androidtv setup.py test && coverage html && coverage report
diff --git a/androidtv/basetv.py b/androidtv/basetv.py
@@ -29,7 +29,7 @@ class BaseTV(object):
                                                         {'paused': {'media_session_state': 3, 'wake_lock_size': 1}},
                                                         'standby']}
 
-    The keys are app IDs, and the values are lists of rules that are evaluated in order by the :meth:`_custom_state_detection` method.
+    The keys are app IDs, and the values are lists of rules that are evaluated in order.
 
     :py:const:`~androidtv.constants.VALID_STATES`
 
@@ -1096,6 +1096,21 @@ def volume_down(self, current_volume_level=None):
 def state_detection_rules_validator(rules, exc=KeyError):
     """Validate the rules (i.e., the ``state_detection_rules`` value) for a given app ID (i.e., a key in ``state_detection_rules``).
 
+    For each ``rule`` in ``rules``, this function checks that:
+
+    * ``rule`` is a string or a dictionary
+    * If ``rule`` is a string:
+
+        * Check that ``rule`` is in :py:const:`~androidtv.constants.VALID_STATES` or :py:const:`~androidtv.constants.VALID_STATE_PROPERTIES`
+
+    * If ``rule`` is a dictionary:
+
+        * Check that each key is in :py:const:`~androidtv.constants.VALID_STATES`
+        * Check that each value is a dictionary
+
+            * Check that each key is in :py:const:`~androidtv.constants.VALID_PROPERTIES`
+            * Check that each value is of the right type, according to :py:const:`~androidtv.constants.VALID_PROPERTIES_TYPES`
+
     See :class:`~androidtv.basetv.BaseTV` for more info about the ``state_detection_rules`` parameter.
 
     Parameters
@@ -1137,12 +1152,8 @@ def state_detection_rules_validator(rules, exc=KeyError):
                     if prop not in constants.VALID_PROPERTIES:
                         raise exc("Invalid property '{0}' is not in {1}".format(prop, constants.VALID_PROPERTIES))
 
-                    # The value for the `audio_state` property must be a string
-                    if prop == "audio_state" and not isinstance(value, str):
-                        raise exc("Conditional value for property 'audio_state' must be a string, not {}".format(type(value).__name__))
-
-                    # The value for the `media_session_state` and `wake_lock_size` properties must be an int
-                    if prop != "audio_state" and not isinstance(value, int):
-                        raise exc("Conditional value for property '{0}' must be an int, not {1}".format(prop, type(value).__name__))
+                    # Make sure the value is of the right type
+                    if not isinstance(value, constants.VALID_PROPERTIES_TYPES[prop]):
+                        raise exc("Conditional value for property '{0}' must be of type {1}, not {2}".format(prop, constants.VALID_PROPERTIES_TYPES[prop].__name__, type(value).__name__))
 
     return rules
diff --git a/androidtv/constants.py b/androidtv/constants.py
@@ -224,15 +224,20 @@
 STATE_STOPPED = 'stopped'
 STATE_UNKNOWN = 'unknown'
 
-#: States that are valid (used by the :meth:`~androidtv.basetv.BaseTV._custom_state_detection` method)
+#: States that are valid (used by :func:`~androidtv.basetv.state_detection_rules_validator`)
 VALID_STATES = (STATE_IDLE, STATE_OFF, STATE_PLAYING, STATE_PAUSED, STATE_STANDBY)
 
-#: Properties that can be used to determine the current state
+#: Properties that can be used to determine the current state (used by :func:`~androidtv.basetv.state_detection_rules_validator`)
 VALID_STATE_PROPERTIES = ("audio_state", "media_session_state")
 
-#: Properties that can be checked by the :meth:`~androidtv.basetv.BaseTV._conditions_are_true` method
+#: Properties that can be checked for custom state detection (used by :func:`~androidtv.basetv.state_detection_rules_validator`)
 VALID_PROPERTIES = VALID_STATE_PROPERTIES + ("wake_lock_size",)
 
+#: The required type for each entry in `VALID_PROPERTIES` (used by :func:`~androidtv.basetv.state_detection_rules_validator`)
+VALID_PROPERTIES_TYPES = {"audio_state": str,
+                          "media_session_state": int,
+                          "wake_lock_size": int}
+
 # https://developer.android.com/reference/android/media/session/PlaybackState.html
 #: States for the :attr:`~androidtv.basetv.BaseTV.media_session_state` property
 MEDIA_SESSION_STATES = {0: None,

diff --git a/setup.cfg b/setup.cfg
diff --git a/tests/test_firetv.py b/tests/test_firetv.py
@@ -203,6 +203,10 @@ def test_get_properties(self):
             properties = self.ftv.get_properties_dict(lazy=True, get_running_apps=False)
             self.assertDictEqual(properties, GET_PROPERTIES_DICT3E)
 
+        with patchers.patch_shell(GET_PROPERTIES_OUTPUT3E)[self.PATCH_KEY]:
+            properties = self.ftv.get_properties_dict(lazy=False, get_running_apps=False)
+            self.assertDictEqual(properties, GET_PROPERTIES_DICT3E)
+
         with patchers.patch_shell(GET_PROPERTIES_OUTPUT4)[self.PATCH_KEY]:
             properties = self.ftv.get_properties_dict(lazy=True)
             self.assertDictEqual(properties, GET_PROPERTIES_DICT4)