fmtr.tools 1.1.1__py3-none-any.whl → 1.4.37__py3-none-any.whl

fmtr/tools/function_tools.py

@@ -1,4 +1,8 @@
-from typing import Tuple
+import functools
+import inspect
+from typing import Tuple, Callable, Self
+
+from fmtr.tools import context_tools
 
 
 def combine_args_kwargs(args: dict=None, kwargs: dict=None) -> dict:
@@ -31,3 +35,75 @@ def split_args_kwargs(args_kwargs: dict) -> Tuple[list, dict]:
     return args, kwargs
 
 
+class MethodDecorator:
+    """
+
+    Bound method decorator with overridable start/stop and context manager
+
+    """
+
+    CONTEXT_KEY = 'context'
+
+    def __init__(self):
+        """
+
+        Initialise the decorator itself with any arguments
+
+        """
+        self.func = None
+
+    def __call__(self, func: Callable) -> Self:
+        """
+
+        Add the (unbound) method.
+
+        """
+        self.func = func
+        functools.update_wrapper(self, func)
+        return self
+
+    def __get__(self, instance, owner):
+        """
+
+        Wrap bound method at runtime, call start/stop within context.
+
+        """
+        if instance is None:  # Class method called.
+            return self.func
+
+        if inspect.iscoroutinefunction(self.func):
+            async def async_wrapper(*args, **kwargs):
+                with self.get_context(instance):
+                    self.start(instance, *args, **kwargs)
+                    result = await self.func(instance, *args, **kwargs)
+                    self.stop(instance, *args, **kwargs)
+                    return result
+
+            return async_wrapper
+
+        else:
+            def sync_wrapper(*args, **kwargs):
+                with self.get_context(instance):
+                    self.start(instance, *args, **kwargs)
+                    result = self.func(instance, *args, **kwargs)
+                    self.stop(instance, *args, **kwargs)
+                    return result
+
+            return sync_wrapper
+
+    def get_context(self, instance):
+        """
+
+        If the instance has a context attribute, use that - otherwise use a null context.
+
+        """
+        context = getattr(instance, self.CONTEXT_KEY, None)
+        if context:
+            return context
+        return context_tools.null()
+
+    def start(self, instance, *args, **kwargs):
+        pass
+
+    def stop(self, instance, *args, **kwargs):
+        pass

fmtr/tools/google_api_tools.py

@@ -1,3 +1,4 @@
+from google.auth.transport.requests import Request
 from google.oauth2.credentials import Credentials
 from google_auth_oauthlib.flow import InstalledAppFlow
 from googleapiclient.discovery import build
@@ -20,8 +21,12 @@ class Authenticator:
 
     @classmethod
     def auth(cls):
-        msg = f'Doing auth for service {cls.SERVICE} ({cls.VERSION})...'
-        logger.info(msg)
+        """
+
+        Do initial authentication or refresh token if expired.
+
+        """
+        logger.info(f'Doing auth for service {cls.SERVICE} ({cls.VERSION})...')
 
         PATH_CREDS = cls.PATH / 'credentials.json'
         PATH_TOKEN = cls.PATH / f'{cls.SERVICE}.json'
@@ -29,9 +34,15 @@ class Authenticator:
         if PATH_TOKEN.exists():
             data_token = PATH_TOKEN.read_json()
             credentials = Credentials.from_authorized_user_info(data_token, cls.SCOPES)
+            if credentials.expired:
+                with logger.span(f'Credentials expired for {cls.SERVICE}. Will refresh...'):
+                    logger.warning(f'{cls.SERVICE}. {PATH_CREDS.exists()=} {PATH_TOKEN.exists()=} {credentials.valid=} {credentials.expired=} {credentials.expiry=}')
+                    credentials.refresh(Request())
+                    PATH_TOKEN.write_text(credentials.to_json())
         else:
             flow = InstalledAppFlow.from_client_secrets_file(PATH_CREDS, cls.SCOPES)
+            flow.authorization_url(prompt='consent', access_type='offline')
             credentials = flow.run_local_server(open_browser=False, port=cls.PORT)
             PATH_TOKEN.write_text(credentials.to_json())
-        service = build(cls.SERVICE, cls.VERSION, credentials=credentials)
-        return service
+
+        return build(cls.SERVICE, cls.VERSION, credentials=credentials)

fmtr/tools/ha_tools/__init__.py

@@ -0,0 +1,8 @@
+from fmtr.tools.import_tools import MissingExtraMockModule
+
+try:
+    from fmtr.tools.ha_tools import core, supervisor, constants
+    from fmtr.tools.ha_tools.utils import apply_addon_env
+
+except ModuleNotFoundError as exception:
+    core = supervisor = constants = apply_addon_env = MissingExtraMockModule('ha', exception)

fmtr/tools/ha_tools/constants.py

@@ -0,0 +1,9 @@
+from fmtr.tools.path_tools.path_tools import root
+
+SUPERVISOR_TOKEN_KEY = 'SUPERVISOR_TOKEN'
+URL_SUPERVISOR_ADDON = "http://supervisor"
+URL_CORE_ADDON = F"{URL_SUPERVISOR_ADDON}/core/api"
+PATH_ADDON_ENV = root / 'addon.env'
+PATH_ADDON_OPTIONS = root / 'data' / 'options.json'
+PATH_ADDON_CONFIG = root / 'config'
+PATH_ADDON_MEDIA = root / 'media'

fmtr/tools/ha_tools/core.py

@@ -0,0 +1,16 @@
+import homeassistant_api
+
+from fmtr.tools import environment_tools as env
+from fmtr.tools.ha_tools import constants
+
+
+class Client(homeassistant_api.Client):
+    """
+
+    Client stub
+
+    """
+
+    def __init__(self, *args, api_url: str = constants.URL_CORE_ADDON, token: str, **kwargs):
+        token = token or env.get(constants.SUPERVISOR_TOKEN_KEY)
+        super().__init__(*args, api_url=api_url, token=token, **kwargs)

fmtr/tools/ha_tools/supervisor.py

@@ -0,0 +1,16 @@
+import aiohasupervisor
+
+from fmtr.tools import environment_tools as env
+from fmtr.tools.ha_tools import constants
+
+
+class Client(aiohasupervisor.SupervisorClient):
+    """
+
+    Client stub
+
+    """
+
+    def __init__(self, *args, api_url: str = constants.URL_SUPERVISOR_ADDON, token: str, **kwargs):
+        token = token or env.get(constants.SUPERVISOR_TOKEN_KEY)
+        super().__init__(*args, api_host=api_url, token=token, **kwargs)

fmtr/tools/ha_tools/utils.py

@@ -0,0 +1,46 @@
+import os
+from dotenv import load_dotenv
+
+from fmtr.tools.ha_tools import constants
+from fmtr.tools.logging_tools import logger
+from fmtr.tools.string_tools import ELLIPSIS
+
+
+def apply_addon_env():
+    """
+
+    If we're inside an addon container, we need to source its environment file and convert its options.json to environment variables.
+
+    """
+    path = constants.PATH_ADDON_ENV
+    if path.exists():
+        logger.warning(f'Loading addon environment from "{path}"...')
+        load_dotenv(path)
+
+    for key, value in convert_options_data().items():
+        os.environ[key] = value
+
+
+def convert_options_data() -> dict[str, str]:
+    """
+
+    Convert Home Assistant addon options.json to an environment-ready dict.
+
+    """
+    path = constants.PATH_ADDON_OPTIONS
+
+    data_env = {}
+
+    if not path.exists():
+        return data_env
+
+    data_json = path.read_json()
+
+    with logger.span(f'Converting addon "{path}" to environment variables...'):
+        for key, value in data_json.items():
+            key_env = key.upper()
+            val_env = str(value)
+            logger.debug(f'Converting {key_env}={ELLIPSIS}" to environment variable...')
+            data_env[key_env] = val_env
+
+    return data_env

fmtr/tools/http_tools.py

@@ -0,0 +1,52 @@
+import httpx
+from functools import cached_property
+from httpx_retries import RetryTransport, Retry
+
+from fmtr.tools import logging_tools
+
+logging_tools.logger.instrument_httpx()
+
+
+class Client(httpx.Client):
+    """
+
+    Instrumented client base
+
+    """
+
+    TIMEOUT = 10
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, transport=self.transport, timeout=self.TIMEOUT, **kwargs)
+
+    @cached_property
+    def transport(self) -> RetryTransport:
+        """
+
+        Default Transport with retry
+
+        """
+        return RetryTransport(
+            retry=self.retry
+        )
+
+    @cached_property
+    def retry(self) -> Retry:
+        """
+
+        Default Retry
+
+        """
+        return Retry(
+            allowed_methods=Retry.RETRYABLE_METHODS,
+            backoff_factor=1.0
+        )
+
+
+client = Client()
+
+if __name__ == '__main__':
+    resp = client.get('https://postman-echo.com/delay/5')
+    resp.raise_for_status()
+    print(resp.json())
+    resp

fmtr/tools/inherit_tools.py

@@ -0,0 +1,27 @@
+from typing import TypeVar, Generic
+
+T = TypeVar("T")
+
+
+class Inherit(Generic[T]):
+    """
+
+    Runtime inheritance. Acts like a wrapper around an instantiated base class of type T, and allows overriding methods in subclasses like regular inheritance.
+
+    """
+
+    def __init__(self, parent: T):
+        """
+
+        Set parent
+
+        """
+        object.__setattr__(self, "_parent", parent)
+
+    def __getattr__(self, name):
+        """
+
+        Since regular attribute access checks own methods first, we don't need to do anything fancy to fall back to the parent when not implemented.
+
+        """
+        return getattr(self._parent, name)

fmtr/tools/interface_tools/__init__.py

@@ -0,0 +1,8 @@
+from fmtr.tools.import_tools import MissingExtraMockModule
+
+try:
+    from fmtr.tools.interface_tools.interface_tools import Base, update, progress
+    from fmtr.tools.interface_tools import controls
+    from fmtr.tools.interface_tools.context import Context
+except ModuleNotFoundError as exception:
+    Interface = update = progress = controls = MissingExtraMockModule('interface', exception)

fmtr/tools/interface_tools/context.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+
+from flet.core.page import Page
+
+
+@dataclass
+class Context:
+    """
+
+    Base context class
+
+    """
+    page: Page

fmtr/tools/interface_tools/controls.py

@@ -0,0 +1,354 @@
+import flet as ft
+from dataclasses import dataclass
+from flet.core.gesture_detector import TapEvent
+from flet.core.page import Page
+from flet.core.types import ColorValue, IconValue
+from functools import cached_property
+from typing import Optional
+
+from fmtr.tools.logging_tools import logger
+
+
+class SliderSteps(ft.Slider):
+    """
+
+    Slider control using step instead of divisions
+
+    """
+
+    def __init__(self, *args, min=10, max=100, step=10, **kwargs):
+        self.step = step
+        divisions = (max - min) // step
+        super().__init__(*args, min=min, max=max, divisions=divisions, **kwargs)
+
+
+class Cell(ft.DataCell):
+    """
+
+    Context-aware, clickable data cell.
+
+    """
+
+    def __init__(self, series, column):
+        """
+
+        Store context
+
+        """
+        self.series = series
+        self.column = column
+        self.value = series[column]
+
+        super().__init__(self.gesture_detector)
+
+    @cached_property
+    def text(self):
+        """
+
+        Cell contents text
+
+        """
+
+        return ft.Text(str(self.value), color=self.color, bgcolor=self.bgcolor)
+
+    @property
+    def color(self):
+        """
+
+        Basic conditional formatting
+
+        """
+        if self.value is None:
+            return ft.Colors.GREY
+        else:
+            return None
+
+    @property
+    def bgcolor(self):
+        """
+
+        Basic conditional formatting
+
+        """
+        return None
+
+    @cached_property
+    def gesture_detector(self):
+        """
+
+        Make arbitrary content clickable
+
+        """
+        return ft.GestureDetector(content=self.text, on_tap=self.click_tap, on_double_tap=self.click_double_tap)
+
+    async def click_tap(self, event: TapEvent):
+        """
+
+        Default cell click behavior — override in subclass if needed
+
+        """
+        value = await self.click(event=event)
+        event.page.update()
+        return value
+
+    async def click(self, event: Optional[TapEvent] = None):
+        """
+
+        Default cell click behavior — override in subclass if needed
+
+        """
+        logger.info(f"Clicked {self.column=} {self.series.name=} {self.value=}")
+
+    async def click_double_tap(self, event: TapEvent):
+        """
+
+        Default cell click behavior — override in subclass if needed
+
+        """
+        value = await self.double_click(event=event)
+        event.page.update()
+        return value
+
+    async def double_click(self, event: Optional[TapEvent] = None):
+        """
+
+        Default cell double click behavior — override in subclass if needed
+
+        """
+        logger.info(f"Double-clicked {self.column=} {self.series.id=} {self.value=}")
+
+
+class Row(ft.DataRow):
+    """
+
+    Instantiate a row from a series
+
+    """
+
+    TypesCells = {None: Cell}
+
+    def __init__(self, series):
+        self.series = series
+        super().__init__(self.cells_controls, color=self.row_color)
+
+    @cached_property
+    def cells_data(self) -> dict[str, list[Cell]]:
+        """
+
+        Cell controls lookup
+
+        """
+        data = {}
+        for col in self.series.index:
+            default = self.TypesCells[None]
+            TypeCell = self.TypesCells.get(col, default)
+            data.setdefault(col, []).append(TypeCell(self.series, col))
+        return data
+
+    @cached_property
+    def cells_controls(self) -> list[Cell]:
+        """
+
+        Flat list of controls
+
+        """
+        controls = []
+        for cells in self.cells_data.values():
+            for cell in cells:
+                controls.append(cell)
+        return controls
+
+    def __getitem__(self, item) -> list[Cell]:
+        """
+
+        Get cells by column name
+
+        """
+        return self.cells_data[item]
+
+    @property
+    def row_color(self):
+        """
+
+        Basic conditional formatting
+
+        """
+        return None
+
+
+class Column(ft.DataColumn):
+    """
+
+    Column stub
+
+    """
+
+    def __init__(self, col_name: str):
+        """
+
+        Store context
+
+        """
+
+        self.col_name = col_name
+
+        super().__init__(label=self.text)
+
+    @cached_property
+    def text(self):
+        """
+
+        Cell contents text
+
+        """
+        return ft.Text(str(self.col_name), weight=self.weight)
+
+    @property
+    def weight(self):
+        """
+
+        Default bold headers
+
+        """
+        return ft.FontWeight.BOLD
+
+
+class Table(ft.DataTable):
+    """
+
+    Dataframe with clickable cells
+
+    """
+
+    TypesRows = {None: Row}
+    TypesColumns = {None: Column}
+
+    def __init__(self, df):  # todo move to submodule with tabular deps
+        """
+
+        Set columns/rows using relevant types
+
+        """
+        self.df = df
+        super().__init__(columns=self.columns_controls, rows=self.rows_controls)
+
+    @cached_property
+    def columns_data(self) -> dict[str, list[Column]]:
+        """
+
+        Columns controls lookup
+
+        """
+        data = {}
+        for col in self.df.columns:
+            default = self.TypesColumns[None]
+            TypeColumn = self.TypesColumns.get(col, default)
+            data.setdefault(col, []).append(TypeColumn(col))
+        return data
+
+    @cached_property
+    def columns_controls(self) -> list[Column]:
+        """
+
+        Flat list of controls
+
+        """
+        controls = []
+        for columns in self.columns_data.values():
+            for column in columns:
+                controls.append(column)
+        return controls
+
+    @cached_property
+    def rows_data(self) -> dict[str, list[Row]]:
+        """
+
+        Row controls lookup
+
+        """
+        data = {}
+        for index, row in self.df.iterrows():
+            default = self.TypesRows[None]
+            TypeRow = self.TypesRows.get(index, default)
+            data.setdefault(index, []).append(TypeRow(row))
+        return data
+
+    @cached_property
+    def rows_controls(self) -> list[Row]:
+        """
+
+        Flat list of controls
+
+        """
+        controls = []
+        for rows in self.rows_data.values():
+            for row in rows:
+                controls.append(row)
+        return controls
+
+    def __getitem__(self, item) -> list[Row]:
+        """
+
+        Get row by index
+
+        """
+
+        return self.rows_data[item]
+
+
+@dataclass
+class NotificationDatum:
+    """
+
+    Color and icon for notification bar
+
+    """
+    color: ColorValue
+    icon: IconValue
+
+
+class NotificationBar(ft.SnackBar):
+    """
+
+    Combined logging and notification bar: infers the appropriate UI representation from the log level
+
+    """
+    DATA = {
+        logger.info: NotificationDatum(color=ft.Colors.BLUE, icon=ft.Icons.INFO),
+        logger.warning: NotificationDatum(color=ft.Colors.AMBER, icon=ft.Icons.WARNING),
+        logger.error: NotificationDatum(color=ft.Colors.RED, icon=ft.Icons.ERROR),
+        logger.debug: NotificationDatum(color=ft.Colors.GREY, icon=ft.Icons.BUG_REPORT),
+        logger.exception: NotificationDatum(color=ft.Colors.RED_ACCENT, icon=ft.Icons.REPORT),
+    }
+
+    def __init__(self, msg: str, method=logger.info):
+        """
+
+        Log the message immediately, otherwise configure notification bar icon/color.
+
+        """
+        self.msg = msg
+        self.method = method
+        self.method(msg)
+
+        icon = ft.Icon(self.data.icon, color=self.data.color)
+        text = ft.Text(self.msg)
+        content = ft.Row(controls=[icon, text])
+        super().__init__(content=content)
+
+    @cached_property
+    def data(self) -> NotificationDatum:
+        """
+
+        Fetching data using logging method.
+
+        """
+        return self.DATA[self.method]
+
+    def show(self, page: Page):
+        """
+
+        Show the notification on the relevant page.
+
+        """
+        page.open(self)