dycw-utilities 0.129.9__tar.gz → 0.129.14__tar.gz

{dycw_utilities-0.129.9 → dycw_utilities-0.129.14}/PKG-INFO

@@ -1,13 +1,18 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.129.9
+Version: 0.129.14
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12
 Requires-Dist: typing-extensions<4.15,>=4.14.0
+Provides-Extra: logging
+Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'logging'
+Requires-Dist: coloredlogs<15.1,>=15.0.1; extra == 'logging'
+Requires-Dist: tzlocal<5.4,>=5.3.1; extra == 'logging'
+Requires-Dist: whenever<0.9,>=0.8.4; extra == 'logging'
 Provides-Extra: test
 Requires-Dist: dycw-pytest-only<2.2,>=2.1.1; extra == 'test'
-Requires-Dist: hypothesis<6.136,>=6.135.0; extra == 'test'
+Requires-Dist: hypothesis<6.136,>=6.135.2; extra == 'test'
 Requires-Dist: pytest-asyncio<1.1,>=1.0.0; extra == 'test'
 Requires-Dist: pytest-cov<6.2,>=6.1.1; extra == 'test'
 Requires-Dist: pytest-instafail<0.6,>=0.5.0; extra == 'test'
@@ -19,6 +24,8 @@ Requires-Dist: pytest-rng<1.1,>=1.0.0; extra == 'test'
 Requires-Dist: pytest-timeout<2.5,>=2.4.0; extra == 'test'
 Requires-Dist: pytest-xdist<3.8,>=3.7.0; extra == 'test'
 Requires-Dist: pytest<8.4,>=8.3.5; extra == 'test'
+Provides-Extra: zzz-test-aiolimiter
+Requires-Dist: aiolimiter<1.3,>=1.2.1; extra == 'zzz-test-aiolimiter'
 Provides-Extra: zzz-test-altair
 Requires-Dist: altair<5.6,>=5.5.0; extra == 'zzz-test-altair'
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-altair'
@@ -77,9 +84,9 @@ Provides-Extra: zzz-test-hypothesis
 Requires-Dist: aiosqlite<0.22,>=0.21.0; extra == 'zzz-test-hypothesis'
 Requires-Dist: asyncpg<0.31,>=0.30.0; extra == 'zzz-test-hypothesis'
 Requires-Dist: greenlet<3.3,>=3.2.0; extra == 'zzz-test-hypothesis'
-Requires-Dist: hypothesis<6.136,>=6.135.0; extra == 'zzz-test-hypothesis'
+Requires-Dist: hypothesis<6.136,>=6.135.2; extra == 'zzz-test-hypothesis'
 Requires-Dist: luigi<3.7,>=3.6.0; extra == 'zzz-test-hypothesis'
-Requires-Dist: numpy<2.3,>=2.2.6; extra == 'zzz-test-hypothesis'
+Requires-Dist: numpy<2.4,>=2.3.0; extra == 'zzz-test-hypothesis'
 Requires-Dist: pathvalidate<3.3,>=3.2.3; extra == 'zzz-test-hypothesis'
 Requires-Dist: redis<6.3,>=6.2.0; extra == 'zzz-test-hypothesis'
 Requires-Dist: sqlalchemy<2.1,>=2.0.41; extra == 'zzz-test-hypothesis'
@@ -108,14 +115,14 @@ Provides-Extra: zzz-test-luigi
 Requires-Dist: luigi<3.7,>=3.6.0; extra == 'zzz-test-luigi'
 Requires-Dist: whenever<0.9,>=0.8.4; extra == 'zzz-test-luigi'
 Provides-Extra: zzz-test-math
-Requires-Dist: numpy<2.3,>=2.2.6; extra == 'zzz-test-math'
+Requires-Dist: numpy<2.4,>=2.3.0; extra == 'zzz-test-math'
 Provides-Extra: zzz-test-memory-profiler
 Requires-Dist: memory-profiler<0.62,>=0.61.0; extra == 'zzz-test-memory-profiler'
 Provides-Extra: zzz-test-modules
 Provides-Extra: zzz-test-more-itertools
 Requires-Dist: more-itertools<10.8,>=10.7.0; extra == 'zzz-test-more-itertools'
 Provides-Extra: zzz-test-numpy
-Requires-Dist: numpy<2.3,>=2.2.6; extra == 'zzz-test-numpy'
+Requires-Dist: numpy<2.4,>=2.3.0; extra == 'zzz-test-numpy'
 Provides-Extra: zzz-test-operator
 Requires-Dist: polars-lts-cpu<1.31,>=1.30.0; extra == 'zzz-test-operator'
 Requires-Dist: whenever<0.9,>=0.8.4; extra == 'zzz-test-operator'
@@ -172,7 +179,7 @@ Requires-Dist: scipy<1.16,>=1.15.3; extra == 'zzz-test-scipy'
 Provides-Extra: zzz-test-sentinel
 Provides-Extra: zzz-test-shelve
 Provides-Extra: zzz-test-slack-sdk
-Requires-Dist: aiohttp<3.12.10,>=3.12.9; extra == 'zzz-test-slack-sdk'
+Requires-Dist: aiohttp<3.13,>=3.12.11; extra == 'zzz-test-slack-sdk'
 Requires-Dist: slack-sdk<3.36,>=3.35.0; extra == 'zzz-test-slack-sdk'
 Provides-Extra: zzz-test-socket
 Provides-Extra: zzz-test-sqlalchemy

{dycw_utilities-0.129.9 → dycw_utilities-0.129.14}/pyproject.toml

@@ -8,7 +8,8 @@ requires = ["hatchling"]
 # dependency groups
 [dependency-groups]
 dev = [
-  "aiohttp >= 3.12.9, < 3.12.10",  # for slack
+  "aiohttp >= 3.12.11, < 3.13",  # for slack
+  "aiolimiter >= 1.2.1, < 1.3",
   "aiosqlite >= 0.21.0, < 0.22",
   "altair >= 5.5.0, < 5.6",
   "asyncpg >= 0.30.0, < 0.31",  # for sqlalchemy async
@@ -24,8 +25,9 @@ dev = [
   "fpdf2 >= 2.8.3, < 2.9",
   "greenlet >= 3.2.0, < 3.3",  # for sqlalchemy async
   "httpx >= 0.28.1, < 0.29",  # for fastapi
-  "hypothesis >= 6.135.0, < 6.136",
+  "hypothesis >= 6.135.2, < 6.136",
   "img2pdf >= 0.6.0, < 0.7",
+  "inflect >= 7.5.0, < 7.6",
   "lightweight-charts >= 2.1, < 2.2",
   "loguru >= 0.7.3, < 0.8",
   "luigi >= 3.6.0, < 3.7",
@@ -33,7 +35,7 @@ dev = [
   "more-itertools >= 10.7.0, < 10.8",
   "nest-asyncio >= 1.6.0, < 1.7",  # for sqlalchemy async
   "nox >= 2025.2.9, < 2025.3",
-  "numpy >= 2.2.6, < 2.3",
+  "numpy >= 2.3.0, < 2.4",
   "libcst >= 1.8.0, < 1.9",
   "optuna >= 4.3.0, < 4.4",
   "orjson >= 3.10.18, < 3.11",
@@ -82,6 +84,7 @@ dev = [
   "pytest-xdist >= 3.7.0, < 3.8",
   # CI
   "win32_setctime >= 1.2.0, < 1.3",  # https://github.com/Delgan/loguru/issues/147
+  "aiolimiter>=1.2.1",
 ]
 
 # project
@@ -93,12 +96,18 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.129.9"
+version = "0.129.14"
 
 [project.optional-dependencies]
+logging = [
+  "atomicwrites >= 1.4.1, < 1.5",
+  "coloredlogs >= 15.0.1, < 15.1",
+  "tzlocal >= 5.3.1, < 5.4",
+  "whenever >= 0.8.4, < 0.9",
+]
 test = [
   "dycw-pytest-only >= 2.1.1, < 2.2",
-  "hypothesis >= 6.135.0, < 6.136",
+  "hypothesis >= 6.135.2, < 6.136",
   "pytest >= 8.3.5, < 8.4",
   "pytest-asyncio >= 1.0.0, < 1.1",
   "pytest-cov >= 6.1.1, < 6.2",
@@ -111,6 +120,9 @@ test = [
   "pytest-timeout >= 2.4.0, < 2.5",
   "pytest-xdist >= 3.7.0, < 3.8",
 ]
+zzz-test-aiolimiter = [
+  "aiolimiter >= 1.2.1, < 1.3",
+]
 zzz-test-altair = [
   "altair >= 5.5.0, < 5.6",
   "atomicwrites >= 1.4.1, < 1.5",
@@ -173,9 +185,9 @@ zzz-test-hypothesis = [
   "aiosqlite >= 0.21.0, < 0.22",
   "asyncpg >= 0.30.0, < 0.31",  # for sqlalchemy async
   "greenlet >= 3.2.0, < 3.3",  # for sqlalchemy async
-  "hypothesis >= 6.135.0, < 6.136",
+  "hypothesis >= 6.135.2, < 6.136",
   "luigi >= 3.6.0, < 3.7",
-  "numpy >= 2.2.6, < 2.3",
+  "numpy >= 2.3.0, < 2.4",
   "pathvalidate >= 3.2.3, < 3.3",
   "redis >= 6.2.0, < 6.3",
   "sqlalchemy >= 2.0.41, < 2.1",
@@ -206,11 +218,11 @@ zzz-test-luigi = [
   "luigi >= 3.6.0, < 3.7",
   "whenever >= 0.8.4, < 0.9",
 ]
-zzz-test-math = ["numpy >= 2.2.6, < 2.3"]
+zzz-test-math = ["numpy >= 2.3.0, < 2.4"]
 zzz-test-memory-profiler = ["memory-profiler >= 0.61.0, < 0.62"]
 zzz-test-modules = []
 zzz-test-more-itertools = ["more-itertools >= 10.7.0, < 10.8"]
-zzz-test-numpy = ["numpy >= 2.2.6, < 2.3"]
+zzz-test-numpy = ["numpy >= 2.3.0, < 2.4"]
 zzz-test-operator = [
   "polars-lts-cpu >= 1.30.0, < 1.31",
   "whenever >= 0.8.4, < 0.9",
@@ -268,7 +280,7 @@ zzz-test-scipy = ["scipy >= 1.15.3, < 1.16"]
 zzz-test-sentinel = []
 zzz-test-shelve = []
 zzz-test-slack-sdk = [
-  "aiohttp >= 3.12.9, < 3.12.10",  # for slack
+  "aiohttp >= 3.12.11, < 3.13",  # for slack
   "slack-sdk >= 3.35.0, < 3.36",
 ]
 zzz-test-socket = []
@@ -332,7 +344,7 @@ zzz-test-zoneinfo = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.129.9"
+current_version = "0.129.14"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"
@@ -443,6 +455,7 @@ filterwarnings = [
   "ignore:Implicitly cleaning up <TemporaryDirectory '.*'>:ResourceWarning",
   "ignore:ResourceTracker called reentrantly for resource cleanup, which is unsupported:UserWarning",
   "ignore:Task .* without outputs has no custom complete.* method:UserWarning",  # luigi
+  "ignore:The garbage collector is trying to clean up non-checked-in connection <AdaptedConnection <Connection(.*)>>:sqlalchemy.exc.SAWarning",  # sqlalchemy
   "ignore:There is no current event loop:DeprecationWarning",  # eventkit
   "ignore:Using fork.* can cause Polars to deadlock in the child process:RuntimeWarning",  # polars/pqdm
   "ignore:coroutine 'AsyncConnection.close' was never awaited:RuntimeWarning",

dycw_utilities-0.129.14/src/tests/test_aiolimiter.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from asyncio import sleep
+from typing import ClassVar
+
+from utilities.aiolimiter import get_async_limiter
+from utilities.text import unique_str
+from utilities.timer import Timer
+
+
+class TestGetAsyncLimiter:
+    async def test_main(self) -> None:
+        counter = 0
+
+        async def increment() -> None:
+            nonlocal counter
+            counter += 1
+            await sleep(0.01)
+
+        name = unique_str()
+        with Timer() as timer:
+            for _ in range(2):
+                async with get_async_limiter(name, rate=0.5):
+                    await increment()
+        assert timer >= 0.48
+
+    shared: ClassVar[str] = unique_str()
+
+    async def test_shared1(self) -> None:
+        async with get_async_limiter(self.shared):
+            await sleep(0.01)
+
+    async def test_shared2(self) -> None:
+        async with get_async_limiter(self.shared):
+            await sleep(0.01)
+
+    async def test_shared3(self) -> None:
+        async with get_async_limiter(self.shared):
+            await sleep(0.01)

dycw_utilities-0.129.14/src/tests/test_git.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hypothesis import given, settings
+from pytest import raises
+
+from utilities.git import GetRepoRootError, get_repo_root
+from utilities.hypothesis import git_repos
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class TestGetRepoRoot:
+    @given(repo=git_repos())
+    @settings(max_examples=1)
+    def test_main(self, *, repo: Path) -> None:
+        root = get_repo_root(path=repo)
+        expected = repo.resolve()
+        assert root == expected
+
+    def test_error(self, *, tmp_path: Path) -> None:
+        with raises(
+            GetRepoRootError, match="Path is not part of a `git` repository: .*"
+        ):
+            _ = get_repo_root(path=tmp_path)

dycw_utilities-0.129.14/src/tests/test_inflect.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pytest import mark, param
+
+from utilities.inflect import counted_noun
+
+
+class TestCountedNoun:
+    @mark.parametrize(
+        ("num", "expected"),
+        [
+            param(0, "0 words"),
+            param(1, "1 word"),
+            param(2, "2 words"),
+            param(3, "3 words"),
+        ],
+    )
+    def test_main(self, *, num: int, expected: str) -> None:
+        result = counted_noun(num, "word")
+        assert result == expected

{dycw_utilities-0.129.9 → dycw_utilities-0.129.14}/src/tests/test_pathlib.py

@@ -8,11 +8,13 @@ from hypothesis import given, settings
 from hypothesis.strategies import integers, sets
 from pytest import mark, param, raises
 
+from tests.conftest import SKIPIF_CI_AND_WINDOWS
 from utilities.dataclasses import replace_non_sentinel
 from utilities.hypothesis import git_repos, paths, temp_paths
 from utilities.pathlib import (
     GetRootError,
     ensure_suffix,
+    expand_path,
     get_path,
     get_root,
     list_dir,
@@ -40,6 +42,25 @@ class TestEnsureSuffix:
         assert result == expected
 
 
+class TestExpandPath:
+    @mark.parametrize(
+        ("path", "expected"),
+        [
+            param("foo", Path("foo")),
+            param("~", Path.home()),
+            param("~/foo", Path.home().joinpath("foo")),
+            param("$HOME", Path.home(), marks=SKIPIF_CI_AND_WINDOWS),
+            param(
+                "$HOME/foo", Path.home().joinpath("foo"), marks=SKIPIF_CI_AND_WINDOWS
+            ),
+        ],
+        ids=str,
+    )
+    def test_main(self, *, path: Path, expected: Path) -> None:
+        result = expand_path(path)
+        assert result == expected
+
+
 class TestGetPath:
     @given(path=paths())
     def test_path(self, *, path: Path) -> None:

{dycw_utilities-0.129.9 → dycw_utilities-0.129.14}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.129.9"
+__version__ = "0.129.14"

dycw_utilities-0.129.14/src/utilities/aiolimiter.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from asyncio import get_running_loop
+from typing import TYPE_CHECKING
+
+from aiolimiter import AsyncLimiter
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+_LIMITERS: dict[tuple[int, Hashable], AsyncLimiter] = {}
+
+
+def get_async_limiter(key: Hashable, /, *, rate: float = 1.0) -> AsyncLimiter:
+    """Get a loop-aware rate limiter."""
+    id_ = id(get_running_loop())
+    full = (id_, key)
+    try:
+        return _LIMITERS[full]
+    except KeyError:
+        limiter = _LIMITERS[full] = AsyncLimiter(1.0, time_period=rate)
+        return limiter
+
+
+__all__ = ["get_async_limiter"]

dycw_utilities-0.129.14/src/utilities/git.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from re import IGNORECASE, search
+from subprocess import PIPE, CalledProcessError, check_output
+from typing import TYPE_CHECKING, override
+
+from utilities.pathlib import PWD
+
+if TYPE_CHECKING:
+    from utilities.types import PathLike
+
+
+def get_repo_root(*, path: PathLike = PWD) -> Path:
+    """Get the repo root."""
+    try:
+        output = check_output(
+            ["git", "rev-parse", "--show-toplevel"], stderr=PIPE, cwd=path, text=True
+        )
+    except CalledProcessError as error:
+        # newer versions of git report "Not a git repository", whilst older
+        # versions report "not a git repository"
+        if search("fatal: not a git repository", error.stderr, flags=IGNORECASE):
+            raise GetRepoRootError(cwd=path) from error
+        raise  # pragma: no cover
+    else:
+        return Path(output.strip("\n"))
+
+
+@dataclass(kw_only=True, slots=True)
+class GetRepoRootError(Exception):
+    cwd: PathLike
+
+    @override
+    def __str__(self) -> str:
+        return f"Path is not part of a `git` repository: {self.cwd}"
+
+
+__all__ = ["GetRepoRootError", "get_repo_root"]

dycw_utilities-0.129.14/src/utilities/inflect.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import cast
+
+from inflect import Word, engine
+
+_ENGINE = engine()
+
+
+def counted_noun(num: int, noun: str, /) -> str:
+    """Construct a counted noun."""
+    word = cast("Word", noun)
+    sin_or_plu = _ENGINE.plural_noun(word, count=num)
+    return f"{num} {sin_or_plu}"
+
+
+__all__ = ["counted_noun"]

{dycw_utilities-0.129.9 → dycw_utilities-0.129.14}/src/utilities/logging.py

@@ -85,6 +85,9 @@ except ModuleNotFoundError:  # pragma: no cover
 type _When = Literal[
     "S", "M", "H", "D", "midnight", "W0", "W1", "W2", "W3", "W4", "W5", "W6"
 ]
+_BACKUP_COUNT: int = 100
+_MAX_BYTES: int = 10 * 1024**2
+_WHEN: _When = "D"
 
 
 class SizeAndTimeRotatingFileHandler(BaseRotatingHandler):
@@ -100,10 +103,10 @@ class SizeAndTimeRotatingFileHandler(BaseRotatingHandler):
         encoding: str | None = None,
         delay: bool = False,
         errors: Literal["strict", "ignore", "replace"] | None = None,
-        maxBytes: int = 0,
-        when: _When = "midnight",
+        maxBytes: int = _MAX_BYTES,
+        when: _When = _WHEN,
         interval: int = 1,
-        backupCount: int = 0,
+        backupCount: int = _BACKUP_COUNT,
         utc: bool = False,
         atTime: dt.time | None = None,
     ) -> None:
@@ -554,10 +557,10 @@ def setup_logging(
     console_filters: Iterable[_FilterType] | None = None,
     console_fmt: str = "❯ {_zoned_datetime_str} | {name}:{funcName}:{lineno} | {message}",  # noqa: RUF001
     files_dir: MaybeCallablePathLike | None = get_default_logging_path,
-    files_when: _When = "D",
+    files_when: _When = _WHEN,
     files_interval: int = 1,
-    files_backup_count: int = 10,
-    files_max_bytes: int = 10 * 1024**2,
+    files_backup_count: int = _BACKUP_COUNT,
+    files_max_bytes: int = _MAX_BYTES,
     files_filters: Iterable[_FilterType] | None = None,
     files_fmt: str = "{_zoned_datetime_str} | {name}:{funcName}:{lineno} | {levelname:8} | {message}",
     filters: MaybeIterable[_FilterType] | None = None,

{dycw_utilities-0.129.9 → dycw_utilities-0.129.14}/src/utilities/pathlib.py

@@ -5,6 +5,7 @@ from contextlib import contextmanager, suppress
 from dataclasses import dataclass
 from itertools import chain
 from os import chdir
+from os.path import expandvars
 from pathlib import Path
 from re import IGNORECASE, search
 from subprocess import PIPE, CalledProcessError, check_output
@@ -34,6 +35,16 @@ def ensure_suffix(path: PathLike, suffix: str, /) -> Path:
 ##
 
 
+def expand_path(path: PathLike, /) -> Path:
+    """Expand a path."""
+    path = str(path)
+    path = expandvars(path)
+    return Path(path).expanduser()
+
+
+##
+
+
 @overload
 def get_path(*, path: MaybeCallablePathLike | None) -> Path: ...
 @overload
@@ -111,4 +122,4 @@ def temp_cwd(path: PathLike, /) -> Iterator[None]:
         chdir(prev)
 
 
-__all__ = ["PWD", "ensure_suffix", "get_path", "list_dir", "temp_cwd"]
+__all__ = ["PWD", "ensure_suffix", "expand_path", "get_path", "list_dir", "temp_cwd"]

{dycw_utilities-0.129.9 → dycw_utilities-0.129.14}/src/utilities/scipy.py

@@ -19,7 +19,7 @@ def _ppf_1d(array: NDArrayF, cutoff: float, /) -> NDArrayF:
         out = full_like(array, nan, dtype=float)
         out[j] = _ppf_1d(array[j], cutoff)
         return out
-    low, high = min(array), max(array)
+    low, high = array.min(), array.max()
     if is_zero(span := high - low):
         return zeros_like(array, dtype=float)
     centred = (array - low) / span