android-env 1.2.1__py3-none-any.whl → 1.2.3__py3-none-any.whl

android_env/components/device_settings_test.py

@@ -0,0 +1,228 @@
+# coding=utf-8
+# Copyright 2024 DeepMind Technologies Limited.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from unittest import mock
+
+from absl.testing import absltest
+from absl.testing import parameterized
+from android_env.components import config_classes
+from android_env.components import device_settings as device_settings_lib
+from android_env.components.simulators import base_simulator
+import numpy as np
+
+
+class DeviceSettingsTest(parameterized.TestCase):
+
+  def test_screen_size_before_update(self):
+    """The screen size should be 0x0 without calling `update()`."""
+
+    # Arrange.
+    simulator = mock.create_autospec(base_simulator.BaseSimulator)
+    device_settings = device_settings_lib.DeviceSettings(simulator)
+
+    # Act.
+    height = device_settings.screen_height()
+    width = device_settings.screen_width()
+
+    # Assert.
+    self.assertEqual(height, 0)
+    self.assertEqual(width, 0)
+
+  def test_screen_size_after_update(self):
+    """The screen size should be set after calling `update()`."""
+
+    # Arrange.
+    simulator = mock.create_autospec(base_simulator.BaseSimulator)
+    simulator.get_screenshot.return_value = np.random.randint(
+        low=0, high=255, size=(123, 456, 3), dtype=np.uint8
+    )
+    adb_controller = simulator.create_adb_controller.return_value
+    adb_controller.execute_command.return_value = b''
+    device_settings = device_settings_lib.DeviceSettings(simulator)
+
+    # Act.
+    device_settings.update(config_classes.DeviceSettingsConfig())
+    height = device_settings.screen_height()
+    width = device_settings.screen_width()
+
+    # Assert.
+    self.assertEqual(height, 123)
+    self.assertEqual(width, 456)
+
+  @parameterized.named_parameters(
+      (
+          'show_touches',
+          config_classes.DeviceSettingsConfig(show_touches=True),
+          mock.call(
+              ['shell', 'settings', 'put', 'system', 'show_touches', '1'],
+              timeout=None,
+          ),
+      ),
+      (
+          'show_touches_false',
+          config_classes.DeviceSettingsConfig(show_touches=False),
+          mock.call(
+              ['shell', 'settings', 'put', 'system', 'show_touches', '0'],
+              timeout=None,
+          ),
+      ),
+      (
+          'show_pointer_location',
+          config_classes.DeviceSettingsConfig(show_pointer_location=True),
+          mock.call(
+              ['shell', 'settings', 'put', 'system', 'pointer_location', '1'],
+              timeout=None,
+          ),
+      ),
+      (
+          'show_pointer_location_false',
+          config_classes.DeviceSettingsConfig(show_pointer_location=False),
+          mock.call(
+              ['shell', 'settings', 'put', 'system', 'pointer_location', '0'],
+              timeout=None,
+          ),
+      ),
+      (
+          'show_navigation_and_status',
+          config_classes.DeviceSettingsConfig(
+              show_navigation_bar=True, show_status_bar=True
+          ),
+          mock.call(
+              ['shell', 'settings', 'put', 'global', 'policy_control', 'null*'],
+              timeout=None,
+          ),
+      ),
+      (
+          'show_navigation_and_no_status',
+          config_classes.DeviceSettingsConfig(
+              show_navigation_bar=True, show_status_bar=False
+          ),
+          mock.call(
+              [
+                  'shell',
+                  'settings',
+                  'put',
+                  'global',
+                  'policy_control',
+                  'immersive.status=*',
+              ],
+              timeout=None,
+          ),
+      ),
+      (
+          'show_no_navigation_and_status',
+          config_classes.DeviceSettingsConfig(
+              show_navigation_bar=False, show_status_bar=True
+          ),
+          mock.call(
+              [
+                  'shell',
+                  'settings',
+                  'put',
+                  'global',
+                  'policy_control',
+                  'immersive.navigation=*',
+              ],
+              timeout=None,
+          ),
+      ),
+      (
+          'show_no_navigation_and_no_status',
+          config_classes.DeviceSettingsConfig(
+              show_navigation_bar=False, show_status_bar=False
+          ),
+          mock.call(
+              [
+                  'shell',
+                  'settings',
+                  'put',
+                  'global',
+                  'policy_control',
+                  'immersive.full=*',
+              ],
+              timeout=None,
+          ),
+      ),
+  )
+  def test_update(
+      self, settings: config_classes.DeviceSettingsConfig, expected_call
+  ):
+    """We expect the right call for each setting."""
+
+    # Arrange.
+    simulator = mock.create_autospec(base_simulator.BaseSimulator)
+    adb_controller = simulator.create_adb_controller.return_value
+    adb_controller.execute_command.return_value = b''
+    device_settings = device_settings_lib.DeviceSettings(simulator)
+
+    # Act.
+    device_settings.update(settings)
+
+    # Assert.
+    adb_controller.execute_command.assert_has_calls(
+        [expected_call], any_order=True
+    )
+
+  def test_get_orientation_bad_response(self):
+    """The orientation should be unset if the underlying response is bad."""
+
+    # Arrange.
+    simulator = mock.create_autospec(base_simulator.BaseSimulator)
+    adb_controller = simulator.create_adb_controller.return_value
+    adb_controller.execute_command.return_value = b''
+    device_settings = device_settings_lib.DeviceSettings(simulator)
+
+    # Act.
+    orientation = device_settings.get_orientation()
+
+    # Assert.
+    np.testing.assert_array_equal(orientation, np.zeros(4))
+
+  def test_get_orientation_bad_orientation(self):
+    """The orientation should be unset if the underlying orientation is bad."""
+
+    # Arrange.
+    simulator = mock.create_autospec(base_simulator.BaseSimulator)
+    adb_controller = simulator.create_adb_controller.return_value
+    adb_controller.execute_command.return_value = b' InputDeviceOrientation: 9'
+    device_settings = device_settings_lib.DeviceSettings(simulator)
+
+    # Act.
+    orientation = device_settings.get_orientation()
+
+    # Assert.
+    np.testing.assert_array_equal(orientation, np.zeros(4))
+
+  def test_get_orientation_success(self):
+    """Checks that the orientation comes back as expected."""
+
+    # Arrange.
+    simulator = mock.create_autospec(base_simulator.BaseSimulator)
+    adb_controller = simulator.create_adb_controller.return_value
+    adb_controller.execute_command.return_value = b' InputDeviceOrientation: 3'
+    device_settings = device_settings_lib.DeviceSettings(simulator)
+
+    # Act.
+    orientation = device_settings.get_orientation()
+    # The output should be idempotent if the underlying system did not change.
+    orientation_again = device_settings.get_orientation()
+
+    # Assert.
+    np.testing.assert_array_equal(orientation, np.array([0, 0, 0, 1]))
+    np.testing.assert_array_equal(orientation, orientation_again)
+
+
+if __name__ == '__main__':
+  absltest.main()

android_env/components/dumpsys_thread.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-# Copyright 2022 DeepMind Technologies Limited.
+# Copyright 2024 DeepMind Technologies Limited.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,7 +16,6 @@
 """A ThreadFunction that runs and parses adb dumpsys."""
 
 import concurrent.futures
-from typing import Optional
 
 from absl import logging
 from android_env.components import app_screen_checker as app_screen_checker_lib
@@ -56,9 +55,9 @@ class DumpsysThread:
     self._check_frequency = check_frequency
     self._max_failed_activity_extraction = max_failed_current_activity
     self._num_failed_activity_extraction = 0
-    self._latest_check: Optional[concurrent.futures.Future] = None
+    self._latest_check: concurrent.futures.Future | None = None
 
-  def check_user_exited(self, timeout: Optional[float] = None) -> bool:
+  def check_user_exited(self, timeout: float | None = None) -> bool:
     """Returns True if the user is not in the expected screen.
 
     Args:

android_env/components/dumpsys_thread_test.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-# Copyright 2022 DeepMind Technologies Limited.
+# Copyright 2024 DeepMind Technologies Limited.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

android_env/components/errors.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-# Copyright 2022 DeepMind Technologies Limited.
+# Copyright 2024 DeepMind Technologies Limited.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,41 +16,83 @@
 """Definitions of exceptions used by AndroidEnv."""
 
 
-class ReadObservationError(Exception):
+class AndroidEnvError(Exception):
+  """Base class for all known errors generated by AndroidEnv."""
+
+  # An integer that identifies this class of error.
+  # Subclasses should use a different value.
+  ERROR_CODE: int = 0
+
+
+class ReadObservationError(AndroidEnvError):
   """When the environment is unable to obtain an observation from a simulator."""
 
+  ERROR_CODE = 1
+
 
-class CoordinatorError(Exception):
+class CoordinatorError(AndroidEnvError):
   """Error raised by the Coordinator."""
 
+  ERROR_CODE = 2
+
 
 class TooManyRestartsError(CoordinatorError):
   """The number of restarts has exceeded _MAX_RESTART_TRIES."""
 
+  ERROR_CODE = 3
 
-class AdbControllerError(Exception):
-  """Errors that can be raised by ADBController."""
 
+class AdbControllerError(AndroidEnvError):
+  """Errors that can be raised by ADBController."""
 
-class AdbControllerDeviceTimeoutError(AdbControllerError):
-  """Raised when a device takes too long to respond."""
+  ERROR_CODE = 4
 
 
-class SimulatorError(Exception):
+class SimulatorError(AndroidEnvError):
   """Errors that can be raised by a simulator."""
 
+  ERROR_CODE = 5
+
 
-class SendActionError(Exception):
+class SendActionError(AndroidEnvError):
   """Raised when action couldn't be sent successfully."""
 
+  ERROR_CODE = 6
 
-class StepCommandError(Exception):
+
+class StepCommandError(AndroidEnvError):
   """Raised when setup step interpreter cannot process a command."""
 
+  ERROR_CODE = 7
+
 
 class WaitForAppScreenError(StepCommandError):
   """Raised when the wait_for_app_screen success check is not met."""
 
+  ERROR_CODE = 8
+
 
 class CheckInstallError(StepCommandError):
   """Raised when the check_install success check is not met."""
+
+  ERROR_CODE = 9
+
+
+def from_code(code: int, msg: str = '') -> AndroidEnvError | None:
+  """Returns an AndroidEnvError instance from the given arguments."""
+
+  code_to_error = {
+      0: AndroidEnvError,
+      1: ReadObservationError,
+      2: CoordinatorError,
+      3: TooManyRestartsError,
+      4: AdbControllerError,
+      5: SimulatorError,
+      6: SendActionError,
+      7: StepCommandError,
+      8: WaitForAppScreenError,
+      9: CheckInstallError,
+  }
+
+  if code in code_to_error:
+    return code_to_error[code](msg)

android_env/components/errors_test.py

@@ -0,0 +1,110 @@
+# coding=utf-8
+# Copyright 2024 DeepMind Technologies Limited.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tests for errors.py."""
+
+from absl.testing import absltest
+from absl.testing import parameterized
+from android_env.components import errors
+
+
+class ErrorsTest(parameterized.TestCase):
+
+  @parameterized.parameters(
+      (errors.ReadObservationError, 1),
+      (errors.CoordinatorError, 2),
+      (errors.TooManyRestartsError, 3),
+      (errors.AdbControllerError, 4),
+      (errors.SimulatorError, 5),
+      (errors.SendActionError, 6),
+      (errors.StepCommandError, 7),
+      (errors.WaitForAppScreenError, 8),
+      (errors.CheckInstallError, 9),
+  )
+  def test_error_codes(self, error, expected_error_code):
+    with self.assertRaises(error) as context:
+      raise error()
+    self.assertEqual(context.exception.ERROR_CODE, expected_error_code)
+
+  def test_error_codes_unique(self):
+    error_codes = set()
+    errors_list = (
+        errors.ReadObservationError,
+        errors.CoordinatorError,
+        errors.TooManyRestartsError,
+        errors.AdbControllerError,
+        errors.SimulatorError,
+        errors.SendActionError,
+        errors.StepCommandError,
+        errors.WaitForAppScreenError,
+        errors.CheckInstallError,
+    )
+    for error in errors_list:
+      self.assertNotIn(error.ERROR_CODE, error_codes)
+      error_codes.add(error.ERROR_CODE)
+
+  @parameterized.parameters([
+      errors.ReadObservationError(),
+      errors.CoordinatorError(),
+      errors.TooManyRestartsError(),
+      errors.AdbControllerError(),
+      errors.SimulatorError(),
+      errors.SendActionError(),
+      errors.StepCommandError(),
+      errors.WaitForAppScreenError(),
+      errors.CheckInstallError(),
+  ])
+  def test_all_errors_are_androidenv_errors(self, error):
+    self.assertIsInstance(error, errors.AndroidEnvError)
+
+  @parameterized.named_parameters([
+      ('less_than_zero', -1),
+      # The largest `ERROR_CODE` is currently `CheckInstallError == 10`.
+      ('greater_than_all_errors', 10 + 1),
+      ('less_than_zero_float', -3.14159265),
+      ('greater_than_all_errors_float', 123.456),
+  ])
+  def test_from_code_unsupported_code(self, code: int):
+    """Unsupported errors should raise `RuntimeError`."""
+
+    self.assertIsNone(errors.from_code(code))
+
+  @parameterized.parameters([
+      (-1, None, 'No such error code.'),
+      (0, errors.AndroidEnvError, 'hello'),
+      (0, errors.AndroidEnvError, ''),
+      (1, errors.ReadObservationError, 'Could not read obs.'),
+      (2, errors.CoordinatorError, 'Some error'),
+      (3, errors.TooManyRestartsError, 'Too many already...'),
+      (4, errors.AdbControllerError, 'Some adb error...'),
+      (5, errors.SimulatorError, 'Simulator is not coping.'),
+      (6, errors.SendActionError, 'Could not send action.'),
+      (7, errors.StepCommandError, 'Some issue setting up the task.'),
+      (8, errors.WaitForAppScreenError, 'Waited for too long!'),
+      (9, errors.CheckInstallError, 'App did not install correctly.'),
+  ])
+  def test_from_code(self, code: int, expected_class: errors.AndroidEnvError,
+                     msg: str):
+    """`from_code` should produce consistent outputs for known errors."""
+
+    error = errors.from_code(code, msg)
+    if error is not None:
+      self.assertIsInstance(error, expected_class)
+      self.assertEqual(error.ERROR_CODE, code)
+      self.assertEqual(str(error), msg)
+
+
+if __name__ == '__main__':
+  absltest.main()

android_env/components/log_stream.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-# Copyright 2022 DeepMind Technologies Limited.
+# Copyright 2024 DeepMind Technologies Limited.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,8 +16,8 @@
 """Abstract class for handling a stream of logs from a simulator."""
 
 import abc
+from collections.abc import Generator, Sequence
 import threading
-from typing import Generator, List
 from absl import logging
 
 
@@ -44,8 +44,10 @@ class LogStream(metaclass=abc.ABCMeta):
 
   @abc.abstractmethod
   def stop_stream(self) -> None:
-    """Terminates log stream process from the simulator."""
-    pass
+    """Terminates the log stream.
+
+    NOTE: This should only be called _after_ `get_stream_output()`.
+    """
 
   def pause_stream(self) -> None:
     """No lines are yielded while the event is not set."""
@@ -57,6 +59,6 @@ class LogStream(metaclass=abc.ABCMeta):
     logging.info('Resuming LogStream.')
     self._should_stream.set()
 
-  def set_log_filters(self, log_filters: List[str]):
+  def set_log_filters(self, log_filters: Sequence[str]):
     """Sets the filters for the log stream."""
     self._filters = list(log_filters) + ['*:S']

android_env/components/log_stream_test.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-# Copyright 2022 DeepMind Technologies Limited.
+# Copyright 2024 DeepMind Technologies Limited.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

android_env/components/logcat_thread.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-# Copyright 2022 DeepMind Technologies Limited.
+# Copyright 2024 DeepMind Technologies Limited.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,20 +15,21 @@
 
 """A class that launches a thread to read Android log outputs."""
 
+from collections.abc import Callable
+import dataclasses
 import re
 import threading
-# `typing.Pattern` has been deprecated in Python 3.9 in favor of `re.Pattern`,
-# but it is not available even in slightly older Python versions.
-# Please see https://www.python.org/dev/peps/pep-0585/
-from typing import Callable, Match, NamedTuple, Pattern
 
 from absl import logging
 from android_env.components import log_stream as log_stream_lib
 
 
-class EventListener(NamedTuple):
-  regexp: Pattern[str]
-  handler_fn: Callable[[Pattern[str], Match[str]], None]
+@dataclasses.dataclass
+class EventListener:
+  """A function that's called when an event is triggered."""
+
+  regexp: re.Pattern[str]
+  handler_fn: Callable[[re.Pattern[str], re.Match[str]], None]
 
 
 class LogcatThread:

android_env/components/logcat_thread_test.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-# Copyright 2022 DeepMind Technologies Limited.
+# Copyright 2024 DeepMind Technologies Limited.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -17,7 +17,6 @@
 
 import re
 import threading
-from typing import Match, Pattern
 
 from absl.testing import absltest
 from android_env.components import log_stream
@@ -25,7 +24,7 @@ from android_env.components import logcat_thread
 from android_env.proto import task_pb2
 
 
-class FakeStream():
+class FakeStream:
   """This class simulates the logs coming from ADB."""
 
   def __init__(self):
@@ -108,7 +107,7 @@ class LogcatThreadTest(absltest.TestCase):
     # Set up a listener that modifies an arbitrary state.
     some_state = threading.Event()
 
-    def my_handler(event: Pattern[str], match: Match[str]):
+    def my_handler(event: re.Pattern[str], match: re.Match[str]):
       del event, match
       nonlocal some_state
       some_state.set()

android_env/components/{utils.py → pixel_fns.py}

@@ -1,5 +1,5 @@
 # coding=utf-8
-# Copyright 2022 DeepMind Technologies Limited.
+# Copyright 2024 DeepMind Technologies Limited.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,7 +15,7 @@
 
 """Utils for AndroidEnv."""
 
-from typing import Sequence, Tuple
+from collections.abc import Sequence
 
 from dm_env import specs
 import numpy as np
@@ -24,7 +24,7 @@ import numpy as np
 def touch_position_to_pixel_position(
     touch_position: np.ndarray,
     width_height: Sequence[int],
-) -> Tuple[int, int]:
+) -> tuple[int, int]:
   """Maps touch position in [0,1] to the corresponding pixel on the screen."""
   touch_pixels = (touch_position * width_height).astype(np.int32)
   cap_idx = lambda v, idx_len: min(v, idx_len - 1)
@@ -38,27 +38,27 @@ def transpose_pixels(frame: np.ndarray) -> np.ndarray:
 
 def orient_pixels(frame: np.ndarray, orientation: int) -> np.ndarray:
   """Rotates screen pixels according to the given orientation."""
-  if orientation == 0:  # PORTRAIT_90
-    return frame
-  elif orientation == 1:  # LANDSCAPE_90
-    return np.rot90(frame, k=3, axes=(0, 1))
-  elif orientation == 2:  # PORTRAIT_180
-    return np.rot90(frame, k=2, axes=(0, 1))
-  elif orientation == 3:  # LANDSCAPE_270
-    return np.rot90(frame, k=1, axes=(0, 1))
-  else:
-    raise ValueError(
-        'Orientation must be an integer in [0, 3] but is %r' % orientation)
+
+  match orientation:
+    case 0:  # PORTRAIT_90
+      return frame
+    case 1:  # LANDSCAPE_90
+      return np.rot90(frame, k=3, axes=(0, 1))
+    case 2:  # PORTRAIT_180
+      return np.rot90(frame, k=2, axes=(0, 1))
+    case 3:  # LANDSCAPE_270
+      return np.rot90(frame, k=1, axes=(0, 1))
+    case _:
+      raise ValueError(
+          'Orientation must be an integer in [0, 3] but is %r' % orientation
+      )
 
 
-def convert_int_to_float(data: np.ndarray,
-                         data_spec: specs.Array,
-                         float_type: np.dtype = np.float32):
+def convert_int_to_float(data: np.ndarray, data_spec: specs.Array):
   """Converts an array of int values to floats between 0 and 1."""
+
   if not np.issubdtype(data.dtype, np.integer):
     raise TypeError(f'{data.dtype} is not an integer type')
-  if not np.issubdtype(float_type, np.floating):
-    raise TypeError(f'{float_type} is not a floating-point type')
   if isinstance(data_spec, specs.BoundedArray):
     value_min = data_spec.minimum
     value_max = data_spec.maximum
@@ -67,4 +67,4 @@ def convert_int_to_float(data: np.ndarray,
     iinfo = np.iinfo(data_spec.dtype)
     value_min = iinfo.min
     value_max = iinfo.max
-  return float_type(1.0 * (data - value_min) / (value_max - value_min))
+  return np.float32(1.0 * (data - value_min) / (value_max - value_min))