dycw-utilities 0.175.17__py3-none-any.whl → 0.185.8__py3-none-any.whl

utilities/reprlib.py

@@ -1,117 +1,22 @@
 from __future__ import annotations
 
-import reprlib
 from functools import partial
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
+
+from utilities.constants import (
+    RICH_EXPAND_ALL,
+    RICH_INDENT_SIZE,
+    RICH_MAX_DEPTH,
+    RICH_MAX_LENGTH,
+    RICH_MAX_STRING,
+    RICH_MAX_WIDTH,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
     from utilities.types import StrMapping
 
-RICH_MAX_WIDTH: int = 80
-RICH_INDENT_SIZE: int = 4
-RICH_MAX_LENGTH: int | None = 20
-RICH_MAX_STRING: int | None = None
-RICH_MAX_DEPTH: int | None = None
-RICH_EXPAND_ALL: bool = False
-
-
-##
-
-
-def get_call_args_mapping(*args: Any, **kwargs: Any) -> StrMapping:
-    """Get the representation of a set of call arguments."""
-    return {f"args[{i}]": v for i, v in enumerate(args)} | {
-        f"kwargs[{k}]": v for k, v in kwargs.items()
-    }
-
-
-##
-
-
-def get_repr(
-    obj: Any,
-    /,
-    *,
-    max_width: int = RICH_MAX_WIDTH,
-    indent_size: int = RICH_INDENT_SIZE,
-    max_length: int | None = RICH_MAX_LENGTH,
-    max_string: int | None = RICH_MAX_STRING,
-    max_depth: int | None = RICH_MAX_DEPTH,
-    expand_all: bool = RICH_EXPAND_ALL,
-) -> str:
-    """Get the representation of an object."""
-    try:
-        from rich.pretty import pretty_repr
-    except ModuleNotFoundError:  # pragma: no cover
-        return reprlib.repr(obj)
-    return pretty_repr(
-        obj,
-        max_width=max_width,
-        indent_size=indent_size,
-        max_length=max_length,
-        max_string=max_string,
-        max_depth=max_depth,
-        expand_all=expand_all,
-    )
-
-
-##
-
-
-def get_repr_and_class(
-    obj: Any,
-    /,
-    *,
-    max_width: int = RICH_MAX_WIDTH,
-    indent_size: int = RICH_INDENT_SIZE,
-    max_length: int | None = RICH_MAX_LENGTH,
-    max_string: int | None = RICH_MAX_STRING,
-    max_depth: int | None = RICH_MAX_DEPTH,
-    expand_all: bool = RICH_EXPAND_ALL,
-) -> str:
-    """Get the `reprlib`-representation & class of an object."""
-    repr_use = get_repr(
-        obj,
-        max_width=max_width,
-        indent_size=indent_size,
-        max_length=max_length,
-        max_string=max_string,
-        max_depth=max_depth,
-        expand_all=expand_all,
-    )
-    return f"Object {repr_use!r} of type {type(obj).__name__!r}"
-
-
-##
-
-
-def yield_call_args_repr(
-    *args: Any,
-    _max_width: int = RICH_MAX_WIDTH,
-    _indent_size: int = RICH_INDENT_SIZE,
-    _max_length: int | None = RICH_MAX_LENGTH,
-    _max_string: int | None = RICH_MAX_STRING,
-    _max_depth: int | None = RICH_MAX_DEPTH,
-    _expand_all: bool = RICH_EXPAND_ALL,
-    **kwargs: Any,
-) -> Iterator[str]:
-    """Pretty print of a set of positional/keyword arguments."""
-    mapping = get_call_args_mapping(*args, **kwargs)
-    return yield_mapping_repr(
-        mapping,
-        _max_width=_max_width,
-        _indent_size=_indent_size,
-        _max_length=_max_length,
-        _max_string=_max_string,
-        _max_depth=_max_depth,
-        _expand_all=_expand_all,
-    )
-
-
-##
-
 
 def yield_mapping_repr(
     mapping: StrMapping,
@@ -143,16 +48,4 @@ def yield_mapping_repr(
         yield f"{k} = {repr_use(v)}"
 
 
-__all__ = [
-    "RICH_EXPAND_ALL",
-    "RICH_INDENT_SIZE",
-    "RICH_MAX_DEPTH",
-    "RICH_MAX_LENGTH",
-    "RICH_MAX_STRING",
-    "RICH_MAX_WIDTH",
-    "get_call_args_mapping",
-    "get_repr",
-    "get_repr_and_class",
-    "yield_call_args_repr",
-    "yield_mapping_repr",
-]
+__all__ = ["yield_mapping_repr"]

utilities/shellingham.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from os import environ, name
+from pathlib import Path
+from typing import Literal, override
+
+from shellingham import ShellDetectionFailure, detect_shell
+
+from utilities.core import OneEmptyError, one, repr_
+from utilities.typing import get_args
+
+type Shell = Literal["bash", "fish", "posix", "sh", "zsh"]
+
+
+def get_shell() -> Shell:
+    """Get the shell."""
+    try:
+        shell, _ = detect_shell()
+    except ShellDetectionFailure:  # pragma: no cover
+        if name == "posix":
+            shell = environ["SHELL"]
+        elif name == "nt":
+            shell = environ["COMSPEC"]
+        else:
+            raise _GetShellOSError(name=name) from None
+    shells: tuple[Shell, ...] = get_args(Shell)
+    matches: list[Shell] = [s for s in shells if _get_shell_match(shell, s)]
+    try:
+        return one(matches)
+    except OneEmptyError:  # pragma: no cover
+        raise _GetShellUnsupportedError(shell=shell) from None
+
+
+def _get_shell_match(shell: str, candidate: Shell, /) -> bool:
+    *_, name = Path(shell).parts
+    return name == candidate
+
+
+@dataclass(kw_only=True, slots=True)
+class GetShellError(Exception):
+    name: str
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetShellUnsupportedError(Exception):
+    shell: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid shell; got {repr_(self.shell)}"  # pragma: no cover
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetShellOSError(GetShellError):
+    name: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid OS; got {repr_(self.name)}"  # pragma: no cover
+
+
+SHELL = get_shell()
+
+
+__all__ = ["SHELL", "GetShellError", "get_shell"]

utilities/slack_sdk.py

@@ -7,24 +7,25 @@ from typing import TYPE_CHECKING, override
 from slack_sdk.webhook import WebhookClient
 from slack_sdk.webhook.async_client import AsyncWebhookClient
 
-from utilities.asyncio import timeout_td
+import utilities.asyncio
+from utilities.constants import MINUTE
+from utilities.functions import in_seconds
 from utilities.functools import cache
-from utilities.whenever import MINUTE, to_seconds
+from utilities.math import safe_round
 
 if TYPE_CHECKING:
     from slack_sdk.webhook import WebhookResponse
-    from whenever import TimeDelta
 
-    from utilities.types import Delta, MaybeType
+    from utilities.types import Duration, MaybeType
 
 
-_TIMEOUT: Delta = MINUTE
+_TIMEOUT: Duration = MINUTE
 
 
 ##
 
 
-def send_to_slack(url: str, text: str, /, *, timeout: TimeDelta = _TIMEOUT) -> None:
+def send_to_slack(url: str, text: str, /, *, timeout: Duration = _TIMEOUT) -> None:
     """Send a message via Slack synchronously."""
     client = _get_client(url, timeout=timeout)
     response = client.send(text=text)
@@ -33,9 +34,9 @@ def send_to_slack(url: str, text: str, /, *, timeout: TimeDelta = _TIMEOUT) -> N
 
 
 @cache
-def _get_client(url: str, /, *, timeout: Delta = _TIMEOUT) -> WebhookClient:
+def _get_client(url: str, /, *, timeout: Duration = _TIMEOUT) -> WebhookClient:
     """Get the Slack client."""
-    return WebhookClient(url, timeout=to_seconds(timeout))
+    return WebhookClient(url, timeout=safe_round(in_seconds(timeout)))
 
 
 async def send_to_slack_async(
@@ -43,12 +44,12 @@ async def send_to_slack_async(
     text: str,
     /,
     *,
-    timeout: TimeDelta = _TIMEOUT,
+    timeout: Duration = _TIMEOUT,
     error: MaybeType[BaseException] = TimeoutError,
 ) -> None:
     """Send a message via Slack."""
     client = _get_async_client(url, timeout=timeout)
-    async with timeout_td(timeout, error=error):
+    async with utilities.asyncio.timeout(timeout, error=error):
         response = await client.send(text=text)
     if response.status_code != HTTPStatus.OK:  # pragma: no cover
         raise SendToSlackError(text=text, response=response)
@@ -56,10 +57,10 @@ async def send_to_slack_async(
 
 @cache
 def _get_async_client(
-    url: str, /, *, timeout: TimeDelta = _TIMEOUT
+    url: str, /, *, timeout: Duration = _TIMEOUT
 ) -> AsyncWebhookClient:
     """Get the Slack client."""
-    return AsyncWebhookClient(url, timeout=to_seconds(timeout))
+    return AsyncWebhookClient(url, timeout=safe_round(in_seconds(timeout)))
 
 
 @dataclass(kw_only=True, slots=True)

utilities/sqlalchemy.py

@@ -65,33 +65,39 @@ from sqlalchemy.orm import (
 from sqlalchemy.orm.exc import UnmappedClassError
 from sqlalchemy.pool import NullPool, Pool
 
-from utilities.asyncio import timeout_td
-from utilities.functions import ensure_str, get_class_name, yield_object_attributes
+import utilities.asyncio
+from utilities.core import (
+    OneEmptyError,
+    OneNonUniqueError,
+    chunked,
+    get_class_name,
+    is_pytest,
+    normalize_multi_line_str,
+    one,
+    repr_,
+    snake_case,
+)
+from utilities.functions import ensure_str, yield_object_attributes
 from utilities.iterables import (
     CheckLengthError,
     CheckSubSetError,
-    OneEmptyError,
-    OneNonUniqueError,
     check_length,
     check_subset,
-    chunked,
     merge_sets,
     merge_str_mappings,
-    one,
 )
-from utilities.os import is_pytest
-from utilities.reprlib import get_repr
-from utilities.text import secret_str, snake_case
+from utilities.text import secret_str
 from utilities.types import (
-    Delta,
+    Duration,
     MaybeIterable,
     MaybeType,
+    StrDict,
     StrMapping,
     TupleOrStrMapping,
 )
 from utilities.typing import (
     is_sequence_of_tuple_or_str_mapping,
-    is_string_mapping,
+    is_str_mapping,
     is_tuple,
     is_tuple_or_str_mapping,
 )
@@ -127,12 +133,15 @@ async def check_connect_async(
     engine: AsyncEngine,
     /,
     *,
-    timeout: Delta | None = None,
+    timeout: Duration | None = None,
     error: MaybeType[BaseException] = TimeoutError,
 ) -> bool:
     """Check if an engine can connect."""
     try:
-        async with timeout_td(timeout, error=error), engine.connect() as conn:
+        async with (
+            utilities.asyncio.timeout(timeout, error=error),
+            engine.connect() as conn,
+        ):
             return bool((await conn.execute(_SELECT)).scalar_one())
     except (gaierror, ConnectionRefusedError, DatabaseError, TimeoutError):
         return False
@@ -145,7 +154,7 @@ async def check_engine(
     engine: AsyncEngine,
     /,
     *,
-    timeout: Delta | None = None,
+    timeout: Duration | None = None,
     error: MaybeType[BaseException] = TimeoutError,
     num_tables: int | tuple[int, float] | None = None,
 ) -> None:
@@ -183,7 +192,7 @@ class CheckEngineError(Exception):
 
     @override
     def __str__(self) -> str:
-        return f"{get_repr(self.engine)} must have {self.expected} table(s); got {len(self.rows)}"
+        return f"{repr_(self.engine)} must have {self.expected} table(s); got {len(self.rows)}"
 
 
 ##
@@ -352,7 +361,7 @@ async def ensure_tables_created(
     engine: AsyncEngine,
     /,
     *tables_or_orms: TableOrORMInstOrClass,
-    timeout: Delta | None = None,
+    timeout: Duration | None = None,
     error: MaybeType[BaseException] = TimeoutError,
 ) -> None:
     """Ensure a table/set of tables is/are created."""
@@ -381,7 +390,7 @@ async def ensure_tables_created(
 async def ensure_tables_dropped(
     engine: AsyncEngine,
     *tables_or_orms: TableOrORMInstOrClass,
-    timeout: Delta | None = None,
+    timeout: Duration | None = None,
     error: MaybeType[BaseException] = TimeoutError,
 ) -> None:
     """Ensure a table/set of tables is/are dropped."""
@@ -615,9 +624,9 @@ async def insert_items(
     is_upsert: bool = False,
     chunk_size_frac: float = CHUNK_SIZE_FRAC,
     assume_tables_exist: bool = False,
-    timeout_create: Delta | None = None,
+    timeout_create: Duration | None = None,
     error_create: MaybeType[BaseException] = TimeoutError,
-    timeout_insert: Delta | None = None,
+    timeout_insert: Duration | None = None,
     error_insert: MaybeType[BaseException] = TimeoutError,
 ) -> None:
     """Insert a set of items into a database.
@@ -860,9 +869,9 @@ async def migrate_data(
     table_or_orm_to: TableOrORMInstOrClass | None = None,
     chunk_size_frac: float = CHUNK_SIZE_FRAC,
     assume_tables_exist: bool = False,
-    timeout_create: Delta | None = None,
+    timeout_create: Duration | None = None,
     error_create: MaybeType[BaseException] = TimeoutError,
-    timeout_insert: Delta | None = None,
+    timeout_insert: Duration | None = None,
     error_insert: MaybeType[BaseException] = TimeoutError,
 ) -> None:
     """Migrate the contents of a table from one database to another."""
@@ -894,7 +903,7 @@ def selectable_to_string(
     com = selectable.compile(
         dialect=engine_or_conn.dialect, compile_kwargs={"literal_binds": True}
     )
-    return str(com)
+    return normalize_multi_line_str(str(com))
 
 
 ##
@@ -916,12 +925,15 @@ async def yield_connection(
     engine: AsyncEngine,
     /,
     *,
-    timeout: Delta | None = None,
+    timeout: Duration | None = None,
     error: MaybeType[BaseException] = TimeoutError,
 ) -> AsyncIterator[AsyncConnection]:
     """Yield an async connection."""
     try:
-        async with timeout_td(timeout, error=error), engine.begin() as conn:
+        async with (
+            utilities.asyncio.timeout(timeout, error=error),
+            engine.begin() as conn,
+        ):
             yield conn
     except GeneratorExit:  # pragma: no cover
         if not is_pytest():
@@ -1020,7 +1032,7 @@ def _is_pair_of_str_mapping_and_table(
     obj: Any, /
 ) -> TypeGuard[_PairOfStrMappingAndTable]:
     """Check if an object is a pair of a string mapping and a table."""
-    return _is_pair_with_predicate_and_table(obj, is_string_mapping)
+    return _is_pair_with_predicate_and_table(obj, is_str_mapping)
 
 
 def _is_pair_of_tuple_and_table(obj: Any, /) -> TypeGuard[_PairOfTupleAndTable]:
@@ -1063,7 +1075,7 @@ def _map_mapping_to_table(
                 mapping=mapping, columns=columns, extra=error.extra
             ) from None
         return {k: v for k, v in mapping.items() if k in columns}
-    out: dict[str, Any] = {}
+    out: StrDict = {}
     for key, value in mapping.items():
         try:
             col = one(c for c in columns if snake_case(c) == snake_case(key))
@@ -1096,7 +1108,7 @@ class _MapMappingToTableExtraColumnsError(_MapMappingToTableError):
 
     @override
     def __str__(self) -> str:
-        return f"Mapping {get_repr(self.mapping)} must be a subset of table columns {get_repr(self.columns)}; got extra {self.extra}"
+        return f"Mapping {repr_(self.mapping)} must be a subset of table columns {repr_(self.columns)}; got extra {self.extra}"
 
 
 @dataclass(kw_only=True, slots=True)
@@ -1105,7 +1117,7 @@ class _MapMappingToTableSnakeMapEmptyError(_MapMappingToTableError):
 
     @override
     def __str__(self) -> str:
-        return f"Mapping {get_repr(self.mapping)} must be a subset of table columns {get_repr(self.columns)}; cannot find column to map to {self.key!r} modulo snake casing"
+        return f"Mapping {repr_(self.mapping)} must be a subset of table columns {repr_(self.columns)}; cannot find column to map to {self.key!r} modulo snake casing"
 
 
 @dataclass(kw_only=True, slots=True)
@@ -1116,7 +1128,7 @@ class _MapMappingToTableSnakeMapNonUniqueError(_MapMappingToTableError):
 
     @override
     def __str__(self) -> str:
-        return f"Mapping {get_repr(self.mapping)} must be a subset of table columns {get_repr(self.columns)}; found columns {self.first!r}, {self.second!r} and perhaps more to map to {self.key!r} modulo snake casing"
+        return f"Mapping {repr_(self.mapping)} must be a subset of table columns {repr_(self.columns)}; found columns {self.first!r}, {self.second!r} and perhaps more to map to {self.key!r} modulo snake casing"
 
 
 ##
@@ -1156,7 +1168,7 @@ def _orm_inst_to_dict_predicate(
 
 def _tuple_to_mapping(
     values: tuple[Any, ...], table_or_orm: TableOrORMInstOrClass, /
-) -> dict[str, Any]:
+) -> StrDict:
     columns = get_column_names(table_or_orm)
     mapping = dict(zip(columns, tuple(values), strict=False))
     return {k: v for k, v in mapping.items() if v is not None}

utilities/sqlalchemy_polars.py

@@ -26,17 +26,11 @@ from polars import (
 from sqlalchemy import Column, Select, select
 from sqlalchemy.exc import DuplicateColumnError
 
-from utilities.asyncio import timeout_td
-from utilities.functions import identity
-from utilities.iterables import (
-    CheckDuplicatesError,
-    OneError,
-    check_duplicates,
-    chunked,
-    one,
-)
+import utilities.asyncio
+from utilities.constants import UTC
+from utilities.core import OneError, chunked, identity, one, repr_, snake_case
+from utilities.iterables import CheckDuplicatesError, check_duplicates
 from utilities.polars import zoned_date_time_dtype
-from utilities.reprlib import get_repr
 from utilities.sqlalchemy import (
     CHUNK_SIZE_FRAC,
     TableOrORMInstOrClass,
@@ -45,9 +39,7 @@ from utilities.sqlalchemy import (
     get_columns,
     insert_items,
 )
-from utilities.text import snake_case
 from utilities.typing import is_subclass_gen
-from utilities.zoneinfo import UTC
 
 if TYPE_CHECKING:
     from collections.abc import (
@@ -62,9 +54,8 @@ if TYPE_CHECKING:
     from sqlalchemy.ext.asyncio import AsyncEngine
     from sqlalchemy.sql import ColumnCollection
     from sqlalchemy.sql.base import ReadOnlyColumnCollection
-    from whenever import TimeDelta
 
-    from utilities.types import Delta, MaybeType, TimeZoneLike
+    from utilities.types import Duration, MaybeType, TimeZoneLike
 
 
 async def insert_dataframe(
@@ -77,9 +68,9 @@ async def insert_dataframe(
     is_upsert: bool = False,
     chunk_size_frac: float = CHUNK_SIZE_FRAC,
     assume_tables_exist: bool = False,
-    timeout_create: TimeDelta | None = None,
+    timeout_create: Duration | None = None,
     error_create: type[Exception] = TimeoutError,
-    timeout_insert: TimeDelta | None = None,
+    timeout_insert: Duration | None = None,
     error_insert: type[Exception] = TimeoutError,
 ) -> None:
     """Insert/upsert a DataFrame into a database."""
@@ -169,7 +160,7 @@ class _InsertDataFrameMapDFColumnToTableColumnAndTypeError(Exception):
 
     @override
     def __str__(self) -> str:
-        return f"Unable to map DataFrame column {self.df_col_name!r} into table schema {get_repr(self.table_schema)} with snake={self.snake}"
+        return f"Unable to map DataFrame column {self.df_col_name!r} into table schema {repr_(self.table_schema)} with snake={self.snake}"
 
 
 def _insert_dataframe_check_df_and_db_types(
@@ -200,7 +191,7 @@ async def select_to_dataframe(
     in_clauses: tuple[Column[Any], Iterable[Any]] | None = None,
     in_clauses_chunk_size: int | None = None,
     chunk_size_frac: float = CHUNK_SIZE_FRAC,
-    timeout: Delta | None = None,
+    timeout: Duration | None = None,
     error: MaybeType[BaseException] = TimeoutError,
     **kwargs: Any,
 ) -> DataFrame: ...
@@ -216,7 +207,7 @@ async def select_to_dataframe(
     in_clauses: None = None,
     in_clauses_chunk_size: int | None = None,
     chunk_size_frac: float = CHUNK_SIZE_FRAC,
-    timeout: Delta | None = None,
+    timeout: Duration | None = None,
     error: MaybeType[BaseException] = TimeoutError,
     **kwargs: Any,
 ) -> Iterable[DataFrame]: ...
@@ -232,7 +223,7 @@ async def select_to_dataframe(
     in_clauses: tuple[Column[Any], Iterable[Any]],
     in_clauses_chunk_size: int | None = None,
     chunk_size_frac: float = CHUNK_SIZE_FRAC,
-    timeout: Delta | None = None,
+    timeout: Duration | None = None,
     error: MaybeType[BaseException] = TimeoutError,
     **kwargs: Any,
 ) -> AsyncIterable[DataFrame]: ...
@@ -248,7 +239,7 @@ async def select_to_dataframe(
     in_clauses: tuple[Column[Any], Iterable[Any]] | None = None,
     in_clauses_chunk_size: int | None = None,
     chunk_size_frac: float = CHUNK_SIZE_FRAC,
-    timeout: Delta | None = None,
+    timeout: Duration | None = None,
     error: MaybeType[BaseException] = TimeoutError,
     **kwargs: Any,
 ) -> DataFrame | Iterable[DataFrame] | AsyncIterable[DataFrame]: ...
@@ -263,7 +254,7 @@ async def select_to_dataframe(
     in_clauses: tuple[Column[Any], Iterable[Any]] | None = None,
     in_clauses_chunk_size: int | None = None,
     chunk_size_frac: float = CHUNK_SIZE_FRAC,
-    timeout: Delta | None = None,
+    timeout: Duration | None = None,
     error: MaybeType[BaseException] = TimeoutError,
     **kwargs: Any,
 ) -> DataFrame | Iterable[DataFrame] | AsyncIterable[DataFrame]:
@@ -272,7 +263,7 @@ async def select_to_dataframe(
         sel = _select_to_dataframe_apply_snake(sel)
     schema = _select_to_dataframe_map_select_to_df_schema(sel, time_zone=time_zone)
     if in_clauses is None:
-        async with timeout_td(timeout, error=error):
+        async with utilities.asyncio.timeout(timeout, error=error):
             return read_database(
                 sel,
                 cast("Any", engine),
@@ -289,7 +280,7 @@ async def select_to_dataframe(
         chunk_size_frac=chunk_size_frac,
     )
     if batch_size is None:
-        async with timeout_td(timeout, error=error):
+        async with utilities.asyncio.timeout(timeout, error=error):
             dfs = [
                 await select_to_dataframe(
                     sel,
@@ -310,7 +301,7 @@ async def select_to_dataframe(
             return DataFrame(schema=schema)
 
     async def yield_dfs() -> AsyncIterator[DataFrame]:
-        async with timeout_td(timeout, error=error):
+        async with utilities.asyncio.timeout(timeout, error=error):
             for sel_i in sels:
                 for df in await select_to_dataframe(
                     sel_i,