pyflexcfg 0.2.0__tar.gz

pyflexcfg-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Pavel Tserakhau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyflexcfg-0.2.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.1
+Name: pyflexcfg
+Version: 0.2.0
+Summary: Flexible configuration handler for Python projects.
+Home-page: https://github.com/pavelterex/PyFlexCfg
+License: MIT
+Author: Pavel T
+Author-email: pavelterex@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: cryptography (>=43.0.3,<44.0.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Project-URL: Repository, https://github.com/pavelterex/PyFlexCfg
+Description-Content-Type: text/markdown
+
+# PyFlexCfg
+
+Flexible configuration handler for Python projects.
+
+### Description
+
+The handler (a.k.a. Cfg) allows to store project's configuration in YAML files and load them at once when imported.
+
+### Installation
+
+```shell
+pip install pyflexcfg
+```
+
+### Configuration
+
+In order to use encryption\decryption for configuration secrets, make sure to
+set an environment variable **PYFLEX_CFG_KEY** with some encryption key, which will be
+used for secrets encryption\decryption.
+
+By default, Cfg searches for configuration files in the **config** directory
+within current working dir. In order to specify a different path, crate a nenv variable
+**PYFLEX_CFG_ROOT_PATH** with the absolute path to the configuration root.
+
+### Basic Usage
+
+Assuming you have such configuration files structure:
+```
+    \project
+        ├─ config
+            ├─ general.yaml
+            ├─ env
+                ├─ dev.yaml
+                ├─ prd.yaml
+   ```
+And each of the yaml files contains a configuration option **data: test**
+
+Just import the Cfg and you can use your configuration at once:
+
+```python
+from pyflexcfg import Cfg
+
+print(Cfg.general.data)
+print(Cfg.env.dev.data)
+print(Cfg.env.prd.data)
+```
+
+Make sure the names of directories within your configuration are Python object's attribute name compatible.
+
+
+### Override by environment variables
+
+There is an option to override values in YAML files with values from environment variables.
+In order to do so, you have to create env variables which reflect the name of config value to be overwritten.
+For example, if you want to overwrite value for
+```
+Cfg.env.dev.data
+```
+you have to create env variable like this
+```
+CFG__ENV__DEV__DATA
+```
+Having that, you can call 
+```python
+Cfg.update_from_env()
+``` 
+and the value from the YAML file will be overwritten by the value from env variable.
+
+
+### Handling secrets
+
+Any sensitive data to be stored within your configuration files should be encrypted!
+
+Encrypt your secret:
+```python
+from pyflexcfg import AESCipher
+
+aes = AESCipher('secret-key')
+aes.encrypt('some-secret-to-encrypt')
+```
+You will get output like
+
+```python
+b'A1u6BIE2xGtYTSoFRE83H0VHsAW3nrv4WB+T/FEAj1fsh8HIId9r/Rskl0bnDHTI'
+```
+and it can be stored in yaml file with **!encr** prefix:
+
+```yaml
+my_secret: !encr b'A1u6BIE2xGtYTSoFRE83H0VHsAW3nrv4WB+T/FEAj1fsh8HIId9r/Rskl0bnDHTI'
+```
+
+The next time Cfg will be loading this configuration file it will automatically decrypt
+this value, but do not forget to set up env variable **PYFLEX_CFG_KEY** with your 'secret-key',
+otherwise Cfg won't be able to decrypt the data.

pyflexcfg-0.2.0/README.md

@@ -0,0 +1,94 @@
+# PyFlexCfg
+
+Flexible configuration handler for Python projects.
+
+### Description
+
+The handler (a.k.a. Cfg) allows to store project's configuration in YAML files and load them at once when imported.
+
+### Installation
+
+```shell
+pip install pyflexcfg
+```
+
+### Configuration
+
+In order to use encryption\decryption for configuration secrets, make sure to
+set an environment variable **PYFLEX_CFG_KEY** with some encryption key, which will be
+used for secrets encryption\decryption.
+
+By default, Cfg searches for configuration files in the **config** directory
+within current working dir. In order to specify a different path, crate a nenv variable
+**PYFLEX_CFG_ROOT_PATH** with the absolute path to the configuration root.
+
+### Basic Usage
+
+Assuming you have such configuration files structure:
+```
+    \project
+        ├─ config
+            ├─ general.yaml
+            ├─ env
+                ├─ dev.yaml
+                ├─ prd.yaml
+   ```
+And each of the yaml files contains a configuration option **data: test**
+
+Just import the Cfg and you can use your configuration at once:
+
+```python
+from pyflexcfg import Cfg
+
+print(Cfg.general.data)
+print(Cfg.env.dev.data)
+print(Cfg.env.prd.data)
+```
+
+Make sure the names of directories within your configuration are Python object's attribute name compatible.
+
+
+### Override by environment variables
+
+There is an option to override values in YAML files with values from environment variables.
+In order to do so, you have to create env variables which reflect the name of config value to be overwritten.
+For example, if you want to overwrite value for
+```
+Cfg.env.dev.data
+```
+you have to create env variable like this
+```
+CFG__ENV__DEV__DATA
+```
+Having that, you can call 
+```python
+Cfg.update_from_env()
+``` 
+and the value from the YAML file will be overwritten by the value from env variable.
+
+
+### Handling secrets
+
+Any sensitive data to be stored within your configuration files should be encrypted!
+
+Encrypt your secret:
+```python
+from pyflexcfg import AESCipher
+
+aes = AESCipher('secret-key')
+aes.encrypt('some-secret-to-encrypt')
+```
+You will get output like
+
+```python
+b'A1u6BIE2xGtYTSoFRE83H0VHsAW3nrv4WB+T/FEAj1fsh8HIId9r/Rskl0bnDHTI'
+```
+and it can be stored in yaml file with **!encr** prefix:
+
+```yaml
+my_secret: !encr b'A1u6BIE2xGtYTSoFRE83H0VHsAW3nrv4WB+T/FEAj1fsh8HIId9r/Rskl0bnDHTI'
+```
+
+The next time Cfg will be loading this configuration file it will automatically decrypt
+this value, but do not forget to set up env variable **PYFLEX_CFG_KEY** with your 'secret-key',
+otherwise Cfg won't be able to decrypt the data.

pyflexcfg-0.2.0/pyflexcfg/__init__.py

@@ -0,0 +1,5 @@
+from .components.encryption import AESCipher
+from .components.misc import AttrDict
+from .config_handler import ConfigHandler as Cfg
+
+__all__ = ['Cfg', 'AESCipher', 'AttrDict']

pyflexcfg-0.2.0/pyflexcfg/components/abstractclasses.py

@@ -0,0 +1,10 @@
+from abc import ABC, abstractmethod
+
+
+class ICipher(ABC):
+
+    @abstractmethod
+    def encrypt(self, plaintext: str) -> bytes: ...
+
+    @abstractmethod
+    def decrypt(self, encrypted: bytes | str) -> str: ...

pyflexcfg-0.2.0/pyflexcfg/components/constants.py

@@ -0,0 +1,8 @@
+# Name of the environment variable containing encryption key
+ENCRYPTION_KEY_ENV_VAR = 'PYFLEX_CFG_KEY'
+
+# env variable which contains the name of the root directory of project's configuration
+ROOT_CONFIG_PATH_ENV = 'PYFLEX_CFG_ROOT_PATH'
+
+# name of the root directory of project's configuration
+ROOT_CONFIG_DIR_NAME = 'config'

pyflexcfg-0.2.0/pyflexcfg/components/encryption.py

@@ -0,0 +1,54 @@
+import base64
+import hashlib
+import os
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import padding
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+from .abstractclasses import ICipher
+
+AES_BLOCK_SIZE = 16
+
+
+class AESCipher(ICipher):
+    def __init__(self, key: str):
+        """
+        Initializes the AES cipher with a static key provided as a string.
+        The string key is hashed to ensure it fits the length in bytes required by AES.
+
+        :param key: encryption key string
+        """
+        self.key = hashlib.sha256(key.encode('utf-8')).digest()
+
+    def encrypt(self, plaintext: str) -> bytes:
+        """
+        Encrypts a plaintext string using AES CBC mode with PKCS7 padding.
+
+        :param plaintext: plaintext string to encrypt
+        :return: encrypted data as bytes IV prepended
+        """
+        iv = os.urandom(AES_BLOCK_SIZE)
+        cipher = Cipher(algorithms.AES(self.key), modes.CBC(iv), backend=default_backend())
+        encryptor = cipher.encryptor()
+        padder = padding.PKCS7(128).padder()
+        padded_data = padder.update(plaintext.encode('utf-8')) + padder.finalize()
+        encrypted = encryptor.update(padded_data) + encryptor.finalize()
+        return base64.b64encode(iv + encrypted)
+
+    def decrypt(self, encrypted: bytes | str) -> str:
+        """
+        Decrypts an encrypted string using AES CBC mode with PKCS7 padding.
+
+        :param encrypted: encrypted data as bytes or string IV prepended
+        :return: decrypted plaintext string
+        """
+        encrypted = base64.b64decode(encrypted)
+        iv = encrypted[:AES_BLOCK_SIZE]
+        actual_encrypted_data = encrypted[AES_BLOCK_SIZE:]
+        cipher = Cipher(algorithms.AES(self.key), modes.CBC(iv), backend=default_backend())
+        decryptor = cipher.decryptor()
+        padded_plaintext = decryptor.update(actual_encrypted_data) + decryptor.finalize()
+        unpadder = padding.PKCS7(128).unpadder()
+        plaintext_bytes = unpadder.update(padded_plaintext) + unpadder.finalize()
+        return plaintext_bytes.decode('utf-8')

pyflexcfg-0.2.0/pyflexcfg/components/metaclasses.py

@@ -0,0 +1,71 @@
+import os
+from pathlib import Path
+from typing import AnyStr, Sequence
+
+import yaml
+
+from .constants import ROOT_CONFIG_DIR_NAME, ROOT_CONFIG_PATH_ENV
+from .misc import AttrDict
+from .yaml_loader import YamlLoader
+
+
+class HandlerMeta(type):
+    """
+    Metaclass for Config Handler class.
+
+    General purpose is to load values from existing configuration files while being imported,
+    so no additional initialization is required.
+    """
+    config_root = os.getenv(ROOT_CONFIG_PATH_ENV, Path.cwd() / ROOT_CONFIG_DIR_NAME)
+
+    def __new__(cls, name, bases, namespace):
+        init_attrs = AttrDict(namespace)
+
+        if not cls.config_root.exists():
+            raise RuntimeError(f'Configuration root path {cls.config_root} is not found!')
+
+        cls.load_config(cls.config_root, init_attrs)
+        return super().__new__(cls, name, bases, init_attrs)
+
+    def __str__(cls):
+        """ Pretty print current settings. """
+        dct = {k: v for k, v in list(cls.__dict__.items()) if not k.startswith('_') and not callable(getattr(cls, k))}
+        return str(dct)
+
+    @classmethod
+    def to_attrdict(cls, data: AnyStr | AttrDict | Sequence) -> AnyStr | AttrDict | Sequence:
+        if isinstance(data, dict):
+            for key, value in data.items():
+                data[key] = cls.to_attrdict(value)
+            data = AttrDict(**data)
+
+        elif isinstance(data, list | tuple):
+            for index, item in enumerate(data):
+                data[index] = cls.to_attrdict(item)
+
+        return data
+
+    @classmethod
+    def load_config(cls, config_path: Path, dct: AttrDict) -> None:
+        """
+        Traverse root config dir recursively and update given AttrDict with loaded YAML files' values.
+
+        :param config_path: root directory of configuration
+        :param dct: AttrDict instance to be updated with loaded values
+        """
+        for item in config_path.iterdir():
+            if item.is_dir():
+                try:
+                    dct[item.name] = AttrDict()
+                except KeyError:
+                    raise RuntimeError(f'Directory "{item.name}" is not valid for namespace assignment!')
+                cls.load_config(item, dct[item.name])
+
+            if item.suffix in ('.yml', '.yaml'):
+                cls._load_yaml_from_file(dct, item)
+
+    @classmethod
+    def _load_yaml_from_file(cls, dct: AttrDict | object, file: Path) -> None:
+        with file.open() as cfg_file:
+            data = cls.to_attrdict(yaml.load(cfg_file, YamlLoader))
+            setattr(dct, file.stem, data)

pyflexcfg-0.2.0/pyflexcfg/components/misc.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+
+class AttrDict(dict):
+    """
+    Implementation of a dict class, which is also able to operate with attributes in an object-like manner.
+
+    Since _setitem_ and _getitem_ methods aren't overridden, it can be inherited from a dict class, having all its
+    under-the-hood optimisations, instead of inheriting from UserDict class which is less optimised.
+    """
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            value = self[name]
+            if isinstance(value, dict) and not isinstance(value, AttrDict):
+                self[name] = AttrDict(value)
+            return self[name]
+        except KeyError:
+            raise AttributeError(name)
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        self[key] = value
+
+
+class Secret(str):
+    """ Simple implementation of secret string with masked output. """
+
+    def __repr__(self) -> str:
+        return '********'
+
+    def __str__(self) -> str:
+        return '********'

pyflexcfg-0.2.0/pyflexcfg/components/yaml_loader.py

@@ -0,0 +1,58 @@
+import os
+from pathlib import Path, PurePosixPath, PureWindowsPath, PurePath
+from typing import Optional
+
+from yaml import Loader, ScalarNode, SequenceNode
+
+from .abstractclasses import ICipher
+from .constants import ENCRYPTION_KEY_ENV_VAR
+from .encryption import AESCipher
+from .misc import Secret
+
+
+class YamlLoader(Loader):
+    """ Customized loader for YAML files. """
+
+    def __init__(self, *args, **kwargs):
+        self._cipher: Optional[ICipher] = None
+        super().__init__(*args, **kwargs)
+
+        def string(loader: Loader, node: SequenceNode) -> str:
+            """ String-like constructor, combines parts as a string. """
+            seq = loader.construct_sequence(node)
+            return ''.join([str(i) for i in seq])
+
+        def path_win(loader: Loader, node: SequenceNode) -> PureWindowsPath:
+            """ Path-like constructor, combines parts as a Windows path. """
+            seq = loader.construct_sequence(node)
+            return PureWindowsPath(*seq)
+
+        def path_posix(loader: Loader, node: SequenceNode) -> PurePosixPath:
+            """ Path-like constructor, combines parts as a Posix path. """
+            seq = loader.construct_sequence(node)
+            return PurePosixPath(*seq)
+
+        def home_dir(loader: Loader, node: SequenceNode) -> PurePath:
+            """ Constructor for paths (both Windows and Posix), starting from User's HOME directory. """
+            _home = Path.home()
+            seq = loader.construct_sequence(node)
+            return PurePath(_home, *seq)
+
+        def encrypted(loader: Loader, node: ScalarNode) -> str:
+            """ Constructor for encrypted data (strings and bytes). """
+            encr_value = loader.construct_scalar(node)
+            return Secret(self.cipher.decrypt(encr_value))
+
+        self.add_constructor('!string', string)
+        self.add_constructor('!path_win', path_win)
+        self.add_constructor('!path_posix', path_posix)
+        self.add_constructor('!home_dir', home_dir)
+        self.add_constructor('!encr', encrypted)
+
+    @property
+    def cipher(self):
+        if not self._cipher:
+            if (key := os.getenv(ENCRYPTION_KEY_ENV_VAR)) is None:
+                raise RuntimeError(f'Env variable {ENCRYPTION_KEY_ENV_VAR} is not found!')
+            self._cipher = AESCipher(key)
+        return self._cipher

pyflexcfg-0.2.0/pyflexcfg/config_handler.py

@@ -0,0 +1,22 @@
+import os
+
+from .components.metaclasses import HandlerMeta
+from .components.misc import AttrDict
+
+
+class ConfigHandler(AttrDict, metaclass=HandlerMeta):
+
+    @classmethod
+    def update_from_env(cls) -> None:
+        """ Override existing config values with ones loaded from env variables. """
+        for var_name, var_value in os.environ.items():
+            var_name = var_name.lower()
+
+            if var_name.startswith('cfg__'):
+                var_name = var_name.replace('cfg__', 'cls.', 1).replace('__', '.')
+
+                # try to identify whether the value is boolean or not before putting it in Cfg
+                if (var_lower := var_value.lower()) in ('true', 'false'):
+                    exec(f'{var_name} = bool({var_lower.capitalize()})')  # as bool
+                else:
+                    exec(f'{var_name} = "{var_value}"')  # as str

pyflexcfg-0.2.0/pyflexcfg/temp.py

@@ -0,0 +1,6 @@
+from pyflexcfg.config_handler import ConfigHandler as Cfg
+
+
+print(Cfg)
+pass
+

pyflexcfg-0.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[tool.poetry]
+name = "pyflexcfg"
+version = "0.2.0"
+description = "Flexible configuration handler for Python projects."
+authors = ["Pavel T <pavelterex@gmail.com>"]
+license = "MIT license"
+readme = "README.md"
+repository = "https://github.com/pavelterex/PyFlexCfg"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+cryptography = "^43.0.3"
+pyyaml = "^6.0.2"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.3"
+pytest-assume = "^2.4.3"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"