aletk 0.1.0__py3-none-any.whl

aletk/ResultMonad.py

@@ -0,0 +1,279 @@
+from logging import Logger
+from typing import Any, Callable, NamedTuple
+from functools import wraps
+
+
+
+class Ok[T](NamedTuple):
+    """
+    Model for the success case of a function in this project.
+
+    Attributes
+    ----------
+    out : T
+        The data returned by the function.
+    """
+
+    out: T
+
+
+class Err(NamedTuple):
+    """
+    Model for the error case of a function in this project.
+
+    Attributes
+    ----------
+    message : str
+        A message describing the error.
+    code : int
+        A code that can be used to handle different error cases.
+    """
+
+    message: str
+    code: int
+
+
+type TResult[T] = Ok[T] | Err
+
+
+def rmap[T, U](f: Callable[[T], U], result: TResult[T]) -> TResult[U]:
+    """
+    Map a function over a Result.
+
+    Parameters
+    ----------
+    f : Callable[[T], U]
+        The function to map over the Result.
+    result : Result[T]
+        The Result to map the function over.
+
+    Returns
+    -------
+    Result[U]
+        The Result with the function mapped over it.
+    """
+
+    match result:
+        case Ok(out=data):
+            return Ok(out=f(data))
+        case Err(message=msg, code=code):
+            return Err(message=msg, code=code)
+        case _:
+            raise ValueError("Unknown Result type.")
+
+
+def rbind[T, U](f: Callable[[T], TResult[U]], result: TResult[T]) -> TResult[U]:
+    """
+    "result bind". Binds a function to a Result.
+
+    Parameters
+    ----------
+    f : Callable[[T], Result[E]]
+        The function to bind to the Result.
+    result : Result[T]
+        The Result to bind the function to.
+
+    Returns
+    -------
+    Result[E]
+        The Result with the function bound to it.
+    """
+
+    match result:
+        case Ok(out=data):
+            return f(data)
+        case Err(message=msg, code=code):
+            return Err(message=msg, code=code)
+        case _:
+            raise ValueError("Unknown Result type.")
+
+
+def runwrap[T](result: TResult[T]) -> T:
+    """
+    Unwrap a Result.
+
+    Parameters
+    ----------
+    result : Result[T]
+        The Result to unwrap.
+
+    Returns
+    -------
+    T
+        The data inside the Result.
+
+    Raises
+    ------
+    ValueError
+        If the Result is an Err.
+    """
+
+    match result:
+        case Ok(out=data):
+            return data
+        case Err(message=msg, code=code):
+            raise ValueError(f"Error: {msg}")
+
+
+def runwrap_or[T](result: TResult[T], default: T) -> T:
+    """
+    Unwrap a Result, returning a default value if the Result is an Err.
+
+    Parameters
+    ----------
+    result : Result[T]
+        The Result to unwrap.
+    default : T
+        The default value to return if the Result is an Err.
+
+    Returns
+    -------
+    T
+        The data inside the Result, or the default value if the Result is an Err.
+    """
+
+    match result:
+        case Ok(out=data):
+            return data
+        case Err(message=msg, code=code):
+            return default
+
+
+def try_except_wrapper[T](logger: Logger) -> Callable[[Callable[..., T]], Callable[..., TResult[T]]]:
+    """
+    Decorator that wraps a function in a try-except block, logging any errors that occur. The wrapped function will then always return a Ok[T] or Err as output.
+
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., TResult[T]]:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> TResult[T]:
+            try:
+                # logger.debug(f"Calling function '{func.__name__}' with args: {args} and kwargs: {kwargs}")
+                result = func(*args, **kwargs)
+
+                match result:
+                    case Err(message=msg, code=code):
+                        return result
+                    case Ok():
+                        # logger.debug(f"Function '{func.__name__}' executed successfully.")
+                        return result
+                    case _:
+                        # logger.debug(f"Function '{func.__name__}' executed successfully.")
+                        return Ok[T](out=result)
+
+            except Exception as e:
+                error_message_logger = f"An error occurred in function '{func.__name__}'. Detail:\n{e}"
+                logger.error(error_message_logger)
+
+                error_message_debug = f"The function that triggered the error was '{func.__name__}', called with... \n\t\targs: '[ {args} ]\n\t\tkwargs: [ {kwargs} ]'"
+                logger.debug(error_message_debug)
+
+                error_message_return = f"An error occurred in function '{func.__name__}'. Detail: {e}"
+
+                return Err(message=error_message_return, code=-1)
+
+        return wrapper
+
+    return decorator
+
+
+def runwrap_soft[T](result: TResult[T]) -> T | Err:
+    """
+    Unwrap a Result.
+
+    Parameters
+    ----------
+    result : Result[T]
+        The Result to unwrap.
+
+    Returns
+    -------
+    T
+        The data inside the Result.
+
+    Raises
+    ------
+    ValueError
+        If the Result is an Err.
+    """
+
+    match result:
+        case Ok(out=data):
+            return data
+        case Err(message=msg, code=code):
+            return Err(message=msg, code=code)
+
+
+def funwrap[T](func: Callable[..., TResult[T]]) -> Callable[..., T | Err]:
+    """
+    Wrap a function that returns a Result in a function that returns the data inside the Result.
+    """
+
+    def wrapper(*args: Any, **kwargs: Any) -> T | Err:
+        result = func(*args, **kwargs)
+        match result:
+            case Ok(out=data):
+                return data
+            case Err(message=msg, code=code):
+                return Err(message=msg, code=code)
+            case _:
+                raise ValueError(f"Function '{func.__name__}' returned an unknown Result type, with value '{result}'.")
+
+    return wrapper
+
+
+def main_try_except_wrapper[T](logger: Logger) -> Callable[[Callable[..., T]], Callable[..., TResult[T]]]:
+    """
+    Decorator that wraps a function in a try-except block, logging any errors that occur. The wrapped function will then always return a Ok[T] or Err as output.
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., TResult[T]]:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> TResult[T]:
+            try:
+                result = func(*args, **kwargs)
+
+                match result:
+                    case Err(message=msg, code=code):
+                        return result
+                    case Ok():
+                        return result
+                    case _:
+                        return Ok(out=result)
+
+            except Exception as e:
+                error_message_logger = f"'{func.__name__}':\n{e}"
+                logger.error(error_message_logger)
+
+                error_message_return = f"'{func.__name__}': {e}"
+                return Err(message=error_message_return, code=-1)
+
+        return wrapper
+
+    return decorator
+
+
+def light_error_handler[T](debug: bool = False) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Decorator that wraps a function in a try-except block, and returns a better error message if an exception is raised.
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            try:
+                return func(*args, **kwargs)
+
+            except Exception as e:
+                if not debug:
+                    error_message = f"An error occurred in function '{func.__name__}'. {e.__class__.__name__}: {e}"
+
+                else:
+                    error_message = f"An error occured in function '{func.__name__}', called with...\n\targs: [[ {args} ]]\n\tkwargs: [[ {kwargs} ]]\n\n{e.__class__.__name__}: {e}"
+
+                raise Exception(error_message)
+
+        return wrapper
+
+    return decorator

aletk/adapters.py

@@ -0,0 +1,29 @@
+from typing import Callable, Generator, Iterator
+
+
+
+class ReusableGenerator[T]():
+    """
+    Adapter class to allow consuming a generator more than once. Usage example:
+
+    ```python
+    def my_generator() -> Generator[int, None, None]:
+        yield 1
+        yield 2
+        yield 3
+
+    adapter = GeneratorAdapter(my_generator)
+
+    for item in adapter:
+        print(item)
+
+    for item in adapter:
+        print(item)
+    ```
+    """
+
+    def __init__(self, iterator_factory: Callable[[], Generator[T, None, None]]) -> None:
+        self.iterator_factory = iterator_factory
+
+    def __iter__(self) -> Iterator[T]:
+        return self.iterator_factory()

aletk/utils.py

@@ -0,0 +1,125 @@
+from datetime import datetime
+import logging
+from os import getenv
+from typing import FrozenSet
+from fuzzywuzzy import fuzz
+
+from .ResultMonad import Err
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Returns a logger object. Pass the name of the logger as an argument.
+
+    You can also pass the environment variables 'LOGGING_LEVEL' or 'LOG_LEVEL' to set the logging level. If none is passed, the default is 'INFO'.
+    """
+
+    if name is None or not isinstance(name, str):
+        raise ValueError("Utils::GetLogger::Argument 'name' has to be a non None string.")
+
+    logging_level = getenv("LOGGING_LEVEL", "")
+
+    if not logging_level:
+        logging_level = getenv("LOG_LEVEL", "INFO")
+
+    logger = logging.getLogger(name)
+    logger.setLevel(logging_level)
+
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setLevel(logging_level)
+        datefmt = "%Y-%m-%d %H:%M:%S"
+        formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt)
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+
+    return logger
+
+
+def remove_extra_whitespace(string: str) -> str:
+    """
+    Remove extra whitespace from a string. This version removes all newlines, tabs, carriage returns, trailing and leading whitespace, and multiple spaces in a row.
+
+    If the input is None or not a string, a ValueError is raised.
+    """
+    if string is None or not isinstance(string, str):
+        raise ValueError("Utils::RemoveExtraWhiteSpace::Argument string has to be a (non None) string.")
+
+    cleaned_string = " ".join(string.split()).strip()
+
+    return cleaned_string
+
+
+def get_timestamp() -> str:
+    """
+    Returns a string timestamp in the format YYYYMMDD_HHMMSS.
+    """
+    dt = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+    return dt
+
+
+def fuzzy_match_score(
+    str1: str,
+    str2: str,
+) -> int:
+    """
+    Returns a fuzzy match score between two strings.
+
+    If any of the inputs is None or not a string, a ValueError is raised.
+    """
+
+    if str1 is None or str2 is None or not isinstance(str1, str) or not isinstance(str2, str):
+        raise ValueError(f"Utils::FuzzyMatchScore::Arguments have to be non None strings. Got:\n'{str1}'\n'{str2}'")
+
+    score = fuzz.token_sort_ratio(str1, str2)
+
+    if not isinstance(score, int):
+        raise ValueError(
+            f"Utils::FuzzyMatchScore::The score returned by the fuzzywuzzy library is not an integer. Got: {score}"
+        )
+
+    return score
+
+
+def lginf(frame: str, msg: str, logger: logging.Logger) -> None:
+    """
+    Log an info message in a standard format.
+    """
+    logger.info(f"{frame}\n\t{msg}")
+
+
+def handle_error(frame: str, msg: str, logger: logging.Logger, code: int) -> Err:
+    """
+    Handle errors. This function returns an Err object with the message and code.
+    """
+    message = f"{frame}\n\t{msg}"
+    logger.error(message)
+    return Err(message=message, code=code)
+
+
+def handle_unexpected_exception(msg: str, logger: logging.Logger, code: int = -1) -> Err:
+    """
+    Handle unexpected exceptions. This function logs the message and returns an Err object with the message and code.
+    """
+    message = f"Unexpected exception!\n{msg}"
+    logger.error(message)
+    return Err(message=message, code=code)
+
+
+def pretty_format_frozenset(fs: FrozenSet[object]) -> str:
+    """
+    Pretty format a FrozenSet object, to be used in logging or printing.
+    """
+    if fs is None or fs == frozenset():
+        return ""
+    return ", ".join(sorted([f"{item}" for item in fs]))
+
+
+def dump_frozenset(fs: FrozenSet[object]) -> list[str]:
+    """
+    Dump a FrozenSet object to a list of strings.
+    """
+    if fs is None or fs == frozenset():
+        return []
+    return sorted([f"{item}" for item in fs])

aletk-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Luis Alejandro Bordo García
+
+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.

aletk-0.1.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.1
+Name: aletk
+Version: 0.1.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+License-File: LICENSE
+Requires-Dist: fuzzywuzzy
+Requires-Dist: python-Levenshtein
+Provides-Extra: dev
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: jupyter; extra == "dev"

aletk-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+aletk/ResultMonad.py,sha256=XPK1Ckg0L9u4iTJjUqHQIYT_RFdBlL47zm33GrGApG0,7732
+aletk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aletk/adapters.py,sha256=xahzDbinDpxaomP-gzFZ5CcasFTD1CkjP2H8Ly7bM1M,660
+aletk/utils.py,sha256=nvG-fRt4qIr-hBOFcpLN27mC0EEp877k3sf72O1rBE0,3800
+aletk-0.1.0.dist-info/LICENSE,sha256=hZFMbARrXo4zfuo80-Sg3-FT5_ceiSDf0QpjgJoUdGc,1085
+aletk-0.1.0.dist-info/METADATA,sha256=y5UVAZ4EQyZsuzqk4zkjqyKBM58WzdceYtD55Amf62Y,471
+aletk-0.1.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+aletk-0.1.0.dist-info/top_level.txt,sha256=LYDb8QWbh4W4hIkF0TVg5ITKEsaj-pb_xcYQRGzLqUU,6
+aletk-0.1.0.dist-info/RECORD,,

aletk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aletk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aletk