dycw-utilities 0.125.2__tar.gz → 0.125.4__tar.gz

{dycw_utilities-0.125.2 → dycw_utilities-0.125.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.125.2
+Version: 0.125.4
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -10,7 +10,7 @@ Requires-Dist: hypothesis<6.132,>=6.131.27; extra == 'test'
 Requires-Dist: pytest-asyncio<0.27,>=0.26.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'
-Requires-Dist: pytest-lazy-fixtures<1.2,>=1.1.2; extra == 'test'
+Requires-Dist: pytest-lazy-fixtures<1.2,>=1.1.3; extra == 'test'
 Requires-Dist: pytest-only<2.2,>=2.1.2; extra == 'test'
 Requires-Dist: pytest-randomly<3.17,>=3.16.0; extra == 'test'
 Requires-Dist: pytest-regressions<2.8,>=2.7.0; extra == 'test'
@@ -174,7 +174,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,>=3.11.16; extra == 'zzz-test-slack-sdk'
+Requires-Dist: aiohttp<3.13,>=3.12.0; 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.125.2 → dycw_utilities-0.125.4}/pyproject.toml

@@ -8,7 +8,7 @@ requires = ["hatchling"]
 # dependency groups
 [dependency-groups]
 dev = [
-  "aiohttp >= 3.11.16, < 3.12",  # for slack
+  "aiohttp >= 3.12.0, < 3.13",  # for slack
   "aiosqlite >= 0.21.0, < 0.22",
   "altair >= 5.5.0, < 5.6",
   "asyncpg >= 0.30.0, < 0.31",  # for sqlalchemy async
@@ -35,6 +35,7 @@ dev = [
   "nest-asyncio >= 1.6.0, < 1.7",  # for sqlalchemy async
   "nox >= 2025.2.9, < 2025.3",
   "numpy >= 2.2.6, < 2.3",
+  "libcst >= 1.7.0, < 1.8",
   "optuna >= 4.3.0, < 4.4",
   "orjson >= 3.10.18, < 3.11",
   "pathvalidate >= 3.2.3, < 3.3",
@@ -70,7 +71,7 @@ dev = [
   "pytest-asyncio >= 0.26.0, < 0.27",
   "pytest-cov >= 6.1.1, < 6.2",
   "pytest-instafail >= 0.5.0, < 0.6",
-  "pytest-lazy-fixtures >= 1.1.2, < 1.2",
+  "pytest-lazy-fixtures >= 1.1.3, < 1.2",
   "pytest-only >= 2.1.2, < 2.2",
   "pytest-randomly >= 3.16.0, < 3.17",
   "pytest-rerunfailures >= 15.1, < 16",
@@ -91,7 +92,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.125.2"
+version = "0.125.4"
 
 [project.optional-dependencies]
 test = [
@@ -100,7 +101,7 @@ test = [
   "pytest-asyncio >= 0.26.0, < 0.27",
   "pytest-cov >= 6.1.1, < 6.2",
   "pytest-instafail >= 0.5.0, < 0.6",
-  "pytest-lazy-fixtures >= 1.1.2, < 1.2",
+  "pytest-lazy-fixtures >= 1.1.3, < 1.2",
   "pytest-only >= 2.1.2, < 2.2",
   "pytest-randomly >= 3.16.0, < 3.17",
   "pytest-regressions >= 2.7.0, < 2.8",
@@ -268,7 +269,7 @@ zzz-test-scipy = ["scipy >= 1.15.3, < 1.16"]
 zzz-test-sentinel = []
 zzz-test-shelve = []
 zzz-test-slack-sdk = [
-  "aiohttp >= 3.11.16, < 3.12",  # for slack
+  "aiohttp >= 3.12.0, < 3.13",  # for slack
   "slack-sdk >= 3.35.0, < 3.36",
 ]
 zzz-test-socket = []
@@ -332,7 +333,7 @@ zzz-test-zoneinfo = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.125.2"
+current_version = "0.125.4"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

dycw_utilities-0.125.4/src/tests/test_libcst.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from hypothesis import given
+from hypothesis.strategies import sampled_from
+from libcst import (
+    Attribute,
+    Dot,
+    Expr,
+    Import,
+    ImportAlias,
+    ImportFrom,
+    ImportStar,
+    Integer,
+    Module,
+    Name,
+    SimpleStatementLine,
+)
+from pytest import raises
+
+from tests.conftest import SKIPIF_CI
+from utilities.iterables import one
+from utilities.libcst import (
+    JoinDottedStrError,
+    _ParseImportAliasError,
+    _ParseImportEmptyModuleError,
+    generate_f_string,
+    generate_from_import,
+    generate_import,
+    join_dotted_str,
+    parse_import,
+    render_module,
+    split_dotted_str,
+)
+
+
+class TestGenerateFString:
+    def test_main(self) -> None:
+        string = generate_f_string("foo", "bar")
+        result = Module([SimpleStatementLine([Expr(string)])]).code.strip("\n")
+        expected = 'f"{foo}bar"'
+        assert result == expected
+
+
+class TestGenerateFromImport:
+    @given(
+        case=sampled_from([
+            ("foo", "bar", None, "from foo import bar"),
+            ("foo", "bar", "bar2", "from foo import bar as bar2"),
+            ("foo.bar", "baz", None, "from foo.bar import baz"),
+            ("foo.bar", "baz", "baz2", "from foo.bar import baz as baz2"),
+        ])
+    )
+    def test_main(self, *, case: tuple[str, str, str | None, str]) -> None:
+        module, name, asname, expected = case
+        imp = generate_from_import(module, name, asname=asname)
+        result = Module([SimpleStatementLine([imp])]).code.strip("\n")
+        assert result == expected
+
+
+class TestGenerateImport:
+    @given(
+        case=sampled_from([
+            ("foo", None, "import foo"),
+            ("foo", "foo2", "import foo as foo2"),
+            ("foo.bar", None, "import foo.bar"),
+            ("foo.bar", "bar2", "import foo.bar as bar2"),
+        ])
+    )
+    def test_main(self, *, case: tuple[str, str | None, str]) -> None:
+        module, asname, expected = case
+        imp = generate_import(module, asname=asname)
+        result = Module([SimpleStatementLine([imp])]).code.strip("\n")
+        assert result == expected
+
+
+class TestParseImport:
+    def test_import_one_name(self) -> None:
+        imp = Import(names=[ImportAlias(Name("foo"))])
+        parsed = one(parse_import(imp))
+        assert parsed.module == "foo"
+        assert parsed.name is None
+
+    def test_import_one_attr(self) -> None:
+        imp = Import(names=[ImportAlias(Attribute(Name("foo"), Name("bar")))])
+        parsed = one(parse_import(imp))
+        assert parsed.module == "foo.bar"
+        assert parsed.name is None
+
+    def test_import_many(self) -> None:
+        imp = Import(names=[ImportAlias(Name("foo")), ImportAlias(Name("bar"))])
+        result = parse_import(imp)
+        assert len(result) == 2
+        first, second = result
+        assert first.module == "foo"
+        assert first.name is None
+        assert second.module == "bar"
+        assert second.name is None
+
+    def test_from_import_one(self) -> None:
+        imp = ImportFrom(module=Name("foo"), names=[ImportAlias(Name("bar"))])
+        result = one(parse_import(imp))
+        assert result.module == "foo"
+        assert result.name == "bar"
+
+    def test_from_import_many(self) -> None:
+        imp = ImportFrom(
+            module=Name("foo"),
+            names=[ImportAlias(Name("bar")), ImportAlias(Name("baz"))],
+        )
+        result = parse_import(imp)
+        first, second = result
+        assert first.module == "foo"
+        assert first.name == "bar"
+        assert second.module == "foo"
+        assert second.name == "baz"
+
+    def test_from_import_star(self) -> None:
+        imp = ImportFrom(module=Name("foo"), names=ImportStar())
+        result = one(parse_import(imp))
+        assert result.module == "foo"
+        assert result.name == "*"
+
+    def test_error_empty_module(self) -> None:
+        alias = ImportAlias(name=Name("foo"))
+        imp = ImportFrom(module=None, names=[alias], relative=[Dot()])
+        with raises(
+            _ParseImportEmptyModuleError, match="Module must not be None; got .*"
+        ):
+            _ = parse_import(imp)
+
+    def test_error_alias(self) -> None:
+        alias = ImportAlias(name=Attribute(Name("foo"), Name("bar")))
+        imp = ImportFrom(module=Name("baz"), names=[alias])
+        with raises(
+            _ParseImportAliasError,
+            match=r"Invalid alias name; got module 'baz' and attribute 'foo\.bar'",
+        ):
+            _ = parse_import(imp)
+
+
+class TestRenderModule:
+    @SKIPIF_CI
+    def test_main(self) -> None:
+        module = Module([SimpleStatementLine([generate_import("foo")])])
+        result = render_module(module)
+        expected = "import foo\n"
+        assert result == expected
+
+
+class TestSplitAndJoinDottedStr:
+    @given(text=sampled_from(["foo", "foo.bar", "foo.bar.baz"]))
+    def test_main(self, *, text: str) -> None:
+        result = join_dotted_str(split_dotted_str(text))
+        assert result == text
+
+    def test_join_dotted_fallback_expression(self) -> None:
+        with raises(
+            JoinDottedStrError, match="Only names & attributes allowed; got .*"
+        ):
+            _ = join_dotted_str(Integer("0"))

{dycw_utilities-0.125.2 → dycw_utilities-0.125.4}/src/tests/test_more_itertools.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 from collections.abc import Iterator
+from re import escape
 from typing import TYPE_CHECKING, Any, ClassVar, TypeGuard
 
 from pytest import mark, param, raises
 
 from utilities.more_itertools import (
+    BucketMappingError,
     Split,
     bucket_mapping,
     partition_list,
@@ -64,6 +66,46 @@ class TestBucketMapping:
         assert mapping["b"] == [1, 2, 3]
         assert mapping["c"] == [1, 2]
 
+    iterable_unique: ClassVar[list[str]] = ["a1", "b2", "c3"]
+
+    def test_unique(self) -> None:
+        mapping = bucket_mapping(self.iterable_unique, lambda x: x[0], unique=True)
+        expected = {"a": "a1", "b": "b2", "c": "c3"}
+        assert mapping == expected
+
+    def test_transform_and_unique(self) -> None:
+        mapping = bucket_mapping(
+            self.iterable_unique,
+            lambda x: x[0],
+            transform=lambda x: int(x[-1]),
+            unique=True,
+        )
+        expected = {"a": 1, "b": 2, "c": 3}
+        assert mapping == expected
+
+    def test_error_unique(self) -> None:
+        with raises(
+            BucketMappingError,
+            match=escape(
+                "Buckets must contain exactly one item each; got 'a' (#1: 'a1', #2: 'a2'), 'b' (#1: 'b1', #2: 'b2'), 'c' (#1: 'c1', #2: 'c2')"
+            ),
+        ):
+            _ = bucket_mapping(self.iterable, lambda x: x[0], unique=True)
+
+    def test_error_transform_and_unique(self) -> None:
+        with raises(
+            BucketMappingError,
+            match=escape(
+                "Buckets must contain exactly one item each; got 'a' (#1: 1, #2: 2), 'b' (#1: 1, #2: 2), 'c' (#1: 1, #2: 2)"
+            ),
+        ):
+            _ = bucket_mapping(
+                self.iterable,
+                lambda x: x[0],
+                transform=lambda x: int(x[-1]),
+                unique=True,
+            )
+
 
 class TestPartitionList:
     def test_main(self) -> None:

{dycw_utilities-0.125.2 → dycw_utilities-0.125.4}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.125.2"
+__version__ = "0.125.4"

dycw_utilities-0.125.4/src/utilities/libcst.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from subprocess import check_output
+from typing import assert_never, override
+
+from libcst import (
+    AsName,
+    Attribute,
+    BaseExpression,
+    FormattedString,
+    FormattedStringExpression,
+    FormattedStringText,
+    Import,
+    ImportAlias,
+    ImportFrom,
+    ImportStar,
+    Module,
+    Name,
+)
+
+
+def generate_from_import(
+    module: str, name: str, /, *, asname: str | None = None
+) -> ImportFrom:
+    """Generate an `ImportFrom` object."""
+    alias = ImportAlias(
+        name=Name(name), asname=AsName(Name(asname)) if asname else None
+    )
+    return ImportFrom(module=split_dotted_str(module), names=[alias])
+
+
+def generate_f_string(var: str, suffix: str, /) -> FormattedString:
+    """Generate an f-string."""
+    return FormattedString([
+        FormattedStringExpression(expression=Name(var)),
+        FormattedStringText(suffix),
+    ])
+
+
+def generate_import(module: str, /, *, asname: str | None = None) -> Import:
+    """Generate an `Import` object."""
+    alias = ImportAlias(
+        name=split_dotted_str(module), asname=AsName(Name(asname)) if asname else None
+    )
+    return Import(names=[alias])
+
+
+##
+
+
+@dataclass(kw_only=True, slots=True)
+class _ParseImportOutput:
+    module: str
+    name: str | None = None
+
+
+def parse_import(import_: Import | ImportFrom, /) -> Sequence[_ParseImportOutput]:
+    """Parse an import."""
+    match import_:
+        case Import():
+            return [_parse_import_one(n) for n in import_.names]
+        case ImportFrom():
+            if (attr_or_name := import_.module) is None:
+                raise _ParseImportEmptyModuleError(import_=import_)
+            module = join_dotted_str(attr_or_name)
+            match import_.names:
+                case Sequence() as names:
+                    return [_parse_import_from_one(module, n) for n in names]
+                case ImportStar():
+                    return [_ParseImportOutput(module=module, name="*")]
+                case _ as never:
+                    assert_never(never)
+        case _ as never:
+            assert_never(never)
+
+
+def _parse_import_one(alias: ImportAlias, /) -> _ParseImportOutput:
+    return _ParseImportOutput(module=join_dotted_str(alias.name))
+
+
+def _parse_import_from_one(module: str, alias: ImportAlias, /) -> _ParseImportOutput:
+    match alias.name:
+        case Name(name):
+            return _ParseImportOutput(module=module, name=name)
+        case Attribute() as attr:
+            raise _ParseImportAliasError(module=module, attr=attr)
+        case _ as never:
+            assert_never(never)
+
+
+@dataclass(kw_only=True, slots=True)
+class ParseImportError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _ParseImportEmptyModuleError(ParseImportError):
+    import_: ImportFrom
+
+    @override
+    def __str__(self) -> str:
+        return f"Module must not be None; got {self.import_}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _ParseImportAliasError(ParseImportError):
+    module: str
+    attr: Attribute
+
+    @override
+    def __str__(self) -> str:
+        attr = self.attr
+        return f"Invalid alias name; got module {self.module!r} and attribute '{attr.value.value}.{attr.attr.value}'"
+
+
+##
+
+
+def split_dotted_str(dotted: str, /) -> Name | Attribute:
+    """Split a dotted string into a name/attribute."""
+    parts = dotted.split(".")
+    node = Name(parts[0])
+    for part in parts[1:]:
+        node = Attribute(value=node, attr=Name(part))
+    return node
+
+
+def join_dotted_str(name_or_attr: Name | Attribute, /) -> str:
+    """Join a dotted from from a name/attribute."""
+    parts: Sequence[str] = []
+    curr: BaseExpression | Name | Attribute = name_or_attr
+    while True:
+        match curr:
+            case Name(value=value):
+                parts.append(value)
+                break
+            case Attribute(value=value, attr=Name(value=attr_value)):
+                parts.append(attr_value)
+                curr = value
+            case BaseExpression() as expr:
+                raise JoinDottedStrError(name_or_attr=name_or_attr, expr=expr)
+            case _ as never:
+                assert_never(never)
+    return ".".join(reversed(parts))
+
+
+@dataclass(kw_only=True, slots=True)
+class JoinDottedStrError(Exception):
+    name_or_attr: Name | Attribute
+    expr: BaseExpression
+
+    @override
+    def __str__(self) -> str:
+        return f"Only names & attributes allowed; got {self.expr}"
+
+
+##
+
+
+def render_module(source: str | Module, /) -> str:
+    """Render a module."""
+    match source:  # skipif-ci
+        case str() as text:
+            return check_output(["ruff", "format", "-"], input=text, text=True)
+        case Module() as module:
+            return render_module(module.code)
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
+__all__ = [
+    "ParseImportError",
+    "generate_f_string",
+    "generate_from_import",
+    "generate_import",
+    "join_dotted_str",
+    "parse_import",
+    "render_module",
+    "split_dotted_str",
+]

{dycw_utilities-0.125.2 → dycw_utilities-0.125.4}/src/utilities/more_itertools.py

@@ -21,12 +21,14 @@ from more_itertools import bucket, partition, split_into
 from more_itertools import peekable as _peekable
 
 from utilities.functions import get_class_name
+from utilities.iterables import OneNonUniqueError, one
+from utilities.reprlib import get_repr
 from utilities.sentinel import Sentinel, sentinel
+from utilities.types import THashable
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
 
-    from utilities.types import THashable
 
 _T = TypeVar("_T")
 _U = TypeVar("_U")
@@ -35,6 +37,26 @@ _U = TypeVar("_U")
 ##
 
 
+@overload
+def bucket_mapping(
+    iterable: Iterable[_T],
+    func: Callable[[_T], THashable],
+    /,
+    *,
+    transform: Callable[[_T], _U],
+    list: bool = False,
+    unique: Literal[True],
+) -> Mapping[THashable, _U]: ...
+@overload
+def bucket_mapping(
+    iterable: Iterable[_T],
+    func: Callable[[_T], THashable],
+    /,
+    *,
+    transform: Callable[[_T], _U] | None = None,
+    list: bool = False,
+    unique: Literal[True],
+) -> Mapping[THashable, _T]: ...
 @overload
 def bucket_mapping(
     iterable: Iterable[_T],
@@ -79,11 +101,14 @@ def bucket_mapping(
     *,
     transform: Callable[[_T], _U] | None = None,
     list: bool = False,
+    unique: bool = False,
 ) -> (
     Mapping[THashable, Iterator[_T]]
     | Mapping[THashable, Iterator[_U]]
     | Mapping[THashable, Sequence[_T]]
     | Mapping[THashable, Sequence[_U]]
+    | Mapping[THashable, _T]
+    | Mapping[THashable, _U]
 ): ...
 def bucket_mapping(
     iterable: Iterable[_T],
@@ -92,26 +117,55 @@ def bucket_mapping(
     *,
     transform: Callable[[_T], _U] | None = None,
     list: bool = False,  # noqa: A002
+    unique: bool = False,
 ) -> (
     Mapping[THashable, Iterator[_T]]
     | Mapping[THashable, Iterator[_U]]
     | Mapping[THashable, Sequence[_T]]
     | Mapping[THashable, Sequence[_U]]
+    | Mapping[THashable, _T]
+    | Mapping[THashable, _U]
 ):
     """Bucket the values of iterable into a mapping."""
     b = bucket(iterable, func)
     mapping = {key: b[key] for key in b}
     match transform, list:
         case None, False:
-            return mapping
+            ...
         case None, True:
-            return {k: builtins.list(v) for k, v in mapping.items()}
+            mapping = {k: builtins.list(v) for k, v in mapping.items()}
         case _, False:
-            return {k: map(transform, v) for k, v in mapping.items()}
+            mapping = {k: map(transform, v) for k, v in mapping.items()}
         case _, True:
-            return {k: builtins.list(map(transform, v)) for k, v in mapping.items()}
+            mapping = {k: builtins.list(map(transform, v)) for k, v in mapping.items()}
         case _ as never:
             assert_never(never)
+    if not unique:
+        return mapping
+    results = {}
+    error_no_transform: dict[THashable, tuple[_T, _T]] = {}
+    for key, value in mapping.items():
+        try:
+            results[key] = one(value)
+        except OneNonUniqueError as error:
+            error_no_transform[key] = (error.first, error.second)
+    if len(error_no_transform) >= 1:
+        raise BucketMappingError(errors=error_no_transform)
+    return results
+
+
+@dataclass(kw_only=True, slots=True)
+class BucketMappingError(Exception, Generic[THashable, _U]):
+    errors: Mapping[THashable, tuple[_U, _U]]
+
+    @override
+    def __str__(self) -> str:
+        parts = [
+            f"{get_repr(key)} (#1: {get_repr(first)}, #2: {get_repr(second)})"
+            for key, (first, second) in self.errors.items()
+        ]
+        desc = ", ".join(parts)
+        return f"Buckets must contain exactly one item each; got {desc}"
 
 
 ##
@@ -264,6 +318,7 @@ def _yield_splits3(
 
 
 __all__ = [
+    "BucketMappingError",
     "Split",
     "bucket_mapping",
     "partition_list",