directed-inputs-class 0.1.0__py3-none-any.whl

directed_inputs_class/__init__.py

@@ -0,0 +1,14 @@
+"""Directed Inputs Class.
+
+This package provides tools for managing and processing directed inputs from
+various sources like environment variables, stdin, and predefined dictionaries.
+"""
+
+from __future__ import annotations
+
+from .__main__ import DirectedInputsClass
+
+
+__version__ = "0.1.0"
+
+__all__ = ["DirectedInputsClass"]

directed_inputs_class/__main__.py

@@ -0,0 +1,233 @@
+"""Module to handle directed inputs for the DirectedInputsClass library.
+
+This module provides functionality for managing inputs from various sources
+(environment, stdin) and allows for dynamic merging, freezing, and thawing
+of inputs. It includes methods to decode inputs from JSON, YAML, and Base64
+formats, as well as handling boolean and integer conversions.
+"""
+
+from __future__ import annotations
+
+import binascii
+import json
+import os
+import sys
+
+from copy import deepcopy
+from typing import Any
+
+from case_insensitive_dict import CaseInsensitiveDict
+from deepmerge import Merger  # type: ignore[import-untyped]
+from extended_data_types import (
+    base64_decode,
+    decode_json,
+    decode_yaml,
+    is_nothing,
+    strtobool,
+)
+from yaml import YAMLError
+
+
+class DirectedInputsClass:
+    """A class to manage and process directed inputs from environment variables.
+
+    stdin, or provided dictionaries.
+
+    Attributes:
+        inputs (CaseInsensitiveDict): Dictionary to store inputs.
+        frozen_inputs (CaseInsensitiveDict): Dictionary to store frozen inputs.
+        from_stdin (bool): Flag indicating if inputs were read from stdin.
+        merger (Merger): Object to manage deep merging of dictionaries.
+    """
+
+    def __init__(
+        self,
+        inputs: Any | None = None,
+        from_environment: bool = True,
+        from_stdin: bool = False,
+    ):
+        """Initializes the DirectedInputsClass with the provided inputs.
+
+        Optionally loading additional inputs from environment variables and stdin.
+
+        Args:
+            inputs (Any | None): Initial inputs to be processed.
+            from_environment (bool): Whether to load inputs from environment variables.
+            from_stdin (bool): Whether to load inputs from stdin.
+        """
+        if inputs is None:
+            inputs = {}
+
+        if from_environment:
+            env_inputs = dict(os.environ)
+            env_inputs.update(inputs)
+            inputs = env_inputs
+
+        if from_stdin and not strtobool(os.getenv("OVERRIDE_STDIN", "False")):
+            inputs_from_stdin = sys.stdin.read()
+
+            if not is_nothing(inputs_from_stdin):
+                try:
+                    stdin_inputs = json.loads(inputs_from_stdin)
+                    stdin_inputs.update(inputs)
+                    inputs = stdin_inputs
+                except json.JSONDecodeError as exc:
+                    message = f"Failed to decode stdin:\n{inputs_from_stdin}"
+                    raise RuntimeError(message) from exc
+
+        self.from_stdin = from_stdin
+        self.inputs: CaseInsensitiveDict[str, Any] = CaseInsensitiveDict(inputs)
+        self.frozen_inputs: CaseInsensitiveDict[str, Any] = CaseInsensitiveDict()
+        self.merger = Merger(
+            [(list, ["append"]), (dict, ["merge"]), (set, ["union"])],
+            ["override"],
+            ["override"],
+        )
+
+    def get_input(
+        self,
+        k: str,
+        default: Any | None = None,
+        required: bool = False,
+        is_bool: bool = False,
+        is_integer: bool = False,
+    ) -> Any:
+        """Retrieves an input by key, with options for type conversion and default values.
+
+        Args:
+            k (str): The key for the input.
+            default (Any | None): The default value if the key is not found.
+            required (bool): Whether the input is required. Raises an error if required and not found.
+            is_bool (bool): Whether to convert the input to a boolean.
+            is_integer (bool): Whether to convert the input to an integer.
+
+        Returns:
+            Any: The retrieved input, potentially converted or defaulted.
+        """
+        inp = self.inputs.get(k, default)
+
+        if is_nothing(inp):
+            inp = default
+
+        if is_bool:
+            inp = strtobool(inp)
+
+        if is_integer and inp is not None:
+            try:
+                inp = int(inp)
+            except TypeError as exc:
+                message = f"Input {k} not an integer: {inp}"
+                raise RuntimeError(message) from exc
+
+        if is_nothing(inp) and required:
+            message = f"Required input {k} not passed from inputs:\n{self.inputs}"
+            raise RuntimeError(message)
+
+        return inp
+
+    def decode_input(
+        self,
+        k: str,
+        default: Any | None = None,
+        required: bool = False,
+        decode_from_json: bool = False,
+        decode_from_yaml: bool = False,
+        decode_from_base64: bool = False,
+        allow_none: bool = True,
+    ) -> Any:
+        """Decodes an input value, optionally from Base64, JSON, or YAML.
+
+        Args:
+            k (str): The key for the input.
+            default (Any | None): The default value if the key is not found.
+            required (bool): Whether the input is required. Raises an error if required and not found.
+            decode_from_json (bool): Whether to decode the input from JSON format.
+            decode_from_yaml (bool): Whether to decode the input from YAML format.
+            decode_from_base64 (bool): Whether to decode the input from Base64.
+            allow_none (bool): Whether to allow None as a valid return value.
+
+        Returns:
+            Any: The decoded input, potentially converted or defaulted.
+        """
+        conf = self.get_input(k, default=default, required=required)
+
+        if conf is None or conf == default:
+            return conf
+
+        if decode_from_base64:
+            try:
+                conf = base64_decode(
+                    conf,
+                    unwrap_raw_data=decode_from_json or decode_from_yaml,
+                    encoding="json" if decode_from_json else "yaml",
+                )
+            except binascii.Error as exc:
+                message = f"Failed to decode {conf} from base64"
+                raise RuntimeError(message) from exc
+
+        if isinstance(conf, memoryview):
+            conf = conf.tobytes().decode("utf-8")
+        elif isinstance(conf, (bytes, bytearray)):
+            try:
+                conf = conf.decode("utf-8")
+            except UnicodeDecodeError as exc:
+                message = f"Failed to decode bytes to string: {conf}"
+                raise RuntimeError(message) from exc
+
+        if decode_from_yaml:
+            try:
+                conf = decode_yaml(conf)
+            except YAMLError as exc:
+                message = f"Failed to decode {conf} from YAML"
+                raise RuntimeError(message) from exc
+        elif decode_from_json:
+            try:
+                conf = decode_json(conf)
+            except json.JSONDecodeError as exc:
+                message = f"Failed to decode {conf} from JSON"
+                raise RuntimeError(message) from exc
+
+        if conf is None and not allow_none:
+            return default
+
+        return conf
+
+    def freeze_inputs(self) -> CaseInsensitiveDict[str, Any]:
+        """Freezes the current inputs, preventing further modifications until thawed.
+
+        Returns:
+            CaseInsensitiveDict: The frozen inputs.
+        """
+        if is_nothing(self.frozen_inputs):
+            self.frozen_inputs = deepcopy(self.inputs)
+            self.inputs = CaseInsensitiveDict()
+
+        return self.frozen_inputs
+
+    def thaw_inputs(self) -> CaseInsensitiveDict[str, Any]:
+        """Thaws the inputs, merging the frozen inputs back into the current inputs.
+
+        Returns:
+            CaseInsensitiveDict: The thawed inputs.
+        """
+        if is_nothing(self.inputs):
+            self.inputs = deepcopy(self.frozen_inputs)
+            self.frozen_inputs = CaseInsensitiveDict()
+            return self.inputs
+
+        self.inputs = self.merger.merge(
+            deepcopy(self.inputs), deepcopy(self.frozen_inputs)
+        )
+        self.frozen_inputs = CaseInsensitiveDict()
+        return self.inputs
+
+    def shift_inputs(self) -> CaseInsensitiveDict[str, Any]:
+        """Shifts between frozen and thawed inputs.
+
+        Returns:
+            CaseInsensitiveDict: The resulting inputs after the shift.
+        """
+        if is_nothing(self.frozen_inputs):
+            return self.freeze_inputs()
+
+        return self.thaw_inputs()

directed_inputs_class-0.1.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.3
+Name: directed-inputs-class
+Version: 0.1.0
+Summary: Directed inputs class consumes and processes inputs from sources beyond args and kwargs
+Project-URL: Documentation, https://github.com/jbcom/directed-inputs-class#readme
+Project-URL: Issues, https://github.com/jbcom/directed-inputs-class/issues
+Project-URL: Source, https://github.com/jbcom/directed-inputs-class
+Author-email: Jon Bogaty <jon@jonbogaty.com>
+Maintainer-email: Jon Bogaty <jon@jonbogaty.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: python3
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: case-insensitive-dictionary>=0.2.1
+Requires-Dist: deepmerge>=1.1.1
+Requires-Dist: extended-data-types>=1.0.2
+Requires-Dist: future>=1.0.0
+Provides-Extra: docs
+Requires-Dist: docutils>=0.17; extra == 'docs'
+Requires-Dist: myst-parser>=3.0.1; extra == 'docs'
+Requires-Dist: sphinx-autodoc2>=0.5.0; extra == 'docs'
+Requires-Dist: sphinx<7.5,>=7.2; extra == 'docs'
+Requires-Dist: sphinxawesome-theme>=5.2.0; extra == 'docs'
+Provides-Extra: tests
+Requires-Dist: coverage[toml]>=7.6.0; extra == 'tests'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'tests'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'tests'
+Requires-Dist: pytest-xdist>=3.6.1; extra == 'tests'
+Requires-Dist: pytest>=8.2.2; extra == 'tests'
+Provides-Extra: typing
+Requires-Dist: mypy>=1.0.0; extra == 'typing'
+Requires-Dist: sortedcontainers-stubs>=2.4.2; extra == 'typing'
+Requires-Dist: types-pyyaml>=6.0.12.20240724; extra == 'typing'
+Description-Content-Type: text/markdown
+
+
+# Directed Inputs Class
+
+![Directed Inputs Class Logo](docs/_static/logo.webp)
+
+*🛠️ Manage your Python inputs efficiently! 🎯*
+
+[![CI Status](https://github.com/jbcom/directed-inputs-class/workflows/CI/badge.svg)](https://github.com/jbcom/directed-inputs-class/actions?query=workflow%3ACI)
+[![Documentation Status](https://readthedocs.org/projects/directed-inputs-class/badge/?version=latest)](https://directed-inputs-class.readthedocs.io/en/latest/?badge=latest)
+[![PyPI Package latest release](https://img.shields.io/pypi/v/directed-inputs-class.svg)](https://pypi.org/project/directed-inputs-class/)
+[![Supported versions](https://img.shields.io/pypi/pyversions/directed-inputs-class.svg)](https://pypi.org/project/directed-inputs-class/)
+
+Directed Inputs Class is a Python library that provides a flexible and robust interface for managing inputs from various sources such as environment variables, stdin, and predefined dictionaries. It offers features like input freezing, thawing, and advanced decoding utilities.
+
+## Key Features
+
+- 🧩 **Environment Variable Integration** - Seamlessly integrates environment variables into your inputs.
+- 📥 **Stdin Input Handling** - Read and merge inputs from stdin with optional overrides.
+- ❄️ **Input Freezing and Thawing** - Freeze inputs to prevent modifications, and thaw them when needed.
+- 🔄 **Advanced Decoding Utilities** - Decode inputs from Base64, JSON, and YAML formats with error handling.
+- 🔧 **Type Conversion** - Convert inputs to boolean or integer types with robust error handling.
+
+### Example Usage
+
+```python
+from directed_inputs_class import DirectedInputsClass
+
+# Initialize with environment variables and stdin
+dic = DirectedInputsClass(from_environment=True, from_stdin=True)
+
+# Retrieve and decode an input
+decoded_value = dic.decode_input("example_key", decode_from_base64=True)
+print(decoded_value)
+```
+
+### Freezing and Thawing Inputs
+
+```python
+from directed_inputs_class import DirectedInputsClass
+
+# Initialize with some inputs
+dic = DirectedInputsClass(inputs={"key1": "value1"})
+
+# Freeze the inputs
+frozen_inputs = dic.freeze_inputs()
+print(frozen_inputs)  # Outputs: {'key1': 'value1'}
+
+# Thaw the inputs
+thawed_inputs = dic.thaw_inputs()
+print(thawed_inputs)  # Outputs: {'key1': 'value1'}
+```
+
+For more usage examples, see the [Usage](https://directed-inputs-class.readthedocs.io/en/latest/usage.md) documentation.
+
+## Contributing
+
+Contributions are welcome! Please see the [Contributing Guidelines](https://github.com/jbcom/directed-inputs-class/blob/main/CONTRIBUTING.md) for more information.
+
+## Credit
+
+Directed Inputs Class is written and maintained by [Your Name](mailto:yourname@example.com).
+
+## Project Links
+
+- [**Get Help**](https://stackoverflow.com/questions/tagged/directed-inputs-class) (use the *directed-inputs-class* tag on
+  Stack Overflow)
+- [**PyPI**](https://pypi.org/project/directed-inputs-class/)
+- [**GitHub**](https://github.com/jbcom/directed-inputs-class)
+- [**Documentation**](https://directed-inputs-class.readthedocs.io/en/latest/)
+- [**Changelog**](https://github.com/jbcom/directed-inputs-class/tree/main/CHANGELOG.md)

directed_inputs_class-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+directed_inputs_class/__init__.py,sha256=OnoxTORWlE7Qc3FDFsUyPCD3xiTpcHrx48KQUArrVjk,326
+directed_inputs_class/__main__.py,sha256=KgrpMDfbqTxmiGXgjuvYJxXDyeBQQ7NTmdK9Vxl98Fs,8144
+directed_inputs_class-0.1.0.dist-info/METADATA,sha256=CbMQrwl3rJfoBjwH7wqVozAh1xF4KLvH-DN7epY_RwI,5071
+directed_inputs_class-0.1.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+directed_inputs_class-0.1.0.dist-info/licenses/LICENSE,sha256=0bZwPE-woPfUEqxkVpNKtp9j9x3XLYfixj1X9YQf5hE,1067
+directed_inputs_class-0.1.0.dist-info/RECORD,,

directed_inputs_class-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

directed_inputs_class-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jon Bogaty
+
+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.