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

fmtr/tools/interface_tools/interface_tools.py

@@ -0,0 +1,189 @@
+import os
+from typing import TypeVar, Generic, Type
+
+import flet as ft
+from flet.core.control_event import ControlEvent
+from flet.core.types import AppView
+from flet.core.view import View
+
+from fmtr.tools import environment_tools
+from fmtr.tools.constants import Constants
+from fmtr.tools.function_tools import MethodDecorator
+from fmtr.tools.interface_tools.context import Context
+from fmtr.tools.logging_tools import logger
+
+
+class update(MethodDecorator):
+    """
+
+    Update the page after the decorated function is called.
+
+    """
+
+    def stop(self, instance, *args, **kwargs):
+        instance.page.update()
+
+
+class progress(update):
+    """
+
+    Run the function while a progress indicator (e.g. spinner) is and within the object-defined context (e.g. logging span).
+
+    """
+
+    def start(self, instance, *args, **kwargs):
+        """
+
+        Make progress visible and update.
+
+        """
+        instance.progress.visible = True
+        instance.page.update()
+
+    def stop(self, instance, *args, **kwargs):
+        """
+
+         Make progress not visible and update.
+
+        """
+        instance.progress.visible = False
+        super().stop(instance)
+
+
+T = TypeVar('T', bound=Context)
+
+
+class Base(Generic[T], ft.Column):
+    """
+
+    Simple interface base class.
+
+    """
+    TITLE = 'Base Interface'
+    HOST = '0.0.0.0'
+    PORT = 8080
+    URL = Constants.FMTR_DEV_INTERFACE_URL if environment_tools.IS_DEV else None
+    APPVIEW = AppView.WEB_BROWSER
+    PATH_ASSETS = None
+    PATH_UPLOADS = None
+    SCROLL = ft.ScrollMode.AUTO
+
+    SECRET_KEY_KEY = 'FLET_SECRET_KEY'
+    ROUTE_ROOT = '/'
+
+    TypeContext: Type[T] = Context
+
+    @classmethod
+    async def new(cls, page: ft.Page):
+        """
+
+        Interface entry point/async constructor. Set relevant callbacks, and add instantiated self to page views.
+
+        Override this to work with `Context`, do async setup. Otherwise, override __init__ (which is regular Column __init__) for a simple interface.
+
+        """
+        page.scroll = cls.SCROLL
+        page.title = cls.TITLE
+        page.on_connect = cls.on_connect
+        page.on_disconnect = cls.on_disconnect
+        page.on_route_change = cls.route
+        page.on_view_pop = cls.pop
+        page.theme = cls.get_theme()
+
+        context = cls.TypeContext(page=page)
+        self = cls()
+        self.context = context
+
+        page.controls.append(self)
+        page.update()
+
+        return self
+
+    @classmethod
+    def route(cls, event: ft.RouteChangeEvent):
+        """
+
+        Overridable router.
+
+        """
+        logger.debug(f'Route change: {event=}')
+
+    @classmethod
+    def pop(cls, view: View, page: ft.Page):
+        """
+
+        Overridable view pop.
+
+        """
+        logger.debug(f'View popped: {page.route=} {len(page.views)=} {view=}')
+
+    @classmethod
+    def on_connect(cls, event: ControlEvent):
+        """
+
+        Log connections
+
+        """
+        page = event.control
+        logger.warning(f'Connect: {page.client_user_agent=} {page.platform.name=}')
+
+    @classmethod
+    def on_disconnect(cls, event: ControlEvent):
+        """
+
+        Log disconnections
+
+        """
+        page = event.control
+        logger.warning(f'Disconnect {page.client_user_agent=} {page.platform.name=}')
+
+
+    @classmethod
+    def get_theme(self):
+        """
+
+        Overridable theme definition
+
+        """
+        text_style = ft.TextStyle(size=20)
+        theme = ft.Theme(
+            text_theme=ft.TextTheme(body_large=text_style),
+        )
+        return theme
+
+    @classmethod
+    def launch(cls):
+        """
+
+        Launch via async constructor method
+
+        """
+
+        if cls.URL:
+            url = cls.URL
+        else:
+            url = f'http://{cls.HOST}:{cls.PORT}'
+
+        if not environment_tools.get(cls.SECRET_KEY_KEY, default=None):
+            os.environ["FLET_SECRET_KEY"] = os.urandom(12).hex()
+
+        logger.info(f"Launching {cls.TITLE} at {url}")
+        ft.app(cls.new, view=cls.APPVIEW, host=cls.HOST, port=cls.PORT, assets_dir=cls.PATH_ASSETS, upload_dir=cls.PATH_UPLOADS)
+
+
+class Test(Base[Context]):
+    """
+
+    Simple test interface, showing typing example.
+
+    """
+    TypeContext: Type[Context] = Context
+
+    TITLE = 'Test Interface'
+
+    def __init__(self):
+        controls = [ft.Text(self.TITLE)]
+        super().__init__(controls=controls)
+
+if __name__ == "__main__":
+    Test.launch()

fmtr/tools/iterator_tools.py

@@ -1,5 +1,8 @@
 from itertools import chain, batched
-from typing import List, Dict, Any
+
+from typing import List, Dict, Any, TypeVar, Generic, Iterable
+
+from fmtr.tools.datatype_tools import is_none
 
 
 def enlist(value) -> List[Any]:
@@ -52,3 +55,121 @@ def rebatch(batches, size: int):
 
     """
     return batched(chain.from_iterable(batches), size)
+
+
+def strip_none(*items):
+    """
+
+    Remove nones from a list of arguments
+
+    """
+    return [item for item in items if not is_none(item)]
+
+
+def dedupe(items):
+    """
+
+    Deduplicate a list of items, retaining order
+
+    """
+    return list(dict.fromkeys(items))
+
+
+def get_class_lookup(*classes, name_function=lambda cls: cls.__name__):
+    """
+
+    Dictionary of class names to classes
+
+    """
+    return {name_function(cls): cls for cls in classes}
+
+
+IndexListT = TypeVar('IndexListT')  # Generic type for list items
+
+
+class IndexList(list[IndexListT], Generic[IndexListT]):
+    """
+
+    List of objects selectable via attribute lookup, plus currently-selected item.
+
+    """
+
+    def __init__(self, iterable: Iterable[IndexListT] = ()):
+        """
+
+        Initialize with iterable
+
+        """
+        super().__init__(iterable)
+        self.current: IndexListT | None = self[0] if self else None
+
+    def __getattr__(self, name):
+        """
+
+        Return a lookup dict keyed on the specified field of each item in the self/list.
+
+        """
+
+        try:
+            return self.__dict__[name]
+        except KeyError:
+            pass
+
+        if hasattr(list, name):
+            return getattr(self, name)
+
+        result = {}
+        for obj in self:
+            try:
+                value = getattr(obj, name)
+            except AttributeError:
+                value = obj[name]  # assume dict-like
+            result[value] = obj
+        return result
+
+
+IterDifferT = TypeVar("IterDifferT")
+
+
+class IterDiffer(Generic[IterDifferT]):
+    """
+
+    Compute added/removed differences between two iterables.
+
+    """
+
+    def __init__(self, before: Iterable[IterDifferT], after: Iterable[IterDifferT]):
+        """
+
+        Initialize with two iterables.
+
+        """
+        self.before: set[IterDifferT] = set(before)
+        self.after: set[IterDifferT] = set(after)
+
+    @property
+    def added(self) -> set[IterDifferT]:
+        """
+
+        Items in `after` not in `before`.
+
+        """
+        return self.after - self.before
+
+    @property
+    def removed(self) -> set[IterDifferT]:
+        """
+
+        Items in `before` not in `after`.
+
+        """
+        return self.before - self.after
+
+    @property
+    def is_changed(self) -> bool:
+        """
+
+        True if any items added or removed.
+
+        """
+        return bool(self.added or self.removed)

fmtr/tools/logging_tools.py

@@ -4,23 +4,24 @@ import os
 from fmtr.tools import environment_tools
 from fmtr.tools.constants import Constants
 
-DEVELOPMENT = "development"
-PRODUCTION = "production"
-STREAM_DEFAULT = DEVELOPMENT
-ENVIRONMENT_DEFAULT = DEVELOPMENT
-
-LEVEL_DEFAULT = logging.DEBUG if environment_tools.IS_DEBUG else logging.INFO
+if environment_tools.IS_DEV:
+    STREAM_DEFAULT = ENVIRONMENT_DEFAULT = Constants.DEVELOPMENT
+else:
+    STREAM_DEFAULT = None
+    ENVIRONMENT_DEFAULT = Constants.PRODUCTION
 
+LEVEL_DEFAULT = logging.DEBUG if environment_tools.IS_DEV else logging.INFO
 
 def get_logger(name, version=None, host=Constants.FMTR_OBS_HOST, key=None, org=Constants.ORG_NAME,
-               stream=STREAM_DEFAULT,
-               environment=ENVIRONMENT_DEFAULT, level=LEVEL_DEFAULT):
+               stream=STREAM_DEFAULT, environment=ENVIRONMENT_DEFAULT, level=LEVEL_DEFAULT):
     """
 
     Get a pre-configured logfire logger, if dependency is present, otherwise default to native logger.
 
     """
 
+    stream = stream or name
+
     try:
         import logfire
     except ImportError:
@@ -30,36 +31,116 @@ def get_logger(name, version=None, host=Constants.FMTR_OBS_HOST, key=None, org=C
 
         return logger
 
+    logger = logfire
+
     if key is None:
-        key = environment_tools.get(Constants.FMTR_OBS_API_KEY_KEY)
-    url = f"https://{host}/api/{org}/v1/traces"
-    headers = f"Authorization=Basic {key},stream-name={stream}"
+        key = environment_tools.get(Constants.FMTR_OBS_API_KEY_KEY, default=None)
+
+    if key:
+        url = f"https://{host}/api/{org}/v1/traces"
+        headers = f"Authorization=Basic {key},stream-name={stream}"
 
-    os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = url
-    os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = headers
-    os.environ["OTEL_EXPORTER_OTLP_INSECURE"] = str(False).lower()
+        os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = url
+        os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = headers
+        os.environ["OTEL_EXPORTER_OTLP_INSECURE"] = str(False).lower()
 
     if not version:
         from fmtr.tools import version_tools
         version = version_tools.read()
 
+    lev_name_otel = get_otel_level_name(level)
+
+    console_opts = logfire.ConsoleOptions(
+        colors='always',
+        min_log_level=lev_name_otel,
+    )
+
     logfire.configure(
         service_name=name,
         service_version=version,
         environment=environment,
         send_to_logfire=False,
-        console=logfire.ConsoleOptions(colors='always' if environment_tools.IS_DEBUG else 'auto')
+        console=console_opts,
+        scrubbing=logfire.ScrubbingOptions(callback=null_scrubber)
     )
 
-    logging.getLogger(name).setLevel(level)
-
-    logger = logfire
     return logger
 
 
+def null_scrubber(match):
+    """
+
+    Effectively disable scrubbing
+
+    """
+    return match.value
+
+
+def get_current_level(logger):
+    """
+
+    Get the current console log level.
+
+    """
+    level = logger.DEFAULT_LOGFIRE_INSTANCE.config.console.min_log_level
+    return level
+
+
+def get_logger_names():
+    """
+
+    Fetch current native logger names
+
+    """
+    return list(logging.getLogger().manager.loggerDict.keys())
+
+
+OTEL_TO_NATIVE = {
+    1: 1,  # trace
+    3: 5,  # debug
+    5: 10,  # debug (canonical)
+    6: 13,  # warn
+    8: 17,  # error
+    9: 20,  # info
+    10: 23,  # notice
+    11: 25,  # success/loguru
+    13: 30,  # warning
+    17: 40,  # error
+    21: 50,  # fatal
+}
+
+
+def get_otel_level_name(native_level: int) -> str:
+    """
+
+    Convert a native Python logging level number to an OTEL/logfire level name.
+
+    """
+
+    from logfire._internal import constants
+
+    otel_num = constants.LOGGING_TO_OTEL_LEVEL_NUMBERS[native_level]
+    name = constants.NUMBER_TO_LEVEL[otel_num]
+    return name
+
+
+def get_native_level_from_otel(otel_name: str) -> int:
+    """
+
+    Convert an OTEL/logfire level name to a native Python logging level number.
+
+    """
+    from logfire._internal import constants
+
+    otel_num = constants.LEVEL_NUMBERS[otel_name]
+    level = OTEL_TO_NATIVE[otel_num]
+    return level
+
+
 logger = get_logger(name=Constants.LIBRARY_NAME)
 
 if __name__ == '__main__':
     logger.info('Hello World')
     logger.warning('test warning')
     logger.debug('Hello World')
+    logger

fmtr/tools/mqtt_tools.py

@@ -0,0 +1,89 @@
+import aiomqtt
+import logging
+from dataclasses import dataclass, asdict
+from paho.mqtt.client import CleanStartOption, MQTT_CLEAN_START_FIRST_ONLY
+from typing import Literal, Self
+
+from fmtr.tools.logging_tools import logger, get_current_level, get_native_level_from_otel
+
+LOGGER = logging.getLogger("mqtt")
+LOGGER.handlers.clear()
+LOGGER.addHandler(logger.LogfireLoggingHandler())
+LOGGER.propagate = False
+
+
+@dataclass
+class Args:
+    """
+
+    The (serialisable subset of the) init args for Client (e.g. for init via Pydantic Settings)
+
+    """
+    hostname: str
+    port: int = 1883
+    username: str | None = None
+    password: str | None = None
+    identifier: str | None = None
+    clean_session: bool | None = None
+    transport: Literal["tcp", "websockets", "unix"] = "tcp"
+    timeout: float | None = None
+    keepalive: int = 60
+    bind_address: str = ""
+    bind_port: int = 0
+    clean_start: CleanStartOption = MQTT_CLEAN_START_FIRST_ONLY
+    max_queued_incoming_messages: int | None = None
+    max_queued_outgoing_messages: int | None = None
+    max_inflight_messages: int | None = None
+    max_concurrent_outgoing_calls: int | None = None
+    tls_insecure: bool | None = None
+
+
+
+
+class Client(aiomqtt.Client):
+    """
+
+    Client stub
+
+    """
+
+    LOGGER = LOGGER
+    SYNC_LOG_LEVEL = False
+    Args = Args
+
+    def __init__(self, *args, **kwargs):
+        """
+
+        Seems a little goofy to sync with logfire on every init, but unsure how to do it better.
+
+        """
+        if self.SYNC_LOG_LEVEL:
+            self.sync_log_level()
+        super().__init__(*args, **kwargs)
+
+    def sync_log_level(self):
+        """
+
+        Sync log level with logfire, which might have changed since handler set.
+
+        """
+        level = get_current_level(logger)
+        level_no = get_native_level_from_otel(level)
+        self.LOGGER.setLevel(level_no)
+
+    @classmethod
+    def from_args(cls, args_obj: Args, **kwargs) -> Self:
+        """
+
+        Initialise from Args dataclass.
+
+        """
+        args = asdict(args_obj) | kwargs
+        return cls(**args)
+
+class Will(aiomqtt.Will):
+    """
+
+    Will stub
+
+    """

fmtr/tools/networking_tools.py

@@ -0,0 +1,73 @@
+import socket
+
+import uuid
+from dataclasses import dataclass, field
+from functools import cached_property
+
+get_hostname = socket.gethostname
+get_fqdn = socket.getfqdn
+
+
+@dataclass(frozen=True)
+class MAC:
+    value: int = field(default_factory=uuid.getnode)
+
+    @classmethod
+    def from_string(cls, s: str):
+        """
+
+        Initialise from a string.
+
+        """
+        s = s.lower().replace(":", "").replace("-", "")
+        return cls(int(s, 16))
+
+    @cached_property
+    def int(self):
+        return self.value
+
+    @cached_property
+    def hex(self):
+        """
+
+        Plain 12-character hex string, no separators.
+
+        """
+        return f"{self.value:012x}"
+
+    @cached_property
+    def components(self):
+        """
+
+        Return list of six 2-digit hex strings.
+
+        """
+        h = self.hex
+        return [h[i:i + 2] for i in range(0, 12, 2)]
+
+    @cached_property
+    def hex_colon(self):
+        """
+
+        Colon-separated hex string (default standard).
+
+        """
+        return self.string(":")
+
+    @cached_property
+    def is_random(self) -> bool:
+        """
+
+        Detect if this MAC is likely randomly generated by uuid.getnode().
+        Checks the "multicast" bit (bit 1 of the first byte).
+
+        """
+        return bool(self.value & (1 << 40))
+
+    def string(self, sep: str = ":") -> str:
+        """
+
+        Return MAC as a string with separator `sep`.
+
+        """
+        return sep.join(self.components)

fmtr/tools/packaging_tools.py

@@ -0,0 +1,14 @@
+import importlib.metadata
+
+
+def get_version(module):
+    """
+
+    Retrieve the version of a specified module.
+
+    """
+
+    if type(module) is not str:
+        module = module.__name__
+    version = importlib.metadata.version(module)
+    return version

fmtr/tools/path_tools/__init__.py

@@ -0,0 +1,12 @@
+from fmtr.tools.import_tools import MissingExtraMockModule
+from fmtr.tools.path_tools.path_tools import Path, PackagePaths, root
+
+try:
+    from fmtr.tools.path_tools.app_path_tools import AppPaths
+except ModuleNotFoundError as exception:
+    AppPaths = MissingExtraMockModule('path.app', exception)
+
+try:
+    from fmtr.tools.path_tools.type_path_tools import guess
+except ModuleNotFoundError as exception:
+    guess = MissingExtraMockModule('path.type', exception)

fmtr/tools/path_tools/app_path_tools.py

@@ -0,0 +1,40 @@
+import appdirs
+
+from fmtr.tools.path_tools import Path
+
+
+class AppPaths:
+    """
+
+    Wrap appdirs to return Path objects
+
+    """
+    PathType = Path
+
+    def user_data_dir(self, appname=None, appauthor=None, version=None, roaming=False):
+        path_str = appdirs.user_data_dir(appname=appname, appauthor=appauthor, version=version, roaming=roaming)
+        return self.PathType(path_str)
+
+    def user_config_dir(self, appname=None, appauthor=None, version=None, roaming=False):
+        path_str = appdirs.user_config_dir(appname=appname, appauthor=appauthor, version=version, roaming=roaming)
+        return self.PathType(path_str)
+
+    def site_config_dir(self, appname=None, appauthor=None, version=None):
+        path_str = appdirs.site_config_dir(appname=appname, appauthor=appauthor, version=version, multipath=False)
+        return self.PathType(path_str)
+
+    def site_data_dir(self, appname=None, appauthor=None, version=None):
+        path_str = appdirs.site_data_dir(appname=appname, appauthor=appauthor, version=version, multipath=False)
+        return self.PathType(path_str)
+
+    def user_cache_dir(self, appname=None, appauthor=None, version=None):
+        path_str = appdirs.user_cache_dir(appname=appname, appauthor=appauthor, version=version)
+        return self.PathType(path_str)
+
+    def user_state_dir(self, appname=None, appauthor=None, version=None):
+        path_str = appdirs.user_state_dir(appname=appname, appauthor=appauthor, version=version)
+        return self.PathType(path_str)
+
+    def user_log_dir(self, appname=None, appauthor=None, version=None):
+        path_str = appdirs.user_log_dir(appname=appname, appauthor=appauthor, version=version)
+        return self.PathType(path_str)