dycw-utilities 0.146.2__py3-none-any.whl → 0.178.1__py3-none-any.whl

dycw_utilities-0.178.1.dist-info/METADATA

@@ -0,0 +1,34 @@
+Metadata-Version: 2.3
+Name: dycw-utilities
+Version: 0.178.1
+Summary: Miscellaneous Python utilities
+Author: Derek Wan
+Author-email: Derek Wan <d.wan@icloud.com>
+Requires-Dist: atomicwrites>=1.4.1,<2
+Requires-Dist: typing-extensions>=4.15.0,<5
+Requires-Dist: tzlocal>=5.3.1,<6
+Requires-Dist: whenever>=0.9.4,<1
+Requires-Dist: coloredlogs>=15.0.1,<16 ; extra == 'logging'
+Requires-Dist: dycw-pytest-only>=2.1.1,<3 ; extra == 'test'
+Requires-Dist: hypothesis>=6.150.0,<7 ; extra == 'test'
+Requires-Dist: pytest>=9.0.2,<10 ; extra == 'test'
+Requires-Dist: pytest-asyncio>=1.3.0,<2 ; extra == 'test'
+Requires-Dist: pytest-cov>=7.0.0,<8 ; extra == 'test'
+Requires-Dist: pytest-instafail>=0.5.0,<1 ; extra == 'test'
+Requires-Dist: pytest-lazy-fixtures>=1.4.0,<2 ; extra == 'test'
+Requires-Dist: pytest-randomly>=4.0.1,<5 ; extra == 'test'
+Requires-Dist: pytest-regressions>=2.8.3,<3 ; extra == 'test'
+Requires-Dist: pytest-repeat>=0.9.4,<1 ; extra == 'test'
+Requires-Dist: pytest-rerunfailures>=16.1,<17 ; extra == 'test'
+Requires-Dist: pytest-rng>=1.0.0,<2 ; extra == 'test'
+Requires-Dist: pytest-timeout>=2.4.0,<3 ; extra == 'test'
+Requires-Dist: pytest-xdist>=3.8.0,<4 ; extra == 'test'
+Requires-Dist: testbook>=0.4.2,<1 ; extra == 'test'
+Requires-Python: >=3.12
+Provides-Extra: logging
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# `python-utilities`
+
+Miscellaneous Python utilities

dycw_utilities-0.178.1.dist-info/RECORD

@@ -0,0 +1,105 @@
+utilities/__init__.py,sha256=UPRGb4cG5FkpFHiF05BtsrvJN4xEBqAOklkZld8UbEc,60
+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=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=_cUgyU3207VH8e6IdQ88GNssvOVSkvEsUx95LiaayjY,10635
+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=18Zda7nTloARdcEudH8YJ4e13xAdWShAGhPNN4w2Gyc,21498
+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=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
+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/packaging.py,sha256=z_3v2ofEkqIMLhiEvP8zvQUaUFIqY6d-9XK_ZfsZTb0,3723
+utilities/parse.py,sha256=g7Qm9eBOIeDId2tGA021CIaeF6jp1TI8rx4srdvlyoo,17937
+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=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
+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=p8fjpiBuMUbaH0DnpM0j5BxnPLtH3uiMEkBKAjpM3Ss,6481
+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=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
+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=eGRRQF-OXDy2kMSy7dv4fUzcPizvRgGBxYvPh-QVqZo,53980
+utilities/tempfile.py,sha256=4kRGd4hyINDX4hpcYMtwzDcd-4IKjpTWT0MnjnKD4hE,4221
+utilities/testbook.py,sha256=dy9ID7GoFitMTCi4XBDTE4_mJm9uLTPyGgGrkJ1yuec,1304
+utilities/text.py,sha256=UKW6xtF4bb0i-Gu1jctJvvQmeXk6U6UYNqoEnCLdaOo,14102
+utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
+utilities/throttle.py,sha256=zVyqSdFGIAUQUj4dk-Zh8SFiuX0DUmRWMsn-qwSYk3g,4911
+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.178.1.dist-info/WHEEL,sha256=KSLUh82mDPEPk0Bx0ScXlWL64bc8KmzIPNcpQZFV-6E,79
+dycw_utilities-0.178.1.dist-info/entry_points.txt,sha256=cOGtKeJI0KXLSV7MJ8Dhc2G8jPgDcBDm53MVNJU4ycI,136
+dycw_utilities-0.178.1.dist-info/METADATA,sha256=Brf1aK3mbaluoqDK93fH9FVQ09bBfP6JDIx85DCRa0M,1398
+dycw_utilities-0.178.1.dist-info/RECORD,,

dycw_utilities-0.178.1.dist-info/WHEEL

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

{dycw_utilities-0.146.2.dist-info → dycw_utilities-0.178.1.dist-info}/entry_points.txt

@@ -1,3 +1,4 @@
 [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.146.2"
+__version__ = "0.178.1"

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,
@@ -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)
@@ -229,7 +231,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,20 +31,26 @@ from typing import (
     Self,
     TextIO,
     assert_never,
+    cast,
     overload,
     override,
 )
 
-from utilities.errors import ImpossibleCaseError
-from utilities.functions import ensure_int, ensure_not_none, to_bool
+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
 
 if TYPE_CHECKING:
     from asyncio import _CoroutineLike
     from asyncio.subprocess import Process
     from collections.abc import (
+        AsyncIterable,
         AsyncIterator,
         Callable,
         ItemsView,
@@ -56,15 +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,
-        MaybeCallableBool,
+        MaybeCallableBoolLike,
         MaybeType,
+        PathLike,
         SupportsKeysAndGetItem,
     )
 
@@ -222,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
 
@@ -233,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
@@ -266,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
@@ -303,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](
@@ -318,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)
         )
 
@@ -340,13 +349,43 @@ 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()
+    name = coro.__name__
+    with suppress_warnings(
+        message="coroutine '.*' was never awaited", category=RuntimeWarning
+    ):
+        del coro
+    return name
+
+
+##
+
+
 async def get_items[T](queue: Queue[T], /, *, max_size: int | None = None) -> list[T]:
     """Get items from a queue; if empty then wait."""
     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 []
@@ -376,27 +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]],
-    /,
-    *,
-    error: Callable[[Exception], None] | None = None,
-    sleep: Delta | None = None,
-) -> None:
-    """Repeatedly call a coroutine until it succeeds."""
-    while True:
-        try:
-            return await func()
-        except Exception as err:  # noqa: BLE001
-            if error is not None:
-                error(err)
-            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)
-            await sleep_td(sleep)
+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"
 
 
 ##
@@ -463,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()
     )
 
@@ -492,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
@@ -518,13 +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",
@@ -533,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)
 
 

utilities/atools.py

@@ -1,14 +1,17 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from functools import partial
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast, overload
 
-from atools import memoize
+import atools
+from whenever import TimeDelta
 
-from utilities.types import Coro
+from utilities.types import Coro, PathLike
 
 if TYPE_CHECKING:
-    from whenever import TimeDelta
+    from atools._memoize_decorator import Keygen, Pickler
 
 
 type _Key[**P, T] = tuple[Callable[P, Coro[T]], TimeDelta]
@@ -36,4 +39,61 @@ async def call_memoized[**P, T](
     return await memoized_func(*args, **kwargs)
 
 
+##
+
+
+@overload
+def memoize[F: Callable[..., Coro[Any]]](
+    func: F,
+    /,
+    *,
+    db_path: PathLike | None = None,
+    duration: float | TimeDelta | None = None,
+    keygen: Keygen | None = None,
+    pickler: Pickler | None = None,
+    size: int | None = None,
+) -> F: ...
+@overload
+def memoize[F: Callable[..., Coro[Any]]](
+    func: None = None,
+    /,
+    *,
+    db_path: PathLike | None = None,
+    duration: float | TimeDelta | None = None,
+    keygen: Keygen | None = None,
+    pickler: Pickler | None = None,
+    size: int | None = None,
+) -> Callable[[F], F]: ...
+def memoize[F: Callable[..., Coro[Any]]](
+    func: F | None = None,
+    /,
+    *,
+    db_path: PathLike | None = None,
+    duration: float | TimeDelta | None = None,
+    keygen: Keygen | None = None,
+    pickler: Pickler | None = None,
+    size: int | None = None,
+) -> F | Callable[[F], F]:
+    """Memoize a function."""
+    if func is None:
+        result = partial(
+            memoize,
+            db_path=db_path,
+            duration=duration,
+            keygen=keygen,
+            pickler=pickler,
+            size=size,
+        )
+        return cast("Callable[[F], F]", result)
+    return atools.memoize(
+        db_path=None if db_path is None else Path(db_path),
+        duration=duration.py_timedelta()
+        if isinstance(duration, TimeDelta)
+        else duration,
+        keygen=keygen,
+        pickler=pickler,
+        size=size,
+    )(func)
+
+
 __all__ = ["call_memoized"]

utilities/cachetools.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from collections.abc import Callable, Hashable, Iterable, Iterator, MutableSet
 from math import inf
 from time import monotonic
-from typing import TYPE_CHECKING, Any, override
+from typing import TYPE_CHECKING, Any, cast, override
 
 import cachetools
 from cachetools.func import ttl_cache
@@ -100,11 +100,14 @@ def cache[F: Callable](
     typed_: bool = False,
 ) -> Callable[[F], F]:
     """Decorate a function with `max_size` and/or `ttl` settings."""
-    return ttl_cache(
-        maxsize=inf if max_size is None else max_size,
-        ttl=inf if max_duration is None else max_duration.in_seconds(),
-        timer=timer,
-        typed=typed_,
+    return cast(
+        "F",
+        ttl_cache(
+            maxsize=max_size,
+            ttl=inf if max_duration is None else max_duration.in_seconds(),
+            timer=timer,
+            typed=typed_,
+        ),
     )