click-extended 0.4.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

click_extended/decorators/convert/convert_weight.py

@@ -0,0 +1,158 @@
+"""Convert between various weight units."""
+
+from decimal import Decimal, getcontext
+from typing import Any, Literal
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+getcontext().prec = 28
+
+MASS_UNITS = {
+    "ug": Decimal("1e-9"),
+    "mg": Decimal("1e-6"),
+    "g": Decimal("1e-3"),
+    "kg": Decimal("1"),
+    "t": Decimal("1000"),
+    "lb": Decimal("0.45359237"),
+    "oz": Decimal("0.028349523125"),
+    "st": Decimal("6.35029318"),
+    "ct": Decimal("0.0002"),
+    "amu": Decimal("1.66053906660e-27"),
+    "slg": Decimal("14.593903"),
+}
+
+FORCE_UNITS = {
+    "n": Decimal("1"),
+    "kn": Decimal("1000"),
+    "lbf": Decimal("4.4482216152605"),
+    "ozf": Decimal("0.27801385095378125"),
+    "kgf": Decimal("9.80665"),
+    "dyn": Decimal("1e-5"),
+}
+
+
+class ConvertWeight(ChildNode):
+    """Convert between various weight units."""
+
+    def handle_numeric(
+        self,
+        value: int | float,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> float:
+        from_unit = kwargs["from_unit"]
+        to_unit = kwargs["to_unit"]
+        gravity = Decimal(str(kwargs["gravity"]))
+        val = Decimal(str(value))
+
+        if from_unit in MASS_UNITS:
+            base_value = val * MASS_UNITS[from_unit]
+            is_mass = True
+        elif from_unit in FORCE_UNITS:
+            base_value = val * FORCE_UNITS[from_unit]
+            is_mass = False
+        else:
+            raise ValueError(f"Unknown unit '{from_unit}'")
+
+        if is_mass and to_unit in FORCE_UNITS:
+            base_value = base_value * gravity
+        elif not is_mass and to_unit in MASS_UNITS:
+            base_value = base_value / gravity
+
+        if to_unit in MASS_UNITS:
+            result = base_value / MASS_UNITS[to_unit]
+        elif to_unit in FORCE_UNITS:
+            result = base_value / FORCE_UNITS[to_unit]
+        else:
+            raise ValueError(f"Unknown unit '{to_unit}'")
+
+        return float(result)
+
+
+def convert_weight(
+    from_unit: Literal[
+        "ug",
+        "mg",
+        "g",
+        "kg",
+        "t",
+        "lb",
+        "oz",
+        "st",
+        "n",
+        "kn",
+        "ct",
+        "amu",
+        "lbf",
+        "ozf",
+        "kgf",
+        "dyn",
+        "slg",
+    ],
+    to_unit: Literal[
+        "ug",
+        "mg",
+        "g",
+        "kg",
+        "t",
+        "lb",
+        "oz",
+        "st",
+        "n",
+        "kn",
+        "ct",
+        "amu",
+        "lbf",
+        "ozf",
+        "kgf",
+        "dyn",
+        "slg",
+    ],
+    gravity: float = 9.80665,
+) -> Decorator:
+    """
+    Convert between various weight units.
+
+    Type: `ChildNode`
+
+    Supports: `int`, `float`
+
+    Units:
+        - **ug**: Micrograms (mass)
+        - **mg**: Milligrams (mass)
+        - **g**: Grams (mass)
+        - **kg**: Kilograms (mass)
+        - **t**: Metric tonne (mass)
+        - **lb**: Pound (mass)
+        - **oz**: Ounce (mass)
+        - **st**: Stone (mass)
+        - **n**: Newton (force)
+        - **kn**: Kilonewton (force)
+        - **ct**: Carat (mass)
+        - **amu**: Atomic mass unit (mass)
+        - **lbf**: Pound-force (force)
+        - **ozf**: Ounce-force (force)
+        - **kgf**: Kilogram-force (force)
+        - **dyn**: Dyne (force)
+        - **slg**: Slug (mass)
+
+    Args:
+        from_unit (str):
+            The unit to convert from.
+        to_unit (str):
+            The unit to convert to.
+        gravity (float, optional):
+            The gravity constant, used for force units. Defaults to `9.80665`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return ConvertWeight.as_decorator(
+        from_unit=from_unit,
+        to_unit=to_unit,
+        gravity=gravity,
+    )

click_extended/decorators/load/__init__.py

@@ -0,0 +1,13 @@
+"""Initialization file for the `click_extended.decorators.load` module."""
+
+from click_extended.decorators.load.load_csv import load_csv
+from click_extended.decorators.load.load_json import load_json
+from click_extended.decorators.load.load_toml import load_toml
+from click_extended.decorators.load.load_yaml import load_yaml
+
+__all__ = [
+    "load_csv",
+    "load_json",
+    "load_toml",
+    "load_yaml",
+]

click_extended/decorators/load/load_csv.py

@@ -0,0 +1,117 @@
+"""Child decorator to load the contents of a CSV file."""
+
+# pylint: disable=too-many-locals
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+
+import csv
+from pathlib import Path
+from typing import Any, Literal
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class LoadCsv(ChildNode):
+    """Child decorator to load the contents of a CSV file."""
+
+    def handle_path(
+        self, value: Path, context: Context, *args: Any, **kwargs: Any
+    ) -> list[dict[str, str]] | list[list[str]]:
+        dialect = kwargs["dialect"]
+        delimiter = kwargs["delimiter"]
+        has_header = kwargs["has_header"]
+        as_dict = kwargs["as_dict"]
+        encoding = kwargs["encoding"]
+        skip_empty = kwargs["skip_empty"]
+
+        if value.is_dir():
+            raise IsADirectoryError(
+                f"Path '{value.absolute()}' is a directory, but must be a file."
+            )
+
+        with value.open("r", encoding=encoding, newline="") as f:
+            reader_kwargs: dict[str, Any] = {}
+            if dialect:
+                reader_kwargs["dialect"] = dialect
+            if delimiter:
+                reader_kwargs["delimiter"] = delimiter
+
+            if as_dict:
+                reader = csv.DictReader(f, **reader_kwargs)
+                rows: list[dict[str, str]] = []
+                for row_dict in reader:
+                    if skip_empty and not any(row_dict.values()):
+                        continue
+                    rows.append(row_dict)
+                return rows
+
+            reader_list = csv.reader(f, **reader_kwargs)
+            rows_list: list[list[str]] = []
+
+            if has_header:
+                next(reader_list, None)  # Skip header row
+
+            for row_list in reader_list:
+                if skip_empty and not any(row_list):
+                    continue
+                rows_list.append(row_list)
+            return rows_list
+
+
+def load_csv(
+    dialect: Literal["excel", "excel-tab", "unix"] | None = None,
+    delimiter: str | None = None,
+    has_header: bool = True,
+    as_dict: bool = True,
+    encoding: str = "utf-8",
+    skip_empty: bool = True,
+) -> Decorator:
+    """
+    Load the contents of a CSV file.
+
+    Type: `ChildNode`
+
+    Supports: `pathlib.Path`
+
+    Args:
+        dialect (Literal["excel", "excel-tab", "unix"] | None, optional):
+            CSV dialect to use:
+            - `"excel"`: Excel-generated CSV files (comma-delimited)
+            - `"excel-tab"`: Excel-generated tab-delimited files
+            - `"unix"`: Unix-style CSV files (quote all fields)
+            If not specified, the reader will use default settings.
+            Defaults to `None`.
+        delimiter (str, optional):
+            Character used to separate fields. Common values are ',' and '\\t'.
+            If not specified, defaults to comma for most dialects.
+            Defaults to `None`.
+        has_header (bool, optional):
+            Whether the CSV file has a header row. Only used when
+            `as_dict=False`. When `as_dict=True`, the first row is
+            always treated as headers. Defaults to `True`.
+        as_dict (bool, optional):
+            Whether to return rows as dictionaries (using header as keys)
+            or as lists. When `True`, uses `csv.DictReader`. When `False`,
+            uses `csv.reader`.
+            Defaults to `True`.
+        encoding (str, optional):
+            The encoding to use when reading the file.
+            Defaults to `"utf-8"`.
+        skip_empty (bool, optional):
+            Whether to skip empty rows in the CSV file.
+            Defaults to `True`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return LoadCsv.as_decorator(
+        dialect=dialect,
+        delimiter=delimiter,
+        has_header=has_header,
+        as_dict=as_dict,
+        encoding=encoding,
+        skip_empty=skip_empty,
+    )

click_extended/decorators/load/load_json.py

@@ -0,0 +1,61 @@
+"""Child decorator to load contents from a JSON file."""
+
+import json
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class LoadJson(ChildNode):
+    """Child decorator to load contents from a JSON file."""
+
+    def handle_path(
+        self, value: Path, context: Context, *args: Any, **kwargs: Any
+    ) -> Any:
+        encoding = kwargs["encoding"]
+        strict = kwargs["strict"]
+
+        if value.is_dir():
+            raise IsADirectoryError(
+                f"Path '{value.absolute()}' is a directory, but must be a file."
+            )
+
+        with value.open("r", encoding=encoding) as f:
+            if strict:
+                return json.load(f, parse_float=Decimal)
+            return json.load(f)
+
+
+def load_json(
+    encoding: str = "utf-8",
+    strict: bool = True,
+) -> Decorator:
+    """
+    Load a JSON file from a `pathlib.Path` object.
+
+    Type: `ChildNode`
+
+    Supports: `pathlib.Path`
+
+    Args:
+        encoding (str, optional):
+            The encoding to use when reading the file.
+            Defaults to `"utf-8"`.
+        strict (bool, optional):
+            Whether to use strict parsing for numerical values.
+            When `True`, floats are parsed as `Decimal` for precision.
+            When `False`, floats are parsed as standard Python `float`.
+            Defaults to `True`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return LoadJson.as_decorator(
+        encoding=encoding,
+        strict=strict,
+    )

click_extended/decorators/load/load_toml.py

@@ -0,0 +1,47 @@
+"""Child decorator to load the contents of a TOML file."""
+
+# pylint: disable=wrong-import-position
+
+import sys
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-not-found]
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class LoadToml(ChildNode):
+    """Child decorator to load the contents of a TOML file."""
+
+    def handle_path(
+        self, value: Path, context: Context, *args: Any, **kwargs: Any
+    ) -> dict[str, Any]:
+        if value.is_dir():
+            raise IsADirectoryError(
+                f"Path '{value.absolute()}' is a directory, but must be a file."
+            )
+
+        with value.open("rb") as f:
+            result: dict[str, Any] = tomllib.load(f)
+            return result
+
+
+def load_toml() -> Decorator:
+    """
+    Load the contents of a TOML file from a `pathlib.Path` object.
+
+    Type: `ChildNode`
+
+    Supports: `pathlib.Path`
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return LoadToml.as_decorator()

click_extended/decorators/load/load_yaml.py

@@ -0,0 +1,72 @@
+"""Child decorator to load the contents of a YAML file."""
+
+from pathlib import Path
+from typing import Any, Literal
+
+from yaml import FullLoader, SafeLoader, UnsafeLoader, load
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class LoadYaml(ChildNode):
+    """Child decorator to load the contents of a YAML file."""
+
+    def handle_path(
+        self, value: Path, context: Context, *args: Any, **kwargs: Any
+    ) -> Any:
+        if value.is_dir():
+            raise IsADirectoryError(
+                f"Path '{value.absolute()}' is a directory, but must be a file."
+            )
+
+        loader_name = kwargs["loader"]
+        loader: type[SafeLoader] | type[FullLoader] | type[UnsafeLoader]
+
+        if loader_name == "safe":
+            loader = SafeLoader
+        elif loader_name == "unsafe":
+            loader = UnsafeLoader
+        else:
+            loader = FullLoader
+
+        with value.open("r", encoding=kwargs["encoding"]) as f:
+            return load(f, Loader=loader)
+
+
+def load_yaml(
+    encoding: str = "utf-8",
+    loader: Literal["safe", "unsafe", "full"] = "safe",
+) -> Decorator:
+    """
+    Load the contents of a YAML file.
+
+    Type: `ChildNode`
+
+    Supports: `pathlib.Path`
+
+    Args:
+        encoding (str, optional):
+            The encoding to use when reading the file.
+            Defaults to `"utf-8"`.
+        loader (Literal["safe", "unsafe", "full"], optional):
+            The YAML loader to use:
+            - `"safe"`: SafeLoader - Only constructs simple Python objects
+              (strings, lists, dicts, numbers, dates). Recommended for
+              untrusted input.
+            - `"unsafe"`: UnsafeLoader - Can construct arbitrary Python
+              objects. Use only with trusted YAML files.
+            - `"full"`: FullLoader - Constructs simple Python objects and
+              some additional types. Safer than unsafe but less restrictive
+              than safe.
+            Defaults to `"safe"`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return LoadYaml.as_decorator(
+        encoding=encoding,
+        loader=loader,
+    )

click_extended/decorators/math/__init__.py

@@ -0,0 +1,37 @@
+"""Initialization file for the `click_extended.decorators.math` module."""
+
+from click_extended.decorators.math.absolute import absolute
+from click_extended.decorators.math.add import add
+from click_extended.decorators.math.ceil import ceil
+from click_extended.decorators.math.clamp import clamp
+from click_extended.decorators.math.divide import divide
+from click_extended.decorators.math.floor import floor
+from click_extended.decorators.math.maximum import maximum
+from click_extended.decorators.math.minimum import minimum
+from click_extended.decorators.math.modulo import modulo
+from click_extended.decorators.math.multiply import multiply
+from click_extended.decorators.math.normalize import normalize
+from click_extended.decorators.math.power import power
+from click_extended.decorators.math.rounded import rounded
+from click_extended.decorators.math.sqrt import sqrt
+from click_extended.decorators.math.subtract import subtract
+from click_extended.decorators.math.to_percent import to_percent
+
+__all__ = [
+    "absolute",
+    "add",
+    "ceil",
+    "clamp",
+    "divide",
+    "floor",
+    "maximum",
+    "minimum",
+    "modulo",
+    "multiply",
+    "normalize",
+    "power",
+    "rounded",
+    "sqrt",
+    "subtract",
+    "to_percent",
+]

click_extended/decorators/math/absolute.py

@@ -0,0 +1,35 @@
+"""Return the absolute value of the input."""
+
+from typing import Any
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class Absolute(ChildNode):
+    """Return the absolute value of the input."""
+
+    def handle_numeric(
+        self,
+        value: int | float,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        return abs(value)
+
+
+def absolute() -> Decorator:
+    """
+    Return the absolute value of the input.
+
+    Type: `ChildNode`
+
+    Supports: `int`, `float`
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Absolute.as_decorator()

click_extended/decorators/math/add.py

@@ -0,0 +1,48 @@
+"""Add a value to the input."""
+
+from typing import Any
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class Add(ChildNode):
+    """Add a value to the input."""
+
+    def handle_numeric(
+        self,
+        value: int | float,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        return value + kwargs["n"]
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        return value + str(kwargs["n"])
+
+
+def add(n: int | float | str) -> Decorator:
+    """
+    Add a value to the input.
+
+    Type: `ChildNode`
+
+    Supports: `int`, `float`, `str`
+
+    Args:
+        n (int | float | str):
+            The value to add.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Add.as_decorator(n=n)

click_extended/decorators/math/ceil.py

@@ -0,0 +1,36 @@
+"""Calculate the ceiling of the input."""
+
+import math
+from typing import Any
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class Ceil(ChildNode):
+    """Calculate the ceiling of the input."""
+
+    def handle_numeric(
+        self,
+        value: int | float,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        return math.ceil(value)
+
+
+def ceil() -> Decorator:
+    """
+    Calculate the ceiling of the input.
+
+    Type: `ChildNode`
+
+    Supports: `int`, `float`
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Ceil.as_decorator()

click_extended/decorators/math/clamp.py

@@ -0,0 +1,51 @@
+"""Clamp the input value between a minimum and maximum."""
+
+from typing import Any
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class Clamp(ChildNode):
+    """Clamp the input value between a minimum and maximum."""
+
+    def handle_numeric(
+        self,
+        value: int | float,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        min_val = kwargs.get("min_val")
+        max_val = kwargs.get("max_val")
+
+        if min_val is not None and value < min_val:
+            return min_val
+        if max_val is not None and value > max_val:
+            return max_val
+        return value
+
+
+def clamp(
+    min_val: int | float | None = None,
+    max_val: int | float | None = None,
+) -> Decorator:
+    """
+    Clamp the input value between a minimum and maximum.
+
+    Type: `ChildNode`
+
+    Supports: `int`, `float`
+
+    Args:
+        min_val (int | float, optional):
+            The minimum value.
+        max_val (int | float, optional):
+            The maximum value.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Clamp.as_decorator(min_val=min_val, max_val=max_val)