yumako 0.1.12__tar.gz

yumako-0.1.12/LICENSE

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

yumako-0.1.12/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.3
+Name: yumako
+Version: 0.1.12
+Summary: 
+License: MIT
+Keywords: util,vanilla,for humans
+Author: Nanw1103
+Author-email: nanw1103@gmail.com
+Requires-Python: >=3.9
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/markdown
+
+# Yumako ![Yumako](doc/yumako.png) 
+
+Vanilla python utilities, for humans.
+
+[![PyPI version](https://badge.fury.io/py/yumako.svg)](https://badge.fury.io/py/yumako)
+[![Python Versions](https://img.shields.io/pypi/pyversions/yumako.svg)](https://pypi.org/project/yumako/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
+[![Typed](https://img.shields.io/badge/Typed-Yes-blue.svg)](https://github.com/yumako/yumako)
+[![Downloads](https://static.pepy.tech/badge/yumako)](https://pepy.tech/projects/yumako)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![Sourcery](https://img.shields.io/badge/Sourcery-enabled-brightgreen)](https://sourcery.ai)
+
+
+
+
+
+Install:
+```bash
+pip install yumako
+
+# Yumako utilities are based on vanilla python: no other dependencies.
+```
+
+Usage:
+```python
+import yumako
+# Yumako submodules are loaded only when needed.
+
+# ---------------------------------------
+# Yumako utilities are designed for human
+# ---------------------------------------
+print(yumako.time.of("2025-01-17H23:00:00.000-05:00"))  # Any popular timeformat
+print(yumako.time.of("-3d"))  # 3 days ago
+
+seconds = yumako.time.duration("3m4s")  # 3m4s -> 184 seconds
+delta = timedelta(seconds=seconds)
+print(yumako.time.display(delta))  # 3m4s
+
+# ---------------------------------------
+# Yumako utilities are highly performant
+# ---------------------------------------
+lru = yumako.lru.LRUDict()
+lru[1] = True
+lru["hello"] = "mortal"
+print(lru)
+
+lru_set = yumako.lru.LRUSet()
+lru_set.add("ユマ果")
+print(lru_set)
+```
+

yumako-0.1.12/README.md

@@ -0,0 +1,55 @@
+# Yumako ![Yumako](doc/yumako.png) 
+
+Vanilla python utilities, for humans.
+
+[![PyPI version](https://badge.fury.io/py/yumako.svg)](https://badge.fury.io/py/yumako)
+[![Python Versions](https://img.shields.io/pypi/pyversions/yumako.svg)](https://pypi.org/project/yumako/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
+[![Typed](https://img.shields.io/badge/Typed-Yes-blue.svg)](https://github.com/yumako/yumako)
+[![Downloads](https://static.pepy.tech/badge/yumako)](https://pepy.tech/projects/yumako)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![Sourcery](https://img.shields.io/badge/Sourcery-enabled-brightgreen)](https://sourcery.ai)
+
+
+
+
+
+Install:
+```bash
+pip install yumako
+
+# Yumako utilities are based on vanilla python: no other dependencies.
+```
+
+Usage:
+```python
+import yumako
+# Yumako submodules are loaded only when needed.
+
+# ---------------------------------------
+# Yumako utilities are designed for human
+# ---------------------------------------
+print(yumako.time.of("2025-01-17H23:00:00.000-05:00"))  # Any popular timeformat
+print(yumako.time.of("-3d"))  # 3 days ago
+
+seconds = yumako.time.duration("3m4s")  # 3m4s -> 184 seconds
+delta = timedelta(seconds=seconds)
+print(yumako.time.display(delta))  # 3m4s
+
+# ---------------------------------------
+# Yumako utilities are highly performant
+# ---------------------------------------
+lru = yumako.lru.LRUDict()
+lru[1] = True
+lru["hello"] = "mortal"
+print(lru)
+
+lru_set = yumako.lru.LRUSet()
+lru_set.add("ユマ果")
+print(lru_set)
+```

yumako-0.1.12/pyproject.toml

@@ -0,0 +1,94 @@
+[project]
+name = "yumako"
+version = "0.1.12"
+description = ""
+authors = [{ name="Nanw1103", email="nanw1103@gmail.com" }]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+homepage = "https://github.com/nanw1103/yumako"
+repository = "https://github.com/nanw1103/yumako"
+documentation = "https://github.com/nanw1103/yumako#readme"
+"Bug Tracker" = "https://github.com/nanw1103/yumako/issues"
+
+keywords = ["util", "vanilla", "for humans"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+
+packages = [
+    { include = "yumako", from = "src", format = ["sdist"] }
+]
+exclude = ["tests", "tests.*", "examples"]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.3"
+black = "^23.11.0"
+isort = "^5.12.0"
+mypy = "^1.7.1"
+ruff = "^0.1.6"
+tomlkit = "^0.12.0"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 120
+target-version = ['py39']
+include = '\.pyi?$'
+extend-exclude = '''
+# A regex preceded with ^/ will apply only to files and directories
+# in the root of the project.
+^/.venv
+'''
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+line_length = 120
+skip = [".venv"]
+src_paths = ["src", "tests"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+exclude = [
+    ".venv"
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+select = ["E", "F", "I", "N", "W", "B", "UP"]
+exclude = [
+    ".venv",
+    "__init__.py"
+]
+src = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-ra -q"
+filterwarnings = [
+    "error",
+    "ignore::DeprecationWarning",
+    "ignore::UserWarning",
+]
+
+[tool.poetry-dynamic-versioning]
+enable = true
+vcs = "git"
+style = "pep440"
+pattern = "^(?P<base>\\d+\\.\\d+\\.\\d+)"
+

yumako-0.1.12/src/yumako/__init__.py

@@ -0,0 +1,34 @@
+"""
+Yumako - Vanilla python utilities.
+"""
+
+import importlib
+from types import ModuleType
+from typing import TYPE_CHECKING
+
+__submodules = [
+    "template",
+    "time",
+    "lru",
+]
+__submodule_map = {name: f"yumako.{name}" for name in __submodules}
+
+if TYPE_CHECKING:
+    from . import lru  # type: ignore
+    from . import template  # type: ignore
+    from . import time  # type: ignore
+
+
+def __getattr__(name: str) -> ModuleType:
+    if name in __submodule_map:
+        submodule = importlib.import_module(__submodule_map[name])
+        globals()[name] = submodule
+        return submodule
+    raise AttributeError(f"Module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = __submodules
+
+
+def __dir__() -> list[str]:
+    return __all__

yumako-0.1.12/src/yumako/lru.py

@@ -0,0 +1,322 @@
+from collections import ChainMap
+from collections.abc import ItemsView, Iterator, KeysView, MutableMapping, MutableSet, ValuesView
+from typing import TypeVar, cast
+from weakref import WeakSet, WeakValueDictionary
+
+T = TypeVar("T")  # Item type for Set
+K = TypeVar("K")  # Key type
+V = TypeVar("V")  # Value type
+
+
+class LRUSet(MutableSet[T]):
+    """A Least Recently Used (LRU) Set with weak references and fixed capacity.
+
+    Implementation:
+        Uses two set caches for O(1) operations:
+        - new_cache: holds recently used items
+        - old_cache: holds less recently used items
+
+        When new_cache reaches capacity:
+        1. old_cache becomes the current new_cache
+        2. new_cache is reset empty
+
+        On item access:
+        1. Check new_cache first (fast path)
+        2. If not found, check old_cache
+        3. If found in old_cache, promote to new_cache
+
+    Performance:
+        - add: O(1)
+        - contains: O(1)
+        - discard: O(1)
+        - len: O(1)
+        - iter: O(n)
+
+    Memory:
+        - If weak=true, uses weak references, items may be garbage collected
+        - Maximum memory: 2 * capacity items
+
+    Thread Safety:
+        - Not thread-safe
+        - Use external synchronization if needed
+
+    Args:
+        capacity: Maximum items per cache. Must be positive integer.
+
+    Example:
+        >>> class Item:
+        ...     def __init__(self, value): self.value = value
+        >>> lru = LRUSet(capacity=2)
+        >>> items = [Item(i) for i in range(3)]
+        >>> lru.add(items[0])      # new_cache: [0]
+        >>> lru.add(items[1])      # new_cache: [0,1]
+        >>> items[0] in lru        # promotes 0: [1,0]
+        >>> lru.add(items[2])      # rotates: old=[1,0], new=[2]
+    """
+
+    _capacity: int
+    _new_cache: MutableSet[T]
+    _old_cache: MutableSet[T]
+
+    def __init__(self, capacity: int = 32, weak: bool = False) -> None:
+        if not isinstance(capacity, int):
+            raise TypeError("capacity must be an integer")
+        if capacity <= 0:
+            raise ValueError("capacity must be positive")
+
+        self._capacity = capacity
+        self._weak = weak
+        self._new_cache = WeakSet() if weak else set()  # Recently used items
+        self._old_cache = WeakSet() if weak else set()  # Less recently used items
+
+    def add(self, item: T) -> None:
+        """Add an item to the set."""
+        # If item exists in new_cache, we're done
+        if item in self._new_cache:
+            return
+
+        # Add to new_cache
+        self._new_cache.add(item)
+
+        # If size exceeds capacity, rotate caches
+        if not self._ensure_rotation():
+            # Remove from old_cache if present
+            self._old_cache.discard(item)
+
+    def discard(self, item: T) -> None:
+        """Remove an item from the set if it exists."""
+        self._new_cache.discard(item)
+        self._old_cache.discard(item)
+
+    def __contains__(self, item: object) -> bool:
+        """Check if an item is in the set."""
+        if item in self._new_cache:
+            return True
+
+        if item in self._old_cache:
+            # Promote to new_cache
+            item_t = cast(T, item)  # Safe cast since we checked type above
+            self._new_cache.add(item_t)
+
+            if not self._ensure_rotation():
+                self._old_cache.discard(item_t)
+            return True
+
+        return False
+
+    def _ensure_rotation(self) -> bool:
+        """Rotate caches if necessary."""
+        if len(self._new_cache) <= self._capacity:
+            return False
+        self._old_cache = self._new_cache
+        self._new_cache = WeakSet() if self._weak else set()
+        return True
+
+    def __len__(self) -> int:
+        """Return total number of items across both caches."""
+        return len(self._new_cache) + len(self._old_cache)
+
+    def __iter__(self) -> Iterator[T]:
+        """Iterate over all items in the set."""
+        # Yield from new_cache first
+        yield from self._new_cache
+
+        # Then yield from old_cache (skipping duplicates)
+        yield from self._old_cache
+
+    def clear(self) -> None:
+        """Remove all items from the set."""
+        self._new_cache.clear()
+        self._old_cache.clear()
+
+    @property
+    def capacity(self) -> int:
+        """Get the capacity of each cache."""
+        return self._capacity
+
+    def __repr__(self) -> str:
+        """Return a string representation of the set.
+
+        Format: LRUSet(capacity=N)
+        """
+        return f"{type(self).__name__}(capacity={self._capacity}, weak={self._weak}, size={len(self)})"
+
+    def __str__(self) -> str:
+        """Return a string of the set contents.
+
+        Format: {item1, item2, ...}
+        """
+        items = ", ".join(str(item) for item in self)
+        return "{" + items + "}"
+
+
+class LRUDict(MutableMapping[K, V]):
+    """A Least Recently Used (LRU) Dictionary with weak references and fixed capacity.
+
+    Implementation:
+        Uses two dictionary caches for O(1) operations:
+        - new_cache: holds recently used items
+        - old_cache: holds less recently used items
+
+        When new_cache reaches capacity:
+        1. old_cache becomes the current new_cache
+        2. new_cache is reset empty
+
+        On key access:
+        1. Check new_cache first (fast path)
+        2. If not found, check old_cache
+        3. If found in old_cache, promote to new_cache
+
+    Performance:
+        - get/set: O(1)
+        - contains: O(1)
+        - delete: O(1)
+        - len: O(1)
+        - iter: O(n)
+
+    Memory:
+        - If weak is true, uses weak references for values, may be garbage collected
+        - Keys are stored strongly
+        - Maximum memory: 2 * capacity items
+
+    Thread Safety:
+        - Not thread-safe
+        - Use external synchronization if needed
+
+    Args:
+        capacity: Maximum items per cache. Must be positive integer.
+
+    Example:
+        >>> class Value:
+        ...     def __init__(self, x): self.x = x
+        >>> lru = LRUDict(capacity=2)
+        >>> v1, v2, v3 = Value(1), Value(2), Value(3)
+        >>> lru['a'] = v1         # new_cache: {'a':v1}
+        >>> lru['b'] = v2         # new_cache: {'a':v1, 'b':v2}
+        >>> _ = lru['a']          # promotes 'a': {'b':v2, 'a':v1}
+        >>> lru['c'] = v3         # rotates: old={'b':v2, 'a':v1}, new={'c':v3}
+    """
+
+    _capacity: int
+    _weak: bool
+    _new_cache: MutableMapping[K, V]
+    _old_cache: MutableMapping[K, V]
+
+    def __init__(self, capacity: int = 32, weak: bool = False) -> None:
+        if not isinstance(capacity, int):
+            raise TypeError("capacity must be an integer")
+        if capacity <= 0:
+            raise ValueError("capacity must be positive")
+
+        self._capacity = capacity
+        self._weak = weak
+        self._new_cache = WeakValueDictionary() if weak else dict()
+        self._old_cache = WeakValueDictionary() if weak else dict()
+
+    def _ensure_rotation(self) -> bool:
+        """Rotate caches if necessary."""
+        if len(self._new_cache) <= self._capacity:
+            return False
+        self._old_cache = self._new_cache
+        self._new_cache = WeakValueDictionary() if self._weak else dict()
+        return True
+
+    def __setitem__(self, key: K, value: V) -> None:
+        if key in self._new_cache:
+            self._new_cache[key] = value
+            return
+
+        self._new_cache[key] = value
+
+        # If size exceeds capacity, rotate caches
+        if not self._ensure_rotation():
+            # Remove from old_cache if present
+            self._old_cache.pop(key, None)
+
+    def __getitem__(self, key: K) -> V:
+        # Check new_cache first
+        try:
+            return self._new_cache[key]
+        except KeyError:
+            # Check old_cache and promote if found
+            value = self._old_cache[key]
+            # Promote to new_cache
+            self._new_cache[key] = value
+
+            # If size exceeds capacity, rotate caches
+            if not self._ensure_rotation():
+                self._old_cache.pop(key, None)
+
+            return value
+
+    def __delitem__(self, key: K) -> None:
+        """Remove an item from either cache."""
+        self._new_cache.pop(key, None)
+        self._old_cache.pop(key, None)
+
+    def __len__(self) -> int:
+        return len(self._new_cache) + len(self._old_cache)
+
+    def __contains__(self, key: object) -> bool:
+        """Return True if key exists in the dictionary."""
+        key_k = cast(K, key)  # Safe cast since we checked type above
+        return key_k in self._new_cache or key_k in self._old_cache
+
+    def __iter__(self) -> Iterator[K]:
+        yield from self._new_cache
+        yield from self._old_cache
+
+    def clear(self) -> None:
+        self._new_cache.clear()
+        self._old_cache.clear()
+
+    @property
+    def capacity(self) -> int:
+        return self._capacity
+
+    def items(self) -> ItemsView[K, V]:
+        """Iterate over (key, value) pairs in LRU order."""
+        # Create a dict view directly from the caches without intermediate dicts
+        combined = ChainMap(self._new_cache, self._old_cache)
+        return ItemsView(combined)
+
+    def keys(self) -> KeysView[K]:
+        """Iterate over keys in LRU order."""
+        combined = ChainMap(self._new_cache, self._old_cache)
+        return KeysView(combined)
+
+    def values(self) -> ValuesView[V]:
+        """Iterate over values in LRU order."""
+        combined = ChainMap(self._new_cache, self._old_cache)
+        return ValuesView(combined)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(capacity={self._capacity}, weak={self._weak}, size={len(self)})"
+
+    def __str__(self) -> str:
+        return str(dict(self.items()))
+
+    def popitem(self) -> tuple[K, V]:
+        """Remove and return the most recently used item.
+
+        Returns:
+            tuple: A (key, value) pair from new_cache
+
+        Raises:
+            KeyError: If dictionary is empty
+        """
+        if not self:
+            raise KeyError("dictionary is empty")
+
+        try:
+            # Try to pop from new_cache first
+            key = next(iter(self._new_cache))
+            value = self._new_cache[key]
+            del self._new_cache[key]
+            return key, value
+        except (StopIteration, KeyError):
+            # If new_cache is empty, pop from old_cache
+            key = next(iter(self._old_cache))
+            value = self._old_cache[key]
+            del self._old_cache[key]
+            return key, value

yumako-0.1.12/src/yumako/template.py

@@ -0,0 +1,23 @@
+import re
+
+
+def replace(
+    text: str, mapping: dict, strict_on_unresolved_vars: bool = True, strict_on_unused_var: bool = False
+) -> str:
+    unused_vars = set(mapping.keys())
+    for k, v in mapping.items():
+        new_text = text.replace("{{" + k + "}}", str(v))
+        if new_text != text:
+            text = new_text
+            unused_vars.remove(k)
+
+    if strict_on_unresolved_vars:
+        unresolved_vars = re.findall(r"\{\{([^}]+)\}\}", text)
+        if unresolved_vars:
+            raise Exception(f"Strict mode: template variables unresolved: {unresolved_vars}")
+
+    if strict_on_unused_var:
+        if unused_vars:
+            raise Exception(f"Strict mode: var specified but not in template: {unused_vars}")
+
+    return text

yumako-0.1.12/src/yumako/time.py

@@ -0,0 +1,353 @@
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Union
+
+
+def display(d: timedelta, use_double_digits: bool = False) -> str:
+    """
+    Format a timedelta into a human-readable string.
+
+    Args:
+        d: The timedelta to format
+        use_double_digits: If True, pad numbers with leading zeros
+
+    Returns:
+        A formatted string like "1y2w" or "01y02w" depending on use_double_digits
+    """
+    is_negative = d.total_seconds() < 0
+    if is_negative:
+        d = abs(d)
+
+    total_days = d.days
+
+    # Only use years if we have exactly 365 days or more
+    years = total_days // 365 if total_days >= 365 else 0
+    remaining_days = total_days % 365 if years > 0 else total_days
+
+    weeks = remaining_days // 7
+    days = remaining_days % 7
+
+    hours = d.seconds // 3600
+    remaining = d.seconds % 3600
+    minutes = remaining // 60
+    seconds = remaining % 60
+
+    parts = []
+    if years > 0:
+        parts.append((years, "y"))
+    if weeks > 0:
+        parts.append((weeks, "w"))
+    if days > 0:
+        parts.append((days, "d"))
+    if hours > 0:
+        parts.append((hours, "h"))
+    if minutes > 0:
+        parts.append((minutes, "m"))
+    if seconds > 0:
+        parts.append((seconds, "s"))
+
+    if len(parts) > 2:
+        parts = parts[:2]
+    elif len(parts) == 0:
+        return "00s" if use_double_digits else "0s"
+
+    ret = "-" if is_negative else ""
+    for part in parts:
+        if use_double_digits:
+            ret += f"{part[0]:02d}{part[1]}"
+        else:
+            ret += f"{part[0]}{part[1]}"
+    return ret
+
+
+def _parse_iso_with_colon_offset(x: str) -> datetime:
+    if abs(int(x[-5:-3])) > 14:
+        raise ValueError("Invalid timezone offset")
+    return datetime.strptime(
+        f"{x[:-6]}{x[-6:].replace(':','')}",
+        "%Y-%m-%dT%H:%M:%S.%f%z" if "." in x else "%Y-%m-%dT%H:%M:%S%z",
+    )
+
+
+def _parse_iso_with_colon_offset2(x: str) -> datetime:
+    if abs(int(x[-4:-2])) > 14:
+        raise ValueError("Invalid timezone offset")
+    return datetime.strptime(x, "%Y-%m-%dT%H:%M:%S.%f%z" if "." in x else "%Y-%m-%dT%H:%M:%S%z")
+
+
+# Try parsing common formats
+_all_human_time_formats = [
+    # Unix timestamps
+    (r"^\d{13}$", lambda x: datetime.fromtimestamp(int(x) / 1000, tz=timezone.utc)),
+    (r"^\d{10}$", lambda x: datetime.fromtimestamp(int(x), tz=timezone.utc)),
+    (r"^\d+\.\d+$", lambda x: datetime.fromtimestamp(float(x), tz=timezone.utc)),
+    # ISO formats
+    (r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$", "%Y-%m-%dT%H:%M:%S.%fZ"),
+    (r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$", "%Y-%m-%dT%H:%M:%SZ"),
+    (r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$", "%Y-%m-%dT%H:%M:%S"),
+    (r"^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$", "%Y-%m-%d %H:%M:%S"),
+    (
+        r"^\d{2}:\d{2}:\d{2}Z$",
+        lambda x: datetime.combine(
+            datetime.now(timezone.utc).date(),
+            datetime.strptime(x, "%H:%M:%SZ").time(),
+            tzinfo=timezone.utc,
+        ),
+    ),
+    (r"^\d{4}-\d{2}-\d{2}$", "%Y-%m-%d"),
+    (
+        r"^\d{2}:\d{2}$",
+        lambda x: datetime.combine(
+            datetime.now(timezone.utc).date(),
+            datetime.strptime(x, "%H:%M").time(),
+            tzinfo=timezone.utc,
+        ),
+    ),
+    # Non-standard formats
+    (r"^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d+$", "%Y-%m-%d %H:%M:%S.%f"),
+    (r"^\d{2}/\d{2}/\d{4}$", "%m/%d/%Y"),
+    (r"^\d{4}\.\d{2}\.\d{2}$", "%Y.%m.%d"),
+    (r"^\d{8}$", "%Y%m%d"),
+    (r"^\d{4}/\d{2}/\d{2}$", "%Y/%m/%d"),
+    # RFC 2822
+    (
+        r"^[A-Z]{3}, \d{2} [A-Z]{3} \d{4} \d{2}:\d{2}:\d{2} [+-]\d{4}$",
+        "%a, %d %b %Y %H:%M:%S %z",
+    ),
+    # ISO with timezone offset (with colon)
+    (
+        r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?[+-]\d{2}:\d{2}$",
+        _parse_iso_with_colon_offset,
+    ),
+    # ISO with timezone offset (without colon)
+    (
+        r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?[+-]\d{4}$",
+        _parse_iso_with_colon_offset2,
+    ),
+    # European date formats
+    (r"^\d{2}-\d{2}-\d{4}$", ["%d-%m-%Y", "%m-%d-%Y"]),
+    (r"^\d{2}/\d{2}/\d{4}$", ["%d/%m/%Y", "%m/%d/%Y"]),
+    (r"^\d{2}\.\d{2}\.\d{4}$", ["%d.%m.%Y", "%m.%d.%Y"]),
+    # Additional common formats
+    (r"^[A-Z]{3} \d{1,2}, \d{4}$", "%b %d, %Y"),  # DEC 4, 2023
+    (r"^[A-Z]{3} \d{1,2} \d{4}$", "%b %d %Y"),  # DEC 4 2023
+    (r"^\d{1,2} [A-Z]{3} \d{4}$", "%d %b %Y"),  # 4 DEC 2023
+    (r"^[A-Z]{6,9} \d{1,2}, \d{4}$", "%B %d, %Y"),  # DECEMBER 4, 2023
+    # Time only with Z
+    (
+        r"^\d{2}:\d{2}:\d{2}Z$",
+        lambda x: datetime.combine(
+            datetime.now(timezone.utc).date(),
+            datetime.strptime(x, "%H:%M:%SZ").time(),
+            tzinfo=timezone.utc,
+        ),
+    ),
+    # Time only without Z
+    (
+        r"^\d{2}:\d{2}:\d{2}$",
+        lambda x: datetime.combine(
+            datetime.now(timezone.utc).date(),
+            datetime.strptime(x, "%H:%M:%S").time(),
+            tzinfo=timezone.utc,
+        ),
+    ),
+    # Time only (HH:MM)
+    (
+        r"^\d{2}:\d{2}$",
+        lambda x: datetime.combine(
+            datetime.now(timezone.utc).date(),
+            datetime.strptime(x, "%H:%M").time(),
+            tzinfo=timezone.utc,
+        ),
+    ),
+]
+
+# Could cache compiled regex patterns
+_COMPILED_PATTERNS = [(re.compile(pattern), handler) for pattern, handler in _all_human_time_formats]
+
+
+def of(human_time: Union[str, datetime, int, float]) -> datetime:
+    """
+    Convert various time formats (ISO-8601, Unix timestamps, relative times, etc.) to a datetime object.
+
+    Args:
+        human_time: Input time in one of these formats:
+            - int: Unix timestamp in milliseconds
+            - datetime: Returns the input unchanged
+            - str: One of:
+                - "now": Current UTC time
+                - Relative time with +/- (e.g. "-1h", "-7d","+30m", "+1w")
+                - Relative time with multiple units (e.g. "-1h30m", "+1w2d", "-7d12h30m")
+                - Unix timestamp in milliseconds as string (e.g. "1734010792148") or seconds (e.g. "1734010792")
+                - ISO formats:
+                    - With milliseconds and Z (e.g. "2023-12-04T00:19:22.854Z")
+                    - With Z (e.g. "2023-12-04T00:19:22Z")
+                    - Without timezone (e.g. "2023-12-04T00:19:22")
+                    - With space separator (e.g. "2023-12-04 00:19:22")
+                    - Time only with Z (e.g. "00:19:22Z")
+                    - Date only (e.g. "2023-12-04")
+                    - Time only (e.g. "00:19")
+                    - With timezone offset (e.g. "2023-12-04T00:19:22+01:00", "2023-12-04T00:19:22-0500")
+                        Valid offsets are between -14:00 and +14:00
+                - Common formats:
+                    - With milliseconds (e.g. "2023-12-04 00:19:22.854")
+                    - US date (e.g. "12/04/2023")
+                    - Dotted date (e.g. "2023.12.04")
+                    - Compact date (e.g. "20231204")
+                    - Forward slash date (e.g. "2023/12/04")
+                    - RFC 2822 (e.g. "Mon, 04 Dec 2023 00:19:22 +0000")
+                    - European dates (e.g. "04-12-2023", "04/12/2023", "04.12.2023")
+                    - Month name formats:
+                        - Short with comma (e.g. "Dec 4, 2023")
+                        - Short without comma (e.g. "Dec 4 2023")
+                        - Day first (e.g. "4 Dec 2023")
+                        - Full month (e.g. "December 4, 2023")
+
+    Returns:
+        datetime: A timezone-aware datetime object
+
+    Raises:
+        ValueError: If the input format is not recognized or invalid (e.g., timezone offset > ±14:00)
+
+    Examples:
+        >>> of("-1d")
+        minus 1 day from now
+        >>> of("+2w")
+        plus 2 weeks from now
+        >>> of("2023-12-04T12:30:45+02:00")
+        Parsing common time formats
+    """
+    if isinstance(human_time, int):
+        return datetime.fromtimestamp(human_time / 1000, tz=timezone.utc)
+
+    if isinstance(human_time, float):
+        return datetime.fromtimestamp(human_time / 1000, tz=timezone.utc)
+
+    if isinstance(human_time, datetime):
+        return human_time.astimezone(timezone.utc)
+
+    if not isinstance(human_time, str):
+        raise ValueError("Invalid input type: " + type(human_time).__name__)
+
+    human_time = human_time.strip()
+    original_input = human_time  # Keep original for error message
+    human_time = human_time.upper()  # Convert to uppercase for simpler regex matching
+
+    if human_time == "NOW":
+        return datetime.now(timezone.utc)
+
+    # Handle relative times (+/-)
+    if human_time.startswith("-") or human_time.startswith("+"):
+        sign = -1 if human_time.startswith("-") else 1
+
+        # Remove leading +/- and split into components
+        time_str = human_time[1:]
+        time_delta = timedelta(seconds=duration(time_str))
+        return datetime.now(timezone.utc) + time_delta * sign
+
+    # Try each format pattern
+    for pattern, fmt in _COMPILED_PATTERNS:
+        if re.match(pattern, human_time):
+            try:
+                if callable(fmt):
+                    dt: datetime = fmt(human_time)
+                    if not isinstance(dt, datetime):
+                        raise ValueError(f"Expected datetime, got {type(dt).__name__}")
+                    return dt
+                if isinstance(fmt, list):
+                    # Try multiple formats
+                    for f in fmt:
+                        try:
+                            dt = datetime.strptime(human_time, f)
+                            if dt.tzinfo is None:
+                                return dt.replace(tzinfo=timezone.utc)  # Treat naive times as UTC
+                            else:
+                                return dt.astimezone(timezone.utc)
+                        except ValueError:
+                            continue
+                dt = datetime.strptime(human_time, str(fmt))
+                if dt.tzinfo is None:
+                    return dt.replace(tzinfo=timezone.utc)
+                else:
+                    return dt.astimezone(timezone.utc)
+            except ValueError:
+                continue
+
+    raise ValueError("Unsupported time format: " + original_input)
+
+
+def duration(human_time: str) -> int:
+    """
+    Parse a human-friendly duration string into seconds, either ISO-8601 format or human format.
+    Less than 1 second is rounded to 0.
+
+    Args:
+        human_time (str): Duration string in:
+            ISO-8601 format (e.g. 'PT5M', 'P1DT2H'),
+            human format (e.g. '1h30m', '1w2d', '7d12h30m')
+
+    Returns:
+        timedelta: The parsed duration as a timedelta object
+
+    Raises:
+        ValueError: If the duration string format is not supported
+
+    Examples:
+        >>> duration('PT5S')  # 5 seconds
+        >>> duration('PT9M15S')  # 9 minutes 15 seconds
+        >>> duration('PT9H15M')  # 9 hours 15 minutes
+        >>> duration('P1DT2H')  # 1 day 2 hours
+        >>> duration('30m')  # 30 minutes
+        >>> duration('1h30m')  # 1 hour 30 minutes
+        >>> duration('1w2d')  # 1 week 2 days
+        >>> duration('7d12h30m')  # 7 days 12 hours 30 minutes
+    """
+
+    if not human_time:
+        raise ValueError(f"Invalid duration format: {human_time}")
+
+    human_time = human_time.upper()
+
+    # First try ISO-8601 format
+    iso_pattern = r"^P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$"
+    iso_match = re.match(iso_pattern, human_time)
+
+    if iso_match:
+        # PT with no values specified is invalid - must have at least one value
+        if human_time == "PT" or human_time == "P" or human_time == "":
+            raise ValueError(f"Invalid duration format: {human_time}")
+
+        weeks = int(iso_match.group(1) or 0)
+        days = int(iso_match.group(2) or 0)
+        hours = int(iso_match.group(3) or 0)
+        minutes = int(iso_match.group(4) or 0)
+        seconds = float(iso_match.group(5) or 0)
+
+        return int(timedelta(weeks=weeks, days=days, hours=hours, minutes=minutes, seconds=seconds).total_seconds())
+
+    # Try human readable format (e.g. 1h30m, 1w2d)
+    human_pattern = r"^(?:(\d+)Y)?(?:(\d+)W)?(?:(\d+)D)?(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?$"
+    human_match = re.match(human_pattern, human_time)
+
+    if human_match:
+        years = int(human_match.group(1) or 0)
+        weeks = int(human_match.group(2) or 0)
+        days = int(human_match.group(3) or 0)
+        hours = int(human_match.group(4) or 0)
+        minutes = int(human_match.group(5) or 0)
+        seconds = int(human_match.group(6) or 0)
+
+        # Convert years to days (assuming 365 days per year)
+        days_from_years = years * 365
+
+        return int(
+            timedelta(
+                weeks=weeks,
+                days=days + days_from_years,
+                hours=hours,
+                minutes=minutes,
+                seconds=seconds,
+            ).total_seconds()
+        )
+
+    raise ValueError(f"Unsupported duration format: {human_time}")