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

dycw_utilities-0.174.12.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.3
+Name: dycw-utilities
+Version: 0.174.12
+Author: Derek Wan
+Author-email: Derek Wan <d.wan@icloud.com>
+Requires-Dist: atomicwrites>=1.4.1,<1.5
+Requires-Dist: typing-extensions>=4.15.0,<4.16
+Requires-Dist: tzlocal>=5.3.1,<5.4
+Requires-Dist: whenever>=0.9.4,<0.10
+Requires-Dist: coloredlogs>=15.0.1,<15.1 ; extra == 'logging'
+Requires-Dist: dycw-pytest-only>=2.1.1,<2.2 ; extra == 'test'
+Requires-Dist: hypothesis>=6.148.8,<6.149 ; extra == 'test'
+Requires-Dist: pytest>=9.0.2,<9.1 ; extra == 'test'
+Requires-Dist: pytest-asyncio>=1.3.0,<1.4 ; extra == 'test'
+Requires-Dist: pytest-cov>=7.0.0,<7.1 ; extra == 'test'
+Requires-Dist: pytest-instafail>=0.5.0,<0.6 ; extra == 'test'
+Requires-Dist: pytest-lazy-fixtures>=1.4.0,<1.5 ; extra == 'test'
+Requires-Dist: pytest-randomly>=4.0.1,<4.1 ; extra == 'test'
+Requires-Dist: pytest-regressions>=2.8.3,<2.9 ; extra == 'test'
+Requires-Dist: pytest-repeat>=0.9.4,<0.10 ; extra == 'test'
+Requires-Dist: pytest-rerunfailures>=16.1,<16.2 ; extra == 'test'
+Requires-Dist: pytest-rng>=1.0.0,<1.1 ; extra == 'test'
+Requires-Dist: pytest-timeout>=2.4.0,<2.5 ; extra == 'test'
+Requires-Dist: pytest-xdist>=3.8.0,<3.9 ; extra == 'test'
+Requires-Dist: testbook>=0.4.2,<0.5 ; extra == 'test'
+Requires-Python: >=3.12
+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)
+
+# `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).

dycw_utilities-0.174.12.dist-info/RECORD

@@ -0,0 +1,104 @@
+utilities/__init__.py,sha256=VFU3kmpNxjyAnXuMdW-ygHCxl3CNmUA0rP-wy1y_uzg,61
+utilities/aeventkit.py,sha256=OmDBhYGgbsKrB7cdC5FFpJHUatX9O76eTeKVVTksp2Y,12673
+utilities/altair.py,sha256=rUK99g9x6CYDDfiZrf-aTx5fSRbL1Q8ctgKORowzXHg,9060
+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/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/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/functools.py,sha256=I00ru2gQPakZw2SHVeKIKXfTv741655s6HI0lUoE0D4,1552
+utilities/getpass.py,sha256=DfN5UgMAtFCqS3dSfFHUfqIMZX2shXvwphOz_6J6f6A,103
+utilities/git.py,sha256=U1RFvCTANGENgx9wVBDvllioqBQZM2ns12ivKhOsaO4,414
+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/inflect.py,sha256=v7YkOWSu8NAmVghPcf4F3YBZQoJCS47_DLf9jbfWIs0,581
+utilities/ipython.py,sha256=V2oMYHvEKvlNBzxDXdLvKi48oUq2SclRg5xasjaXStw,763
+utilities/iterables.py,sha256=t2TsW-K3rVlS6y4_tqcc1fk9RwJV-bi7G_VwduMABK0,42558
+utilities/jinja2.py,sha256=JpNHMcyMJDguX8rBN4wEz-v4En7w6WHXvYJr4Xw-F0o,4691
+utilities/json.py,sha256=-WcGtSsCr9Y42wHZzAMnfvU6ihAfVftylFfRUORaDFo,2102
+utilities/jupyter.py,sha256=ft5JA7fBxXKzP-L9W8f2-wbF0QeYc_2uLQNFDVk4Z-M,2917
+utilities/libcst.py,sha256=ngD4wxnR3Kh-RBVmU5l5ST7cuZLhMZwyMDjHZe5mhTs,5581
+utilities/lightweight_charts.py,sha256=YM3ojBvJxuCSUBu_KrhFBmaMCvRPvupKC3qkm-UVZq4,2751
+utilities/logging.py,sha256=mckcX_0Q5njVgnhtIoePcDHjYjTVELw7ExutiiDnzsU,18724
+utilities/math.py,sha256=cevB-YyEYAzJTWtkAr7qeeu-hbxorDI3gMznXlmNQkw,26897
+utilities/memory_profiler.py,sha256=XzN56jDCa5aqXS_DxEjb_K4L6aIWh_5zyKi6OhcIxw0,853
+utilities/modules.py,sha256=iuvLluJya-hvl1Q25-Jk3dLgx2Es3ck4SjJiEkAlVTs,3195
+utilities/more_itertools.py,sha256=syfIPhQF_WS-YiicdGe2h5F1G-Ld12Q2XsVduL2hA40,10908
+utilities/numpy.py,sha256=Xn23sA2ZbVNqwUYEgNJD3XBYH6IbCri_WkHSNhg3NkY,26122
+utilities/operator.py,sha256=C3NylZWGTVWRpwYHOPVhaLgRhw0DfpS4_XQ8KfPhBLQ,3613
+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/pickle.py,sha256=MBT2xZCsv0pH868IXLGKnlcqNx2IRVKYNpRcqiQQqxw,653
+utilities/platform.py,sha256=0pYO5v7L2sU5UN87zHhEEhTKsZ9NIEM8N6UCr0F7bLY,2778
+utilities/polars.py,sha256=cNFBLWgOMUAp_Sz4xtlto17uZswZRrcfQYC95QKyaY4,87483
+utilities/polars_ols.py,sha256=LNTFNLPuYW7fcAHymlbnams_DhitToblYvib3mhKbwI,5615
+utilities/postgres.py,sha256=g3tEwTI8TdmiCbRME61ffQ0xaibdpXPu8mJOOHvjPKc,12532
+utilities/pottery.py,sha256=nA0SsF9irvfC0tk68YAr08tuL9lGRSlBKihSx7Ibk84,3963
+utilities/pqdm.py,sha256=idv2seRVP2f6NeSfpeEnT5A-tQezaHZKDyeu16g2-0E,3091
+utilities/psutil.py,sha256=KUlu4lrUw9Zg1V7ZGetpWpGb9DB8l_SSDWGbANFNCPU,2104
+utilities/pwd.py,sha256=pzlLkBfSTZsCVkMrAxEmuEoNmm-6goklfAygVmOEZqs,707
+utilities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+utilities/pydantic.py,sha256=z_PnYXN_UNNLQwo_XF7cr4GDcf5wicvscD6aFYVOEvA,238
+utilities/pydantic_settings.py,sha256=53tQTpHFtA6UIuzHKzauZtW_bSRwL5lQnNwTWeO4Fjw,7608
+utilities/pydantic_settings_sops.py,sha256=9Ou6Cx6PiYOU49vtkKqqW1Sdp_i3WlVyg8KkUUKNliM,2310
+utilities/pyinstrument.py,sha256=hnXaL-4HE7wWBI5JKaPfYTpsrXe68YiuZKahHV0VJn8,841
+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/random.py,sha256=hZlH4gnAtoaofWswuJYjcygejrY8db4CzP-z_adO2Mo,4165
+utilities/re.py,sha256=S4h-DLL6ScMPqjboZ_uQ1BVTJajrqV06r_81D--_HCE,4573
+utilities/redis.py,sha256=gybjqKea33Jy50n4dHTS14JdquqHaJqHF2dixQljYWQ,30172
+utilities/reprlib.py,sha256=ssYTcBW-TeRh3fhCJv57sopTZHF5FrPyyUg9yp5XBlo,3953
+utilities/scipy.py,sha256=wZJM7fEgBAkLSYYvSmsg5ac-QuwAI0BGqHVetw1_Hb0,947
+utilities/sentinel.py,sha256=A_p5jX2K0Yc5XBfoYHyBLqHsEWzE1ByOdDuzzA2pZnE,1434
+utilities/shelve.py,sha256=4OzjQI6kGuUbJciqf535rwnao-_IBv66gsT6tRGiUt0,759
+utilities/shutil.py,sha256=knJ7hx42FtIfGByxQZMcOSgQCDlaSony325g505ps3A,480
+utilities/slack_sdk.py,sha256=76-DYtcGiUhEvl-voMamc5OjfF7Y7nCq54Bys1arqzw,2233
+utilities/socket.py,sha256=K77vfREvzoVTrpYKo6MZakol0EYu2q1sWJnnZqL0So0,118
+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/testbook.py,sha256=j1KmaVbrX9VrbeMgtPh5gk55myAsn3dyRUn7jGbPbRk,1294
+utilities/text.py,sha256=7SvwcSR2l_5cOrm1samGnR4C-ZI6qyFLHLzSpO1zeHQ,13958
+utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
+utilities/timer.py,sha256=BGlwEVznx67scuLOUohyWJ4d5rTnwtk-IR4yLXFiNfo,2574
+utilities/traceback.py,sha256=B_sc0TRUv-mGDnF-ek05nbqjmBiHr3-wvxliAqIF5hI,9608
+utilities/types.py,sha256=UwxYajRnupKTCnzReaYWYqtKdpIPeSO-d97Wu4bLEq8,18878
+utilities/typing.py,sha256=xuR8LxzjD-XlSftTM3TNvGVdQyV1mzpdwWdDMzWwCPE,25310
+utilities/tzdata.py,sha256=fgNVj66yUbCSI_-vrRVzSD3gtf-L_8IEJEPjP_Jel5Y,266
+utilities/tzlocal.py,sha256=KyCXEgCTjqGFx-389JdTuhMRUaT06U1RCMdWoED-qro,728
+utilities/uuid.py,sha256=nQZs6tFX4mqtc2Ku3KqjloYCqwpTKeTj8eKwQwh3FQI,1572
+utilities/version.py,sha256=ipBj5-WYY_nelp2uwFlApfWWCzTLzPwpovUi9x_OBMs,5085
+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.174.12.dist-info/WHEEL

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

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

@@ -1,3 +1,6 @@
+[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.148.5"
+__version__ = "0.174.12"

utilities/{eventkit.py → aeventkit.py}

@@ -29,12 +29,12 @@ from eventkit import (
 
 from utilities.functions import apply_decorators
 from utilities.iterables import always_iterable
-from utilities.logging import get_logger
+from utilities.logging import to_logger
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    from utilities.types import Coro, LoggerOrName, MaybeCoro, MaybeIterable, TypeLike
+    from utilities.types import Coro, LoggerLike, MaybeCoro, MaybeIterable, TypeLike
 
 
 ##
@@ -47,7 +47,7 @@ def add_listener[E: Event, F: Callable](
     *,
     error: Callable[[Event, BaseException], MaybeCoro[None]] | None = None,
     ignore: TypeLike[BaseException] | None = None,
-    logger: LoggerOrName | None = None,
+    logger: LoggerLike | None = None,
     decorators: MaybeIterable[Callable[[F], F]] | None = None,
     done: Callable[..., MaybeCoro[None]] | None = None,
     keep_ref: bool = False,
@@ -92,7 +92,7 @@ class LiftedEvent[F: Callable[..., MaybeCoro[None]]]:
         *,
         error: Callable[[Event, BaseException], MaybeCoro[None]] | None = None,
         ignore: TypeLike[BaseException] | None = None,
-        logger: LoggerOrName | None = None,
+        logger: LoggerLike | None = None,
         decorators: MaybeIterable[Callable[[F2], F2]] | None = None,
         done: Callable[..., MaybeCoro[None]] | None = None,
         keep_ref: bool = False,
@@ -169,7 +169,8 @@ class LiftedEvent[F: Callable[..., MaybeCoro[None]]]:
     def __await__(self) -> Any:
         return self.event.__await__()  # pragma: no cover
 
-    __aiter__ = aiter
+    def __aiter__(self) -> Any:
+        return self.event.aiter()  # pragma: no cover
 
     def __contains__(self, c: Any, /) -> bool:
         return self.event.__contains__(c)  # pragma: no cover
@@ -255,7 +256,7 @@ class TypedEvent[F: Callable[..., MaybeCoro[None]]](Event):
         keep_ref: bool = False,
         *,
         ignore: TypeLike[BaseException] | None = None,
-        logger: LoggerOrName | None = None,
+        logger: LoggerLike | None = None,
         decorators: MaybeIterable[Callable[[F2], F2]] | None = None,
     ) -> Self:
         lifted = lift_listener(
@@ -283,7 +284,7 @@ def lift_listener[F1: Callable[..., MaybeCoro[None]], F2: Callable](
     *,
     error: Callable[[Event, BaseException], MaybeCoro[None]] | None = None,
     ignore: TypeLike[BaseException] | None = None,
-    logger: LoggerOrName | None = None,
+    logger: LoggerLike | None = None,
     decorators: MaybeIterable[Callable[[F2], F2]] | None = None,
 ) -> F1:
     match error, bool(iscoroutinefunction(listener)):
@@ -297,7 +298,7 @@ def lift_listener[F1: Callable[..., MaybeCoro[None]], F2: Callable](
                 except Exception as exc:  # noqa: BLE001
                     if (ignore is not None) and isinstance(exc, ignore):
                         return
-                    get_logger(logger=logger).exception("")
+                    to_logger(logger).exception("")
 
             lifted = listener_no_error_sync
 
@@ -311,7 +312,7 @@ def lift_listener[F1: Callable[..., MaybeCoro[None]], F2: Callable](
                 except Exception as exc:  # noqa: BLE001
                     if (ignore is not None) and isinstance(exc, ignore):
                         return
-                    get_logger(logger=logger).exception("")
+                    to_logger(logger).exception("")
 
             lifted = listener_no_error_async
         case _, _:
@@ -359,9 +360,9 @@ def lift_listener[F1: Callable[..., MaybeCoro[None]], F2: Callable](
                             error_typed(event, exc)
 
                     lifted = listener_have_error_async
-                case _ as never:
+                case never:
                     assert_never(never)
-        case _ as never:
+        case never:
             assert_never(never)
 
     if decorators is not None:

utilities/altair.py

@@ -29,8 +29,6 @@ from utilities.iterables import always_iterable
 from utilities.tempfile import TemporaryDirectory
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
-
     from polars import DataFrame
 
     from utilities.types import PathLike
@@ -43,7 +41,7 @@ _WIDTH = 800
 
 @dataclass(kw_only=True, slots=True)
 class _PlotDataFramesSpec:
-    y: Sequence[str]
+    y: list[str]
     height: int = _HEIGHT
 
 
@@ -96,7 +94,8 @@ def plot_dataframes(
     # lines
     selection = selection_point(bind="legend", fields=[var_name], nearest=False)
     lines = [
-        chart.mark_line(interpolate=interpolate)
+        chart
+        .mark_line(interpolate=interpolate)
         .encode(
             x=x_use,
             y=Y(value_name).scale(zero=False),
@@ -126,7 +125,8 @@ def plot_dataframes(
     else:
         tooltip_format_use = Undefined
     rules = [
-        chart.transform_pivot(var_name, value=value_name, groupby=[x_use])
+        chart
+        .transform_pivot(var_name, value=value_name, groupby=[x_use])
         .mark_rule(color="gray")
         .encode(
             x=x_use,
@@ -229,7 +229,8 @@ def plot_intraday_dataframe(
     )
 
     data4 = (
-        data3.group_by("_date_index")
+        data3
+        .group_by("_date_index")
         .agg(
             col(f"_{datetime}_index").min().alias(f"{datetime}_index_min"),
             (col(f"_{datetime}_index").max() + 1).alias(f"{datetime}_index_max"),

utilities/asyncio.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import asyncio
-import sys
 from asyncio import (
     Lock,
     Queue,
@@ -22,6 +21,7 @@ from contextlib import (
 )
 from dataclasses import dataclass
 from io import StringIO
+from pathlib import Path
 from subprocess import PIPE
 from sys import stderr, stdout
 from typing import (
@@ -31,15 +31,18 @@ from typing import (
     Self,
     TextIO,
     assert_never,
+    cast,
     overload,
     override,
 )
 
-from utilities.errors import ImpossibleCaseError, is_instance_error
-from utilities.functions import ensure_int, ensure_not_none, to_bool
-from utilities.logging import get_logger
+from utilities.functions import ensure_int, ensure_not_none
+from utilities.os import is_pytest
 from utilities.random import SYSTEM_RANDOM
+from utilities.reprlib import get_repr
 from utilities.sentinel import Sentinel, sentinel
+from utilities.shelve import yield_shelf
+from utilities.text import to_bool
 from utilities.warnings import suppress_warnings
 from utilities.whenever import get_now, round_date_or_date_time, to_nanoseconds
 
@@ -47,6 +50,7 @@ if TYPE_CHECKING:
     from asyncio import _CoroutineLike
     from asyncio.subprocess import Process
     from collections.abc import (
+        AsyncIterable,
         AsyncIterator,
         Callable,
         ItemsView,
@@ -58,17 +62,18 @@ if TYPE_CHECKING:
     )
     from contextvars import Context
     from random import Random
+    from shelve import Shelf
     from types import TracebackType
 
     from whenever import ZonedDateTime
 
+    from utilities.shelve import _Flag
     from utilities.types import (
         Coro,
         Delta,
-        ExceptionTypeLike,
-        LoggerOrName,
-        MaybeCallableBool,
+        MaybeCallableBoolLike,
         MaybeType,
+        PathLike,
         SupportsKeysAndGetItem,
     )
 
@@ -226,7 +231,7 @@ class EnhancedTaskGroup(TaskGroup):
     _semaphore: Semaphore | None
     _timeout: Delta | None
     _error: MaybeType[BaseException]
-    _debug: MaybeCallableBool
+    _debug: MaybeCallableBoolLike
     _stack: AsyncExitStack
     _timeout_cm: _AsyncGeneratorContextManager[None] | None
 
@@ -237,7 +242,7 @@ class EnhancedTaskGroup(TaskGroup):
         max_tasks: int | None = None,
         timeout: Delta | None = None,
         error: MaybeType[BaseException] = TimeoutError,
-        debug: MaybeCallableBool = False,
+        debug: MaybeCallableBoolLike = False,
     ) -> None:
         super().__init__()
         self._max_tasks = max_tasks
@@ -270,7 +275,7 @@ class EnhancedTaskGroup(TaskGroup):
                     _ = await super().__aexit__(et, exc, tb)
             case False:
                 _ = await super().__aexit__(et, exc, tb)
-            case _ as never:
+            case never:
                 assert_never(never)
 
     @override
@@ -307,7 +312,7 @@ class EnhancedTaskGroup(TaskGroup):
                     self.create_task(make_coro(*args, **kwargs))
                     for _ in range(self._max_tasks)
                 ]
-            case _ as never:
+            case never:
                 assert_never(never)
 
     async def run_or_create_task[T](
@@ -322,11 +327,11 @@ class EnhancedTaskGroup(TaskGroup):
                 return await coro
             case False:
                 return self.create_task(coro, name=name, context=context)
-            case _ as never:
+            case never:
                 assert_never(never)
 
     def _is_debug(self) -> bool:
-        return to_bool(bool_=self._debug) or (
+        return to_bool(self._debug) or (
             (self._max_tasks is not None) and (self._max_tasks <= 0)
         )
 
@@ -344,6 +349,24 @@ class EnhancedTaskGroup(TaskGroup):
 ##
 
 
+def chain_async[T](*iterables: Iterable[T] | AsyncIterable[T]) -> AsyncIterator[T]:
+    """Asynchronous version of `chain`."""
+
+    async def iterator() -> AsyncIterator[T]:
+        for it in iterables:
+            try:
+                async for item in cast("AsyncIterable[T]", it):
+                    yield item
+            except TypeError:
+                for item in cast("Iterable[T]", it):
+                    yield item
+
+    return iterator()
+
+
+##
+
+
 def get_coroutine_name(func: Callable[[], Coro[Any]], /) -> str:
     """Get the name of a coroutine, and then dispose of it gracefully."""
     coro = func()
@@ -363,8 +386,6 @@ async def get_items[T](queue: Queue[T], /, *, max_size: int | None = None) -> li
     try:
         items = [await queue.get()]
     except RuntimeError as error:  # pragma: no cover
-        from utilities.pytest import is_pytest
-
         if (not is_pytest()) or (error.args[0] != "Event loop is closed"):
             raise
         return []
@@ -394,38 +415,38 @@ def get_items_nowait[T](queue: Queue[T], /, *, max_size: int | None = None) -> l
 ##
 
 
-async def loop_until_succeed(
-    func: Callable[[], Coro[None]],
-    /,
-    *,
-    logger: LoggerOrName | None = None,
-    errors: ExceptionTypeLike[Exception] | None = None,
-    sleep: Delta | None = None,
-) -> bool:
-    """Repeatedly call a coroutine until it succeeds."""
-    name = get_coroutine_name(func)
-    while True:
-        try:
-            await func()
-        except Exception as error:  # noqa: BLE001
-            if logger is not None:
-                get_logger(logger=logger).error("Error running %r", name, exc_info=True)
-            exc_type, exc_value, traceback = sys.exc_info()
-            if (exc_type is None) or (exc_value is None):  # pragma: no cover
-                raise ImpossibleCaseError(
-                    case=[f"{exc_type=}", f"{exc_value=}"]
-                ) from None
-            sys.excepthook(exc_type, exc_value, traceback)
-            if (errors is not None) and is_instance_error(error, errors):
-                return False
-            if sleep is not None:
-                if logger is not None:
-                    get_logger(logger=logger).info("Sleeping for %s...", sleep)
-                await sleep_td(sleep)
-            if logger is not None:
-                get_logger(logger=logger).info("Retrying %r...", name)
-        else:
-            return True
+async def one_async[T](*iterables: Iterable[T] | AsyncIterable[T]) -> T:
+    """Asynchronous version of `one`."""
+    result: T | Sentinel = sentinel
+    async for item in chain_async(*iterables):
+        if not isinstance(result, Sentinel):
+            raise OneAsyncNonUniqueError(iterables=iterables, first=result, second=item)
+        result = item
+    if isinstance(result, Sentinel):
+        raise OneAsyncEmptyError(iterables=iterables)
+    return result
+
+
+@dataclass(kw_only=True, slots=True)
+class OneAsyncError[T](Exception):
+    iterables: tuple[Iterable[T] | AsyncIterable[T], ...]
+
+
+@dataclass(kw_only=True, slots=True)
+class OneAsyncEmptyError[T](OneAsyncError[T]):
+    @override
+    def __str__(self) -> str:
+        return f"Iterable(s) {get_repr(self.iterables)} must not be empty"
+
+
+@dataclass(kw_only=True, slots=True)
+class OneAsyncNonUniqueError[T](OneAsyncError):
+    first: T
+    second: T
+
+    @override
+    def __str__(self) -> str:
+        return f"Iterable(s) {get_repr(self.iterables)} must contain exactly one item; got {self.first}, {self.second} and perhaps more"
 
 
 ##
@@ -492,27 +513,21 @@ class StreamCommandOutput:
 
     @property
     def return_code(self) -> int:
-        return ensure_int(self.process.returncode)  # skipif-not-windows
+        return ensure_int(self.process.returncode)
 
 
 async def stream_command(cmd: str, /) -> StreamCommandOutput:
     """Run a shell command asynchronously and stream its output in real time."""
-    process = await create_subprocess_shell(  # skipif-not-windows
-        cmd, stdout=PIPE, stderr=PIPE
-    )
-    proc_stdout = ensure_not_none(  # skipif-not-windows
-        process.stdout, desc="process.stdout"
-    )
-    proc_stderr = ensure_not_none(  # skipif-not-windows
-        process.stderr, desc="process.stderr"
-    )
-    ret_stdout = StringIO()  # skipif-not-windows
-    ret_stderr = StringIO()  # skipif-not-windows
-    async with TaskGroup() as tg:  # skipif-not-windows
+    process = await create_subprocess_shell(cmd, stdout=PIPE, stderr=PIPE)
+    proc_stdout = ensure_not_none(process.stdout, desc="process.stdout")
+    proc_stderr = ensure_not_none(process.stderr, desc="process.stderr")
+    ret_stdout = StringIO()
+    ret_stderr = StringIO()
+    async with TaskGroup() as tg:
         _ = tg.create_task(_stream_one(proc_stdout, stdout, ret_stdout))
         _ = tg.create_task(_stream_one(proc_stderr, stderr, ret_stderr))
-    _ = await process.wait()  # skipif-not-windows
-    return StreamCommandOutput(  # skipif-not-windows
+    _ = await process.wait()
+    return StreamCommandOutput(
         process=process, stdout=ret_stdout.getvalue(), stderr=ret_stderr.getvalue()
     )
 
@@ -521,7 +536,7 @@ async def _stream_one(
     input_: StreamReader, out_stream: TextIO, ret_stream: StringIO, /
 ) -> None:
     """Asynchronously read from a stream and write to the target output stream."""
-    while True:  # skipif-not-windows
+    while True:
         line = await input_.readline()
         if not line:
             break
@@ -547,14 +562,47 @@ async def timeout_td(
         raise error from None
 
 
+##
+
+
+_LOCKS: AsyncDict[Path, Lock] = AsyncDict()
+
+
+@asynccontextmanager
+async def yield_locked_shelf(
+    path: PathLike,
+    /,
+    *,
+    flag: _Flag = "c",
+    protocol: int | None = None,
+    writeback: bool = False,
+) -> AsyncIterator[Shelf[Any]]:
+    """Yield a shelf, behind a lock."""
+    path = Path(path)
+    try:
+        lock = _LOCKS[path]
+    except KeyError:
+        lock = Lock()
+        await _LOCKS.set(path, lock)
+    async with lock:
+        with yield_shelf(
+            path, flag=flag, protocol=protocol, writeback=writeback
+        ) as shelf:
+            yield shelf
+
+
 __all__ = [
     "AsyncDict",
     "EnhancedTaskGroup",
+    "OneAsyncEmptyError",
+    "OneAsyncError",
+    "OneAsyncNonUniqueError",
     "StreamCommandOutput",
+    "chain_async",
     "get_coroutine_name",
     "get_items",
     "get_items_nowait",
-    "loop_until_succeed",
+    "one_async",
     "put_items",
     "put_items_nowait",
     "sleep_max",
@@ -563,4 +611,5 @@ __all__ = [
     "sleep_until",
     "stream_command",
     "timeout_td",
+    "yield_locked_shelf",
 ]

utilities/atomicwrites.py

@@ -57,7 +57,7 @@ def move(
             raise ImpossibleCaseError(
                 case=[f"{source.is_file()=}", f"{source.is_dir()=}"]
             )
-        case _ as never:
+        case never:
             assert_never(never)