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

fmtr/tools/__init__.py

@@ -1,4 +1,4 @@
-import fmtr.tools.async_tools as asyncio
+import fmtr.tools.async_tools as aio
 import fmtr.tools.database_tools as db
 import fmtr.tools.dataclass_tools as dataclass
 import fmtr.tools.datatype_tools as datatype
@@ -12,6 +12,7 @@ import fmtr.tools.iterator_tools as iterator
 import fmtr.tools.json_tools as json
 import fmtr.tools.logging_tools as logging
 import fmtr.tools.name_tools as name
+import fmtr.tools.networking_tools as net
 import fmtr.tools.packaging_tools as packaging
 import fmtr.tools.path_tools as path
 import fmtr.tools.platform_tools as platform
@@ -22,6 +23,7 @@ from fmtr.tools import ai_tools as ai
 from fmtr.tools import datetime_tools as dt
 from fmtr.tools import dns_tools as dns
 from fmtr.tools import docker_tools as docker
+from fmtr.tools import ha_tools as ha
 from fmtr.tools import interface_tools as interface
 from fmtr.tools import version_tools as version
 from fmtr.tools.constants import Constants
@@ -171,6 +173,22 @@ try:
 except ModuleNotFoundError as exception:
     webhook = MissingExtraMockModule('webhook', exception)
 
+try:
+    from fmtr.tools import mqtt_tools as mqtt
+except ModuleNotFoundError as exception:
+    mqtt = MissingExtraMockModule('mqtt', exception)
+
+try:
+    from fmtr.tools import av_tools as av
+except ModuleNotFoundError as exception:
+    av = MissingExtraMockModule('av', exception)
+
+try:
+    from fmtr.tools import youtube_tools as youtube
+except ModuleNotFoundError as exception:
+    youtube = MissingExtraMockModule('youtube', exception)
+
+
 
 def get_version():
     """

fmtr/tools/api_tools.py

@@ -1,12 +1,18 @@
-import uvicorn
+import logging
 from dataclasses import dataclass
-from fastapi import FastAPI, Request
 from typing import Callable, List, Optional, Union
 
+import uvicorn
+from fastapi import FastAPI, Request
+
 from fmtr.tools import environment_tools
 from fmtr.tools.iterator_tools import enlist
 from fmtr.tools.logging_tools import logger
 
+for name in ["uvicorn.access", "uvicorn.error", "uvicorn"]:
+    logger_uvicorn = logging.getLogger(name)
+    logger_uvicorn.handlers.clear()
+    logger_uvicorn.propagate = False
 
 @dataclass
 class Endpoint:
@@ -34,6 +40,7 @@ class Base:
     HOST = '0.0.0.0'
     PORT = 8080
     SWAGGER_PARAMS = dict(tryItOutEnabled=True)
+    URL = None
     URL_DOCS = '/docs'
 
     def add_endpoint(self, endpoint: Endpoint):
@@ -83,17 +90,68 @@ class Base:
         exception
         raise
 
+    @property
+    def url(self) -> str:
+        """
+
+        Default URL unless overridden.
+
+        """
+        if self.URL:
+            url = self.URL
+        else:
+            url = f'http://{self.HOST}:{self.PORT}'
+        return url
+
+    @property
+    def message(self) -> str:
+        """
+
+        Launch message.
+
+        """
+        return f"Launching {self.TITLE} at {self.url}"
+
+    @property
+    def config(self) -> uvicorn.Config:
+        """
+
+        Uvicorn config.
+
+        """
+        return uvicorn.Config(self.app, host=self.HOST, port=self.PORT, access_log=False)
+
+    @property
+    def server(self) -> uvicorn.Server:
+        """"
+
+        Uvicorn server.
+
+        """
+        return uvicorn.Server(self.config)
 
     @classmethod
-    def launch(cls):
+    async def launch_async(cls, *args, **kwargs):
         """
 
-        Initialise self and launch.
+        Initialise and launch.
 
         """
-        self = cls()
-        logger.info(f'Launching API {cls.TITLE}...')
-        uvicorn.run(self.app, host=self.HOST, port=self.PORT)
+
+        self = cls(*args, **kwargs)
+        logger.info(self.message)
+        await self.server.serve()
+
+    @classmethod
+    def launch(cls, *args, **kwargs):
+        """
+
+        Convenience method to launch async from a regular context.
+
+        """
+        import asyncio
+        return asyncio.run(cls.launch_async(*args, **kwargs))
+
 
 
 if __name__ == '__main__':

fmtr/tools/async_tools.py

@@ -1,4 +1,5 @@
 import asyncio
+import inspect
 
 
 def ensure_loop():
@@ -13,3 +14,6 @@ def ensure_loop():
         loop = asyncio.new_event_loop()
         asyncio.set_event_loop(loop)
         return loop
+
+
+is_async = inspect.iscoroutinefunction

fmtr/tools/av_tools.py

@@ -0,0 +1,7 @@
+import av
+
+av = av
+
+open = av.open
+AudioResampler = av.AudioResampler
+AudioFrame = av.AudioFrame

fmtr/tools/constants.py

@@ -14,9 +14,14 @@ class Constants:
     DATETIME_NOW_STR = DATETIME_NOW.strftime(DATETIME_FILENAME_FORMAT)
     SERIALIZATION_INDENT = 4
 
+    ENV_NESTED_DELIMITER = '__'
+
     ARROW = '→'
+    ARROW_RIGHT = ARROW
     ARROW_SEP = f' {ARROW} '
 
+    ARROW_LEFT = '←'
+
     FMTR_DEV_KEY = 'FMTR_DEV'
     FMTR_LOG_LEVEL_KEY = 'FMTR_LOG_LEVEL'
     FMTR_OBS_API_KEY_KEY = 'FMTR_OBS_API_KEY'
@@ -49,9 +54,12 @@ class Constants:
     ENTRYPOINT = 'entrypoint'
     ENTRYPOINTS_DIR = f'{ENTRYPOINT}s'
     ENTRYPOINT_FILE = f'{ENTRYPOINT}.py'
+    SCRIPTS_DIR = 'scripts'
 
-    PACKAGE_EXCLUDE_DIRS = {'data', 'build', 'dist', '.*', '*egg-info*'}
+    PACKAGE_EXCLUDE_DIRS = {SCRIPTS_DIR, 'data', 'build', 'dist', '.*', '*egg-info*'}
     INIT_FILENAME = '__init__.py'
+    DOCS_DIR = 'docs'
+    DOCS_CONFIG_FILENAME = 'mkdocs.yml'
 
     DEVELOPMENT = "development"
     PRODUCTION = "production"

fmtr/tools/datatype_tools.py

@@ -3,7 +3,7 @@ from typing import Any, get_origin, get_args, Union, Annotated
 
 from fmtr.tools.tools import Raise
 
-TRUES = {str(True).lower(), str(1), 'y', 'yes'}
+TRUES = {str(True).lower(), str(1), 'y', 'yes', 'on'}
 
 
 class TypeConversionFailed(ValueError):

fmtr/tools/debugging_tools.py

@@ -1,7 +1,5 @@
 import dataclasses
 
-import pydevd_pycharm
-
 from fmtr.tools import environment_tools as env
 from fmtr.tools.constants import Constants
 
@@ -64,6 +62,7 @@ def trace(is_debug=None, host=None, port=None, stdoutToServer=True, stderrToServ
     msg = MASK.format(host=host, port=port)
     logger.info(msg)
 
+    import pydevd_pycharm
     pydevd_pycharm.settrace(host, port=port, stdoutToServer=stdoutToServer, stderrToServer=stderrToServer, **kwargs)
 
 

fmtr/tools/environment_tools.py

@@ -77,3 +77,4 @@ get_datetime = get_getter(datetime.fromisoformat)
 get_path = get_getter(Path)
 
 IS_DEV = get_bool(Constants.FMTR_DEV_KEY, default=False)
+CHANNEL = Constants.DEVELOPMENT if IS_DEV else Constants.PRODUCTION

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

@@ -1,5 +1,6 @@
 import httpx
-from httpx_retries import RetryTransport
+from functools import cached_property
+from httpx_retries import RetryTransport, Retry
 
 from fmtr.tools import logging_tools
 
@@ -13,14 +14,39 @@ class Client(httpx.Client):
 
     """
 
-    TRANSPORT = RetryTransport()
+    TIMEOUT = 10
 
     def __init__(self, *args, **kwargs):
-        super().__init__(*args, transport=self.TRANSPORT, **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('http://httpbin.org/delay/10')
+    resp = client.get('https://postman-echo.com/delay/5')
+    resp.raise_for_status()
+    print(resp.json())
     resp

fmtr/tools/iterator_tools.py

@@ -1,5 +1,6 @@
 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
 
@@ -81,3 +82,94 @@ def get_class_lookup(*classes, name_function=lambda cls: cls.__name__):
 
     """
     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

@@ -10,17 +10,7 @@ else:
     STREAM_DEFAULT = None
     ENVIRONMENT_DEFAULT = Constants.PRODUCTION
 
-IS_DEBUG = environment_tools.get(Constants.FMTR_LOG_LEVEL_KEY, None, converter=str.upper) == 'DEBUG'
-LEVEL_DEFAULT = logging.DEBUG if IS_DEBUG else logging.INFO
-
-
-def null_scrubber(match):
-    """
-
-    Effectively disable scrubbing
-
-    """
-    return match.value
+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):
@@ -58,9 +48,7 @@ def get_logger(name, version=None, host=Constants.FMTR_OBS_HOST, key=None, org=C
         from fmtr.tools import version_tools
         version = version_tools.read()
 
-    # Rigmarole to translate native levels to logfire/otel ones.
-    lev_num_otel = logfire._internal.constants.LOGGING_TO_OTEL_LEVEL_NUMBERS[level]
-    lev_name_otel = logfire._internal.constants.NUMBER_TO_LEVEL[lev_num_otel]
+    lev_name_otel = get_otel_level_name(level)
 
     console_opts = logfire.ConsoleOptions(
         colors='always',
@@ -76,13 +64,79 @@ def get_logger(name, version=None, host=Constants.FMTR_OBS_HOST, key=None, org=C
         scrubbing=logfire.ScrubbingOptions(callback=null_scrubber)
     )
 
-    if key is None:
-        msg = f'Observability dependencies installed, but "{Constants.FMTR_OBS_API_KEY_KEY}" not set. Cloud observability will be disabled.'
-        logger.warning(msg)
-
     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__':

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
+
+    """