potato-util 0.0.1__py3-none-any.whl

potato_util/__init__.py

@@ -0,0 +1,6 @@
+from .__version__ import __version__
+
+
+__all__ = [
+    "__version__",
+]

potato_util/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

potato_util/_base.py

@@ -0,0 +1,117 @@
+import re
+import copy
+import logging
+
+from pydantic import validate_call
+
+
+logger = logging.getLogger(__name__)
+
+
+@validate_call
+def deep_merge(dict1: dict, dict2: dict) -> dict:
+    """Return a new dictionary that's the result of a deep merge of two dictionaries.
+    If there are conflicts, values from `dict2` will overwrite those in `dict1`.
+
+    Args:
+        dict1 (dict, required): The base dictionary that will be merged.
+        dict2 (dict, required): The dictionary to merge into `dict1`.
+
+    Returns:
+        dict: The merged dictionary.
+    """
+
+    _merged = copy.deepcopy(dict1)
+    for _key, _val in dict2.items():
+        if (
+            _key in _merged
+            and isinstance(_merged[_key], dict)
+            and isinstance(_val, dict)
+        ):
+            _merged[_key] = deep_merge(_merged[_key], _val)
+        else:
+            _merged[_key] = copy.deepcopy(_val)
+
+    return _merged
+
+
+@validate_call
+def camel_to_snake(val: str) -> str:
+    """Convert CamelCase to snake_case.
+
+    Args:
+        val (str): CamelCase string to convert.
+
+    Returns:
+        str: Converted snake_case string.
+    """
+
+    val = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", val)
+    val = re.sub("([a-z0-9])([A-Z])", r"\1_\2", val).lower()
+    return val
+
+
+@validate_call
+def clean_obj_dict(obj_dict: dict, cls_name: str) -> dict:
+    """Clean class name from object.__dict__ for str(object).
+
+    Args:
+        obj_dict (dict, required): Object dictionary by object.__dict__.
+        cls_name (str , required): Class name by cls.__name__.
+
+    Returns:
+        dict: Clean object dictionary.
+    """
+
+    try:
+        if not obj_dict:
+            raise ValueError("'obj_dict' argument value is empty!")
+
+        if not cls_name:
+            raise ValueError("'cls_name' argument value is empty!")
+    except ValueError as err:
+        logger.error(err)
+        raise
+
+    _self_dict = obj_dict.copy()
+    for _key in _self_dict.copy():
+        _class_prefix = f"_{cls_name}__"
+        if _key.startswith(_class_prefix):
+            _new_key = _key.replace(_class_prefix, "")
+            _self_dict[_new_key] = _self_dict.pop(_key)
+    return _self_dict
+
+
+@validate_call(config={"arbitrary_types_allowed": True})
+def obj_to_repr(obj: object) -> str:
+    """Modifying object default repr() to custom info.
+
+    Args:
+        obj (object, required): Any python object.
+
+    Returns:
+        str: String for repr() method.
+    """
+
+    try:
+        if not obj:
+            raise ValueError("'obj' argument value is empty!")
+    except ValueError as err:
+        logger.error(err)
+        raise
+
+    _self_repr = (
+        f"<{obj.__class__.__module__}.{obj.__class__.__name__} object at {hex(id(obj))}: "
+        + "{"
+        + f"{str(dir(obj)).replace('[', '').replace(']', '')}"
+        + "}>"
+    )
+    return _self_repr
+
+
+__all__ = [
+    "deep_merge",
+    "camel_to_snake",
+    "clean_obj_dict",
+    "obj_to_repr",
+]

potato_util/constants/__init__.py

@@ -0,0 +1,5 @@
+# flake8: noqa
+
+from ._base import *
+from ._enum import *
+from ._regex import *

potato_util/constants/_base.py

@@ -0,0 +1,5 @@
+MAX_PATH_LENGTH = 1024
+
+__all__ = [
+    "MAX_PATH_LENGTH",
+]

potato_util/constants/_enum.py

@@ -0,0 +1,31 @@
+from enum import Enum
+
+
+class WarnEnum(str, Enum):
+    ERROR = "ERROR"
+    ALWAYS = "ALWAYS"
+    DEBUG = "DEBUG"
+    IGNORE = "IGNORE"
+
+
+class TSUnitEnum(str, Enum):
+    SECONDS = "SECONDS"
+    MILLISECONDS = "MILLISECONDS"
+    MICROSECONDS = "MICROSECONDS"
+    NANOSECONDS = "NANOSECONDS"
+
+
+class HashAlgoEnum(str, Enum):
+    md5 = "md5"
+    sha1 = "sha1"
+    sha224 = "sha224"
+    sha256 = "sha256"
+    sha384 = "sha384"
+    sha512 = "sha512"
+
+
+__all__ = [
+    "WarnEnum",
+    "TSUnitEnum",
+    "HashAlgoEnum",
+]

potato_util/constants/_regex.py

@@ -0,0 +1,23 @@
+REQUEST_ID_REGEX = (
+    r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b|"
+    r"\b[0-9a-fA-F]{32}\b"
+)
+
+# Invalid characters:
+SPECIAL_CHARS_REGEX = r"[&'\"<>]"
+SPECIAL_CHARS_BASE_REGEX = r"[&'\"<>\\\/]"
+SPECIAL_CHARS_LOW_REGEX = r"[&'\"<>\\\/`{}|]"
+SPECIAL_CHARS_MEDIUM_REGEX = r"[&'\"<>\\\/`{}|()\[\]]"
+SPECIAL_CHARS_HIGH_REGEX = r"[&'\"<>\\\/`{}|()\[\]!@#$%^*;:?]"
+SPECIAL_CHARS_STRICT_REGEX = r"[&'\"<>\\\/`{}|()\[\]~!@#$%^*_=\-+;:,.?\t\n ]"
+
+
+__all__ = [
+    "REQUEST_ID_REGEX",
+    "SPECIAL_CHARS_REGEX",
+    "SPECIAL_CHARS_BASE_REGEX",
+    "SPECIAL_CHARS_LOW_REGEX",
+    "SPECIAL_CHARS_MEDIUM_REGEX",
+    "SPECIAL_CHARS_HIGH_REGEX",
+    "SPECIAL_CHARS_STRICT_REGEX",
+]

potato_util/dt.py

@@ -0,0 +1,240 @@
+import time
+import logging
+from zoneinfo import ZoneInfo
+from datetime import datetime, timezone, tzinfo, timedelta
+
+from pydantic import validate_call
+
+from .constants import WarnEnum, TSUnitEnum
+
+
+logger = logging.getLogger(__name__)
+
+
+@validate_call(config={"arbitrary_types_allowed": True})
+def add_tzinfo(dt: datetime, tz: ZoneInfo | tzinfo | str) -> datetime:
+    """Add or replace timezone info to datetime object.
+
+    Args:
+        dt (datetime                    , required): Datetime object.
+        tz (Union[ZoneInfo, tzinfo, str], required): Timezone info.
+
+    Returns:
+        datetime: Datetime object with timezone info.
+    """
+
+    if isinstance(tz, str):
+        tz = ZoneInfo(tz)
+
+    dt = dt.replace(tzinfo=tz)
+    return dt
+
+
+@validate_call
+def datetime_to_iso(
+    dt: datetime, sep: str = "T", warn_mode: WarnEnum = WarnEnum.IGNORE
+) -> str:
+    """Convert datetime object to ISO 8601 format.
+
+    Args:
+        dt        (datetime, required): Datetime object.
+        sep       (str     , optional): Separator between date and time. Defaults to "T".
+        warn_mode (WarnEnum, optional): Warning mode. Defaults to WarnEnum.IGNORE.
+
+    Raises:
+        ValueError: If `sep` argument length is greater than 8.
+        ValueError: If `dt` argument doesn't have any timezone info and `warn_mode` is set to WarnEnum.ERROR.
+
+    Returns:
+        str: Datetime string in ISO 8601 format.
+    """
+
+    sep = sep.strip()
+    if 8 < len(sep):
+        raise ValueError(
+            f"`sep` argument length '{len(sep)}' is too long, must be less than or equal to 8!"
+        )
+
+    if not dt.tzinfo:
+        _message = "Not found any timezone info in `dt` argument, assuming it's UTC timezone..."
+        if warn_mode == WarnEnum.ALWAYS:
+            logger.warning(_message)
+        elif warn_mode == WarnEnum.DEBUG:
+            logger.debug(_message)
+        elif warn_mode == WarnEnum.ERROR:
+            _message = "Not found any timezone info in `dt` argument!"
+            logger.error(_message)
+            raise ValueError(_message)
+
+        dt = add_tzinfo(dt=dt, tz="UTC")
+
+    _dt_str = dt.isoformat(sep=sep, timespec="milliseconds")
+    return _dt_str
+
+
+@validate_call(config={"arbitrary_types_allowed": True})
+def convert_tz(
+    dt: datetime, tz: ZoneInfo | tzinfo | str, warn_mode: WarnEnum = WarnEnum.ALWAYS
+) -> datetime:
+    """Convert datetime object to another timezone.
+
+    Args:
+        dt        (datetime                    , required): Datetime object to convert.
+        tz        (Union[ZoneInfo, tzinfo, str], required): Timezone info to convert.
+        warn_mode (WarnEnum                    , optional): Warning mode. Defaults to WarnEnum.ALWAYS.
+
+    Raises:
+        ValueError: If `dt` argument doesn't have any timezone info and `warn_mode` is set to WarnEnum.ERROR.
+
+    Returns:
+        datetime: Datetime object which has been converted to another timezone.
+    """
+
+    if not dt.tzinfo:
+        _message = "Not found any timezone info in `dt` argument, assuming it's UTC timezone..."
+        if warn_mode == WarnEnum.ALWAYS:
+            logger.warning(_message)
+        elif warn_mode == WarnEnum.DEBUG:
+            logger.debug(_message)
+        elif warn_mode == WarnEnum.ERROR:
+            _message = "Not found any timezone info in `dt` argument!"
+            logger.error(_message)
+            raise ValueError(_message)
+
+        dt = add_tzinfo(dt=dt, tz="UTC")
+
+    if isinstance(tz, str):
+        tz = ZoneInfo(tz)
+
+    dt = dt.astimezone(tz=tz)
+    return dt
+
+
+def now_utc_dt() -> datetime:
+    """Get current datetime in UTC timezone with tzinfo.
+
+    Returns:
+        datetime: Current datetime in UTC timezone with tzinfo.
+    """
+
+    _utc_dt = datetime.now(tz=timezone.utc)
+    return _utc_dt
+
+
+def now_local_dt() -> datetime:
+    """Get current datetime in local timezone with tzinfo.
+
+    Returns:
+        datetime: Current datetime in local timezone with tzinfo.
+    """
+
+    _local_dt = datetime.now().astimezone()
+    return _local_dt
+
+
+@validate_call(config={"arbitrary_types_allowed": True})
+def now_dt(tz: ZoneInfo | tzinfo | str) -> datetime:
+    """Get current datetime in specified timezone with tzinfo.
+
+    Args:
+        tz (Union[ZoneInfo, tzinfo, str], required): Timezone info.
+
+    Returns:
+        datetime: Current datetime in specified timezone with tzinfo.
+    """
+
+    _dt = now_utc_dt()
+    _dt = convert_tz(dt=_dt, tz=tz)
+    return _dt
+
+
+@validate_call
+def now_ts(unit: TSUnitEnum = TSUnitEnum.SECONDS) -> int:
+    """Get current timestamp in UTC timezone.
+
+    Args:
+        unit (TSUnitEnum, optional): Type of timestamp unit. Defaults to `TSUnitEnum.SECONDS`.
+
+    Returns:
+        int: Current timestamp.
+    """
+
+    _now_ts: int
+    if unit == TSUnitEnum.SECONDS:
+        _now_ts = int(time.time())
+    elif unit == TSUnitEnum.MILLISECONDS:
+        _now_ts = int(time.time() * 1000)
+    elif unit == TSUnitEnum.MICROSECONDS:
+        _now_ts = int(time.time_ns() / 1000)
+    elif unit == TSUnitEnum.NANOSECONDS:
+        _now_ts = int(time.time_ns())
+
+    return _now_ts
+
+
+@validate_call
+def convert_ts(dt: datetime, unit: TSUnitEnum = TSUnitEnum.SECONDS) -> int:
+    """Convert datetime to timestamp.
+
+    Args:
+        dt   (datetime  , required): Datetime object to convert.
+        unit (TSUnitEnum, optional): Type of timestamp unit. Defaults to `TSUnitEnum.SECONDS`.
+
+    Returns:
+        int: Converted timestamp.
+    """
+
+    _ts: int
+    if unit == TSUnitEnum.SECONDS:
+        _ts = int(dt.timestamp())
+    elif unit == TSUnitEnum.MILLISECONDS:
+        _ts = int(dt.timestamp() * 1000)
+    elif unit == TSUnitEnum.MICROSECONDS:
+        _ts = int(dt.timestamp() * 1000000)
+    elif unit == TSUnitEnum.NANOSECONDS:
+        _ts = int(dt.timestamp() * 1000000000)
+
+    return _ts
+
+
+@validate_call(config={"arbitrary_types_allowed": True})
+def calc_future_dt(
+    delta: timedelta | int,
+    dt: datetime | None = None,
+    tz: ZoneInfo | tzinfo | str | None = None,
+) -> datetime:
+    """Calculate future datetime by adding delta time to current or specified datetime.
+
+    Args:
+        delta (Union[timedelta, int]             , required): Delta time to add to current or specified datetime.
+        dt    (Optional[datetime]                , optional): Datetime before adding delta time. Defaults to None.
+        tz    (Union[ZoneInfo, tzinfo, str, None], optional): Timezone info. Defaults to None.
+
+    Returns:
+        datetime: Calculated future datetime.
+    """
+
+    if not dt:
+        dt = now_utc_dt()
+
+    if tz:
+        dt = convert_tz(dt=dt, tz=tz)
+
+    if isinstance(delta, int):
+        delta = timedelta(seconds=delta)
+
+    _future_dt = dt + delta
+    return _future_dt
+
+
+__all__ = [
+    "add_tzinfo",
+    "datetime_to_iso",
+    "convert_tz",
+    "now_utc_dt",
+    "now_local_dt",
+    "now_dt",
+    "now_ts",
+    "convert_ts",
+    "calc_future_dt",
+]

potato_util/http/__init__.py

@@ -0,0 +1,12 @@
+# flake8: noqa
+
+import importlib.util
+
+from ._base import *
+from ._sync import *
+
+_async_package_name = "aiohttp"
+_async_spec = importlib.util.find_spec(_async_package_name)
+
+if _async_spec is not None:
+    from ._async import *

potato_util/http/_async.py

@@ -0,0 +1,42 @@
+import aiohttp
+from pydantic import validate_call, AnyHttpUrl
+
+
+@validate_call
+async def async_is_connectable(
+    url: AnyHttpUrl = AnyHttpUrl("https://www.google.com"),
+    timeout: int = 3,
+    check_status: bool = False,
+) -> bool:
+    """Check if the url is connectable.
+
+    Args:
+        url          (AnyHttpUrl, optional): URL to check. Defaults to 'https://www.google.com'.
+        timeout      (int       , optional): Timeout in seconds. Defaults to 3.
+        check_status (bool      , optional): Check HTTP status code (200). Defaults to False.
+
+    Raise:
+        ValueError: If `timeout` is less than 1.
+
+    Returns:
+        bool: True if connectable, False otherwise.
+    """
+
+    if timeout < 1:
+        raise ValueError(
+            f"`timeout` argument value {timeout} is invalid, must be greater than 0!"
+        )
+
+    try:
+        async with aiohttp.ClientSession() as _session:
+            async with _session.get(str(url), timeout=timeout) as _response:
+                if check_status:
+                    return _response.status == 200
+                return True
+    except Exception:
+        return False
+
+
+__all__ = [
+    "async_is_connectable",
+]

potato_util/http/_base.py

@@ -0,0 +1,46 @@
+from http import HTTPStatus
+
+from pydantic import validate_call
+
+
+@validate_call
+def get_http_status(status_code: int) -> tuple[HTTPStatus, bool]:
+    """Get HTTP status code enum from integer value.
+
+    Args:
+        status_code (int, required): Status code for HTTP response: [100 <= status_code <= 599].
+
+    Raises:
+        ValueError: If status code is not in range [100 <= status_code <= 599].
+
+    Returns:
+        Tuple[HTTPStatus, bool]: Tuple of HTTP status code enum and boolean value if status code is known.
+    """
+
+    _http_status: HTTPStatus
+    _is_known_status = False
+    try:
+        _http_status = HTTPStatus(status_code)
+        _is_known_status = True
+    except ValueError:
+        if (100 <= status_code) and (status_code < 200):
+            status_code = 100
+        elif (200 <= status_code) and (status_code < 300):
+            status_code = 200
+        elif (300 <= status_code) and (status_code < 400):
+            status_code = 304
+        elif (400 <= status_code) and (status_code < 500):
+            status_code = 400
+        elif (500 <= status_code) and (status_code < 600):
+            status_code = 500
+        else:
+            raise ValueError(f"Invalid HTTP status code: '{status_code}'!")
+
+        _http_status = HTTPStatus(status_code)
+
+    return (_http_status, _is_known_status)
+
+
+__all__ = [
+    "get_http_status",
+]

potato_util/http/_sync.py

@@ -0,0 +1,45 @@
+from urllib import request
+from http.client import HTTPResponse
+
+from pydantic import validate_call, AnyHttpUrl
+
+
+@validate_call
+def is_connectable(
+    url: AnyHttpUrl = AnyHttpUrl("https://www.google.com"),
+    timeout: int = 3,
+    check_status: bool = False,
+) -> bool:
+    """Check if the url is connectable.
+
+    Args:
+        url          (AnyHttpUrl, optional): URL to check. Defaults to 'https://www.google.com'.
+        timeout      (int       , optional): Timeout in seconds. Defaults to 3.
+        check_status (bool      , optional): Check HTTP status code (200). Defaults to False.
+
+    Raise:
+        ValueError: If `timeout` is less than 1.
+
+    Returns:
+        bool: True if connectable, False otherwise.
+    """
+
+    if timeout < 1:
+        raise ValueError(
+            f"`timeout` argument value {timeout} is invalid, must be greater than 0!"
+        )
+
+    try:
+        _response: HTTPResponse = request.urlopen(
+            str(url), timeout=timeout
+        )  # nosec B310
+        if check_status:
+            return _response.getcode() == 200
+        return True
+    except Exception:
+        return False
+
+
+__all__ = [
+    "is_connectable",
+]

potato_util/http/fastapi.py

@@ -0,0 +1,26 @@
+from pydantic import validate_call
+from starlette.datastructures import URL
+from fastapi import Request
+
+
+@validate_call(config={"arbitrary_types_allowed": True})
+def get_relative_url(val: Request | URL) -> str:
+    """Get relative url only path with query params from request object or URL object.
+
+    Args:
+        val (Union[Request, URL]): Request object or URL object to extract relative url.
+
+    Returns:
+        str: Relative url only path with query params.
+    """
+
+    if isinstance(val, Request):
+        val = val.url
+
+    _relative_url = str(val).replace(f"{val.scheme}://{val.netloc}", "")
+    return _relative_url
+
+
+__all__ = [
+    "get_relative_url",
+]

potato_util/io/__init__.py

@@ -0,0 +1,11 @@
+# flake8: noqa
+
+import importlib.util
+
+from ._sync import *
+
+_async_package_name = "aiofiles"
+_async_spec = importlib.util.find_spec(_async_package_name)
+
+if _async_spec is not None:
+    from ._async import *