fakts-next 1.0.0__tar.gz

fakts_next-1.0.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.1
+Name: fakts-next
+Version: 1.0.0
+Summary: asynchronous configuration provider ( tailored to support dynamic client-server relations)
+License: CC BY-NC 3.0
+Author: jhnnsrs
+Author-email: jhnnsrs@gmail.com
+Requires-Python: >=3.8,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: cli
+Provides-Extra: remote
+Requires-Dist: PyYAML (>=6)
+Requires-Dist: QtPy (>=2.0.1,<3.0.0)
+Requires-Dist: aiohttp (>=3.8.2,<4.0.0) ; extra == "remote"
+Requires-Dist: certifi (>2021) ; extra == "remote"
+Requires-Dist: koil (>=1.0.0)
+Requires-Dist: netifaces (>=0.11.0,<0.12.0) ; extra == "cli"
+Requires-Dist: pydantic (>2)
+Requires-Dist: rich_click (>=0.3) ; extra == "cli"
+Description-Content-Type: text/markdown
+
+# fakts
+
+[![codecov](https://codecov.io/gh/jhnnsrs/fakts/branch/master/graph/badge.svg?token=UGXEA2THBV)](https://codecov.io/gh/jhnnsrs/fakts)
+[![PyPI version](https://badge.fury.io/py/fakts.svg)](https://pypi.org/project/fakts/)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://pypi.org/project/fakts/)
+![Maintainer](https://img.shields.io/badge/maintainer-jhnnsrs-blue)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/fakts.svg)](https://pypi.python.org/pypi/fakts/)
+[![PyPI status](https://img.shields.io/pypi/status/fakts.svg)](https://pypi.python.org/pypi/fakts/)
+[![PyPI download day](https://img.shields.io/pypi/dm/fakts.svg)](https://pypi.python.org/pypi/fakts/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/jhnnsrs/fakts)
+
+
+## Inspiration
+
+Fakts was designed to make configuration of apps compatible with modern concurrency patterns, it is designed to allow
+for asynchronous retrieval of configuration from various sources, may it be a config file, environmental variables
+or a remote server (via the "fakts remote protocol", described in the documentation.).
+
+Fakts was conceived as a way to provide a configuration interface for the [arkitekt](https://arkitekt.live) platform,
+where clients needed to dynamically retrieve configuration from a remote server, but it is designed to be used in any python project.
+
+# Core Design
+
+Fakts uses `Grants` to obtain configuration asynchronously, a grant is a way of retrieving the configuration from a
+specific source. It can be a local config file (eg. yaml, toml, json), environemnt variables, a remote configuration (eg. from a fakts server), or a database.
+The `Fakts` class then wraps the grant to ensure both a sychronous and asychronous interface that is threadsafe.
+
+Grants are designed to be composable through `MetaGrants` so by desigining a specifc grant structure, one can
+highly customize the retrieval logic. Please check out the documentation for more information.
+
+# Example:
+
+By default fakts follows a key-value structure, where the key is a string, and the value can be any serializable
+python object.
+
+```python
+async with Fakts(grant=YamlGrant("config.yaml")) as fakts:
+    config = await fakts.aget("group_name")
+    # will return the configuration for the group_name key in the yaml file
+```
+
+or
+
+```python
+with Fakts(grant=YamlGrant("config.yaml")) as fakts:
+    value = fakts.get("nested.key.path")
+    # will return the configuration for a nested key in the yaml file
+```
+
+Fakts should be used as a context manager, and will set the current fakts context variable to itself, letting
+you access the current fakts instance from anywhere in your code (async or sync) without specifically passing a referece.
+
+
+# Composability
+
+You can compose grants through meta grants in order to load configuration from multiple sources (eg. a local, file
+that can be overwritten by a remote configuration, or some envionment variables).
+
+Example:
+
+```python
+async with Fakts(grant=FailsafeGrant(
+    grants=[
+        EnvGrant(),
+        YamlGrant("config.yaml")
+    ]
+)) as fakts:
+    config = await fakts.get("group_name")
+```
+
+In this example fakts will load the configuration from the environment variables first, and if that fails,
+it will load it from the yaml file.
+
+## Fakts Remote Protocol
+
+Fakts provides the remote grant protocol for retrieval of configuration in dynamic client-server relationships.
+With these grants you provide a software manifest for a configuration server (fakts-server), that then grants
+the configuration (either through user approval (similar to device code grant)). These grants are mainly used
+to setup or claim an oauth2 application on the backend securely that then can be used to identify the application in the
+future. These grants are at the moment highly specific to the arkitekt platform and subject to change.
+
+

fakts_next-1.0.0/README.md

@@ -0,0 +1,83 @@
+# fakts
+
+[![codecov](https://codecov.io/gh/jhnnsrs/fakts/branch/master/graph/badge.svg?token=UGXEA2THBV)](https://codecov.io/gh/jhnnsrs/fakts)
+[![PyPI version](https://badge.fury.io/py/fakts.svg)](https://pypi.org/project/fakts/)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://pypi.org/project/fakts/)
+![Maintainer](https://img.shields.io/badge/maintainer-jhnnsrs-blue)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/fakts.svg)](https://pypi.python.org/pypi/fakts/)
+[![PyPI status](https://img.shields.io/pypi/status/fakts.svg)](https://pypi.python.org/pypi/fakts/)
+[![PyPI download day](https://img.shields.io/pypi/dm/fakts.svg)](https://pypi.python.org/pypi/fakts/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/jhnnsrs/fakts)
+
+
+## Inspiration
+
+Fakts was designed to make configuration of apps compatible with modern concurrency patterns, it is designed to allow
+for asynchronous retrieval of configuration from various sources, may it be a config file, environmental variables
+or a remote server (via the "fakts remote protocol", described in the documentation.).
+
+Fakts was conceived as a way to provide a configuration interface for the [arkitekt](https://arkitekt.live) platform,
+where clients needed to dynamically retrieve configuration from a remote server, but it is designed to be used in any python project.
+
+# Core Design
+
+Fakts uses `Grants` to obtain configuration asynchronously, a grant is a way of retrieving the configuration from a
+specific source. It can be a local config file (eg. yaml, toml, json), environemnt variables, a remote configuration (eg. from a fakts server), or a database.
+The `Fakts` class then wraps the grant to ensure both a sychronous and asychronous interface that is threadsafe.
+
+Grants are designed to be composable through `MetaGrants` so by desigining a specifc grant structure, one can
+highly customize the retrieval logic. Please check out the documentation for more information.
+
+# Example:
+
+By default fakts follows a key-value structure, where the key is a string, and the value can be any serializable
+python object.
+
+```python
+async with Fakts(grant=YamlGrant("config.yaml")) as fakts:
+    config = await fakts.aget("group_name")
+    # will return the configuration for the group_name key in the yaml file
+```
+
+or
+
+```python
+with Fakts(grant=YamlGrant("config.yaml")) as fakts:
+    value = fakts.get("nested.key.path")
+    # will return the configuration for a nested key in the yaml file
+```
+
+Fakts should be used as a context manager, and will set the current fakts context variable to itself, letting
+you access the current fakts instance from anywhere in your code (async or sync) without specifically passing a referece.
+
+
+# Composability
+
+You can compose grants through meta grants in order to load configuration from multiple sources (eg. a local, file
+that can be overwritten by a remote configuration, or some envionment variables).
+
+Example:
+
+```python
+async with Fakts(grant=FailsafeGrant(
+    grants=[
+        EnvGrant(),
+        YamlGrant("config.yaml")
+    ]
+)) as fakts:
+    config = await fakts.get("group_name")
+```
+
+In this example fakts will load the configuration from the environment variables first, and if that fails,
+it will load it from the yaml file.
+
+## Fakts Remote Protocol
+
+Fakts provides the remote grant protocol for retrieval of configuration in dynamic client-server relationships.
+With these grants you provide a software manifest for a configuration server (fakts-server), that then grants
+the configuration (either through user approval (similar to device code grant)). These grants are mainly used
+to setup or claim an oauth2 application on the backend securely that then can be used to identify the application in the
+future. These grants are at the moment highly specific to the arkitekt platform and subject to change.
+

fakts_next-1.0.0/fakts_next/__init__.py

@@ -0,0 +1,32 @@
+"""Fakts package.
+
+Fakts is a configuration management library. It allows you to
+load configuration from different sources and use it in your
+application.
+
+In comparison to other configuration management libraries, Fakts
+is designed to be used in an async environment, or with primarily
+async grants (e.g. a database). It also allows you to use multiple
+grants at the same time, and will merge the results together.
+
+Fakts comes also with a few remote grants, that allow you to connect
+to a remote configuration server, and fetch the configuration from
+there, and follows a similar design the oauth2 protocol, to allow for
+safe and secure configuration management.
+
+"""
+
+from .fakts import Fakts, FaktsGrant, get_current_fakts_next
+from .errors import FaktsError
+from .grants import EnvGrant, GrantError
+
+
+__all__ = [
+    "Fakts",
+    "Fakt",
+    "FaktsGrant",
+    "EnvGrant",
+    "GrantError",
+    "get_current_fakts_next",
+    "FaktsError",
+]

fakts_next-1.0.0/fakts_next/cache/file.py

@@ -0,0 +1,148 @@
+import os
+from typing import Any, Dict, Optional
+import pydantic
+import datetime
+import logging
+import json
+from fakts_next.protocols import FaktValue, FaktsGrant
+
+logger = logging.getLogger(__name__)
+
+
+class CacheFile(pydantic.BaseModel):
+    """Cache file model"""
+
+    config: Dict[str, Any]
+    created: datetime.datetime
+    hash: str = ""
+
+
+class FileCache(pydantic.BaseModel):
+    """Grant that caches the result of another grant
+
+    This grant will cache the result of another grant in a file.
+    It will load the grant on the first call, and then will load
+    the cached version of the grant.
+
+    Only if the cache is expired, or a "hash" value that is passed
+    to the grant is different from the one in the cache, will it
+    load the grant again.
+
+    You can set the expires_in parameter to set the time in seconds
+    for the cache to expire.
+
+    FaktsRequest context parameters:
+        - allow_cache: bool - whether to allow the grant to use the cache
+
+
+    Attributes
+    ----------
+    grant : FaktsGrant
+        The grant to cache
+    cache_file : str
+        The path to the cache file
+    hash : str
+        The hash to validate the cache against
+    expires_in : Optional[int]
+        The time in seconds for the cache to expire
+
+
+    """
+
+    model_config = pydantic.ConfigDict(arbitrary_types_allowed=True)
+    """The grant to cache"""
+
+    cache_file: str = ".fakts_cache.json"
+    """The path to the cache file"""
+    hash: str = pydantic.Field(
+        default_factory=lambda: "",
+        description="Validating against the hash of the config",
+    )
+    """The hash to validate the cache against (if this value differes from the one in the cache, the grant will be reloaded)"""
+
+    expires_in: Optional[int] = None
+    """When should the cache expire"""
+
+    async def aload(self) -> Optional[Dict[str, FaktValue]]:
+        """Loads the configuration from the grant
+
+        It will try to load the configuration from the cache file.
+        If the cache is expired, or the hash value is different from
+        the one in the cache, it will load the grant again.
+
+        Parameters
+        ----------
+        request : FaktsRequest
+            The request object that may contain additional information needed for loading the configuration.
+
+        Returns
+        -------
+        dict
+            The configuration loaded from the grant.
+
+
+        """
+
+        cache = None
+
+        if (
+            os.path.exists(self.cache_file)
+        ):
+            with open(self.cache_file, "r") as f:
+                x = json.load(f)
+                try:
+                    cache = CacheFile(**x)
+
+                    if self.hash and cache.hash != self.hash:
+                        cache = None
+
+                    elif self.expires_in:
+                        if (
+                            cache.created + datetime.timedelta(seconds=self.expires_in)
+                            < datetime.datetime.now()
+                        ):
+                            cache = None
+
+                except pydantic.ValidationError as e:
+                    logger.error(f"Could not load cache file: {e}. Ignoring it")
+
+                if cache is None:
+                        return None
+                
+
+                return cache.config
+
+    async def aset(self, value: Dict[str, FaktValue]):
+        """Refreshes the configuration from the grant
+
+        This function is used to refresh the configuration from the grant.
+        This is used to refresh the configuration from the grant, and should
+        be used to refresh the configuration from the grant.
+
+        The request object is used to pass information
+        """
+
+        cache = CacheFile(
+            config=value, created=datetime.datetime.now(), hash=self.hash
+        )
+
+        with open(self.cache_file, "w+") as f:
+            print("Setting cache", cache.model_dump_json())
+            json.dump(json.loads(cache.model_dump_json()), f)
+
+
+    async def areset(self):
+        """Resets the cache
+
+        This function is used to reset the cache.
+        This is used to reset the cache, and should
+        be used to reset the cache.
+
+        The request object is used to pass information
+        """
+
+        if os.path.exists(self.cache_file):
+            os.remove(self.cache_file)
+        return None
+
+

fakts_next-1.0.0/fakts_next/cache/model.py

@@ -0,0 +1,11 @@
+import pydantic
+from typing import Dict, Any
+import datetime
+
+
+class CacheModel(pydantic.BaseModel):
+    """Cache file model"""
+
+    config: Dict[str, Any]
+    created: datetime.datetime
+    hash: str = ""

fakts_next-1.0.0/fakts_next/cache/nocache.py

@@ -0,0 +1,55 @@
+from typing import Any, Dict, Optional
+from fakts_next.protocols import FaktValue, FaktsGrant
+
+
+
+class NoCache:
+
+
+    async def aload(self) -> Optional[Dict[str, FaktValue]]:
+        """Loads the configuration from the grant
+
+        It will try to load the configuration from the cache file.
+        If the cache is expired, or the hash value is different from
+        the one in the cache, it will load the grant again.
+
+        Parameters
+        ----------
+        request : FaktsRequest
+            The request object that may contain additional information needed for loading the configuration.
+
+        Returns
+        -------
+        dict
+            The configuration loaded from the grant.
+
+
+        """
+
+        cache = None
+
+        return None
+
+    async def aset(self, value: Dict[str, FaktValue]):
+        """Refreshes the configuration from the grant
+
+        This function is used to refresh the configuration from the grant.
+        This is used to refresh the configuration from the grant, and should
+        be used to refresh the configuration from the grant.
+
+        The request object is used to pass information
+        """
+
+        pass
+
+    async def areset(self):
+        """Resets the cache
+
+        This function is used to reset the cache.
+        This is used to reset the cache, and should
+        be used to reset the cache.
+
+        The request object is used to pass information
+        """
+
+        pass

fakts_next-1.0.0/fakts_next/cache/qt/settings.py

@@ -0,0 +1,79 @@
+import logging
+from qtpy import QtCore
+
+from fakts.grants.remote.models import FaktsEndpoint
+from typing import Optional, Dict
+import datetime
+from fakts.protocols import FaktValue
+from pydantic import BaseModel, ConfigDict, Field
+from fakts_next.cache.model import CacheModel
+logger = logging.getLogger(__name__)
+
+
+class QtSettingsCache(BaseModel):
+    """Retrieves and stores users matching the currently
+    active fakts grant"""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    settings: QtCore.QSettings
+    save_key: str
+    hash: str = Field(
+        default_factory=lambda: "",
+        description="Validating against the hash of the config",
+    )
+
+
+    async def aset(self, value: Dict[str, FaktValue]) -> None:
+        """Stores the value in the settings
+
+        Parameters
+        ----------
+        value : Dict[str, FaktValue]
+            The value to store
+        """
+
+        cache = CacheModel(
+            config=value, created=datetime.datetime.now(), hash=self.hash
+        )
+
+
+
+
+        self.settings.setValue(self.save_key, cache.model_dump_json())
+
+    async def aload(self) -> Optional[Dict[str, FaktValue]]:
+        """Loads the value from the settings
+
+        Returns
+        -------
+        Optional[Dict[str, FaktValue]]
+            The value, or None if there is no value
+        """
+
+        un_storage = self.settings.value(self.save_key, None)
+        if not un_storage:
+            return None
+        try:
+            storage = CacheModel.model_validate_json(un_storage)
+            if storage.hash != self.hash:
+                return None
+            
+
+            
+            return storage.config
+        except Exception as e:
+            print(e)
+
+        return None
+
+    async def areset(self) -> Optional[FaktsEndpoint]:
+        """A function that gets the default endpoint
+
+        Returns
+        -------
+        Optional[FaktsEndpoint]
+            The stored endpoint, or None if there is no endpoint
+
+        """
+
+        self.settings.setValue(self.save_key, None)

fakts_next-1.0.0/fakts_next/cli/__init__.py

@@ -0,0 +1,12 @@
+""" Fakts CLI module.
+
+This module contains the CLI for the fakts_next package.
+It allows you act and interface with the fakts_next package
+from the command line.
+
+Currently it only supports advertising a fakts_next endpoint
+on the local network, but in the future it will also
+support other features, like fetching the configuration
+from a remote endpoint.
+
+"""

fakts_next-1.0.0/fakts_next/cli/advertise.py

@@ -0,0 +1,134 @@
+from typing import List
+from pydantic import BaseModel
+from socket import AF_INET, SOCK_DGRAM, SOL_SOCKET, SO_BROADCAST, socket
+import asyncio
+import json
+import logging
+
+
+logger = logging.getLogger(__name__)
+
+
+class BeaconProtocol(asyncio.DatagramProtocol):
+    """A protocol that sends beacons to a broadcast address
+
+    This protocol is used to send beacons to a broadcast address.
+    It is used by the advertise function.
+
+
+    """
+
+    pass
+
+
+class AdvertiseBeacon(BaseModel):
+    """A beacon that is sent when advertising"""
+
+    url: str
+
+
+class AdvertiseBinding(BaseModel):
+    """A binding for the advertise function
+
+    This binding specifies the interface to use, the broadcast address
+    and the address to bind to. It also specifies the port to use and
+    a magic phrase that is used to identify the beacon.
+
+    It is retrieved by the retrieve_bindings function, and
+    used by the advertise function.
+
+    """
+
+    interface: str
+    broadcast_addr: str
+    bind_addr: str
+    broadcast_port: int = 45678
+    magic_phrase: str = "beacon-fakts_next"
+
+
+def retrieve_bindings() -> List[AdvertiseBinding]:
+    """Uses the netifaces library to retrieve all available interfaces and
+    if they are up and running and have a broadcast address, it will return
+    a list of bindings for the beacon to use.
+
+    Raises:
+        ImportError: An importError is raised if the netifaces library is not installed
+
+    Returns:
+        List[Binding]: The list of bindings
+    """
+
+    try:
+        import netifaces
+    except ImportError as e:
+        raise ImportError(
+            "netifaces is required to use the advertised discovery. please install it seperately or install fakts_next with the 'beacon' extras"
+        ) from e
+
+    potential_bindings: List[AdvertiseBinding] = []
+
+    for interface in netifaces.interfaces():
+        addrs = netifaces.ifaddresses(interface)
+        if netifaces.AF_INET in addrs:
+            informations = addrs[netifaces.AF_INET]
+            for i in informations:
+                if "broadcast" in i:
+                    potential_bindings.append(
+                        AdvertiseBinding(
+                            interface=interface,
+                            bind_addr=i["addr"],
+                            broadcast_addr=i["broadcast"],
+                        )
+                    )
+    return potential_bindings
+
+
+async def advertise(
+    binding: AdvertiseBinding,
+    endpoints: List[AdvertiseBeacon],
+    interval: int = 1,
+    iterations: int = 10,
+) -> None:
+    """Advertises the given endpoints on the given binding
+
+    This function opens a udp socket and sends the endpoints as json to the broadcast address
+    on the given port. It will repeat this for the given number of iterations with the given
+    interval in between.
+
+    If interval is -1 it will repeat forever, until this task is cancelled
+
+    Args:
+        binding (Binding): The binding to use (interface, broadcast address, port)
+        endpoints (List[FaktsEndpoint]): The list of endpoints to advertise
+        interval (int, optional): The interval between a beacon send in seconds. Defaults to 1.
+        iterations (int, optional): The amount of sends that should happen, -1 means infinite (until cancelled). Defaults to 10.
+
+    """
+
+    s = socket(AF_INET, SOCK_DGRAM)  # create UDP socket.
+
+    try:
+        s.bind((binding.bind_addr, 0))
+        s.setsockopt(SOL_SOCKET, SO_BROADCAST, 1)  # this is a broadcast socket
+
+        loop = asyncio.get_event_loop()
+        transport, pr = await loop.create_datagram_endpoint(BeaconProtocol, sock=s)
+
+        messages = [
+            bytes(binding.magic_phrase + json.dumps(beacon.model_dump()), "utf8")
+            for beacon in endpoints
+        ]
+        i = 1
+        while i <= iterations or iterations == -1:
+            for message in messages:
+                transport.sendto(  # type: ignore
+                    message, (binding.broadcast_addr, binding.broadcast_port)
+                )
+                logger.debug(f"Send Message {message!r}")
+
+            await asyncio.sleep(interval)
+            i += 1
+    except asyncio.CancelledError as e:
+        transport.close()
+        s.close()
+        raise e