UniversalFunctions 1.3.0__tar.gz → 2.1.0__tar.gz

{universalfunctions-1.3.0/UniversalFunctions.egg-info → universalfunctions-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: UniversalFunctions
-Version: 1.3.0
+Version: 2.1.0
 Summary: A Python utility library providing foundational functions, validators, and infrastructure.
 Author-email: "Miah M. Sabiq" <miah.sabiq@gibs.at>
 Requires-Python: >=3.14
@@ -28,10 +28,12 @@ The package requires Python 3.14 or later.
 
 UniversalFunctions is imported through the UF Python package:
 
+```python
 from UF.Validators import TypeValidate
 from numbers import Real
 
 TypeValidate(Real)(56)
+```
 
 The distribution name is UniversalFunctions, while the Python import package is UF.
 
@@ -49,16 +51,25 @@ Provides runtime validation utilities and validation classes for enforcing types
 
 #### Notable components include:
 
-* ``TypeValidate``
-* ``TupleValidate``
-* ``LessThan``
-* ``LessOrEqual``
-* ``GreaterOrEqual``
-* ``Positive``
-* ``real_validate``
-* ``str_validate``
+* ``TypeValidate`` -> class for validating an object against an expected type
+* ``SequenceValidate`` -> class used to validate a sequence of objects
+* ``LessThan`` -> class to validate a real number, constraint: value < expected
+* ``qtm_validation_decorator`` -> when applied to a function, the decorator takes the provided parameter values and validates them against the expected type
+* ``ErrorDedent``
 * Callable validation utilities
 
+This package inside UF contains numerous validators designed to validate all sorts of values and types, 
+including some sophisticated ones like SequenceValidate which allows users to enter extra restrictions to the items in a given sequence.
+
+There are 2 extra errors which are provided: 
+* ``ItemCountError``
+* ``ConstraintError``
+
+ItemCountError was created since Python does not have an error for a situation where the values and types 
+might be correct, though the number of items is not.
+
+ConstraintError provides users to express that the type of a value might be correct, though it fails to pass a specific constraint.
+
 The validation system also contains the Quantum Turtle Mechanics (QTM) validation infrastructure used for more structured runtime validation.
 
 ### Decorators
@@ -67,9 +78,8 @@ UniversalFunctions provides reusable decorator infrastructure, including decorat
 
 #### Notable components include:
 
-* ``class_decorator``
-* ``deco_superposition``
-* ``cls_deco_superposition``
+* ``deco_superposition`` -> applies an arbitrary number of decorators to a function
+* ``cls_deco_superposition`` -> applies an arbitrary number of decorators to every function in a class, except for protected ones (names starting with "_")
 * Quantum Turtle Mechanics validation decorators
 
 ### Helper Functions
@@ -106,16 +116,6 @@ Python 3.14 or later
 
 UniversalFunctions is designed for modern Python and makes use of contemporary Python typing and language features.
 
-## Development
-
-Clone the repository and install it in editable mode:
-
-git clone https://github.com/Mangosaber2026/UniversalFunctions.git
-cd UniversalFunctions
-pip install -e .
-
-Editable installation allows changes to the source code to be reflected immediately without reinstalling the package.
-
 ## License
 
 UniversalFunctions is distributed under the terms of the license included in this repository.

{universalfunctions-1.3.0 → universalfunctions-2.1.0}/README.md

@@ -18,10 +18,12 @@ The package requires Python 3.14 or later.
 
 UniversalFunctions is imported through the UF Python package:
 
+```python
 from UF.Validators import TypeValidate
 from numbers import Real
 
 TypeValidate(Real)(56)
+```
 
 The distribution name is UniversalFunctions, while the Python import package is UF.
 
@@ -39,16 +41,25 @@ Provides runtime validation utilities and validation classes for enforcing types
 
 #### Notable components include:
 
-* ``TypeValidate``
-* ``TupleValidate``
-* ``LessThan``
-* ``LessOrEqual``
-* ``GreaterOrEqual``
-* ``Positive``
-* ``real_validate``
-* ``str_validate``
+* ``TypeValidate`` -> class for validating an object against an expected type
+* ``SequenceValidate`` -> class used to validate a sequence of objects
+* ``LessThan`` -> class to validate a real number, constraint: value < expected
+* ``qtm_validation_decorator`` -> when applied to a function, the decorator takes the provided parameter values and validates them against the expected type
+* ``ErrorDedent``
 * Callable validation utilities
 
+This package inside UF contains numerous validators designed to validate all sorts of values and types, 
+including some sophisticated ones like SequenceValidate which allows users to enter extra restrictions to the items in a given sequence.
+
+There are 2 extra errors which are provided: 
+* ``ItemCountError``
+* ``ConstraintError``
+
+ItemCountError was created since Python does not have an error for a situation where the values and types 
+might be correct, though the number of items is not.
+
+ConstraintError provides users to express that the type of a value might be correct, though it fails to pass a specific constraint.
+
 The validation system also contains the Quantum Turtle Mechanics (QTM) validation infrastructure used for more structured runtime validation.
 
 ### Decorators
@@ -57,9 +68,8 @@ UniversalFunctions provides reusable decorator infrastructure, including decorat
 
 #### Notable components include:
 
-* ``class_decorator``
-* ``deco_superposition``
-* ``cls_deco_superposition``
+* ``deco_superposition`` -> applies an arbitrary number of decorators to a function
+* ``cls_deco_superposition`` -> applies an arbitrary number of decorators to every function in a class, except for protected ones (names starting with "_")
 * Quantum Turtle Mechanics validation decorators
 
 ### Helper Functions
@@ -96,16 +106,6 @@ Python 3.14 or later
 
 UniversalFunctions is designed for modern Python and makes use of contemporary Python typing and language features.
 
-## Development
-
-Clone the repository and install it in editable mode:
-
-git clone https://github.com/Mangosaber2026/UniversalFunctions.git
-cd UniversalFunctions
-pip install -e .
-
-Editable installation allows changes to the source code to be reflected immediately without reinstalling the package.
-
 ## License
 
 UniversalFunctions is distributed under the terms of the license included in this repository.

{universalfunctions-1.3.0 → universalfunctions-2.1.0}/UF/ClassToDict.py

@@ -17,6 +17,7 @@ def classes_to_dict(*classes: type) -> dict[str, Callable]:
     >>> result = classes_to_dict(RandomClass)
     >>> list(result)
     ['get_item']
+
     :param classes: Classes from which the callables are extracted
     :return: Dictionary of callable names and their objects
     """

universalfunctions-2.1.0/UF/GetVariable.py

@@ -0,0 +1,116 @@
+"""
+This module contains an extremely important function: get_num, which takes a numerical value from the user.
+"""
+
+from time import sleep as rest
+from typing import overload, Literal, Final
+from numbers import Real
+from .Validators import (
+    LessThan,
+    str_validate,
+    real_validate,
+    TypeValidate,
+    GreaterOrEqual,
+    LessOrEqual,
+    type_error,
+    GreaterThan,
+)
+
+
+type int_type = type[int]
+type float_type = type[float]
+
+@overload
+def get_num(TYPE: int_type, entry: str, **options) -> int: ...
+
+@overload
+def get_num(TYPE: float_type, entry: str, **options) -> float: ...
+
+def get_num(
+        TYPE: float_type|int_type,
+        entry: str,
+        **options
+) -> Real:
+    """
+    Gets a real numerical value from the user
+
+    :param TYPE: float or int;  which type of value to check for
+    :param entry: str; input string
+    :param options: MAX, MIN, store
+    :return: float or int
+    """
+    func_name: Final[Literal["get_num"]] = "get_num"
+    type_obj_name: Final[Literal["TYPE"]] = "TYPE"
+
+    store_var: Final[Literal["store"]] = "store"
+    store_value = options[store_var]
+
+    min_var: Final[Literal["MIN"]] = "MIN"
+    min_value = options[min_var]
+
+    max_var: Final[Literal["MAX"]] = "MAX"
+    max_value = options[max_var]
+
+    if TYPE not in (int, float):
+        raise type_error()(f"""
+            TypeError
+            
+            Function: {func_name}
+            Parameter {type_obj_name} must be type float or int!
+            Expected: int or float object
+            Received:
+                Name: {type_obj_name}
+                Value: {TYPE}
+            """)
+
+    str_validate()(entry, name="entry")
+
+    real_validate()(max_value, name=max_var)
+    real_validate()(min_value, name=min_var)
+
+    if min_var in options and max_var in options:
+        LessThan(max_value)(min_value, name=min_var)
+
+    if store_var in options:
+        TypeValidate((Real, type(None)))(store_value, name=store_var)
+
+    if (
+        store_var in options
+        and min_var in options
+        and max_var in options
+        and store_value is not None
+    ):
+        GreaterThan(min_value)(store_value, name=store_var)
+
+    while True:
+        try:
+            if store_var in options:
+                reserve: str = input(entry)
+                if reserve == "ans":
+                    if isinstance(store_value, Real):
+                        value: Real = store_value
+                    else:
+                        print("\nThere is no value stored yet!")
+                        continue
+                else:
+                    value: Real = TYPE(reserve)
+            else:
+                value: Real = TYPE(input(entry))
+            value_name: Literal["value"] = "value"
+
+            if min_var in options and max_var in options:
+                GreaterOrEqual(min_value)(value, name=value_name)
+                LessOrEqual(max_value)(value, name=value_name)
+
+            elif min_var in options:
+                GreaterOrEqual(min_value)(value, name=value_name)
+
+            elif max_var in options:
+                LessOrEqual(max_value)(value, name=value_name)
+
+            elif store_var in options:
+                options["store"] = value
+            return value
+        except ValueError as error:
+            print(error)
+            rest(1.5)

{universalfunctions-1.3.0 → universalfunctions-2.1.0}/UF/Trigonometry.py

@@ -1,3 +1,7 @@
+"""
+This module contains a collection of trigonometric functions to be used with degrees.
+"""
+
 from math import (
     radians,
     degrees,
@@ -12,6 +16,10 @@ from .Validators import real_validate
 def sine(angle: Real) -> Real:
     """
     Calculates the sine of a given angle
+
+    >>> sin(0)
+    0
+
     :param angle: value required in degrees
     :return: sine value
     """
@@ -21,6 +29,10 @@ def sine(angle: Real) -> Real:
 def cosine(angle: Real) -> Real:
     """
     Calculates the cosine of a given angle
+
+    >>> cosine(0)
+    1
+
     :param angle: value required in degrees
     :return: cosine value
     """
@@ -30,6 +42,10 @@ def cosine(angle: Real) -> Real:
 def asine(value: Real) -> Real:
     """
     Calculates the asine of a given angle
+
+    >>> asine(0)
+    0
+
     :param value: real value
     :return: asine value
     """

universalfunctions-2.1.0/UF/Validators/Errors.py

@@ -0,0 +1,130 @@
+"""
+This module provides a collection of error message deliverers and separate errors created by the author which
+are not normally provided with Python.
+
+The custom errors in this module can be used just like any other conventional error provided by Python itself.
+"""
+
+from textwrap import dedent
+from typing import Callable, Final, Literal
+
+
+class ErrorDedent:
+    """
+    This class is the error raiser for the other validators found in this package (UF).
+
+    The use of this class is to make the error message be printed with some formatting instead of the conventional
+    way it would be printed otherwise.
+
+    >>> print(ErrorDedent(TypeError)("This is a TypeError!"))
+    TypeError
+    <BLANKLINE>
+    This is a TypeError!
+    """
+    name: Final[Literal["ErrorDedent"]] = "ErrorDedent"
+    def __init__(self, error_func) -> None:
+        if not isinstance(error_func, type) or not issubclass(error_func, Exception):
+            raise TypeError(dedent(f"""
+                TypeError:
+                Validator: ErrorDedent
+                Parameter 'error_func' MUST be an error class!
+                expected: Exception subclass
+                received: {error_func}
+                """).strip())
+        self.error_func = error_func
+
+    def __call__(self, text: str) -> Exception:
+        if not isinstance(text, str):
+            raise TypeError(dedent(f"""
+                TypeError:
+                Validator: {self.name} 
+                Parameter 'text' MUST be a string object!
+                expected: str
+                received: {text}
+                """).strip())
+        return self.error_func(dedent(f"""
+            {self.error_func.__name__}
+            
+            {text}
+            """).strip())
+
+def type_error() -> Callable:
+    """
+    This function returns a callable type error function.
+
+    >>> print(type_error()("This is a TypeError!"))
+    TypeError
+    <BLANKLINE>
+    This is a TypeError!
+
+    :return: ErrorDedent function
+    """
+    return ErrorDedent(TypeError)
+
+def value_error() -> Callable:
+    """
+    This function returns a callable value error function.
+
+    >>> print(value_error()("This is a ValueError!"))
+    ValueError
+    <BLANKLINE>
+    This is a ValueError!
+
+    :return: ErrorDedent function
+    """
+    return ErrorDedent(ValueError)
+
+def item_count_error() -> Callable:
+    """
+    This function returns a callable item count error function.
+
+    >>> print(item_count_error()("This is an Item Count Error!"))
+    ItemCountError
+    <BLANKLINE>
+    This is an Item Count Error!
+
+    :return: ErrorDedent function
+    """
+    return ErrorDedent(ItemCountError)
+
+def constraint_error() -> Callable:
+    """
+    This function returns a callable constraint error function.
+
+    >>> print(constraint_error()("This is a Constraint Error!"))
+    ConstraintError
+    <BLANKLINE>
+    This is a Constraint Error!
+
+    :return: ErrorDedent function
+    """
+    return ErrorDedent(ConstraintError)
+
+def attribute_error() -> Callable:
+    """
+    This function returns a callable attribute error function.
+
+    >>> print(attribute_error()("This is an Attribute Error!"))
+    AttributeError
+    <BLANKLINE>
+    This is an Attribute Error!
+
+    :return: ErrorDedent function
+    """
+    return ErrorDedent(AttributeError)
+
+class ItemCountError(Exception):
+    """
+    This exception is raised when an item count does not match the expected count.
+
+    >>> print(ItemCountError("This is an Item Count Error!"))
+    This is an Item Count Error!
+    """
+
+class ConstraintError(Exception):
+    """
+    This exception is raised when an item does not pass the expected constraint.
+
+    >>> print(ConstraintError("This is a Constraint Error!"))
+    This is a Constraint Error!
+    """

{universalfunctions-1.3.0 → universalfunctions-2.1.0}/UF/Validators/QuantumFuncValidators.py

@@ -10,13 +10,13 @@ from functools import wraps
 from .ValidationClasses import TypeValidate
 
 
-def qtm_func_validator(func: Callable, *args, **kwargs) -> bool:
+def qtm_func_validator(func: Callable, *args, **kwargs) -> Callable:
     """
     Takes a function and compares the entered value with the expected type
     :param func: given function
     :param args: arguments
     :param kwargs: keyword arguments
-    :return: True if the provided argument matches the expected type, raises an error if not
+    :return: given function if the provided argument matches the expected type, raises an error if not
     """
     TypeValidate(Callable)(func, name=func.__name__)
     sig = signature(func)
@@ -40,11 +40,11 @@ def qtm_func_validator(func: Callable, *args, **kwargs) -> bool:
         else:
             TypeValidate(type_)(value, name=name)
 
-    return True
+    return func
 
 def qtm_validation_decorator(func: Callable) -> Callable:
     """
-    DECORATOR!
+    QUANTUM DECORATOR!
 
     Decorates a function with the quantum function validator and returns the function
     :param func: provided function
@@ -56,4 +56,4 @@ def qtm_validation_decorator(func: Callable) -> Callable:
     def wrapper(*args, **kwargs):
         qtm_func_validator(func, *args, **kwargs)
         return func(*args, **kwargs)
-    return wrapper
+    return wrapper

{universalfunctions-1.3.0 → universalfunctions-2.1.0}/UF/Validators/QuantumValidators.py

@@ -4,6 +4,8 @@ This module contains type validators for list and tuple which belong to the QTM
 
 from typing import Any, get_args, get_origin, Annotated
 from .ValidationClasses import TypeValidate, SequenceValidate
+from .Errors import type_error
+from typing import Final, Literal
 
 def qtm_lt_validator(value: list[Any] | tuple[Any, ...], TYPE: Any, name: str) -> tuple | list:
     """
@@ -17,9 +19,15 @@ def qtm_lt_validator(value: list[Any] | tuple[Any, ...], TYPE: Any, name: str) -
     :param name: name of value
     :return: validated list/tuple of elements
     """
+    func_name: Final[Literal["qtm_lt_validator"]] = "qtm_lt_validator"
     origin = get_origin(TYPE)
     if origin not in (list, tuple):
-        raise TypeError(f"{TYPE} must be a list or tuple for a specific type! e.g. list[int]")
+        raise type_error()(f"""
+            Validator: {func_name}
+            Parameter TYPE must be a list/tuple of elements!
+            Expected: type object
+            Received: {TYPE}
+            """)
 
     TypeValidate(origin)(value)
 
@@ -36,9 +44,14 @@ def qtm_constr_validator(value: Any, annotation, name: str) -> Any:
     :param name: name of value
     :return: True, if validation succeeds
     """
-
+    func_name: Final[Literal["qtm_constr_validator"]] = "qtm_constr_validator"
     if get_origin(annotation) is not Annotated:
-        raise TypeError(f"{annotation} is not an Annotated type!")
+        raise type_error()(f"""
+            Validator: {func_name}
+            Parameter annotation is not an Annotated type!
+            Expected: Annotated object
+            Received: {annotation}
+            """)
 
     type_obj, *constraints = get_args(annotation)