oddments 0.1.0__tar.gz

oddments-0.1.0/LICENSE

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

oddments-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.1
+Name: oddments
+Version: 0.1.0
+Summary: Collection of general-purpose utilities.
+Home-page: https://github.com/zteinck/oddments
+License: MIT
+Author: Zachary Einck
+Author-email: zacharyeinck@gmail.com
+Requires-Python: >=3.8,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: numpy
+Requires-Dist: pandas
+Project-URL: Repository, https://github.com/zteinck/oddments
+Description-Content-Type: text/markdown
+
+# oddments
+`oddments` is a Python package that offers a collection of general-purpose utilities.
+
+## Installation
+```sh
+pip install oddments
+```
+

oddments-0.1.0/README.md

@@ -0,0 +1,7 @@
+# oddments
+`oddments` is a Python package that offers a collection of general-purpose utilities.
+
+## Installation
+```sh
+pip install oddments
+```

oddments-0.1.0/oddments/__init__.py

@@ -0,0 +1,2 @@
+__version__ = '0.1.0'
+__author__ = 'Zachary Einck <zacharyeinck@gmail.com>'

oddments-0.1.0/oddments/decorators.py

@@ -0,0 +1,41 @@
+from functools import wraps
+
+from .utils import validate_value
+
+
+
+
+def validate_setter(call_func=False, **kwargs):
+    '''
+    Description
+    ------------
+    Decorator for methods that are ultimately decorated by setters.
+    Validates the value being set via validate_value().
+
+    Parameters
+    ------------
+    call_func : bool
+        If True, the wrapped function is called with self and value arguments
+        passed. Otherwise, a protected attribute is set mirroring func's name.
+        This parameter is useful for those scenarios where custom logic needs
+        to be applied before setting the protected attribute.
+    kwargs : dict
+        keyword arguments passed to validate_value().
+
+    Returns
+    ------------
+    None
+    '''
+
+    def decorator(func):
+
+        @wraps(func)
+        def wrapper(self, value):
+            attr = func.__name__
+            validate_value(attr=attr, value=value, **kwargs)
+            if call_func: return func(self, value)
+            setattr(self, '_' + attr, value)
+
+        return wrapper
+
+    return decorator

oddments-0.1.0/oddments/utils.py

@@ -0,0 +1,111 @@
+import numpy as np
+
+
+
+
+def validate_value(
+    value,
+    types,
+    attr=None,
+    finite=False,
+    min_value=None,
+    max_value=None,
+    min_inclusive=False,
+    max_inclusive=False,
+    whitelist=None,
+    blacklist=None,
+    none_ok=False,
+    empty_ok=True
+    ):
+    '''
+    Description
+    ------------
+    Validates an an argument's type and value.
+
+    Parameters
+    ------------
+    value : *
+        argument to validate
+    types : object | tuple
+        one or more valid types of which value is allowed to be an instance.
+    attr : str | None
+        Optional name of value to include in error messages. If None, 'value'
+        is used.
+    finite : bool
+        if True, the value is not allowed to be -np.inf, +np.inf, np.nan, or
+        any other value that would cause np.isfinite to return False.
+    min_value : float | None
+        minimum allowed value
+    max_value : float | None
+        maximum allowed value
+    min_inclusive : bool
+        if True, value is allowed to be equal to min_value (e.g. greater than
+        or equal to)
+    max_inclusive : bool
+        if True, value is allowed to be equal to max_value (e.g. less than or
+        equal to)
+    whitelist : str | list
+        list of acceptable values
+    blacklist : str | list
+        list of prohibited values
+    none_ok : bool
+        if True, None is an acceptable value and no further validation is
+        necessary.
+    empty_ok : bool
+        if True, len(value) is allowed to be zero.
+
+    Returns
+    ------------
+    None
+    '''
+    if none_ok and value is None: return
+    attr_name = f"'{attr or 'value'}'"
+
+    if not isinstance(types, tuple):
+        types = (types,)
+
+    if not isinstance(value, types):
+        type_names = [f'<{x.__name__}>' for x in types]
+        type_names = f"{', '.join(type_names[:-1])} or {type_names[-1]}" \
+                     if len(type_names) > 1 else type_names[0]
+        value_type = f'<{type(value).__name__}>'
+        raise TypeError(f"{attr_name} must be a {type_names}, got {value_type}.")
+
+    if blacklist is not None:
+        if isinstance(blacklist, str):
+            blacklist = [blacklist]
+        if value in blacklist:
+            raise ValueError(f"{attr_name} cannot be in {blacklist}, got {value}.")
+
+    if whitelist is not None:
+        if isinstance(whitelist, str):
+            whitelist = [whitelist]
+        if value in whitelist: return
+        raise ValueError(f"{attr_name} must be in {whitelist}, got {value}.")
+
+    if not empty_ok and len(value) == 0:
+        raise ValueError(f"{attr_name} cannot be empty.")
+
+    if finite:
+        if not np.isfinite(value):
+            raise TypeError(f"{attr_name} must be finite, got {value}")
+
+    msg = f"{attr_name} must be {{0}} {{1}}, got {value}"
+
+    if min_value is not None:
+        symbol = None
+        if min_inclusive and value < min_value:
+            symbol = '≥'
+        if not min_inclusive and value <= min_value:
+            symbol = '>'
+        if symbol is not None:
+            raise ValueError(msg.format(symbol, min_value))
+
+    if max_value is not None:
+        symbol = None
+        if max_inclusive and value > max_value:
+            symbol = '≤'
+        if not max_inclusive and value >= max_value:
+            symbol = '<'
+        if symbol is not None:
+            raise ValueError(msg.format(symbol, max_value))

oddments-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[tool.poetry]
+name = "oddments"
+version = "0.1.0"
+description = "Collection of general-purpose utilities."
+authors = ["Zachary Einck <zacharyeinck@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+repository = "https://github.com/zteinck/oddments"
+homepage = "https://github.com/zteinck/oddments"
+
+[tool.poetry.dependencies]
+python = "^3.8"
+numpy = "*"
+pandas = "*"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"