potato-util 0.0.1__py3-none-any.whl

potato_util/secure.py

@@ -0,0 +1,90 @@
+import uuid
+import string
+import secrets
+import hashlib
+
+from pydantic import validate_call
+
+from .constants import HashAlgoEnum
+from .dt import now_ts
+
+
+@validate_call
+def gen_unique_id(prefix: str = "") -> str:
+    """Generate unique id. Format: '{prefix}{datetime}_{uuid4}'.
+
+    Args:
+        prefix (str, optional): Prefix of id. Defaults to ''.
+
+    Raises:
+        ValueError: If `prefix` length is greater than 32.
+
+    Returns:
+        str: Unique id.
+    """
+
+    prefix = prefix.strip()
+    if 32 < len(prefix):
+        raise ValueError(
+            f"`prefix` argument length {len(prefix)} is too long, must be less than or equal to 32!",
+        )
+
+    _id = str(f"{prefix}{now_ts()}_{uuid.uuid4().hex}").lower()
+    return _id
+
+
+@validate_call
+def gen_random_string(length: int = 16, is_alphanum: bool = True) -> str:
+    """Generate secure random string.
+
+    Args:
+        length      (int , optional): Length of random string. Defaults to 16.
+        is_alphanum (bool, optional): If True, generate only alphanumeric string. Defaults to True.
+
+    Raises:
+        ValueError: If `length` is less than 1.
+
+    Returns:
+        str: Generated random string.
+    """
+
+    if length < 1:
+        raise ValueError(
+            f"`length` argument value {length} is too small, must be greater than or equal to 1!",
+        )
+
+    _base_chars = string.ascii_letters + string.digits
+    if not is_alphanum:
+        _base_chars += string.punctuation
+
+    _random_str = "".join(secrets.choice(_base_chars) for _i in range(length))
+    return _random_str
+
+
+@validate_call
+def hash_str(val: str | bytes, algorithm: HashAlgoEnum = HashAlgoEnum.sha256) -> str:
+    """Hash a string using a specified hash algorithm.
+
+    Args:
+        val       (str | bytes , required): The value to be hashed.
+        algorithm (HashAlgoEnum, required): The hash algorithm to use. Defaults to `HashAlgoEnum.sha256`.
+
+    Returns:
+        str: The hexadecimal representation of the digest.
+    """
+
+    if isinstance(val, str):
+        val = val.encode("utf-8")
+
+    _hash = hashlib.new(algorithm.value)
+    _hash.update(val)
+
+    _hash_val = _hash.hexdigest()
+    return _hash_val
+
+
+__all__ = [
+    "gen_unique_id",
+    "gen_random_string",
+    "hash_str",
+]

potato_util/validator.py

@@ -0,0 +1,150 @@
+import re
+from re import Pattern
+
+from pydantic import validate_call
+
+from .constants import (
+    REQUEST_ID_REGEX,
+    SPECIAL_CHARS_BASE_REGEX,
+    SPECIAL_CHARS_LOW_REGEX,
+    SPECIAL_CHARS_MEDIUM_REGEX,
+    SPECIAL_CHARS_HIGH_REGEX,
+    SPECIAL_CHARS_STRICT_REGEX,
+)
+
+
+@validate_call
+def is_truthy(val: str | bool | int | float | None) -> bool:
+    """Check if the value is truthy.
+
+    Args:
+        val (Union[str, bool, int, float, None], required): Value to check.
+
+    Raises:
+        ValueError: If `val` argument type is string and value is invalid.
+
+    Returns:
+        bool: True if the value is truthy, False otherwise.
+    """
+
+    if isinstance(val, str):
+        val = val.strip().lower()
+
+        if val in ["0", "false", "f", "no", "n", "off"]:
+            return False
+        elif val in ["1", "true", "t", "yes", "y", "on"]:
+            return True
+        else:
+            raise ValueError(f"`val` argument value is invalid: '{val}'!")
+
+    return bool(val)
+
+
+@validate_call
+def is_falsy(val: str | bool | int | float | None) -> bool:
+    """Check if the value is falsy.
+
+    Args:
+        val (Union[str, bool, int, float, None], required): Value to check.
+
+    Returns:
+        bool: True if the value is falsy, False otherwise.
+    """
+
+    return not is_truthy(val)
+
+
+@validate_call
+def is_request_id(val: str) -> bool:
+    """Check if the string is valid request ID.
+
+    Args:
+        val (str, required): String to check.
+
+    Returns:
+        bool: True if the string is valid request ID, False otherwise.
+    """
+
+    _is_valid = bool(re.match(pattern=REQUEST_ID_REGEX, string=val))
+    return _is_valid
+
+
+@validate_call
+def is_blacklisted(val: str, blacklist: list[str]) -> bool:
+    """Check if the string is blacklisted.
+
+    Args:
+        val       (str      , required): String to check.
+        blacklist (List[str], required): List of blacklisted strings.
+
+    Returns:
+        bool: True if the string is blacklisted, False otherwise.
+    """
+
+    for _blacklisted in blacklist:
+        if _blacklisted in val:
+            return True
+
+    return False
+
+
+@validate_call
+def is_valid(val: str, pattern: Pattern | str) -> bool:
+    """Check if the string is valid with given pattern.
+
+    Args:
+        val     (str                , required): String to check.
+        pattern (Union[Pattern, str], required): Pattern regex to check.
+
+    Returns:
+        bool: True if the string is valid with given pattern, False otherwise.
+    """
+
+    _is_valid = bool(re.match(pattern=pattern, string=val))
+    return _is_valid
+
+
+@validate_call
+def has_special_chars(val: str, mode: str = "LOW") -> bool:
+    """Check if the string has special characters.
+
+    Args:
+        val  (str, required): String to check.
+        mode (str, optional): Check mode. Defaults to "LOW".
+
+    Raises:
+        ValueError: If `mode` is unsupported.
+
+    Returns:
+        bool: True if the string has special characters, False otherwise.
+    """
+
+    _has_special_chars = False
+
+    _pattern = r""
+    mode = mode.upper().strip()
+    if (mode == "BASE") or (mode == "HTML"):
+        _pattern = SPECIAL_CHARS_BASE_REGEX
+    elif mode == "LOW":
+        _pattern = SPECIAL_CHARS_LOW_REGEX
+    elif mode == "MEDIUM":
+        _pattern = SPECIAL_CHARS_MEDIUM_REGEX
+    elif (mode == "HIGH") or (mode == "SCRIPT") or (mode == "SQL"):
+        _pattern = SPECIAL_CHARS_HIGH_REGEX
+    elif mode == "STRICT":
+        _pattern = SPECIAL_CHARS_STRICT_REGEX
+    else:
+        raise ValueError(f"Unsupported mode: {mode}")
+
+    _has_special_chars = bool(re.search(pattern=_pattern, string=val))
+    return _has_special_chars
+
+
+__all__ = [
+    "is_truthy",
+    "is_falsy",
+    "is_request_id",
+    "is_blacklisted",
+    "is_valid",
+    "has_special_chars",
+]

potato_util-0.0.1.dist-info/METADATA

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: potato_util
+Version: 0.0.1
+Summary: 'potato_util' is collection of simple useful utils package for python.
+Author-email: Batkhuu Byambajav <batkhuu10@gmail.com>
+Project-URL: Homepage, https://github.com/bybatkhuu/module.python-utils
+Project-URL: Documentation, https://pyutils-docs.bybatkhuu.dev
+Project-URL: Repository, https://github.com/bybatkhuu/module.python-utils.git
+Project-URL: Issues, https://github.com/bybatkhuu/module.python-utils/issues
+Project-URL: Changelog, https://github.com/bybatkhuu/module.python-utils/blob/main/CHANGELOG.md
+Keywords: potato_util,utils,utilities,tools,helpers
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: python-dotenv<2.0.0,>=1.0.1
+Requires-Dist: pydantic[email,timezone]<3.0.0,>=2.0.3
+Requires-Dist: pydantic-settings<3.0.0,>=2.2.1
+Provides-Extra: async
+Requires-Dist: aiofiles<25.0.0,>=24.1.0; extra == "async"
+Requires-Dist: aioshutil<2.0.0,>=1.5; extra == "async"
+Requires-Dist: aiohttp<4.0.0,>=3.11.18; extra == "async"
+Provides-Extra: fastapi
+Requires-Dist: fastapi<1.0.0,>=0.109.2; extra == "fastapi"
+Provides-Extra: all
+Requires-Dist: aiofiles<25.0.0,>=24.1.0; extra == "all"
+Requires-Dist: aioshutil<2.0.0,>=1.5; extra == "all"
+Requires-Dist: aiohttp<4.0.0,>=3.11.18; extra == "all"
+Requires-Dist: fastapi<1.0.0,>=0.109.2; extra == "all"
+Provides-Extra: test
+Requires-Dist: aiofiles<25.0.0,>=24.1.0; extra == "test"
+Requires-Dist: aioshutil<2.0.0,>=1.5; extra == "test"
+Requires-Dist: aiohttp<4.0.0,>=3.11.18; extra == "test"
+Requires-Dist: fastapi<1.0.0,>=0.109.2; extra == "test"
+Requires-Dist: pytest<9.0.0,>=8.0.2; extra == "test"
+Requires-Dist: pytest-cov<8.0.0,>=5.0.0; extra == "test"
+Requires-Dist: pytest-xdist<4.0.0,>=3.6.1; extra == "test"
+Requires-Dist: pytest-benchmark<6.0.0,>=5.0.1; extra == "test"
+Provides-Extra: build
+Requires-Dist: setuptools<81.0.0,>=70.3.0; extra == "build"
+Requires-Dist: wheel<1.0.0,>=0.43.0; extra == "build"
+Requires-Dist: build<2.0.0,>=1.1.1; extra == "build"
+Requires-Dist: twine<7.0.0,>=6.0.1; extra == "build"
+Provides-Extra: docs
+Requires-Dist: pylint<4.0.0,>=3.0.4; extra == "docs"
+Requires-Dist: mkdocs-material<10.0.0,>=9.5.50; extra == "docs"
+Requires-Dist: mkdocs-awesome-nav<4.0.0,>=3.0.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]<1.0.0,>=0.24.3; extra == "docs"
+Requires-Dist: mike<3.0.0,>=2.1.3; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: aiofiles<25.0.0,>=24.1.0; extra == "dev"
+Requires-Dist: aioshutil<2.0.0,>=1.5; extra == "dev"
+Requires-Dist: aiohttp<4.0.0,>=3.11.18; extra == "dev"
+Requires-Dist: fastapi<1.0.0,>=0.109.2; extra == "dev"
+Requires-Dist: pytest<9.0.0,>=8.0.2; extra == "dev"
+Requires-Dist: pytest-cov<8.0.0,>=5.0.0; extra == "dev"
+Requires-Dist: pytest-xdist<4.0.0,>=3.6.1; extra == "dev"
+Requires-Dist: pytest-benchmark<6.0.0,>=5.0.1; extra == "dev"
+Requires-Dist: setuptools<81.0.0,>=70.3.0; extra == "dev"
+Requires-Dist: wheel<1.0.0,>=0.43.0; extra == "dev"
+Requires-Dist: build<2.0.0,>=1.1.1; extra == "dev"
+Requires-Dist: twine<7.0.0,>=6.0.1; extra == "dev"
+Requires-Dist: pylint<4.0.0,>=3.0.4; extra == "dev"
+Requires-Dist: mkdocs-material<10.0.0,>=9.5.50; extra == "dev"
+Requires-Dist: mkdocs-awesome-nav<4.0.0,>=3.0.0; extra == "dev"
+Requires-Dist: mkdocstrings[python]<1.0.0,>=0.24.3; extra == "dev"
+Requires-Dist: mike<3.0.0,>=2.1.3; extra == "dev"
+Requires-Dist: pyright<2.0.0,>=1.1.392; extra == "dev"
+Requires-Dist: pre-commit<5.0.0,>=4.0.1; extra == "dev"
+Dynamic: license-file
+
+# Potato Utils (Python Utils)
+
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/bybatkhuu/module.python-utils/2.build-publish.yml?logo=GitHub)](https://github.com/bybatkhuu/module.python-utils/actions/workflows/2.build-publish.yml)
+[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/bybatkhuu/module.python-utils?logo=GitHub&color=blue)](https://github.com/bybatkhuu/module.python-utils/releases)
+
+'potato_util' is collection of simple useful utils package for python.
+
+## ✨ Features
+
+- Python utilities
+- Datetime utilities
+- File I/O utilities
+- HTTP utilities
+- Security utilities
+- Sanitation utilities
+- Validation utilities
+
+---
+
+## 🛠 Installation
+
+### 1. 🚧 Prerequisites
+
+- Install **Python (>= v3.10)** and **pip (>= 23)**:
+    - **[RECOMMENDED] [Miniconda (v3)](https://www.anaconda.com/docs/getting-started/miniconda/install)**
+    - *[arm64/aarch64] [Miniforge (v3)](https://github.com/conda-forge/miniforge)*
+    - *[Python virutal environment] [venv](https://docs.python.org/3/library/venv.html)*
+
+[OPTIONAL] For **DEVELOPMENT** environment:
+
+- Install [**git**](https://git-scm.com/downloads)
+- Setup an [**SSH key**](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh) ([video tutorial](https://www.youtube.com/watch?v=snCP3c7wXw0))
+
+### 2. 📥 Download or clone the repository
+
+[TIP] Skip this step, if you're going to install the package directly from **PyPi** or **GitHub** repository.
+
+**2.1.** Prepare projects directory (if not exists):
+
+```sh
+# Create projects directory:
+mkdir -pv ~/workspaces/projects
+
+# Enter into projects directory:
+cd ~/workspaces/projects
+```
+
+**2.2.** Follow one of the below options **[A]**, **[B]** or **[C]**:
+
+**OPTION A.** Clone the repository:
+
+```sh
+git clone https://github.com/bybatkhuu/module.python-utils.git && \
+    cd module.python-utils
+```
+
+**OPTION B.** Clone the repository (for **DEVELOPMENT**: git + ssh key):
+
+```sh
+git clone git@github.com:bybatkhuu/module.python-utils.git && \
+    cd module.python-utils
+```
+
+**OPTION C.** Download source code:
+
+1. Download archived **zip** file from [**releases**](https://github.com/bybatkhuu/module.python-utils/releases).
+2. Extract it into the projects directory.
+
+### 3. 📦 Install the package
+
+[NOTE] Choose one of the following methods to install the package **[A ~ F]**:
+
+**OPTION A.** [**RECOMMENDED**] Install from **PyPi**:
+
+```sh
+pip install -U potato_util
+```
+
+**OPTION B.** Install latest version directly from **GitHub** repository:
+
+```sh
+pip install git+https://github.com/bybatkhuu/module.python-utils.git
+```
+
+**OPTION C.** Install from the downloaded **source code**:
+
+```sh
+# Install directly from the source code:
+pip install .
+
+# Or install with editable mode:
+pip install -e .
+```
+
+**OPTION D.** Install for **DEVELOPMENT** environment:
+
+```sh
+pip install -e .[dev]
+```
+
+**OPTION E.** Install from **pre-built release** files:
+
+1. Download **`.whl`** or **`.tar.gz`** file from [**releases**](https://github.com/bybatkhuu/module.python-utils/releases)
+2. Install with pip:
+
+```sh
+# Install from .whl file:
+pip install ./potato_util-[VERSION]-py3-none-any.whl
+
+# Or install from .tar.gz file:
+pip install ./potato_util-[VERSION].tar.gz
+```
+
+**OPTION F.** Copy the **module** into the project directory (for **testing**):
+
+```sh
+# Install python dependencies:
+pip install -r ./requirements.txt
+
+# Copy the module source code into the project:
+cp -r ./src/potato_util [PROJECT_DIR]
+# For example:
+cp -r ./src/potato_util /some/path/project/
+```
+
+## 🚸 Usage/Examples
+
+### Simple
+
+[**`examples/simple/main.py`**](./examples/simple/main.py):
+
+```python
+```
+
+👍
+
+---
+
+### 🌎 Environment Variables
+
+[**`.env.example`**](./.env.example):
+
+```sh
+# ENV=LOCAL
+# DEBUG=false
+# TZ=UTC
+```
+
+---
+
+## 🧪 Running Tests
+
+To run tests, run the following command:
+
+```sh
+# Install python test dependencies:
+pip install .[test]
+
+# Run tests:
+python -m pytest -sv -o log_cli=true
+# Or use the test script:
+./scripts/test.sh -l -v -c
+```
+
+## 🏗️ Build Package
+
+To build the python package, run the following command:
+
+```sh
+# Install python build dependencies:
+pip install -r ./requirements/requirements.build.txt
+
+# Build python package:
+python -m build
+# Or use the build script:
+./scripts/build.sh
+```
+
+## 📝 Generate Docs
+
+To build the documentation, run the following command:
+
+```sh
+# Install python documentation dependencies:
+pip install -r ./requirements/requirements.docs.txt
+
+# Serve documentation locally (for development):
+mkdocs serve -a 0.0.0.0:8000
+# Or use the docs script:
+./scripts/docs.sh
+
+# Or build documentation:
+mkdocs build
+# Or use the docs script:
+./scripts/docs.sh -b
+```
+
+## 📚 Documentation
+
+- [Docs](./docs)
+
+---
+
+## 📑 References
+
+- <https://packaging.python.org/en/latest/tutorials/packaging-projects>
+- <https://python-packaging.readthedocs.io/en/latest>

potato_util-0.0.1.dist-info/RECORD

@@ -0,0 +1,24 @@
+potato_util/__init__.py,sha256=HjN2VbjR-wQBNVKpcRa4fgLaqEcNOQVhRoKQCilFjAM,72
+potato_util/__version__.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+potato_util/_base.py,sha256=x_wIKThJPRi25gI_Ab4hvr6Qg-7RaMfN9dbjpeEPI0g,2923
+potato_util/dt.py,sha256=EMT4r4b-KFWwyStDJ8ajUXci3vnP1cMwJafniwUxxJA,6872
+potato_util/sanitizer.py,sha256=-olqyjG9PorIciV90M5Q4r0g_-0tXC7DJcO7xuHEcPs,1860
+potato_util/secure.py,sha256=gngUBve3fhTjPop92t4gfOKhfWwG3MU7FlvzSwJJgtk,2247
+potato_util/validator.py,sha256=7wOTBuV4MbYNS1CMOOcpIdG2Qjp7yzPWR21LTLZdJpA,3757
+potato_util/constants/__init__.py,sha256=lhxZ2k-QotMR_w9w-Gv-9pCEFrQSKxe1YEIvV83pf8E,80
+potato_util/constants/_base.py,sha256=J1i611erzcrPRZ6USkVgnNZ_IvvN9YLbcltvyIngpcg,61
+potato_util/constants/_enum.py,sha256=tThmf7lFsGfFUNNQE0hOUZ0JKc821ZGZnSyJIj2jVTQ,515
+potato_util/constants/_regex.py,sha256=T7SSsqD0y8jXJJPURwAK2uA59AjLt1uqGfqqUd1a22o,710
+potato_util/http/__init__.py,sha256=qWOzScMVJEHjzClEqOYmGtfkZyU8f8Hz8nT054Dbblo,229
+potato_util/http/_async.py,sha256=dfs-ynchPKdnMNQXqyoqhcz-jhtQ7g_4JnNfVr3bXk0,1178
+potato_util/http/_base.py,sha256=01r87dsY9mNnCTsAsBNfN1TEL_Y_bLSgcX5SxJaZT2I,1365
+potato_util/http/_sync.py,sha256=i8oyRmh-WraOzotaUbssIjOPvBh1pvLPupdoCvyHTK0,1169
+potato_util/http/fastapi.py,sha256=3zE6KvmGDaDokWxxstoEj4OBCBgp6n-vqvS0jQZqPHk,671
+potato_util/io/__init__.py,sha256=FoGcN7t0uArQV4hbMR1X5aeC8Yq-h_ds4xooNpkmgG0,209
+potato_util/io/_async.py,sha256=xDBnMcU7PF8dfVMrJRTYJirU9yqprza30YMgyWbCKjY,9486
+potato_util/io/_sync.py,sha256=cPFlfxKsLVH4NtNOccUt2z8a9K2MkW2GxtJbCXyWVqY,9106
+potato_util-0.0.1.dist-info/licenses/LICENSE.txt,sha256=CUTK-r0BWIg1r0bBiemAcMhakgV0N7HuRhw6rQ-A9A4,1074
+potato_util-0.0.1.dist-info/METADATA,sha256=Z8Zm6HTW6jGtMT7brhpVza-2O21vo8pXGzUG2A9eUNo,8999
+potato_util-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+potato_util-0.0.1.dist-info/top_level.txt,sha256=pLMnSfT6rhlYBpo2Gnd8kKMDxcuvxdVizqsv1dd1frw,12
+potato_util-0.0.1.dist-info/RECORD,,

potato_util-0.0.1.dist-info/WHEEL

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

potato_util-0.0.1.dist-info/licenses/LICENSE.txt

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

potato_util-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+potato_util