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

click_extended/decorators/compare/greater_than.py

@@ -0,0 +1,183 @@
+"""Child decorator to validate that a value is more than a threshold."""
+
+from datetime import date, datetime, time
+from decimal import Decimal
+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 GreaterThan(ChildNode):
+    """Child decorator to validate that a value is more than a threshold."""
+
+    def handle_numeric(
+        self,
+        value: int | float | Decimal,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> int | float | Decimal:
+        threshold = kwargs["threshold"]
+        inclusive = kwargs["inclusive"]
+
+        if inclusive:
+            if value < threshold:
+                raise ValueError(
+                    f"Value must be at least {threshold}, got {value}"
+                )
+        else:
+            if value <= threshold:
+                raise ValueError(
+                    f"Value must be more than {threshold}, got {value}"
+                )
+
+        return value
+
+    def handle_datetime(
+        self,
+        value: datetime,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> datetime:
+        threshold = kwargs["threshold"]
+        inclusive = kwargs["inclusive"]
+
+        if inclusive:
+            if value < threshold:
+                raise ValueError(
+                    f"Value must be at least {threshold}, got {value}"
+                )
+        else:
+            if value <= threshold:
+                raise ValueError(
+                    f"Value must be more than {threshold}, got {value}"
+                )
+
+        return value
+
+    def handle_date(
+        self,
+        value: date,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> date:
+        threshold = kwargs["threshold"]
+        inclusive = kwargs["inclusive"]
+
+        if inclusive:
+            if value < threshold:
+                raise ValueError(
+                    f"Value must be at least {threshold}, got {value}"
+                )
+        else:
+            if value <= threshold:
+                raise ValueError(
+                    f"Value must be more than {threshold}, got {value}"
+                )
+
+        return value
+
+    def handle_time(
+        self,
+        value: time,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> time:
+        threshold = kwargs["threshold"]
+        inclusive = kwargs["inclusive"]
+
+        if inclusive:
+            if value < threshold:
+                raise ValueError(
+                    f"Value must be at least {threshold}, got {value}"
+                )
+        else:
+            if value <= threshold:
+                raise ValueError(
+                    f"Value must be more than {threshold}, got {value}"
+                )
+
+        return value
+
+
+def greater_than(
+    threshold: int | float | Decimal | datetime | date | time,
+    inclusive: bool = False,
+) -> Decorator:
+    """
+    Validate that a value is more than a threshold.
+
+    Type: `ChildNode`
+
+    Supports: `int`, `float`, `Decimal`, `datetime`, `date`, `time`
+
+    Args:
+        threshold (int | float | Decimal | datetime | date | time):
+            The threshold value to compare against.
+        inclusive (bool):
+            If `True`, allows values equal to threshold (>=).
+            If `False`, requires values strictly greater (>).
+            Defaults to `False`.
+
+    Raises:
+        ValueError:
+            If value is not more than (or at least) the threshold.
+        TypeError:
+            If value type cannot be compared with threshold.
+
+    Examples:
+        Basic numeric validation:
+
+        >>> @command()
+        >>> @option("age", type=int)
+        >>> @greater_than(18)
+        >>> def cmd(age):
+        ...     click.echo(f"Age: {age}")
+
+        >>> # Valid: 19, 20, 100
+        >>> # Invalid: 18, 17, 0, -5
+
+        With inclusive parameter:
+
+        >>> @command()
+        >>> @option("score", type=float)
+        >>> @greater_than(0.0, inclusive=True)
+        >>> def cmd(score):
+        ...     click.echo(f"Score: {score}")
+
+        >>> # Valid: 0.0, 0.1, 100.0
+        >>> # Invalid: -0.1, -1.0
+
+        Datetime validation:
+
+        >>> @command()
+        >>> @option("start_date")
+        >>> @to_date()
+        >>> @greater_than(date(2024, 1, 1), inclusive=True)
+        >>> def cmd(start_date):
+        ...     click.echo(f"Start: {start_date}")
+
+        >>> # Valid: 2024-01-01, 2024-12-31, 2025-01-01
+        >>> # Invalid: 2023-12-31, 2023-01-01
+
+        Multiple values (automatic handling):
+
+        >>> @command()
+        >>> @option("numbers", type=int, multiple=True)
+        >>> @greater_than(0)
+        >>> def cmd(numbers):
+        ...     click.echo(f"Numbers: {numbers}")
+
+        >>> # Valid: (1, 2, 3), (5, 10, 15)
+        >>> # Invalid: (1, 0, 3), (-1, 2, 3)
+        >>> # Note: Validation applies to each number individually
+    """
+    return GreaterThan.as_decorator(
+        threshold=threshold,
+        inclusive=inclusive,
+    )

click_extended/decorators/compare/less_than.py

@@ -0,0 +1,183 @@
+"""Child decorator to validate that a value is less than a threshold."""
+
+from datetime import date, datetime, time
+from decimal import Decimal
+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 LessThan(ChildNode):
+    """Child decorator to validate that a value is less than a threshold."""
+
+    def handle_numeric(
+        self,
+        value: int | float | Decimal,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> int | float | Decimal:
+        threshold = kwargs["threshold"]
+        inclusive = kwargs["inclusive"]
+
+        if inclusive:
+            if value > threshold:
+                raise ValueError(
+                    f"Value must be at most {threshold}, got {value}"
+                )
+        else:
+            if value >= threshold:
+                raise ValueError(
+                    f"Value must be less than {threshold}, got {value}"
+                )
+
+        return value
+
+    def handle_datetime(
+        self,
+        value: datetime,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> datetime:
+        threshold = kwargs["threshold"]
+        inclusive = kwargs["inclusive"]
+
+        if inclusive:
+            if value > threshold:
+                raise ValueError(
+                    f"Value must be at most {threshold}, got {value}"
+                )
+        else:
+            if value >= threshold:
+                raise ValueError(
+                    f"Value must be less than {threshold}, got {value}"
+                )
+
+        return value
+
+    def handle_date(
+        self,
+        value: date,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> date:
+        threshold = kwargs["threshold"]
+        inclusive = kwargs["inclusive"]
+
+        if inclusive:
+            if value > threshold:
+                raise ValueError(
+                    f"Value must be at most {threshold}, got {value}"
+                )
+        else:
+            if value >= threshold:
+                raise ValueError(
+                    f"Value must be less than {threshold}, got {value}"
+                )
+
+        return value
+
+    def handle_time(
+        self,
+        value: time,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> time:
+        threshold = kwargs["threshold"]
+        inclusive = kwargs["inclusive"]
+
+        if inclusive:
+            if value > threshold:
+                raise ValueError(
+                    f"Value must be at most {threshold}, got {value}"
+                )
+        else:
+            if value >= threshold:
+                raise ValueError(
+                    f"Value must be less than {threshold}, got {value}"
+                )
+
+        return value
+
+
+def less_than(
+    threshold: int | float | Decimal | datetime | date | time,
+    inclusive: bool = False,
+) -> Decorator:
+    """
+    Validate that a value is less than a threshold.
+
+    Type: `ChildNode`
+
+    Supports: `int`, `float`, `Decimal`, `datetime`, `date`, `time`
+
+    Args:
+        threshold (int | float | Decimal | datetime | date | time):
+            The threshold value to compare against.
+        inclusive (bool):
+            If `True`, allows values equal to threshold (<=).
+            If `False`, requires values strictly less (<).
+            Defaults to `False`.
+
+    Raises:
+        ValueError:
+            If value is not less than (or at most) the threshold.
+        TypeError:
+            If value type cannot be compared with threshold.
+
+    Examples:
+        Basic numeric validation:
+
+        >>> @command()
+        >>> @option("age", type=int)
+        >>> @less_than(100)
+        >>> def cmd(age):
+        ...     click.echo(f"Age: {age}")
+
+        >>> # Valid: 99, 50, 0, -5
+        >>> # Invalid: 100, 101, 200
+
+        With inclusive parameter:
+
+        >>> @command()
+        >>> @option("percentage", type=float)
+        >>> @less_than(100.0, inclusive=True)
+        >>> def cmd(percentage):
+        ...     click.echo(f"Percentage: {percentage}")
+
+        >>> # Valid: 100.0, 99.9, 50.0, 0.0
+        >>> # Invalid: 100.1, 150.0
+
+        Datetime validation:
+
+        >>> @command()
+        >>> @option("deadline")
+        >>> @to_date()
+        >>> @less_than(date(2025, 12, 31), inclusive=True)
+        >>> def cmd(deadline):
+        ...     click.echo(f"Deadline: {deadline}")
+
+        >>> # Valid: 2025-12-31, 2025-01-01, 2024-12-31
+        >>> # Invalid: 2026-01-01, 2026-12-31
+
+        Multiple values (automatic handling):
+
+        >>> @command()
+        >>> @option("scores", type=int, multiple=True)
+        >>> @less_than(100, inclusive=True)
+        >>> def cmd(scores):
+        ...     click.echo(f"Scores: {scores}")
+
+        >>> # Valid: (90, 85, 100), (50, 60, 70)
+        >>> # Invalid: (90, 101, 85), (100, 100, 105)
+        >>> # Note: Validation applies to each score individually
+    """
+    return LessThan.as_decorator(
+        threshold=threshold,
+        inclusive=inclusive,
+    )

click_extended/decorators/convert/__init__.py

@@ -0,0 +1,31 @@
+"""Initialization file for the `click_extended.decorators.convert` module."""
+
+from click_extended.decorators.convert.convert_angle import convert_angle
+from click_extended.decorators.convert.convert_area import convert_area
+from click_extended.decorators.convert.convert_bits import convert_bits
+from click_extended.decorators.convert.convert_distance import convert_distance
+from click_extended.decorators.convert.convert_energy import convert_energy
+from click_extended.decorators.convert.convert_power import convert_power
+from click_extended.decorators.convert.convert_pressure import convert_pressure
+from click_extended.decorators.convert.convert_speed import convert_speed
+from click_extended.decorators.convert.convert_temperature import (
+    convert_temperature,
+)
+from click_extended.decorators.convert.convert_time import convert_time
+from click_extended.decorators.convert.convert_volume import convert_volume
+from click_extended.decorators.convert.convert_weight import convert_weight
+
+__all__ = [
+    "convert_angle",
+    "convert_area",
+    "convert_bits",
+    "convert_distance",
+    "convert_energy",
+    "convert_power",
+    "convert_pressure",
+    "convert_time",
+    "convert_speed",
+    "convert_temperature",
+    "convert_volume",
+    "convert_weight",
+]

click_extended/decorators/convert/convert_angle.py

@@ -0,0 +1,94 @@
+"""Convert between different angle units."""
+
+import math
+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 = 35
+
+PI = Decimal(math.pi)
+
+UNITS = {
+    "deg": Decimal("1"),
+    "rad": Decimal("180") / PI,
+    "grad": Decimal("0.9"),
+    "turn": Decimal("360"),
+    "rev": Decimal("360"),
+    "arcmin": Decimal("1") / Decimal("60"),
+    "arcsec": Decimal("1") / Decimal("3600"),
+    "mil": Decimal("0.05625"),
+}
+
+
+class ConvertAngle(ChildNode):
+    """Convert between different angle 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"]
+        val = Decimal(str(value))
+
+        if from_unit not in UNITS:
+            raise ValueError(f"Unknown unit '{from_unit}'")
+        if to_unit not in UNITS:
+            raise ValueError(f"Unknown unit '{to_unit}'")
+
+        degrees = val * UNITS[from_unit]
+
+        return float(degrees / UNITS[to_unit])
+
+
+def convert_angle(
+    from_unit: Literal[
+        "deg",
+        "rad",
+        "grad",
+        "turn",
+        "arcmin",
+        "arcsec",
+        "rev",
+        "mil",
+    ],
+    to_unit: Literal[
+        "deg",
+        "rad",
+        "grad",
+        "turn",
+        "arcmin",
+        "arcsec",
+        "rev",
+        "mil",
+    ],
+) -> Decorator:
+    """
+    Convert between different angle units.
+
+    Type: `ChildNode`
+
+    Supports: `int`, `float`
+
+    Units:
+        - **deg**: Degree
+        - **rad**: Radian
+        - **grad**: Gradian
+        - **turn**: Full turn
+        - **arcmin**: Arcminute
+        - **arcsec**: Arcsecond
+        - **rev**: Revolution
+        - **mil**: NATO angular mil
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return ConvertAngle.as_decorator(from_unit=from_unit, to_unit=to_unit)

click_extended/decorators/convert/convert_area.py

@@ -0,0 +1,123 @@
+"""Convert between different area 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 = 35
+
+UNITS = {
+    "mm2": Decimal("1e-6"),
+    "cm2": Decimal("1e-4"),
+    "dm2": Decimal("1e-2"),
+    "m2": Decimal("1"),
+    "a": Decimal("100"),
+    "ha": Decimal("10000"),
+    "km2": Decimal("1e6"),
+    "in2": Decimal("0.00064516"),
+    "ft2": Decimal("0.09290304"),
+    "yd2": Decimal("0.83612736"),
+    "mi2": Decimal("2589988.110336"),
+    "acre": Decimal("4046.8564224"),
+    "rood": Decimal("1011.7141056"),
+    "perch": Decimal("25.29285264"),
+    "ang2": Decimal("1e-20"),
+    "tunnland": Decimal("4936.4"),
+}
+
+
+class ConvertArea(ChildNode):
+    """Convert between different area 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"]
+        val = Decimal(str(value))
+
+        if from_unit not in UNITS:
+            raise ValueError(f"Unknown unit '{from_unit}'")
+        if to_unit not in UNITS:
+            raise ValueError(f"Unknown unit '{to_unit}'")
+
+        m2 = val * UNITS[from_unit]
+
+        return float(m2 / UNITS[to_unit])
+
+
+def convert_area(
+    from_unit: Literal[
+        "mm2",
+        "cm2",
+        "dm2",
+        "m2",
+        "a",
+        "ha",
+        "km2",
+        "in2",
+        "ft2",
+        "yd2",
+        "mi2",
+        "acre",
+        "rood",
+        "perch",
+        "ang2",
+        "tunnland",
+    ],
+    to_unit: Literal[
+        "mm2",
+        "cm2",
+        "dm2",
+        "m2",
+        "a",
+        "ha",
+        "km2",
+        "in2",
+        "ft2",
+        "yd2",
+        "mi2",
+        "acre",
+        "rood",
+        "perch",
+        "ang2",
+        "tunnland",
+    ],
+) -> Decorator:
+    """
+    Convert between different area units.
+
+    Type: `ChildNode`
+
+    Supports: `int`, `float`.
+
+    Units:
+        - **mm2**: Square millimeter
+        - **cm2**: Square centimeter
+        - **dm2**: Square decimeter
+        - **m2**: Square meter
+        - **a**: Are (100 m2)
+        - **ha**: Hectare / hektar (10,000 m2)
+        - **km2**: Square kilometer
+        - **in2**: Square inch
+        - **ft2**: Square foot
+        - **yd2**: Square yard
+        - **mi2**: Square mile
+        - **acre**: Acre (43,560 ft2)
+        - **rood**: Rood (1/4 acre)
+        - **perch**: Perch (1/160 acre)
+        - **ang2**: Square ångström
+        - **tunnland**: Historical Swedish area unit (~4,937 m2)
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return ConvertArea.as_decorator(from_unit=from_unit, to_unit=to_unit)