typing: add Context to gradually type

Author: deltragon

safeeyes/context.py

@@ -0,0 +1,132 @@
+# Safe Eyes is a utility to remind you to take break frequently
+# to protect your eyes from eye strain.
+
+# Copyright (C) 2025 Mel Dafert <[email protected]>
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from collections.abc import MutableMapping
+import datetime
+import typing
+
+from safeeyes import utility
+from safeeyes.model import State
+
+if typing.TYPE_CHECKING:
+    from safeeyes.safeeyes import SafeEyes
+
+
+class API:
+    _application: "SafeEyes"
+
+    def __init__(
+        self,
+        application: "SafeEyes",
+    ) -> None:
+        self._application = application
+
+    def __getitem__(self, key: str) -> typing.Callable:
+        """This is soft-deprecated - it is preferred to access the property."""
+        return getattr(self, key)
+
+    def show_settings(self) -> None:
+        utility.execute_main_thread(self._application.show_settings)
+
+    def show_about(self) -> None:
+        utility.execute_main_thread(self._application.show_about)
+
+    def enable_safeeyes(self, next_break_time=-1) -> None:
+        utility.execute_main_thread(self._application.enable_safeeyes, next_break_time)
+
+    def disable_safeeyes(self, status=None, is_resting=False) -> None:
+        utility.execute_main_thread(
+            self._application.disable_safeeyes, status, is_resting
+        )
+
+    def status(self) -> str:
+        return self._application.status()
+
+    def quit(self) -> None:
+        utility.execute_main_thread(self._application.quit)
+
+    def take_break(self, break_type=None) -> None:
+        self._application.take_break(break_type)
+
+    def has_breaks(self, break_type=None) -> bool:
+        return self._application.safe_eyes_core.has_breaks(break_type)
+
+    def postpone(self, duration=-1) -> None:
+        self._application.safe_eyes_core.postpone(duration)
+
+    def get_break_time(self, break_type=None) -> typing.Optional[datetime.datetime]:
+        return self._application.safe_eyes_core.get_break_time(break_type)
+
+
+class Context(MutableMapping):
+    version: str
+    api: API
+    desktop: str
+    is_wayland: bool
+    locale: str
+    session: dict[str, typing.Any]
+    state: State
+
+    ext: dict
+
+    def __init__(
+        self,
+        api: API,
+        locale: str,
+        version: str,
+        session: dict[str, typing.Any],
+    ) -> None:
+        self.version = version
+        self.desktop = utility.desktop_environment()
+        self.is_wayland = utility.is_wayland()
+        self.locale = locale
+        self.session = session
+        self.state = State.START
+        self.api = api
+
+        self.ext = {}
+
+    def __setitem__(self, key: str, value: typing.Any) -> None:
+        """This is soft-deprecated - it is preferred to access the property."""
+        if hasattr(self, key):
+            setattr(self, key, value)
+            return
+
+        self.ext[key] = value
+
+    def __getitem__(self, key: str) -> typing.Any:
+        """This is soft-deprecated - it is preferred to access the property."""
+        if hasattr(self, key):
+            return getattr(self, key)
+
+        return self.ext[key]
+
+    def __delitem__(self, key: str) -> None:
+        """This is soft-deprecated - it is preferred to access the property."""
+        if hasattr(self, key):
+            raise Exception("cannot delete property")
+
+        del self.ext[key]
+
+    def __len__(self) -> int:
+        """This is soft-deprecated."""
+        return len(self.ext)
+
+    def __iter__(self) -> typing.Iterator[typing.Any]:
+        """This is soft-deprecated."""
+        return iter(self.ext)

safeeyes/model.py

@@ -38,6 +38,9 @@
 from safeeyes import utility
 from safeeyes.translations import translate as _
 
+if typing.TYPE_CHECKING:
+    from safeeyes.context import Context
+
 
 class BreakType(Enum):
     """Type of Safe Eyes breaks."""
@@ -105,9 +108,12 @@ class BreakQueue:
     __is_random_order: bool
     __long_queue: typing.Optional[list[Break]]
     __short_queue: typing.Optional[list[Break]]
+    context: "Context"
 
     @classmethod
-    def create(cls, config: "Config", context) -> typing.Optional["BreakQueue"]:
+    def create(
+        cls, config: "Config", context: "Context"
+    ) -> typing.Optional["BreakQueue"]:
         short_break_time = config.get("short_break_interval")
         long_break_time = config.get("long_break_interval")
         is_random_order = config.get("random_order")
@@ -142,7 +148,7 @@ def create(cls, config: "Config", context) -> typing.Optional["BreakQueue"]:
 
     def __init__(
         self,
-        context,
+        context: "Context",
         short_break_time: int,
         long_break_time: int,
         is_random_order: bool,
@@ -166,7 +172,7 @@ def __init__(
         self.__set_next_break()
 
         # Restore the last break from session
-        last_break = context["session"].get("break")
+        last_break = context.session.get("break")
         if last_break is not None:
             current_break = self.get_break()
             if last_break != current_break.name:
@@ -247,7 +253,7 @@ def __set_next_break(self, break_type: typing.Optional[BreakType] = None) -> Non
             break_obj = self.__next_short()
 
         self.__current_break = break_obj
-        self.context["session"]["break"] = self.__current_break.name
+        self.context.session["break"] = self.__current_break.name
 
     def skip_long_break(self) -> None:
         if not (self.__short_queue and self.__long_queue):
@@ -265,7 +271,7 @@ def skip_long_break(self) -> None:
             # we could decrement the __current_long counter, but then we'd need to
             # handle wraparound and possibly randomizing, which seems complicated
             self.__current_break = self.__next_short()
-            self.context["session"]["break"] = self.__current_break.name
+            self.context.session["break"] = self.__current_break.name
 
     def is_empty(self, break_type: BreakType) -> bool:
         """Check if the given break type is empty or not."""
@@ -283,7 +289,7 @@ def __next_short(self) -> Break:
             raise Exception("this may only be called when there are short breaks")
 
         break_obj = shorts[self.__current_short]
-        self.context["break_type"] = "short"
+        self.context.ext["break_type"] = "short"
 
         # Update the index to next
         self.__current_short = (self.__current_short + 1) % len(shorts)
@@ -297,7 +303,7 @@ def __next_long(self) -> Break:
             raise Exception("this may only be called when there are long breaks")
 
         break_obj = longs[self.__current_long]
-        self.context["break_type"] = "long"
+        self.context.ext["break_type"] = "long"
 
         # Update the index to next
         self.__current_long = (self.__current_long + 1) % len(longs)

safeeyes/safeeyes.py

@@ -22,11 +22,10 @@
 
 import atexit
 import logging
-import typing
 from importlib import metadata
 
 import gi
-from safeeyes import utility
+from safeeyes import context, utility
 from safeeyes.ui.about_dialog import AboutDialog
 from safeeyes.ui.break_screen import BreakScreen
 from safeeyes.ui.required_plugin_dialog import RequiredPluginDialog
@@ -47,19 +46,20 @@ class SafeEyes(Gtk.Application):
 
     required_plugin_dialog_active = False
     retry_errored_plugins_count = 0
+    context: context.Context
+    break_screen: BreakScreen
+    safe_eyes_core: SafeEyesCore
+    plugins_manager: PluginManager
+    system_locale: str
 
-    def __init__(self, system_locale, config) -> None:
+    def __init__(self, system_locale: str, config) -> None:
         super().__init__(
             application_id="io.github.slgobinath.SafeEyes",
             flags=Gio.ApplicationFlags.HANDLES_COMMAND_LINE,
         )
 
         self.active = False
-        self.break_screen = None
-        self.safe_eyes_core = None
         self.config = config
-        self.context: typing.Any = {}
-        self.plugins_manager = None
         self.settings_dialog_active = False
         self._status = ""
         self.system_locale = system_locale
@@ -219,39 +219,23 @@ def do_command_line(self, command_line):
 
         return 0
 
-    def do_startup(self):
+    def do_startup(self) -> None:
         Gtk.Application.do_startup(self)
 
         logging.info("Starting up Application")
 
         # Initialize the Safe Eyes Context
-        self.context["version"] = SAFE_EYES_VERSION
-        self.context["desktop"] = utility.desktop_environment()
-        self.context["is_wayland"] = utility.is_wayland()
-        self.context["locale"] = self.system_locale
-        self.context["api"] = {}
-        self.context["api"]["show_settings"] = lambda: utility.execute_main_thread(
-            self.show_settings
-        )
-        self.context["api"]["show_about"] = lambda: utility.execute_main_thread(
-            self.show_about
-        )
-        self.context["api"]["enable_safeeyes"] = (
-            lambda next_break_time=-1: utility.execute_main_thread(
-                self.enable_safeeyes, next_break_time
-            )
-        )
-        self.context["api"]["disable_safeeyes"] = (
-            lambda status=None, is_resting=False: utility.execute_main_thread(
-                self.disable_safeeyes, status, is_resting
-            )
-        )
-        self.context["api"]["status"] = self.status
-        self.context["api"]["quit"] = lambda: utility.execute_main_thread(self.quit)
         if self.config.get("persist_state"):
-            self.context["session"] = utility.open_session()
+            session = utility.open_session()
         else:
-            self.context["session"] = {"plugin": {}}
+            session = {"plugin": {}}
+
+        self.context = context.Context(
+            api=context.API(self),
+            locale=self.system_locale,
+            version=SAFE_EYES_VERSION,
+            session=session,
+        )
 
         # Initialize the theme
         self._initialize_styles()
@@ -269,10 +253,6 @@ def do_startup(self):
         self.safe_eyes_core.on_stop_break += self.stop_break
         self.safe_eyes_core.on_update_next_break += self.update_next_break
         self.safe_eyes_core.initialize(self.config)
-        self.context["api"]["take_break"] = self.take_break
-        self.context["api"]["has_breaks"] = self.safe_eyes_core.has_breaks
-        self.context["api"]["postpone"] = self.safe_eyes_core.postpone
-        self.context["api"]["get_break_time"] = self.safe_eyes_core.get_break_time
 
         try:
             self.plugins_manager.init(self.context, self.config)
@@ -289,7 +269,7 @@ def do_startup(self):
             and self.safe_eyes_core.has_breaks()
         ):
             self.active = True
-            self.context["state"] = State.START
+            self.context.state = State.START
             self.plugins_manager.start()  # Call the start method of all plugins
             self.safe_eyes_core.start()
             self.handle_system_suspend()

safeeyes/tests/test_model.py

@@ -19,7 +19,8 @@
 import pytest
 import random
 import typing
-from safeeyes import model
+from unittest import mock
+from safeeyes import context, model
 
 
 class TestBreak:
@@ -65,9 +66,11 @@ def test_create_empty(self) -> None:
             system_config={},
         )
 
-        context: dict[str, typing.Any] = {}
+        ctx = context.Context(
+            api=mock.Mock(spec=context.API), locale="en_US", version="0.0.0", session={}
+        )
 
-        bq = model.BreakQueue.create(config, context)
+        bq = model.BreakQueue.create(config, ctx)
 
         assert bq is None
 
@@ -98,11 +101,11 @@ def get_bq_only_short(
             system_config={},
         )
 
-        context: dict[str, typing.Any] = {
-            "session": {},
-        }
+        ctx = context.Context(
+            api=mock.Mock(spec=context.API), locale="en_US", version="0.0.0", session={}
+        )
 
-        bq = model.BreakQueue.create(config, context)
+        bq = model.BreakQueue.create(config, ctx)
 
         assert bq is not None
 
@@ -135,11 +138,11 @@ def get_bq_only_long(
             system_config={},
         )
 
-        context: dict[str, typing.Any] = {
-            "session": {},
-        }
+        ctx = context.Context(
+            api=mock.Mock(spec=context.API), locale="en_US", version="0.0.0", session={}
+        )
 
-        bq = model.BreakQueue.create(config, context)
+        bq = model.BreakQueue.create(config, ctx)
 
         assert bq is not None
 
@@ -177,11 +180,11 @@ def get_bq_full(
             system_config={},
         )
 
-        context: dict[str, typing.Any] = {
-            "session": {},
-        }
+        ctx = context.Context(
+            api=mock.Mock(spec=context.API), locale="en_US", version="0.0.0", session={}
+        )
 
-        bq = model.BreakQueue.create(config, context)
+        bq = model.BreakQueue.create(config, ctx)
 
         assert bq is not None