simplibs-types 0.1.0__py3-none-any.whl

simplibs/types/__init__.py

@@ -0,0 +1,285 @@
+from .collections.dict import (
+    dict_not_empty,
+    dict_length,
+    dict_min_length,
+    dict_max_length,
+)
+from .collections.list import (
+    list_not_empty,
+    list_unique,
+    list_unique_not_empty,
+    list_of,
+    list_length,
+    list_min_length,
+    list_max_length,
+)
+from .collections.set import (
+    set_not_empty,
+    set_of,
+    set_length,
+    set_min_length,
+    set_max_length,
+)
+from .collections.tuple import (
+    tuple_not_empty,
+    tuple_of,
+    tuple_length,
+    tuple_min_length,
+    tuple_max_length,
+)
+from .primitives.bool import (
+    bool_true,
+    bool_false,
+)
+from .primitives.bytes import (
+    bytes_empty,
+    bytes_not_empty,
+    bytes_length,
+    bytes_min_length,
+    bytes_max_length,
+    bytes_length_range,
+)
+from .primitives.float import (
+    float_positive,
+    float_negative,
+    float_non_negative,
+    float_non_positive,
+    float_zero,
+    float_not_zero,
+    float_finite,
+    float_not_nan,
+    float_not_infinite,
+    float_probability,
+    float_percentage,
+    float_latitude,
+    float_longitude,
+    float_gt,
+    float_ge,
+    float_lt,
+    float_le,
+    float_in_range,
+)
+from .primitives.int import (
+    int_positive,
+    int_negative,
+    int_non_negative,
+    int_non_positive,
+    int_zero,
+    int_not_zero,
+    int_even,
+    int_odd,
+    int_positive_even,
+    int_positive_odd,
+    int_non_negative_even,
+    int_uint8,
+    int_int8,
+    int_percentage,
+    int_port,
+    int_year,
+    int_month,
+    int_day_of_month,
+    int_hour,
+    int_minute,
+    int_second,
+    int_gt,
+    int_ge,
+    int_lt,
+    int_le,
+    int_eq,
+    int_ne,
+    int_in_range,
+    int_divisible_by,
+    int_multiple_of,
+)
+from .primitives.int_float import (
+    int_float_positive,
+    int_float_negative,
+    int_float_non_negative,
+    int_float_non_positive,
+    int_float_zero,
+    int_float_not_zero,
+    int_float_finite,
+    int_float_in_range,
+)
+from .primitives.str import (
+    str_empty,
+    str_not_empty,
+    str_blank,
+    str_not_blank,
+    str_whitespace,
+    str_alpha,
+    str_alnum,
+    str_digit,
+    str_ascii,
+    str_printable,
+    str_lower,
+    str_upper,
+    str_title,
+    str_no_whitespace,
+    str_single_line,
+    str_identifier,
+    str_slug,
+    str_snake_case,
+    str_email,
+    str_url,
+    str_uuid,
+    str_hex_color,
+    str_length,
+    str_min_length,
+    str_max_length,
+    str_length_range,
+    str_starts_with,
+    str_ends_with,
+    str_contains,
+    str_matches,
+    str_one_of,
+)
+
+
+__all__ = [
+    # collections/dict
+    "dict_not_empty",
+    "dict_length",
+    "dict_min_length",
+    "dict_max_length",
+    # collections/list
+    "list_not_empty",
+    "list_unique",
+    "list_unique_not_empty",
+    "list_of",
+    "list_length",
+    "list_min_length",
+    "list_max_length",
+    # collections/set
+    "set_not_empty",
+    "set_of",
+    "set_length",
+    "set_min_length",
+    "set_max_length",
+    # collections/tuple
+    "tuple_not_empty",
+    "tuple_of",
+    "tuple_length",
+    "tuple_min_length",
+    "tuple_max_length",
+    # types/bool
+    "bool_true",
+    "bool_false",
+    # types/bytes
+    "bytes_empty",
+    "bytes_not_empty",
+    "bytes_length",
+    "bytes_min_length",
+    "bytes_max_length",
+    "bytes_length_range",
+    # types/float
+    "float_positive",
+    "float_negative",
+    "float_non_negative",
+    "float_non_positive",
+    "float_zero",
+    "float_not_zero",
+    "float_finite",
+    "float_not_nan",
+    "float_not_infinite",
+    "float_probability",
+    "float_percentage",
+    "float_latitude",
+    "float_longitude",
+    "float_gt",
+    "float_ge",
+    "float_lt",
+    "float_le",
+    "float_in_range",
+    # types/int
+    "int_positive",
+    "int_negative",
+    "int_non_negative",
+    "int_non_positive",
+    "int_zero",
+    "int_not_zero",
+    "int_even",
+    "int_odd",
+    "int_positive_even",
+    "int_positive_odd",
+    "int_non_negative_even",
+    "int_uint8",
+    "int_int8",
+    "int_percentage",
+    "int_port",
+    "int_year",
+    "int_month",
+    "int_day_of_month",
+    "int_hour",
+    "int_minute",
+    "int_second",
+    "int_gt",
+    "int_ge",
+    "int_lt",
+    "int_le",
+    "int_eq",
+    "int_ne",
+    "int_in_range",
+    "int_divisible_by",
+    "int_multiple_of",
+    # types/int_float
+    "int_float_positive",
+    "int_float_negative",
+    "int_float_non_negative",
+    "int_float_non_positive",
+    "int_float_zero",
+    "int_float_not_zero",
+    "int_float_finite",
+    "int_float_in_range",
+    # types/str
+    "str_empty",
+    "str_not_empty",
+    "str_blank",
+    "str_not_blank",
+    "str_whitespace",
+    "str_alpha",
+    "str_alnum",
+    "str_digit",
+    "str_ascii",
+    "str_printable",
+    "str_lower",
+    "str_upper",
+    "str_title",
+    "str_no_whitespace",
+    "str_single_line",
+    "str_identifier",
+    "str_slug",
+    "str_snake_case",
+    "str_email",
+    "str_url",
+    "str_uuid",
+    "str_hex_color",
+    "str_length",
+    "str_min_length",
+    "str_max_length",
+    "str_length_range",
+    "str_starts_with",
+    "str_ends_with",
+    "str_contains",
+    "str_matches",
+    "str_one_of",
+]
+
+
+_DESIGN_NOTES = """
+# simplibs-types — Package Overview
+
+## Purpose
+The top-level entry point of `simplibs-types`. Re-exports ready-made
+preset type from `presets/colections` and `presets/types`, so a caller
+never has to reach into the internal folder structure directly:
+
+    from simplibs.types import int_positive, str_email, validated_type
+
+## Internal Components Registry
+
+| Component            | Type      | Description                                                     |
+| :---------------------- | :-------- | :-------------------------------------------------------------------- |
+| `presets.colections.*`   | Sub-Package | Container presets (`dict`, `list`, `set`, `tuple`).                   |
+| `presets.types.*`        | Sub-Package | Scalar type presets (`bool`, `bytes`, `float`, `int`, `number`, `str`).|
+"""

simplibs/types/collections/__init__.py

@@ -0,0 +1,18 @@
+# src/simplibs/03_simplibs-types/presets/colections/__init__.py
+_DESIGN_NOTES = """
+# Collections Presets Package
+
+## Purpose
+Validated types for the four built-in container types. Each sub-package
+groups one container's presets (non-emptiness, length constraints, item
+uniqueness, per-item validation via `*_of` factories).
+
+## Internal Components Registry
+
+| Component  | Type      | Description                                       |
+| :---------- | :-------- | :--------------------------------------------------- |
+| `dict`      | Sub-Package | Presets for `dict` (emptiness, length).             |
+| `list`      | Sub-Package | Presets for `list` (emptiness, uniqueness, length, `list_of`). |
+| `set`       | Sub-Package | Presets for `set` (emptiness, length, `set_of`).     |
+| `tuple`     | Sub-Package | Presets for `tuple` (emptiness, length, `tuple_of`). |
+"""

simplibs/types/collections/dict/__init__.py

@@ -0,0 +1,24 @@
+# Direct:
+from .direct.dict_not_empty import dict_not_empty
+# Parametric:
+from .parametrized.dict_length import dict_length
+from .parametrized.dict_min_length import dict_min_length
+from .parametrized.dict_max_length import dict_max_length
+
+
+_DESIGN_NOTES = """
+# Dict Presets Sub-Package
+
+## Purpose
+Validated types for `dict` — non-emptiness and length constraints (exact,
+minimum, maximum number of key-value pairs).
+
+## Internal Components Registry
+
+| Component          | Type            | Description                                    |
+| :------------------ | :-------------- | :---------------------------------------------- |
+| `dict_not_empty`    | Validated Type  | Non-empty dictionary.                            |
+| `dict_length`       | Factory         | Dictionary with an exact number of items.        |
+| `dict_min_length`   | Factory         | Dictionary with a minimum number of items.       |
+| `dict_max_length`   | Factory         | Dictionary with a maximum number of items.       |
+"""

simplibs/types/collections/dict/direct/dict_not_empty.py

@@ -0,0 +1,18 @@
+from simplibs.validate import validated_type
+from simplibs.rules import not_empty
+
+
+dict_not_empty = validated_type(dict, not_empty)
+"""Validated type for a non-empty dictionary.
+
+Init Params:
+    (no parameters)
+
+Validation pipeline:
+    1. Value must be of type `dict`.
+    2. Value must not be empty (must contain at least one item).
+
+Example:
+    @validate_call
+    def process(data: dict_not_empty): ...
+"""

simplibs/types/collections/dict/parametrized/dict_length.py

@@ -0,0 +1,23 @@
+from typing import Any
+from simplibs.validate import validated_type
+from simplibs.rules import has_length
+
+
+def dict_length(exact: int) -> Any:
+    """Validated type for a dictionary with an exact number of items.
+
+    Init Params:
+        exact (int): The exact number of key-value pairs the dictionary
+            must contain.
+
+    Validation pipeline:
+        1. Value must be of type `dict`.
+        2. Value's length must equal `exact`.
+
+    Example:
+        ThreeItemDict = dict_length(3)
+
+        @validate_call
+        def process(data: ThreeItemDict): ...
+    """
+    return validated_type(dict, has_length(exact))

simplibs/types/collections/dict/parametrized/dict_max_length.py

@@ -0,0 +1,23 @@
+from typing import Any
+from simplibs.validate import validated_type
+from simplibs.rules import has_length
+
+
+def dict_max_length(max_length: int) -> Any:
+    """Validated type for a dictionary with a maximum number of items.
+
+    Init Params:
+        max_length (int): The maximum number of key-value pairs the
+            dictionary may contain (inclusive).
+
+    Validation pipeline:
+        1. Value must be of type `dict`.
+        2. Value's length must be less than or equal to `max_length`.
+
+    Example:
+        SmallDict = dict_max_length(10)
+
+        @validate_call
+        def process(data: SmallDict): ...
+    """
+    return validated_type(dict, has_length(max_length=max_length))

simplibs/types/collections/dict/parametrized/dict_min_length.py

@@ -0,0 +1,23 @@
+from typing import Any
+from simplibs.validate import validated_type
+from simplibs.rules import has_length
+
+
+def dict_min_length(min_length: int) -> Any:
+    """Validated type for a dictionary with a minimum number of items.
+
+    Init Params:
+        min_length (int): The minimum number of key-value pairs the
+            dictionary must contain (inclusive).
+
+    Validation pipeline:
+        1. Value must be of type `dict`.
+        2. Value's length must be greater than or equal to `min_length`.
+
+    Example:
+        NonTrivialDict = dict_min_length(2)
+
+        @validate_call
+        def process(data: NonTrivialDict): ...
+    """
+    return validated_type(dict, has_length(min_length=min_length))

simplibs/types/collections/list/__init__.py

@@ -0,0 +1,30 @@
+# Direct:
+from .direct.list_not_empty import list_not_empty
+from .direct.list_unique import list_unique
+from .direct.list_unique_not_empty import list_unique_not_empty
+# Parametric:
+from .parametrized.list_of import list_of
+from .parametrized.list_length import list_length
+from .parametrized.list_min_length import list_min_length
+from .parametrized.list_max_length import list_max_length
+
+
+_DESIGN_NOTES = """
+# List Presets Sub-Package
+
+## Purpose
+Validated types for `list` — non-emptiness, item uniqueness, per-item
+validation via `list_of`, and length constraints (exact, minimum, maximum).
+
+## Internal Components Registry
+
+| Component               | Type            | Description                                       |
+| :----------------------- | :-------------- | :-------------------------------------------------- |
+| `list_not_empty`         | Validated Type  | Non-empty list.                                      |
+| `list_unique`            | Validated Type  | List with all unique items.                          |
+| `list_unique_not_empty`  | Validated Type  | Non-empty list with all unique items.                |
+| `list_of`                | Factory         | List whose every item satisfies a given rule.        |
+| `list_length`            | Factory         | List with an exact number of items.                  |
+| `list_min_length`        | Factory         | List with a minimum number of items.                 |
+| `list_max_length`        | Factory         | List with a maximum number of items.                 |
+"""

simplibs/types/collections/list/direct/list_not_empty.py

@@ -0,0 +1,18 @@
+from simplibs.validate import validated_type
+from simplibs.rules import not_empty
+
+
+list_not_empty = validated_type(list, not_empty)
+"""Validated type for a non-empty list.
+
+Init Params:
+    (no parameters)
+
+Validation pipeline:
+    1. Value must be of type `list`.
+    2. Value must not be empty (must contain at least one item).
+
+Example:
+    @validate_call
+    def process(items: list_not_empty): ...
+"""

simplibs/types/collections/list/direct/list_unique.py

@@ -0,0 +1,18 @@
+from simplibs.validate import validated_type
+from simplibs.rules import all_unique
+
+
+list_unique = validated_type(list, all_unique)
+"""Validated type for a list whose items are all unique.
+
+Init Params:
+    (no parameters)
+
+Validation pipeline:
+    1. Value must be of type `list`.
+    2. All items in the list must be unique (no duplicates).
+
+Example:
+    @validate_call
+    def process(items: list_unique): ...
+"""

simplibs/types/collections/list/direct/list_unique_not_empty.py

@@ -0,0 +1,19 @@
+from simplibs.validate import validated_type
+from simplibs.rules import not_empty, all_unique
+
+
+list_unique_not_empty = validated_type(list, not_empty & all_unique)
+"""Validated type for a non-empty list whose items are all unique.
+
+Init Params:
+    (no parameters)
+
+Validation pipeline:
+    1. Value must be of type `list`.
+    2. Value must not be empty (must contain at least one item).
+    3. All items in the list must be unique (no duplicates).
+
+Example:
+    @validate_call
+    def process(items: list_unique_not_empty): ...
+"""

simplibs/types/collections/list/parametrized/list_length.py

@@ -0,0 +1,22 @@
+from typing import Any
+from simplibs.validate import validated_type
+from simplibs.rules import has_length
+
+
+def list_length(exact: int) -> Any:
+    """Validated type for a list with an exact number of items.
+
+    Init Params:
+        exact (int): The exact number of items the list must contain.
+
+    Validation pipeline:
+        1. Value must be of type `list`.
+        2. Value's length must equal `exact`.
+
+    Example:
+        TripletList = list_length(3)
+
+        @validate_call
+        def process(items: TripletList): ...
+    """
+    return validated_type(list, has_length(exact))

simplibs/types/collections/list/parametrized/list_max_length.py

@@ -0,0 +1,23 @@
+from typing import Any
+from simplibs.validate import validated_type
+from simplibs.rules import has_length
+
+
+def list_max_length(max_length: int) -> Any:
+    """Validated type for a list with a maximum number of items.
+
+    Init Params:
+        max_length (int): The maximum number of items the list may
+            contain (inclusive).
+
+    Validation pipeline:
+        1. Value must be of type `list`.
+        2. Value's length must be less than or equal to `max_length`.
+
+    Example:
+        SmallList = list_max_length(10)
+
+        @validate_call
+        def process(items: SmallList): ...
+    """
+    return validated_type(list, has_length(max_length=max_length))

simplibs/types/collections/list/parametrized/list_min_length.py

@@ -0,0 +1,23 @@
+from typing import Any
+from simplibs.validate import validated_type
+from simplibs.rules import has_length
+
+
+def list_min_length(min_length: int) -> Any:
+    """Validated type for a list with a minimum number of items.
+
+    Init Params:
+        min_length (int): The minimum number of items the list must
+            contain (inclusive).
+
+    Validation pipeline:
+        1. Value must be of type `list`.
+        2. Value's length must be greater than or equal to `min_length`.
+
+    Example:
+        NonTrivialList = list_min_length(2)
+
+        @validate_call
+        def process(items: NonTrivialList): ...
+    """
+    return validated_type(list, has_length(min_length=min_length))

simplibs/types/collections/list/parametrized/list_of.py

@@ -0,0 +1,30 @@
+from typing import Any
+from simplibs.validate import validated_type
+from simplibs.rules import for_each
+
+
+def list_of(item_rule: Any) -> Any:
+    """Validated type for a list whose every item satisfies a given rule.
+
+    Init Params:
+        item_rule (Rule | Callable[[Any], bool]): Rule that every single
+            item of the list must satisfy.
+
+    Validation pipeline:
+        1. Value must be of type `list`.
+        2. Every item of the list must satisfy `item_rule`.
+
+    Detailed description:
+        `item_rule` is applied to each item individually (see `for_each`) —
+        if validation fails for a single item, validation of the whole
+        list fails. `item_rule` itself may be an arbitrarily composed rule
+        (e.g. via `&`, `|`, `~`), including another `validated_type` used
+        as a nested annotation.
+
+    Example:
+        PositiveIntList = list_of(greater_than(0))
+
+        @validate_call
+        def register(scores: PositiveIntList): ...
+    """
+    return validated_type(list, for_each(item_rule))

simplibs/types/collections/set/__init__.py

@@ -0,0 +1,26 @@
+# Direct:
+from .direct.set_not_empty import set_not_empty
+# Parametric:
+from .parametrized.set_of import set_of
+from .parametrized.set_length import set_length
+from .parametrized.set_min_length import set_min_length
+from .parametrized.set_max_length import set_max_length
+
+
+_DESIGN_NOTES = """
+# Set Presets Sub-Package
+
+## Purpose
+Validated types for `set` — non-emptiness, per-item validation via
+`set_of`, and length constraints (exact, minimum, maximum).
+
+## Internal Components Registry
+
+| Component         | Type            | Description                                    |
+| :----------------- | :-------------- | :----------------------------------------------- |
+| `set_not_empty`    | Validated Type  | Non-empty set.                                    |
+| `set_of`           | Factory         | Set whose every item satisfies a given rule.      |
+| `set_length`       | Factory         | Set with an exact number of items.                |
+| `set_min_length`   | Factory         | Set with a minimum number of items.               |
+| `set_max_length`   | Factory         | Set with a maximum number of items.               |
+"""

simplibs/types/collections/set/direct/set_not_empty.py

@@ -0,0 +1,18 @@
+from simplibs.validate import validated_type
+from simplibs.rules import not_empty
+
+
+set_not_empty = validated_type(set, not_empty)
+"""Validated type for a non-empty set.
+
+Init Params:
+    (no parameters)
+
+Validation pipeline:
+    1. Value must be of type `set`.
+    2. Value must not be empty (must contain at least one item).
+
+Example:
+    @validate_call
+    def process(items: set_not_empty): ...
+"""