spArgValidatorPy 1.0.1__py3-none-any.whl

spArgValidatorPy/ArgValidator.py

@@ -0,0 +1,220 @@
+# ================================================================================
+#
+#   ArgValidator class
+#
+#   object for validating function arguments and either raising an exception 
+#   or returning the validated value
+#
+#   MIT License
+#
+#   Copyright (c) 2025 krokoreit (krokoreit@gmail.com)
+#
+#   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.
+#
+# ================================================================================
+
+import sys
+import inspect
+
+
+original_excepthook = sys.excepthook
+stop_TB_at_function_name = None
+def my_excepthook(type, value, traceback):
+    """A replacement for sys.excepthook to stop traceback output at stop_TB_at_function_name."""
+    print("my_excepthook")
+    iter_tb = traceback
+    while iter_tb.tb_next is not None:
+        if iter_tb.tb_next.tb_frame.f_code.co_name is stop_TB_at_function_name:
+            iter_tb.tb_next = None
+            break
+        iter_tb = iter_tb.tb_next
+    original_excepthook(type, value, traceback)
+
+# shift to my handler
+sys.excepthook = my_excepthook
+
+def raise_with_stopped_traceback(exception_type, exception_text):
+    """Raises an exception of exception_type with a formated text with name and signature of the 'error function' and exception_text.
+        Traceback will be stopped at that function."""
+    global stop_TB_at_function_name
+
+    frame = inspect.currentframe().f_back.f_back
+    function_name = frame.f_code.co_name
+    stop_TB_at_function_name = function_name
+    function = None
+    if "self" in frame.f_locals:
+        function = getattr(frame.f_locals["self"].__class__, function_name)
+    else:
+        function = getattr(inspect.getmodule(frame), function_name)
+    if function is None:
+        sig = "()"
+    else:    
+        sig = inspect.signature(function)
+    raise exception_type(function_name + str(sig) + " " + exception_text)
+
+def reset_traceback():
+    """Resets the stop_TB_at_function_name to None. This is to prevent unintended stopping of traceback information. This would occur
+    when a raise_with_stopped_traceback() created exception gets caught with a try-except-block and a subsequent exception 
+    occurs with the stop_TB_at_function_name still being on the calling stack ... Call reset_traceback() at start of each validation."""
+
+def get_value_for_var_name(var_name):
+    """Returns the value for the variable named var_name."""
+    frame = inspect.currentframe().f_back
+    local_vars = frame.f_back.f_locals
+    if len(var_name) == 0:
+        raise_with_stopped_traceback(ValueError, "called without var_name, must be one of " + str(local_vars.keys()) + ".")
+    if var_name not in local_vars:
+        raise_with_stopped_traceback(ValueError, "called with unknown var_name '" + var_name + "', must be one of " + str(local_vars.keys()) + ".")
+    return local_vars[var_name]
+
+
+class ArgValidator:
+
+    def get_validated_int(self, var_name, min_value=None, max_value=None, strict=False, *, default=None, return_limits=False):
+        """Returns a validated integer value or raises exception. Optional checking for limits (min_value, max_value) or in strict 
+        mode (not allowing string representation of an integer). Specifying an integer value with default=[int] or setting 
+        return_limits=True will prohibit an exception being raised and the default or exceeded limit value is returned."""
+        
+        reset_traceback()
+        if default is not None and not isinstance(default, int):
+            raise_with_stopped_traceback(TypeError, "called with 'default' not being an integer.")
+
+        value = get_value_for_var_name(var_name)
+        # might be string representation
+        if isinstance(value, str):
+            if strict:
+                if default is not None:
+                    return default
+                raise_with_stopped_traceback(TypeError, "called with '" + var_name + "' not being a string.")
+            else:
+                sValue = value.strip()
+                try:
+                    value = int(sValue)
+                    if str(value) != sValue:
+                        value = None
+                except Exception as e:
+                    value = None
+        if not isinstance(value, int):
+            if default is not None:
+                return default
+            raise_with_stopped_traceback(TypeError, "called with '" + var_name + "' not being an integer or a string representation of an integer.")
+        if min_value is not None and value < min_value:
+            if return_limits:
+                return min_value
+            if default is not None:
+                return default
+            raise_with_stopped_traceback(ValueError, "called with '" + var_name + "' being less than minimum value of " + str(min_value) + ".")
+        if max_value is not None and value > max_value:
+            if return_limits:
+                return max_value
+            if default is not None:
+                return default
+            raise_with_stopped_traceback(ValueError, "called with '" + var_name + "' being more than maximum value of " + str(max_value) + ".")
+        return value
+
+
+    def get_validated_float(self, var_name, min_value=None, max_value=None, strict=False, *, default=None, return_limits=False):
+        """Returns a validated float value or raises exception. Optional checking for limits (min_value, max_value) or in strict 
+        mode (not allowing string representation of an float). Specifying an float value with default=[float] or setting 
+        return_limits=True will prohibit an exception being raised and the default or exceeded limit value is returned."""
+
+        reset_traceback()
+        if default is not None and not isinstance(default, float):
+            raise_with_stopped_traceback(TypeError, "called with 'default' not being a float.")
+
+        value = get_value_for_var_name(var_name)
+        # might be string representation
+        if isinstance(value, str):
+            if strict:
+                if default is not None:
+                    return default
+                raise_with_stopped_traceback(TypeError, "called with '" + var_name + "' not being a string.")
+            else:
+                sValue = value.strip()
+                period_pos = sValue.find(".")
+                if period_pos > -1:
+                    # trim trailing zeros
+                    sPos = len(sValue) - 1
+                    while sPos > period_pos + 2:
+                        if sValue[sPos] == "0":
+                            sPos -= 1
+                        else:
+                            period_pos = len(sValue)
+                    sValue = sValue[:sPos+1]
+                else:
+                    sValue += ".0"
+                try:
+                    value = float(sValue)
+                    if str(value) != sValue:
+                        value = None
+                except Exception as e:
+                    value = None
+        elif isinstance(value, int):
+            # accepting int as float
+            value = float(value)
+        # check for float
+        if not isinstance(value, float):
+            if default is not None:
+                return default
+            raise_with_stopped_traceback(TypeError, "called with '" + var_name + "' not being a float or a string representation of a float.")
+        if min_value is not None and value < min_value:
+            if return_limits:
+                return min_value
+            if default is not None:
+                return default
+            raise_with_stopped_traceback(ValueError, "called with '" + var_name + "' being less than minimum value of " + str(min_value) + ".")
+        if max_value is not None and value > max_value:
+            if return_limits:
+                return max_value
+            if default is not None:
+                return default
+            raise_with_stopped_traceback(ValueError, "called with '" + var_name + "' being more than maximum value of " + str(max_value) + ".")
+        return value
+
+
+
+    def get_validated_str(self, var_name, min_length=1, strict=False, *, default=None):
+        """Returns a validated string value or raises exception. Optional checking in strict mode (not allowing non-string 
+        values that can be converted to string). Specifying an string value with default=[string] will prohibit an 
+        exception being raised and the default being returned."""
+
+        reset_traceback()
+        if default is not None and not isinstance(default, str):
+            raise_with_stopped_traceback(TypeError, "called with 'default' not being a string.")
+
+        value = get_value_for_var_name(var_name)
+        if not isinstance(value, str):
+            if strict:
+                if default is not None:
+                    return default
+                raise_with_stopped_traceback(TypeError, "called with '" + var_name + "' not being a string.")
+            else:
+                try:
+                    value = str(value)
+                except:
+                    if default is not None:
+                        return default
+                    raise_with_stopped_traceback(TypeError, "called with '" + var_name + "' not being convertable to a string.")
+
+        if len(value) < min_length:
+            if default is not None:
+                return default
+            raise_with_stopped_traceback(ValueError, "called with length of '" + var_name + "' being less than " + str(min_length) + " characters.")
+        return value
+

spArgValidatorPy/__init__.py

@@ -0,0 +1,6 @@
+# limit the exported strings for 'import *' usage
+__all__ = [
+    "ArgValidator"
+]
+
+from .ArgValidator import ArgValidator

spargvalidatorpy-1.0.1.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: spArgValidatorPy
+Version: 1.0.1
+Summary: A Python package for validating function arguments and either raising an exception or returning the validated value.
+Project-URL: Homepage, https://github.com/krokoreit/spArgValidatorPy
+Project-URL: Source Code, https://github.com/krokoreit/spArgValidatorPy
+Author-email: krokoreit <krokoreit@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: argument validation,function arguments,valid float,valid integer,valid string,validator
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# spArgValidatorPy
+
+[![PyPI - Version](https://img.shields.io/pypi/v/spArgValidatorPy.svg)](https://pypi.org/project/spArgValidatorPy)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/spArgValidatorPy.svg)](https://pypi.org/project/spArgValidatorPy)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+This package provides a Python module for validating function arguments. Depending on the outcome, it either raises an exception or returns the validated value.
+
+If a numeric argument is provided as a string representation (e.g. "100" or "3.24"), it will be converted and returned as a valid int or float, unless validation is performed in strict mode. Numeric arguments can also be checked against minimum and/or maximum limits.
+
+String arguments are considered valid if they can be converted to a string (e.g. 123 becomes "123"), unless validation is done in strict mode, which only accepts values of type str. By default, empty strings cause an exception, but this can be disabled by allowing a minimum length of 0.
+
+All validation functions support an optional default argument. If provided, this value is returned instead of raising an exception when validation fails. This simplifies code by removing the need for a separate try–except block to set fallback values. The default must be passed as a keyword argument (default=value) and must match the expected type (str, int, or float).
+
+For numeric validations, you can also enable the return_limits=True option to return the defined minimum or maximum value instead of raising an exception.
+
+For more details, see the API reference below and the examples in examples/example01.py, which includes over 20 usage demonstrations.
+
+Enjoy
+
+&emsp;krokoreit  
+&emsp;&emsp;&emsp;<img src="![assets/krokoreit-01.svg](https://github.com/krokoreit/spArgValidatorPy/blob/main/assets/krokoreit-01.svg)" width="140"/>
+
+
+## Installation
+
+```console
+pip install spArgValidatorPy
+```
+
+
+## Usage & API
+
+### ArgValidator Class
+Import module and instantiate an ArgValidator object:
+```py
+  from spArgValidatorPy import ArgValidator
+
+  av = ArgValidator()
+```
+
+Argument validation is then as simple as
+```py
+  def my_function(str_arg, int_arg, float_arg):
+      str_arg = av.get_validated_str("str_arg")
+      int_arg = av.get_validated_int("int_arg")
+      float_arg = av.get_validated_float("float_arg")
+      ....
+```
+Note that the name of the argument is passed to the validation function and not the value.  
+After successful validation (no exception raised), these variables can be safely used as str, int and float. For more complex validation with the use of strict mode, minimum or maximum values allowed or defaults, see the validation functions below.
+
+
+</br>
+
+### API
+
+#### Methods
+* [get_validated_int()](#get_validated_int-method)  
+* [get_validated_float()](#get_validated_float-method)  
+* [get_validated_str()](#get_validated_str-method)  
+</br>
+</br>
+
+
+#### get_validated_int() Method
+```py
+  get_validated_int(var_name, min_value, max_value, strict, default=int_value, return_limits=boolean_value)
+```
+Arguments:
+- var_name  
+  The name of the argument being validated.
+- min_value  
+  Optional lower limit to validate var_name's value against.
+- max_value  
+  Optional upper limit to validate var_name's value against.
+- strict  
+  Optional boolean argument to allow only integers as var_name's value, when set to True. The default is validation in non-strict mode, which allows string representations of an integer (e.g. "220").
+- default=int_value  
+  Optional keyword argument for an integer default value. When set, it avoids an exception being raised in case var_name's value fails validation and this default value is returned instead. 
+- return_limits=boolean_value  
+  Optional keyword argument to avoid an exception being raised for values outside the limits. 
+  When set to True and with either min_value or max_value being exceeded, this limit value is returned as validated value.
+
+Returns the validated integer value or with the default or return_limits option used, one of these values instead of an exception raised.
+
+<div style="text-align: right"><a href="#methods">&#8679; back up to list of methods</a></div>
+
+</br>
+
+#### get_validated_float() Method
+```py
+  get_validated_float(var_name, min_value, max_value, strict, default=float_value, return_limits=boolean_value)
+```
+Arguments:
+- var_name  
+  The name of the argument being validated.
+- min_value  
+  Optional lower limit to validate var_name's value against.
+- max_value  
+  Optional upper limit to validate var_name's value against.
+- strict  
+  Optional boolean argument to allow only a float as var_name's value, when set to True. The default is validation in non-strict mode, which allows string representations of a float (e.g. "1.99").
+- default=float_value  
+  Optional keyword argument for a float default value. When set, it avoids an exception being raised in case var_name's value fails validation and this default value is returned instead. 
+- return_limits=boolean_value  
+  Optional keyword argument to avoid an exception being raised for values outside the limits. 
+  When set to True and with either min_value or max_value being exceeded, this limit value is returned as validated value.
+
+Returns the validated float value or with the default or return_limits option used, one of these values instead of an exception raised.
+
+
+<div style="text-align: right"><a href="#methods">&#8679; back up to list of methods</a></div>
+
+</br>
+
+#### get_validated_str() Method
+```py
+  get_validated_str(var_name, min_length, strict, default=str_value)
+```
+- var_name  
+  The name of the argument being validated.
+- min_length  
+  The minimum length required for a valid string. By default thi sis set to 1, meaning that empty strings will throw an exception. This can be set to 0 to allow empty strings or to any other length, against which you want to validate.
+- strict  
+  Optional boolean argument to allow only a string as var_name's value, when set to True. The default is validation in non-strict mode, which allows any value, which can be converted into a string.
+- default=str_value  
+  Optional keyword argument for a string default value. When set, it avoids an exception being raised in case var_name's value fails validation and this default value is returned instead. 
+
+Returns the validated string value or with the default option used, this value instead of an exception raised.
+
+<div style="text-align: right"><a href="#methods">&#8679; back up to list of methods</a></div>
+
+</br>
+
+## License
+MIT license  
+Copyright &copy; 2025 by krokoreit

spargvalidatorpy-1.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+spArgValidatorPy/ArgValidator.py,sha256=JCecoyrZp9Krnme3UaVIrQGbIl94PMT5bWZ7xy-AedY,10662
+spArgValidatorPy/__init__.py,sha256=MsbSdo-oz6o-PhLXcomI11bBZkU5bDNiB-9hmreuhl8,129
+spargvalidatorpy-1.0.1.dist-info/METADATA,sha256=4dw1Mf_XxaIYlyVH-3Rib0H0rxa8kkPQ6tb-t4qWdgA,7347
+spargvalidatorpy-1.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+spargvalidatorpy-1.0.1.dist-info/licenses/LICENSE,sha256=OGLCoSaPB4W5LyOH3IQDWolNTYJCyW2UgpllcHnEm3c,1109
+spargvalidatorpy-1.0.1.dist-info/RECORD,,

spargvalidatorpy-1.0.1.dist-info/WHEEL

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

spargvalidatorpy-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 krokoreit (krokoreit@gmail.com)
+
+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.