dycw-utilities 0.174.12__py3-none-any.whl → 0.175.31__py3-none-any.whl

{dycw_utilities-0.174.12.dist-info → dycw_utilities-0.175.31.dist-info}/METADATA

@@ -1,6 +1,7 @@
 Metadata-Version: 2.3
 Name: dycw-utilities
-Version: 0.174.12
+Version: 0.175.31
+Summary: Miscellaneous Python utilities
 Author: Derek Wan
 Author-email: Derek Wan <d.wan@icloud.com>
 Requires-Dist: atomicwrites>=1.4.1,<1.5
@@ -28,14 +29,6 @@ Provides-Extra: logging
 Provides-Extra: test
 Description-Content-Type: text/markdown
 
-[![PyPI version](https://badge.fury.io/py/dycw-utilities.svg)](https://badge.fury.io/py/dycw-utilities)
+# `python-utilities`
 
-# `dycw-utilities`
-
-[All the Python functions I don't want to write twice.](https://github.com/nvim-lua/plenary.nvim)
-
-## Installation
-
-- `pip install dycw-utilities`
-
-or with [extras](https://github.com/dycw/python-utilities/blob/master/pyproject.toml).
+Miscellaneous Python utilities

{dycw_utilities-0.174.12.dist-info → dycw_utilities-0.175.31.dist-info}/RECORD

@@ -1,23 +1,22 @@
-utilities/__init__.py,sha256=VFU3kmpNxjyAnXuMdW-ygHCxl3CNmUA0rP-wy1y_uzg,61
-utilities/aeventkit.py,sha256=OmDBhYGgbsKrB7cdC5FFpJHUatX9O76eTeKVVTksp2Y,12673
-utilities/altair.py,sha256=rUK99g9x6CYDDfiZrf-aTx5fSRbL1Q8ctgKORowzXHg,9060
+utilities/__init__.py,sha256=y-0IecU_rQ9B_0aVstJ6gMlcyWn2-Hw_v-RcSXW8pWY,61
+utilities/altair.py,sha256=TLfRFbG9HwG7SLXoJ-v0r-t49ZaGgTQZD82cpjVi4vs,9085
 utilities/asyncio.py,sha256=aJySVxBY0gqsIYnoNmH7-1r8djKuf4vSsU69VCD08t8,16772
 utilities/atomicwrites.py,sha256=tPo6r-Rypd9u99u66B9z86YBPpnLrlHtwox_8Z7T34Y,5790
 utilities/atools.py,sha256=6neeCcgXxK2dlsc0xp15Za7nSucbCgFtAJepGI_-WXU,2549
 utilities/cachetools.py,sha256=2S9LMHIunDYMIu8JGI7OLN04sQ7-xZGdEdP1Li0vksA,2775
-utilities/click.py,sha256=-_B7V5arQopuVJA6emnwBlZGQvcnq7nq6IYc3cPX5FA,19204
+utilities/click.py,sha256=ScLzBLoBp8Si5YjgB18A0IVMAR-r4sGUnVfJbAaru98,19191
 utilities/concurrent.py,sha256=fHeW2SZ_TEMfFY0C8pyQI6aPlnecvx9x6SuUwBWj_JY,2853
 utilities/contextlib.py,sha256=iP7R2tIm6ZsbfLD5ks6UKBYwj50e9gBI8AkpLN-chro,7476
 utilities/contextvars.py,sha256=J8OhC7jqozAGYOCe2KUWysbPXNGe5JYz3HfaY_mIs08,883
 utilities/cryptography.py,sha256=5PFrzsNUGHay91dFgYnDKwYprXxahrBqztmUqViRzBk,956
 utilities/cvxpy.py,sha256=Rv1-fD-XYerosCavRF8Pohop2DBkU3AlFaGTfD8AEAA,13776
 utilities/dataclasses.py,sha256=xbU3QN1GFy7RC6hIJRZIeUZm7YRlodrgEWmahWG6k2g,32465
-utilities/docker.py,sha256=DBgSz-UPBDHk_XJLPNaNMkNym1kKK8l3Os8IqMwEyW8,7866
+utilities/docker.py,sha256=IOOdxAqfJfy1SXwy3e4VaAR9ag42W0HTcNcQz7DJPF8,10501
 utilities/enum.py,sha256=5l6pwZD1cjSlVW4ss-zBPspWvrbrYrdtJWcg6f5_J5w,5781
 utilities/errors.py,sha256=mFlDGSM0LI1jZ1pbqwLAH3ttLZ2JVIxyZLojw8tGVZU,1479
 utilities/fastapi.py,sha256=TqyKvBjiMS594sXPjrz-KRTLMb3l3D3rZ1zAYV7GfOk,1454
 utilities/fpdf2.py,sha256=dSiYz0FJTD2sQuxpxqFWwwIe2-p6Y7oTB9Tv0Jajit0,1866
-utilities/functions.py,sha256=82qCAaPIB0JmZ5wsQurA3MTYl7fh8LHcoBFkxPs7Zeg,21478
+utilities/functions.py,sha256=18Zda7nTloARdcEudH8YJ4e13xAdWShAGhPNN4w2Gyc,21498
 utilities/functools.py,sha256=I00ru2gQPakZw2SHVeKIKXfTv741655s6HI0lUoE0D4,1552
 utilities/getpass.py,sha256=DfN5UgMAtFCqS3dSfFHUfqIMZX2shXvwphOz_6J6f6A,103
 utilities/git.py,sha256=U1RFvCTANGENgx9wVBDvllioqBQZM2ns12ivKhOsaO4,414
@@ -25,8 +24,8 @@ utilities/grp.py,sha256=1vV3gNR9dQsl1vtUtvC_2qgVdQzm7O8lLMSh56cTbeg,694
 utilities/gzip.py,sha256=fkGP3KdsBfXlstodT4wtlp-PwNyUsogpbDCVVVGdsm4,781
 utilities/hashlib.py,sha256=SVTgtguur0P4elppvzOBbLEjVM3Pea0eWB61yg2ilxo,309
 utilities/http.py,sha256=TsavEfHlRtlLaeV21Z6KZh0qbPw-kvD1zsQdZ7Kep5Q,977
-utilities/hypothesis.py,sha256=wk1HiNdBg7tGPEKLZ5uiNVbtlSZl58QJjlediYoSHkA,46753
-utilities/importlib.py,sha256=mV1xT_O_zt_GnZZ36tl3xOmMaN_3jErDWY54fX39F6Y,429
+utilities/hypothesis.py,sha256=NUu30pl5kjL3tzo-m8SMRwTqLAmTWK-_Sau2NemJcQo,46773
+utilities/importlib.py,sha256=SkVVtIjVC7bjJ36doXnmnmFiYe5tLbip4YAfYJj8Ycg,892
 utilities/inflect.py,sha256=v7YkOWSu8NAmVghPcf4F3YBZQoJCS47_DLf9jbfWIs0,581
 utilities/ipython.py,sha256=V2oMYHvEKvlNBzxDXdLvKi48oUq2SclRg5xasjaXStw,763
 utilities/iterables.py,sha256=t2TsW-K3rVlS6y4_tqcc1fk9RwJV-bi7G_VwduMABK0,42558
@@ -46,11 +45,11 @@ utilities/optuna.py,sha256=C-fhWYiXHVPo1l8QctYkFJ4DyhbSrGorzP1dJb_qvd8,1933
 utilities/orjson.py,sha256=T_0SlK811ysg46d3orvIPY3JpBa4FRMpP2wlPQo7-gU,41854
 utilities/os.py,sha256=kjKKSQfnRqFTTZ315iavaaGd3gGuYNoSWlxVLCJjyQs,4852
 utilities/parse.py,sha256=g7Qm9eBOIeDId2tGA021CIaeF6jp1TI8rx4srdvlyoo,17937
-utilities/pathlib.py,sha256=EKZn-wWxH7MEWFrQGqHIoB-GJzyXeiEj8iDIgvkr8Wk,9325
-utilities/permissions.py,sha256=u-1PMJGC8PDbZltR4SozBuKKX5yIubmXPuiKrBx3IKU,8943
+utilities/pathlib.py,sha256=N4Ip8R9eCM-6GfvxUJ3T9oQIle2C2P52F-13BCFRdTg,9345
+utilities/permissions.py,sha256=vLXlWztSVYffbrxptne7ksj6dU1HLekm4fEvS4ny_4Q,8944
 utilities/pickle.py,sha256=MBT2xZCsv0pH868IXLGKnlcqNx2IRVKYNpRcqiQQqxw,653
-utilities/platform.py,sha256=0pYO5v7L2sU5UN87zHhEEhTKsZ9NIEM8N6UCr0F7bLY,2778
-utilities/polars.py,sha256=cNFBLWgOMUAp_Sz4xtlto17uZswZRrcfQYC95QKyaY4,87483
+utilities/platform.py,sha256=R3ldt2-DlI7la9ng6Rxt1CThd2lL0Ai2tC0TbabtCC0,2800
+utilities/polars.py,sha256=JPzN4UqQDC7R4IXsIuXEIXRiwHSrkiSZcD8UOfwGPuE,87535
 utilities/polars_ols.py,sha256=LNTFNLPuYW7fcAHymlbnams_DhitToblYvib3mhKbwI,5615
 utilities/postgres.py,sha256=g3tEwTI8TdmiCbRME61ffQ0xaibdpXPu8mJOOHvjPKc,12532
 utilities/pottery.py,sha256=nA0SsF9irvfC0tk68YAr08tuL9lGRSlBKihSx7Ibk84,3963
@@ -66,7 +65,7 @@ utilities/pytest.py,sha256=9HHwYgZQe6CRF0ekHQEFH05gmoP4Ne0V54RrtUNDfi4,10524
 utilities/pytest_plugins/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
 utilities/pytest_plugins/pytest_randomly.py,sha256=B1qYVlExGOxTywq2r1SMi5o7btHLk2PNdY_b1p98dkE,409
 utilities/pytest_plugins/pytest_regressions.py,sha256=mnHYBfdprz50UGVkVzV1bZERZN5CFfoF8YbokGxdFwU,1639
-utilities/pytest_regressions.py,sha256=nKdVZAa88_aMo1a8V-EIHg_smZYdk1iDQBm50R3FlO4,4044
+utilities/pytest_regressions.py,sha256=tJxW38u-zpoyjW1N4zogBx4V_07r-ibDInddcEUyXmc,4763
 utilities/random.py,sha256=hZlH4gnAtoaofWswuJYjcygejrY8db4CzP-z_adO2Mo,4165
 utilities/re.py,sha256=S4h-DLL6ScMPqjboZ_uQ1BVTJajrqV06r_81D--_HCE,4573
 utilities/redis.py,sha256=gybjqKea33Jy50n4dHTS14JdquqHaJqHF2dixQljYWQ,30172
@@ -81,8 +80,8 @@ utilities/sqlalchemy.py,sha256=HQYpd7LFxdTF5WYVWYtCJeEBI71EJm7ytvCGyAH9B-U,37163
 utilities/sqlalchemy_polars.py,sha256=JCGhB37raSR7fqeWV5dTsciRTMVzIdVT9YSqKT0piT0,13370
 utilities/statsmodels.py,sha256=koyiBHvpMcSiBfh99wFUfSggLNx7cuAw3rwyfAhoKpQ,3410
 utilities/string.py,sha256=shmBK87zZwzGyixuNuXCiUbqzfeZ9xlrFwz6JTaRvDk,582
-utilities/subprocess.py,sha256=dIBguvLB0WepJKqgBxlzF6r8z9HW5JiGKLg-eslpuec,22549
-utilities/tempfile.py,sha256=Lx6qa16lL1XVH6WdmD_G9vlN6gLI8nrIurxmsFkPKvg,3022
+utilities/subprocess.py,sha256=ei0OD73S0WX7ZqHCQp9UB3hY9OWbAUVIrLoz9niIfQQ,53031
+utilities/tempfile.py,sha256=a3_M1QyxGZql_VcGkBOQBeWbbkItjgkfIpVyzU1UAic,3843
 utilities/testbook.py,sha256=j1KmaVbrX9VrbeMgtPh5gk55myAsn3dyRUn7jGbPbRk,1294
 utilities/text.py,sha256=7SvwcSR2l_5cOrm1samGnR4C-ZI6qyFLHLzSpO1zeHQ,13958
 utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
@@ -98,7 +97,7 @@ utilities/warnings.py,sha256=un1LvHv70PU-LLv8RxPVmugTzDJkkGXRMZTE2-fTQHw,1771
 utilities/whenever.py,sha256=F4ek0-OBWxHYrZdmoZt76N2RnNyKY5KrEHt7rqO4AQE,60183
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=tdIScrTB2-B-LH0ukb1HUXKooLknOfJNwHk10MuMYvA,3619
-dycw_utilities-0.174.12.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
-dycw_utilities-0.174.12.dist-info/entry_points.txt,sha256=ykGI1ArwOPHqm2g5Cqh3ENdMxEej_a_FcOUov5EM5Oc,155
-dycw_utilities-0.174.12.dist-info/METADATA,sha256=Cf8kQqLOY8YDH8nG9Y7WcGf6xJFGxfDIMC1Amw13isc,1710
-dycw_utilities-0.174.12.dist-info/RECORD,,
+dycw_utilities-0.175.31.dist-info/WHEEL,sha256=RRVLqVugUmFOqBedBFAmA4bsgFcROUBiSUKlERi0Hcg,79
+dycw_utilities-0.175.31.dist-info/entry_points.txt,sha256=cOGtKeJI0KXLSV7MJ8Dhc2G8jPgDcBDm53MVNJU4ycI,136
+dycw_utilities-0.175.31.dist-info/METADATA,sha256=WX68a6sQoOamTeIZsrXvDdI_VKItf-Jm3Cam7p1jR_U,1443
+dycw_utilities-0.175.31.dist-info/RECORD,,

{dycw_utilities-0.174.12.dist-info → dycw_utilities-0.175.31.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.18
+Generator: uv 0.9.21
 Root-Is-Purelib: true
 Tag: py3-none-any

{dycw_utilities-0.174.12.dist-info → dycw_utilities-0.175.31.dist-info}/entry_points.txt

@@ -1,5 +1,3 @@
-[console_scripts]
-
 [pytest11]
 pytest-randomly = utilities.pytest_plugins.pytest_randomly
 pytest-regressions = utilities.pytest_plugins.pytest_regressions

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.174.12"
+__version__ = "0.175.31"

utilities/altair.py

@@ -145,7 +145,9 @@ def plot_dataframes(
     ]
     zoom = selection_interval(bind="scales", encodings=["x"])
     chart = (
-        vconcat(*layers).add_params(zoom).resolve_scale(color="independent", x="shared")
+        vconcat_charts(*layers)
+        .add_params(zoom)
+        .resolve_scale(color="independent", x="shared")
     )
     if title is not None:
         chart = chart.properties(title=title)

utilities/click.py

@@ -210,8 +210,7 @@ class EnumPartial[E: enum.Enum](ParamType):
             self.fail(str(error), param, ctx)
         if enum in self._members:
             return enum
-        self.fail(f"{enum.value!r} is not a selected member")
-        return None
+        return self.fail(f"{enum.value!r} is not a selected member")
 
     @override
     def get_metavar(self, param: Parameter, ctx: Context) -> str | None:

utilities/docker.py

@@ -5,6 +5,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Literal, overload
 
 from utilities.errors import ImpossibleCaseError
+from utilities.iterables import always_iterable
 from utilities.logging import to_logger
 from utilities.subprocess import (
     MKTEMP_DIR_CMD,
@@ -18,7 +19,87 @@ from utilities.subprocess import (
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
-    from utilities.types import LoggerLike, PathLike, Retry, StrStrMapping
+    from utilities.types import (
+        LoggerLike,
+        MaybeIterable,
+        PathLike,
+        Retry,
+        StrStrMapping,
+    )
+
+
+def docker_compose_down(
+    *,
+    files: MaybeIterable[PathLike] | None = None,
+    print: bool = False,  # noqa: A002
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+) -> None:
+    """Stop and remove containers."""
+    args = docker_compose_down_cmd(files=files)  # pragma: no cover
+    run(  # pragma: no cover
+        *args, print=print, print_stdout=print_stdout, print_stderr=print_stderr
+    )
+
+
+def docker_compose_down_cmd(
+    *, files: MaybeIterable[PathLike] | None = None
+) -> list[str]:
+    """Command to use 'docker compose down' to stop and remove containers."""
+    return _docker_compose_cmd("down", files=files)
+
+
+def docker_compose_pull(
+    *,
+    files: MaybeIterable[PathLike] | None = None,
+    print: bool = False,  # noqa: A002
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+) -> None:
+    """Pull service images."""
+    args = docker_compose_pull_cmd(files=files)  # pragma: no cover
+    run(  # pragma: no cover
+        *args, print=print, print_stdout=print_stdout, print_stderr=print_stderr
+    )
+
+
+def docker_compose_pull_cmd(
+    *, files: MaybeIterable[PathLike] | None = None
+) -> list[str]:
+    """Command to use 'docker compose pull' to pull service images."""
+    return _docker_compose_cmd("pull", files=files)
+
+
+def docker_compose_up(
+    *,
+    files: MaybeIterable[PathLike] | None = None,
+    print: bool = False,  # noqa: A002
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+) -> None:
+    """Create and start containers."""
+    args = docker_compose_up_cmd(files=files)  # pragma: no cover
+    run(  # pragma: no cover
+        *args, print=print, print_stdout=print_stdout, print_stderr=print_stderr
+    )
+
+
+def docker_compose_up_cmd(*, files: MaybeIterable[PathLike] | None = None) -> list[str]:
+    """Command to use 'docker compose up' to create and start containers."""
+    return _docker_compose_cmd("up", files=files)
+
+
+def _docker_compose_cmd(
+    cmd: str, /, *, files: MaybeIterable[PathLike] | None = None
+) -> list[str]:
+    args: list[str] = ["docker", "compose"]
+    if files is not None:
+        for file in always_iterable(files):
+            args.extend(["--file", str(file)])
+    return [*args, cmd]
+
+
+##
 
 
 @overload
@@ -47,48 +128,39 @@ def docker_cp(
     sudo: bool = False,
     logger: LoggerLike | None = None,
 ) -> None:
-    match src, dest:
+    """Copy between a container and the local file system."""
+    match src, dest:  # skipif-ci
         case Path() | str(), (str() as cont, Path() | str() as dest_path):
             docker_exec(
                 cont, *maybe_sudo_cmd(*mkdir_cmd(dest_path, parent=True), sudo=sudo)
             )
-            run(*docker_cp_cmd(src, dest, sudo=sudo), logger=logger)
+            run(*maybe_sudo_cmd(*docker_cp_cmd(src, dest), sudo=sudo), logger=logger)
         case (str(), Path() | str()), Path() | str():
             mkdir(dest, parent=True, sudo=sudo)
-            run(*docker_cp_cmd(src, dest, sudo=sudo), logger=logger)
+            run(*maybe_sudo_cmd(*docker_cp_cmd(src, dest), sudo=sudo), logger=logger)
         case _:  # pragma: no cover
             raise ImpossibleCaseError(case=[f"{src}", f"{dest=}"])
 
 
 @overload
-def docker_cp_cmd(
-    src: tuple[str, PathLike], dest: PathLike, /, *, sudo: bool = False
-) -> list[str]: ...
+def docker_cp_cmd(src: tuple[str, PathLike], dest: PathLike, /) -> list[str]: ...
 @overload
+def docker_cp_cmd(src: PathLike, dest: tuple[str, PathLike], /) -> list[str]: ...
 def docker_cp_cmd(
-    src: PathLike, dest: tuple[str, PathLike], /, *, sudo: bool = False
-) -> list[str]: ...
-def docker_cp_cmd(
-    src: PathLike | tuple[str, PathLike],
-    dest: PathLike | tuple[str, PathLike],
-    /,
-    *,
-    sudo: bool = False,
+    src: PathLike | tuple[str, PathLike], dest: PathLike | tuple[str, PathLike], /
 ) -> list[str]:
+    """Command to use 'docker cp' to copy between a container and the local file system."""
+    args: list[str] = ["docker", "cp"]
     match src, dest:
-        case (Path() | str()) as src_use, (
-            str() as dest_cont,
-            Path() | str() as dest_path,
-        ):
-            dest_use = f"{dest_cont}:{dest_path}"
-        case (str() as src_cont, (Path() | str()) as src_path), (
-            Path() | str() as dest_use
-        ):
-            src_use = f"{src_cont}:{src_path}"
+        case ((Path() | str()), (str() as cont, Path() | str() as path)):
+            return [*args, str(src), f"{cont}:{path}"]
+        case (str() as cont, (Path() | str()) as path), (Path() | str() as dest):
+            return [*args, f"{cont}:{path}", str(dest)]
         case _:  # pragma: no cover
             raise ImpossibleCaseError(case=[f"{src}", f"{dest=}"])
-    parts: list[str] = ["docker", "cp", str(src_use), str(dest_use)]
-    return maybe_sudo_cmd(*parts, sudo=sudo)
+
+
+##
 
 
 @overload
@@ -210,6 +282,7 @@ def docker_exec(
     logger: LoggerLike | None = None,
     **env_kwargs: str,
 ) -> str | None:
+    """Execute a command in a container."""
     cmd_and_args = docker_exec_cmd(  # skipif-ci
         container,
         cmd,
@@ -245,7 +318,7 @@ def docker_exec_cmd(
     workdir: PathLike | None = None,
     **env_kwargs: str,
 ) -> list[str]:
-    """Build a command for `docker exec`."""
+    """Command to use `docker exec` to execute a command in a container."""
     args: list[str] = ["docker", "exec"]
     mapping: dict[str, str] = ({} if env is None else dict(env)) | env_kwargs
     for key, value in mapping.items():
@@ -259,6 +332,9 @@ def docker_exec_cmd(
     return [*args, container, cmd, *cmds_or_args]
 
 
+##
+
+
 @contextmanager
 def yield_docker_temp_dir(
     container: str,
@@ -269,6 +345,7 @@ def yield_docker_temp_dir(
     logger: LoggerLike | None = None,
     keep: bool = False,
 ) -> Iterator[Path]:
+    """Yield a temporary directory in a Docker container."""
     path = Path(  # skipif-ci
         docker_exec(
             container,
@@ -289,4 +366,16 @@ def yield_docker_temp_dir(
             docker_exec(container, *rm_cmd(path), user=user, retry=retry, logger=logger)
 
 
-__all__ = ["docker_cp_cmd", "docker_exec", "docker_exec_cmd", "yield_docker_temp_dir"]
+__all__ = [
+    "docker_compose_down",
+    "docker_compose_down_cmd",
+    "docker_compose_pull",
+    "docker_compose_pull_cmd",
+    "docker_compose_up",
+    "docker_compose_up_cmd",
+    "docker_cp",
+    "docker_cp_cmd",
+    "docker_exec",
+    "docker_exec_cmd",
+    "yield_docker_temp_dir",
+]

utilities/functions.py

@@ -693,7 +693,7 @@ def second[U](pair: tuple[Any, U], /) -> U:
 
 def skip_if_optimize[**P](func: Callable[P, None], /) -> Callable[P, None]:
     """Skip a function if we are in the optimized mode."""
-    if __debug__:
+    if __debug__:  # pragma: no cover
         return func
 
     @wraps(func)

utilities/hypothesis.py

@@ -1040,7 +1040,7 @@ def setup_hypothesis_profiles(
                     assert_never(never)
 
     phases = {Phase.explicit, Phase.reuse, Phase.generate, Phase.target}
-    if "HYPOTHESIS_NO_SHRINK" not in environ:
+    if "HYPOTHESIS_NO_SHRINK" not in environ:  # pragma: no cover
         phases.add(Phase.shrink)
     for profile in Profile:
         try:

utilities/importlib.py

@@ -1,7 +1,23 @@
 from __future__ import annotations
 
+import importlib.resources
 from importlib import import_module
 from importlib.util import find_spec
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from utilities.errors import ImpossibleCaseError
+
+if TYPE_CHECKING:
+    from importlib.resources import Anchor
+
+
+def files(*, anchor: Anchor | None = None) -> Path:
+    """Get the path for an anchor."""
+    path = importlib.resources.files(anchor)
+    if isinstance(path, Path):
+        return path
+    raise ImpossibleCaseError(case=[f"{path=}"])  # pragma: no cover
 
 
 def is_valid_import(module: str, /, *, name: str | None = None) -> bool:
@@ -15,4 +31,4 @@ def is_valid_import(module: str, /, *, name: str | None = None) -> bool:
     return hasattr(mod, name)
 
 
-__all__ = ["is_valid_import"]
+__all__ = ["files", "is_valid_import"]

utilities/pathlib.py

@@ -127,7 +127,7 @@ class GetRepoRootError(Exception): ...
 class _GetRepoRootGitNotFoundError(GetRepoRootError):
     @override
     def __str__(self) -> str:
-        return "'git' not found"
+        return "'git' not found"  # pragma: no cover
 
 
 @dataclass(kw_only=True, slots=True)

utilities/permissions.py

@@ -25,6 +25,7 @@ from utilities.sentinel import Sentinel, sentinel
 if TYPE_CHECKING:
     from utilities.types import PathLike
 
+
 type PermissionsLike = Permissions | int | str
 
 

utilities/platform.py

@@ -16,7 +16,7 @@ System = Literal["windows", "mac", "linux"]
 def get_system() -> System:
     """Get the system/OS name."""
     sys = system()
-    if sys == "Windows":
+    if sys == "Windows":  # skipif-not-windows
         return "windows"
     if sys == "Darwin":  # skipif-not-macos
         return "mac"

utilities/polars.py

@@ -2639,6 +2639,8 @@ def search_period(
                 return None
             item: dt.datetime = series[index]["start"]
             return index if py_date_time > item else None
+        case never:
+            assert_never(never)
 
 
 ##

utilities/pytest_regressions.py

@@ -1,15 +1,17 @@
 from __future__ import annotations
 
 from contextlib import suppress
+from dataclasses import dataclass
 from json import loads
 from pathlib import Path
 from shutil import copytree
-from typing import TYPE_CHECKING, Any, assert_never
+from typing import TYPE_CHECKING, Any, assert_never, override
 
 from pytest_regressions.file_regression import FileRegressionFixture
 
 from utilities.functions import ensure_str
 from utilities.operator import is_equal
+from utilities.reprlib import get_repr
 
 if TYPE_CHECKING:
     from polars import DataFrame, Series
@@ -70,10 +72,28 @@ class OrjsonRegressionFixture:
             check_fn=self._check_fn,
         )
 
-    def _check_fn(self, path1: Path, path2: Path, /) -> None:
-        left = loads(path1.read_text())
-        right = loads(path2.read_text())
-        assert is_equal(left, right), f"{left=}, {right=}"
+    def _check_fn(self, path_obtained: Path, path_existing: Path, /) -> None:
+        obtained = loads(path_obtained.read_text())
+        existing = loads(path_existing.read_text())
+        if not is_equal(obtained, existing):
+            raise OrjsonRegressionError(
+                path_obtained=path_obtained,
+                path_existing=path_existing,
+                obtained=obtained,
+                existing=existing,
+            )
+
+
+@dataclass(kw_only=True, slots=True)
+class OrjsonRegressionError(Exception):
+    path_obtained: Path
+    path_existing: Path
+    obtained: Any
+    existing: Any
+
+    @override
+    def __str__(self) -> str:
+        return f"Obtained object (at {str(self.path_obtained)!r}) and existing object (at {str(self.path_existing)!r}) differ; got {get_repr(self.obtained)} and {get_repr(self.existing)}"
 
 
 ##