dycw-utilities 0.150.7__py3-none-any.whl → 0.150.9__py3-none-any.whl

{dycw_utilities-0.150.7.dist-info → dycw_utilities-0.150.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.150.7
+Version: 0.150.9
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{dycw_utilities-0.150.7.dist-info → dycw_utilities-0.150.9.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=A1YeWIQQEjqfqiCFF31G03YhEM20RzT8IBH3dcnt8d4,60
+utilities/__init__.py,sha256=GsG3Q0h41dPHASCsd70D14gPFgnAp7k4Bz18oGu00SI,60
 utilities/altair.py,sha256=92E2lCdyHY4Zb-vCw6rEJIsWdKipuu-Tu2ab1ufUfAk,9079
 utilities/asyncio.py,sha256=2m2a2C-Qgc6OHTTHL332-t66A7xDITt_SORT7a1DJWo,16792
 utilities/atomicwrites.py,sha256=xcOWenTBRS0oat3kg7Sqe51AohNThMQ2ixPL7QCG8hw,5795
@@ -23,7 +23,7 @@ utilities/getpass.py,sha256=DfN5UgMAtFCqS3dSfFHUfqIMZX2shXvwphOz_6J6f6A,103
 utilities/gzip.py,sha256=fkGP3KdsBfXlstodT4wtlp-PwNyUsogpbDCVVVGdsm4,781
 utilities/hashlib.py,sha256=SVTgtguur0P4elppvzOBbLEjVM3Pea0eWB61yg2ilxo,309
 utilities/http.py,sha256=TsavEfHlRtlLaeV21Z6KZh0qbPw-kvD1zsQdZ7Kep5Q,977
-utilities/hypothesis.py,sha256=i-TUh9gCgoPMfFYueVwoaUIHtCbZn99tXUkrPvxZxG4,38069
+utilities/hypothesis.py,sha256=_DKCFAHgE4NRE1asv-asYVvs5cqqivxTNrKHPeq2RjE,39282
 utilities/importlib.py,sha256=mV1xT_O_zt_GnZZ36tl3xOmMaN_3jErDWY54fX39F6Y,429
 utilities/inflect.py,sha256=UWOsMRJUJXqcR3rgrQmb35mat-Theu5xo-M9E33eTIE,586
 utilities/ipython.py,sha256=V2oMYHvEKvlNBzxDXdLvKi48oUq2SclRg5xasjaXStw,763
@@ -49,7 +49,7 @@ utilities/pickle.py,sha256=MBT2xZCsv0pH868IXLGKnlcqNx2IRVKYNpRcqiQQqxw,653
 utilities/platform.py,sha256=Ue9LSxYvg9yUXGKuz5aZoy_qkUEXde-v6B09exgSctU,2813
 utilities/polars.py,sha256=BgiDryAVOapi41ddfJqN0wYh_sDj8BNEYtPB36LaHdo,71824
 utilities/polars_ols.py,sha256=Uc9V5kvlWZ5cU93lKZ-cfAKdVFFw81tqwLW9PxtUvMs,5618
-utilities/postgres.py,sha256=L1cunDLu8nK5fCkY9fTgSTHjT1_B8Y0iUJEjPC7Ar3A,13849
+utilities/postgres.py,sha256=48km6Mb6hRUb1-0FWg7FKEfrW75z8-7AY1jahtdu_KY,12406
 utilities/pottery.py,sha256=u0uvyGgYyujxftEMlsv6ppYTKQoVVjHt5jnVxxYz9s4,6596
 utilities/pqdm.py,sha256=BTsYPtbKQWwX-iXF4qCkfPG7DPxIB54J989n83bXrIo,3092
 utilities/psutil.py,sha256=KUlu4lrUw9Zg1V7ZGetpWpGb9DB8l_SSDWGbANFNCPU,2104
@@ -66,12 +66,12 @@ utilities/sentinel.py,sha256=3jIwgpMekWgDAxPDA_hXMP2St43cPhciKN3LWiZ7kv0,1248
 utilities/shelve.py,sha256=4OzjQI6kGuUbJciqf535rwnao-_IBv66gsT6tRGiUt0,759
 utilities/slack_sdk.py,sha256=ppFBvKgfg5IRWiIoKPtpTyzBtBF4XmwEvU3I5wLJikM,2140
 utilities/socket.py,sha256=K77vfREvzoVTrpYKo6MZakol0EYu2q1sWJnnZqL0So0,118
-utilities/sqlalchemy.py,sha256=5TPqPvJUCuxIeiMD7IKTptYg11UXNy7ThGw81reCIRU,37290
+utilities/sqlalchemy.py,sha256=u2ZVvr_4Yrqsur6FlLHUuW0mPaoNrHvaJ2wj7o_WG3A,39264
 utilities/sqlalchemy_polars.py,sha256=18AoEbeNJUKF3-5hroNy9J5LQwS_QJAXbMfKc9sChtk,14250
 utilities/statsmodels.py,sha256=koyiBHvpMcSiBfh99wFUfSggLNx7cuAw3rwyfAhoKpQ,3410
 utilities/string.py,sha256=MB0X6UPTUc06JdAdj-PctZ238IXeCjE5dAJibNw6ZrU,587
 utilities/tempfile.py,sha256=HxB2BF28CcecDJLQ3Bx2Ej-Pb6RJc6W9ngSpB9CnP4k,2018
-utilities/text.py,sha256=ymBFlP_cA8OgNnZRVNs7FAh7OG8HxE6YkiLEMZv5g_A,11297
+utilities/text.py,sha256=bupgC6ILTjmcJKSUGloStzmWuj2Ke0knvVKE2mWLwAM,11619
 utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
 utilities/timer.py,sha256=oXfTii6ymu57niP0BDGZjFD55LEHi2a19kqZKiTgaFQ,2588
 utilities/traceback.py,sha256=zofhzIedpUHrzDNiRJDVzm_wuu_tlTQvVqK4quxVlgM,9151
@@ -89,8 +89,8 @@ utilities/zoneinfo.py,sha256=oEH-nL3t4h9uawyZqWDtNtDAl6M-CLpLYGI_nI6DulM,1971
 utilities/pytest_plugins/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
 utilities/pytest_plugins/pytest_randomly.py,sha256=NXzCcGKbpgYouz5yehKb4jmxmi2SexKKpgF4M65bi10,414
 utilities/pytest_plugins/pytest_regressions.py,sha256=Iwhfv_OJH7UCPZCfoh7ugZ2Xjqjil-BBBsOb8sDwiGI,1471
-dycw_utilities-0.150.7.dist-info/METADATA,sha256=RtXoOrng-vQlgoP2v8k9pfCYWGKzLTAAXhfQN7UADA4,1696
-dycw_utilities-0.150.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.150.7.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
-dycw_utilities-0.150.7.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.150.7.dist-info/RECORD,,
+dycw_utilities-0.150.9.dist-info/METADATA,sha256=h1ki8nwAV6ET-w-Z9jFMsFrXnEezGVzts3XVeQ9kJps,1696
+dycw_utilities-0.150.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.150.9.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
+dycw_utilities-0.150.9.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.150.9.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.150.7"
+__version__ = "0.150.9"

utilities/hypothesis.py

@@ -98,6 +98,7 @@ if TYPE_CHECKING:
     from hypothesis.database import ExampleDatabase
     from libcst import Import, ImportFrom
     from numpy.random import RandomState
+    from sqlalchemy import URL
 
     from utilities.numpy import NDArrayB, NDArrayF, NDArrayI, NDArrayO
     from utilities.types import Number, TimeZoneLike
@@ -1258,6 +1259,41 @@ def uint64s(
 ##
 
 
+@composite
+def urls(
+    draw: DrawFn,
+    /,
+    *,
+    all_: MaybeSearchStrategy[bool] = False,
+    username: MaybeSearchStrategy[bool] = False,
+    password: MaybeSearchStrategy[bool] = False,
+    host: MaybeSearchStrategy[bool] = False,
+    port: MaybeSearchStrategy[bool] = False,
+    database: MaybeSearchStrategy[bool] = False,
+) -> URL:
+    from sqlalchemy import URL
+
+    have_all, have_username, have_password, have_host, have_port, have_database = [
+        draw2(draw, b) for b in [all_, username, password, host, port, database]
+    ]
+    username_use = draw(text_ascii(min_size=1)) if have_all or have_username else None
+    password_use = draw(text_ascii(min_size=1)) if have_all or have_password else None
+    host_use = draw(text_ascii(min_size=1)) if have_all or have_host else None
+    port_use = draw(integers(min_value=1)) if have_all or have_port else None
+    database_use = draw(text_ascii(min_size=1)) if have_all or have_database else None
+    return URL.create(
+        drivername="sqlite",
+        username=username_use,
+        password=password_use,
+        host=host_use,
+        port=port_use,
+        database=database_use,
+    )
+
+
+##
+
+
 @composite
 def versions(draw: DrawFn, /, *, suffix: MaybeSearchStrategy[bool] = False) -> Version:
     """Strategy for generating versions."""
@@ -1392,6 +1428,7 @@ __all__ = [
     "triples",
     "uint32s",
     "uint64s",
+    "urls",
     "versions",
     "year_months",
     "zoned_datetimes",

utilities/postgres.py

@@ -13,7 +13,7 @@ from utilities.iterables import always_iterable
 from utilities.logging import get_logger
 from utilities.os import temp_environ
 from utilities.pathlib import ensure_suffix
-from utilities.sqlalchemy import get_table_name
+from utilities.sqlalchemy import extract_url, get_table_name
 from utilities.timer import Timer
 from utilities.types import PathLike
 
@@ -124,12 +124,11 @@ def _build_pg_dump(
     role: str | None = None,
     docker: str | None = None,
 ) -> str:
-    database, host, port = _extract_url(url)
+    extracted = extract_url(url)
     path = _path_pg_dump(path, format_=format_)
     parts: list[str] = [
         "pg_dump",
         # general options
-        f"--dbname={database}",
         f"--file={str(path)!r}",
         f"--format={format_}",
         "--verbose",
@@ -139,8 +138,10 @@ def _build_pg_dump(
         "--no-owner",
         "--no-privileges",
         # connection options
-        f"--host={host}",
-        f"--port={port}",
+        f"--dbname={extracted.database}",
+        f"--host={extracted.host}",
+        f"--port={extracted.port}",
+        f"--username={extracted.username}",
         "--no-password",
     ]
     if (format_ == "directory") and (jobs is not None):
@@ -167,8 +168,6 @@ def _build_pg_dump(
         parts.append("--inserts")
     if on_conflict_do_nothing:
         parts.append("--on-conflict-do-nothing")
-    if url.username is not None:
-        parts.append(f"--username={url.username}")
     if role is not None:
         parts.append(f"--role={role}")
     if docker is not None:
@@ -203,7 +202,6 @@ async def restore(
     /,
     *,
     psql: bool = False,
-    database: str | None = None,
     data_only: bool = False,
     clean: bool = False,
     create: bool = False,
@@ -221,7 +219,6 @@ async def restore(
         url,
         path,
         psql=psql,
-        database=database,
         data_only=data_only,
         clean=clean,
         create=create,
@@ -270,7 +267,6 @@ def _build_pg_restore_or_psql(
     /,
     *,
     psql: bool = False,
-    database: str | None = None,
     data_only: bool = False,
     clean: bool = False,
     create: bool = False,
@@ -283,11 +279,10 @@ def _build_pg_restore_or_psql(
 ) -> str:
     path = Path(path)
     if (path.suffix == ".sql") or psql:
-        return _build_psql(url, path, database=database, docker=docker)
+        return _build_psql(url, path, docker=docker)
     return _build_pg_restore(
         url,
         path,
-        database=database,
         data_only=data_only,
         clean=clean,
         create=create,
@@ -305,7 +300,6 @@ def _build_pg_restore(
     path: PathLike,
     /,
     *,
-    database: str | None = None,
     data_only: bool = False,
     clean: bool = False,
     create: bool = False,
@@ -317,12 +311,10 @@ def _build_pg_restore(
     docker: str | None = None,
 ) -> str:
     """Run `pg_restore`."""
-    url_database, host, port = _extract_url(url)
-    database_use = url_database if database is None else database
+    extracted = extract_url(url)
     parts: list[str] = [
         "pg_restore",
         # general options
-        f"--dbname={database_use}",
         "--verbose",
         # restore options
         *_resolve_data_only_and_clean(data_only=data_only, clean=clean),
@@ -330,8 +322,10 @@ def _build_pg_restore(
         "--no-owner",
         "--no-privileges",
         # connection options
-        f"--host={host}",
-        f"--port={port}",
+        f"--host={extracted.host}",
+        f"--port={extracted.port}",
+        f"--username={extracted.username}",
+        f"--dbname={extracted.database}",
         "--no-password",
     ]
     if create:
@@ -344,8 +338,6 @@ def _build_pg_restore(
         parts.extend([f"--exclude-schema={s}" for s in always_iterable(schemas_exc)])
     if tables is not None:
         parts.extend([f"--table={_get_table_name(t)}" for t in always_iterable(tables)])
-    if url.username is not None:
-        parts.append(f"--username={url.username}")
     if role is not None:
         parts.append(f"--role={role}")
     if docker is not None:
@@ -354,29 +346,20 @@ def _build_pg_restore(
     return " ".join(parts)
 
 
-def _build_psql(
-    url: URL,
-    path: PathLike,
-    /,
-    *,
-    database: str | None = None,
-    docker: str | None = None,
-) -> str:
+def _build_psql(url: URL, path: PathLike, /, *, docker: str | None = None) -> str:
     """Run `psql`."""
-    url_database, host, port = _extract_url(url)
-    database_use = url_database if database is None else database
+    extracted = extract_url(url)
     parts: list[str] = [
         "psql",
         # general options
-        f"--dbname={database_use}",
+        f"--dbname={extracted.database}",
         f"--file={str(path)!r}",
         # connection options
-        f"--host={host}",
-        f"--port={port}",
+        f"--host={extracted.host}",
+        f"--port={extracted.port}",
+        f"--username={extracted.username}",
         "--no-password",
     ]
-    if url.username is not None:
-        parts.append(f"--username={url.username}")
     if docker is not None:
         parts = _wrap_docker(parts, docker)
     return " ".join(parts)
@@ -385,42 +368,6 @@ def _build_psql(
 ##
 
 
-def _extract_url(url: URL, /) -> tuple[str, str, int]:
-    if url.database is None:
-        raise _ExtractURLDatabaseError(url=url)
-    if url.host is None:
-        raise _ExtractURLHostError(url=url)
-    if url.port is None:
-        raise _ExtractURLPortError(url=url)
-    return url.database, url.host, url.port
-
-
-@dataclass(kw_only=True, slots=True)
-class ExtractURLError(Exception):
-    url: URL
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractURLDatabaseError(ExtractURLError):
-    @override
-    def __str__(self) -> str:
-        return f"Expected URL to contain a 'database'; got {self.url}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractURLHostError(ExtractURLError):
-    @override
-    def __str__(self) -> str:
-        return f"Expected URL to contain a 'host'; got {self.url}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractURLPortError(ExtractURLError):
-    @override
-    def __str__(self) -> str:
-        return f"Expected URL to contain a 'port'; got {self.url}"
-
-
 def _get_table_name(obj: TableOrORMInstOrClass | str, /) -> str:
     match obj:
         case Table() | DeclarativeBase() | type() as table_or_orm:
@@ -458,4 +405,4 @@ def _wrap_docker(parts: list[str], container: str, /) -> list[str]:
     return ["docker", "exec", "-it", container, *parts]
 
 
-__all__ = ["ExtractURLError", "pg_dump", "restore"]
+__all__ = ["pg_dump", "restore"]

utilities/sqlalchemy.py

@@ -96,7 +96,7 @@ from utilities.iterables import (
     one,
 )
 from utilities.reprlib import get_repr
-from utilities.text import snake_case
+from utilities.text import secret_str, snake_case
 from utilities.types import MaybeIterable, MaybeType, StrMapping, TupleOrStrMapping
 
 if TYPE_CHECKING:
@@ -378,6 +378,79 @@ def enum_values(enum: type[StrEnum], /) -> list[str]:
 ##
 
 
+@dataclass(kw_only=True, slots=True)
+class ExtractURLOutput:
+    username: str
+    password: secret_str
+    host: str
+    port: int
+    database: str
+
+
+def extract_url(url: URL, /) -> ExtractURLOutput:
+    """Extract the database, host & port from a URL."""
+    if url.username is None:
+        raise _ExtractURLUsernameError(url=url)
+    if url.password is None:
+        raise _ExtractURLPasswordError(url=url)
+    if url.host is None:
+        raise _ExtractURLHostError(url=url)
+    if url.port is None:
+        raise _ExtractURLPortError(url=url)
+    if url.database is None:
+        raise _ExtractURLDatabaseError(url=url)
+    return ExtractURLOutput(
+        username=url.username,
+        password=secret_str(url.password),
+        host=url.host,
+        port=url.port,
+        database=url.database,
+    )
+
+
+@dataclass(kw_only=True, slots=True)
+class ExtractURLError(Exception):
+    url: URL
+
+
+@dataclass(kw_only=True, slots=True)
+class _ExtractURLUsernameError(ExtractURLError):
+    @override
+    def __str__(self) -> str:
+        return f"Expected URL to contain a user name; got {self.url}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _ExtractURLPasswordError(ExtractURLError):
+    @override
+    def __str__(self) -> str:
+        return f"Expected URL to contain a password; got {self.url}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _ExtractURLHostError(ExtractURLError):
+    @override
+    def __str__(self) -> str:
+        return f"Expected URL to contain a host; got {self.url}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _ExtractURLPortError(ExtractURLError):
+    @override
+    def __str__(self) -> str:
+        return f"Expected URL to contain a port; got {self.url}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _ExtractURLDatabaseError(ExtractURLError):
+    @override
+    def __str__(self) -> str:
+        return f"Expected URL to contain a database; got {self.url}"
+
+
+##
+
+
 def get_chunk_size(
     dialect_or_engine_or_conn: DialectOrEngineOrConnectionOrAsync,
     table_or_orm_or_num_cols: TableOrORMInstOrClass | Sized | int,
@@ -1180,6 +1253,8 @@ __all__ = [
     "CheckEngineError",
     "DialectOrEngineOrConnectionOrAsync",
     "EngineOrConnectionOrAsync",
+    "ExtractURLError",
+    "ExtractURLOutput",
     "GetTableError",
     "InsertItemsError",
     "TablenameMixin",
@@ -1193,6 +1268,7 @@ __all__ = [
     "ensure_tables_dropped",
     "enum_name",
     "enum_values",
+    "extract_url",
     "get_chunk_size",
     "get_column_names",
     "get_columns",

utilities/text.py

@@ -9,7 +9,7 @@ from re import IGNORECASE, Match, escape, search
 from textwrap import dedent
 from threading import get_ident
 from time import time_ns
-from typing import TYPE_CHECKING, Any, Literal, overload, override
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, overload, override
 from uuid import uuid4
 
 from utilities.iterables import CheckDuplicatesError, check_duplicates, transpose
@@ -385,6 +385,24 @@ def _escape_separator(*, separator: str = DEFAULT_SEPARATOR) -> str:
 ##
 
 
+class secret_str(str):  # noqa: N801
+    """A string with an obfuscated representation."""
+
+    __slots__ = ()
+    _REPR: ClassVar[str] = "***"
+
+    @override
+    def __repr__(self) -> str:
+        return self._REPR
+
+    @override
+    def __str__(self) -> str:
+        return self._REPR
+
+
+##
+
+
 def str_encode(obj: Any, /) -> bytes:
     """Return the string representation of the object encoded as bytes."""
     return str(obj).encode()
@@ -424,6 +442,7 @@ __all__ = [
     "parse_bool",
     "parse_none",
     "repr_encode",
+    "secret_str",
     "snake_case",
     "split_key_value_pairs",
     "split_str",