release: 1.0.0

first stable release. pre-1.0.0 verification complete: all surviving MED regressions and
gaps resolved and independently re-fired, tree audited clean across the suite.

Signed-off-by: disqualifier <dev@disqualifier.me>

README.md

@@ -11,18 +11,18 @@ wire-compatible and share the driver, so this covers both.
 `requirements.txt`:
 
 ```
-mysql @ git+ssh://git@git.rethinkstudios.io/rethink-public/mysql.git@v0.1.4
+mysql @ git+ssh://git@git.rethinkstudios.io/rethink-public/mysql.git@v0.1.6
 ```
 
 Direct:
 
 ```bash
-pip install "mysql @ git+ssh://git@git.rethinkstudios.io/rethink-public/mysql.git@v0.1.4"
+pip install "mysql @ git+ssh://git@git.rethinkstudios.io/rethink-public/mysql.git@v0.1.6"
 ```
 
 Pulls `aiomysql` (which pulls `PyMySQL`).
 
-Drop the `@v0.1.3` suffix from the line above to install the latest unpinned.
+Drop the `@v0.1.6` suffix from the line above to install the latest unpinned.
 
 ## The two-layer API
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mysql"
-version = "0.1.4"
+version = "1.0.0"
 description = "async mysql/mariadb wrapper over aiomysql: two-layer API (friendly verbs + raw escape hatch), fail-loud, config-free"
 requires-python = ">=3.10"
 dependencies = [

src/mysql/__init__.py

@@ -1,5 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version
+
 from .mysql import MysqlDB
 
-__version__ = "0.1.4"
+__all__ = ["MysqlDB"]
 
-__all__ = ["MysqlDB", "__version__"]
+try:
+    __version__ = version("mysql")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

src/mysql/mysql.py

@@ -1,55 +1,24 @@
 """
-async mysql / mariadb wrapper over aiomysql — two-layer API (friendly verbs + raw hatch)
+async mysql/mariadb wrapper over aiomysql - two-layer API (friendly verbs + raw hatch)
 
-covers MySQL and MariaDB (wire-compatible, same driver).
-
-object pattern (one pool per process), attach to the app:
     from mysql import MysqlDB
     app.db = await MysqlDB(host="localhost", port=3306, db="app",
                            user="root", password="secret").connect()
     await app.db.insert("users", {"name": "ada", "active": True})
     rows = await app.db.get("users", {"active": True})   # [{"name": "ada", ...}]
-    await app.db.close()                                  # on shutdown
+    await app.db.close()
 
-context manager:
-    async with MysqlDB(db="app", user="root") as db:
-        await db.execute("CREATE TABLE ...")
+layer 1 is IDENTICAL to the `psql` lib's surface (swap psql<->mysql with zero call-site
+changes); layer 2 is the raw `%s`-placeholder escape hatch. see README for the full API
+and mysql/psql dialect differences.
 
-lifecycle:
-    construction is sync and opens no socket. connect() builds the aiomysql pool and
-    validates it with `SELECT 1` so a bad host/credentials fails loud immediately rather
-    than on the first real op, and returns self. close() closes the pool and waits for it.
-    the pool runs with autocommit=True, so the layer-1 verbs and raw execute() commit on
-    their own; transaction() opens an explicit transaction for atomic multi-statement work.
+a literal `%` in layer-2 SQL text must be written `%%` only when params are passed
+(aiomysql runs `query % args` only then); with no params the text is sent verbatim. layer
+1 handles this for you.
 
-two-layer API (IDENTICAL layer-1 surface to the `psql` lib — swap psql<->mysql with zero
-call-site changes; only the dialect below differs, hidden inside the wrapper):
-    LAYER 1 — friendly portable verbs for simple single-table CRUD: create_database,
-    create_table, drop, insert, get, get_one, delete, exists, upsert.
-    LAYER 2 — raw escape hatch for the complex ~20% (joins, aggregates, subqueries): you
-    write the SQL with `%s` placeholders + a params sequence; the wrapper gives pooling,
-    parameterization, fail-loud errors, and dict rows. execute, fetch, fetchone, fetchval,
-    transaction. NOTHING in between — no query builder / ORM.
-
-dialect (mysql-specific; visible only in raw layer-2 SQL you write):
-    - placeholders are `%s` (here) vs `$1` (psql). the `%s` is the DBAPI placeholder the
-      driver consumes, NOT python `%` string formatting — but PyMySQL builds it via
-      `query % args` whenever params are passed, so any OTHER literal `%` in the query
-      text (e.g. `LIKE '%foo%'`) must be written `%%` or it raises. no params -> no
-      substitution -> a lone `%` is fine. layer 1 escapes `%` in identifiers for you.
-    - upsert emits `ON DUPLICATE KEY UPDATE` (here) vs `ON CONFLICT` (psql), via the
-      deprecated `col = VALUES(col)` form (MySQL 8.0.20+ warns; still works, MariaDB is
-      unaffected). layer-1 upsert() hides both.
-
-rows:
-    layer 1 and fetch/fetchone return plain dicts via aiomysql's DictCursor (identical
-    shape to psql). fetchval/exists tolerate a caller-overridden tuple cursorclass too.
-
-errors (FAIL LOUD — unlike the mongo lib's swallow-and-default):
-    every method catches the driver error (pymysql.err.MySQLError, OSError on connection
-    loss), logs via getLogger(__name__), and re-raises. a None/[] return is only ever a
-    real result (no row, empty table) — never a swallowed failure. for anything not
-    wrapped, use the raw `.pool` property (the aiomysql.Pool).
+errors are FAIL LOUD (unlike the mongo lib's swallow-and-default): every method catches
+the driver error, logs via getLogger(__name__), and re-raises. a None/[] return is only
+ever a real result, never a swallowed failure. for anything not wrapped, use `.pool`.
 """
 
 import asyncio
@@ -65,28 +34,35 @@ _DRIVER_ERRORS = (MySQLError, OSError)
 
 
 def _first_value(row) -> Any:
-    """return the first column's value from a dict or sequence row
-
-    fetchval/exists read a single scalar column and work under either cursorclass: the
-    default DictCursor (dict row) or a caller override to a tuple/sequence cursor via
-    pool_kwargs — the only two row shapes aiomysql cursors produce.
-    """
+    """return the first column's value from a dict or sequence row (either cursorclass)"""
     return next(iter(row.values())) if isinstance(row, dict) else row[0]
 
 
-def _quote_ident(identifier: str) -> str:
-    """backtick-quote a sql identifier (table/column), escaping backticks and `%`
+def _norm_params(params: Optional[Sequence]) -> Any:
+    """normalize params for aiomysql: None/empty-sequence -> None (no `query % args`, so a
+    literal `%` is sent as-is); a str/bytes stays a single bound value (never exploded per
+    char); anything else passes through"""
+    if params is None:
+        return None
+    if isinstance(params, (str, bytes, bytearray)):
+        return params
+    if isinstance(params, Sequence) and len(params) == 0:
+        return None
+    return params
 
-    identifiers can't be parameterized, so they are interpolated — backtick-quoting +
-    doubling any embedded backtick is the mysql-safe way to do that for caller names. an
-    embedded `%` is also doubled: PyMySQL applies `query % args` whenever a call passes
-    params, and an unescaped `%` inside an interpolated identifier would hit that same
-    substitution and raise, not just literal `%` written by the caller (see the module
-    docstring's `%%`-escaping rule).
-    """
+
+def _quote_ident(identifier: str) -> str:
+    """backtick-quote an identifier for the params path, doubling `` ` `` and `%` (the `%%`
+    collapses back under `query % args`); use `_quote_ident_literal` on the no-params path"""
     return "`" + identifier.replace("`", "``").replace("%", "%%") + "`"
 
 
+def _quote_ident_literal(identifier: str) -> str:
+    """backtick-quote an identifier for the no-params DDL path; no `%`-doubling (no
+    substitution runs to collapse it), only the backtick escaped"""
+    return "`" + identifier.replace("`", "``") + "`"
+
+
 class MysqlDB:
     """async mysql/mariadb wrapper; one pool per process, attach as app.db"""
 
@@ -107,20 +83,21 @@ class MysqlDB:
         host/port/db/user/password/minsize/maxsize are injected by the caller. extra
         pool_kwargs pass through to aiomysql.create_pool (unix_socket, ssl, charset, ...).
         rows come back as dicts (DictCursor), overridable via pool_kwargs to a tuple
-        cursorclass — fetchval/exists work either way, everything else stays dict-shaped
+        cursorclass - fetchval/exists work either way, everything else stays dict-shaped
         only under DictCursor. autocommit is always on: layer-1 verbs and raw execute()
         rely on it to commit their own writes without an explicit commit, so
-        `autocommit=False` in pool_kwargs is rejected outright — silently accepting it
+        `autocommit=False` in pool_kwargs is rejected outright - silently accepting it
         would mean every write sits uncommitted until something else commits or the
         connection is returned to the pool and rolled back, losing data with no error.
         use transaction() for an atomic multi-statement block instead (it disables
         autocommit for just that block).
         """
-        if pool_kwargs.get("autocommit") is False:
+        if "autocommit" in pool_kwargs and not pool_kwargs["autocommit"]:
             raise ValueError(
-                "mysql: autocommit=False is not supported via pool_kwargs — layer-1 verbs and "
-                "raw execute() need autocommit to persist their writes; use db.transaction() "
-                "for an atomic multi-statement block instead"
+                f"mysql: autocommit must be on (got {pool_kwargs['autocommit']!r}) - layer-1 verbs "
+                "and raw execute() need it to persist writes (False/None/0 all disable it, and None "
+                "means 'server default' = silent data loss under autocommit=0); use db.transaction() "
+                "for atomic blocks"
             )
         self._config = dict(
             host=host,
@@ -149,15 +126,22 @@ class MysqlDB:
         """
         async with self._connect_lock:
             if self._pool is not None:
-                await self.close()
-            pool = await aiomysql.create_pool(**self._config)
+                await self._close_locked()
+            pool = None
             try:
+                pool = await aiomysql.create_pool(**self._config)
                 async with pool.acquire() as conn:
                     async with conn.cursor() as cur:
                         await cur.execute("SELECT 1")
                         await cur.fetchone()
+            except _DRIVER_ERRORS:
+                log.exception("mysql.connect() failed")
+                if pool is not None:
+                    pool.close()
+                    await pool.wait_closed()
+                raise
             except BaseException:
-                log.exception("mysql.connect() validation failed")
+                if pool is not None:
                     pool.close()
                     await pool.wait_closed()
                 raise
@@ -165,7 +149,17 @@ class MysqlDB:
             return self
 
     async def close(self) -> None:
-        """close the pool and wait for it on shutdown"""
+        """close the pool and wait for it on shutdown
+
+        guarded by the same lock as connect() - a close() racing an in-flight connect()
+        waits for it rather than no-opping against a not-yet-installed pool and leaving
+        the just-built one live.
+        """
+        async with self._connect_lock:
+            await self._close_locked()
+
+    async def _close_locked(self) -> None:
+        """close the pool and wait for it; caller must hold `_connect_lock`"""
         if self._pool is None:
             return
         try:
@@ -178,9 +172,11 @@ class MysqlDB:
             self._pool = None
 
     async def __aenter__(self) -> "MysqlDB":
+        """enter: connect() and return self"""
         return await self.connect()
 
     async def __aexit__(self, exc_type, exc, tb) -> None:
+        """exit: close(), ignoring exc_type/exc/tb"""
         await self.close()
 
     @property
@@ -196,30 +192,33 @@ class MysqlDB:
     # -------------------------------------------------------------------------
     #   internal cursor helpers (autocommit pool)
 
-    async def _run(self, query: str, params: Sequence = ()):
-        """execute a statement on a pooled cursor; return (rowcount, lastrowid)"""
+    async def _run(self, query: str, params: Optional[Sequence] = None):
+        """execute a statement on a pooled cursor; return (rowcount, lastrowid)
+
+        params go through `_norm_params` (see it for the no-substitution/str-bytes handling)
+        """
         async with self.pool.acquire() as conn:
             async with conn.cursor() as cur:
-                await cur.execute(query, params or None)
+                await cur.execute(query, _norm_params(params))
                 return cur.rowcount, cur.lastrowid
 
-    async def _fetchall(self, query: str, params: Sequence = ()) -> List[dict]:
+    async def _fetchall(self, query: str, params: Optional[Sequence] = None) -> List[dict]:
         """execute a query and return all rows as dicts"""
         async with self.pool.acquire() as conn:
             async with conn.cursor() as cur:
-                await cur.execute(query, params or None)
+                await cur.execute(query, _norm_params(params))
                 rows = await cur.fetchall()
                 return list(rows)
 
-    async def _fetchone(self, query: str, params: Sequence = ()) -> Optional[dict]:
+    async def _fetchone(self, query: str, params: Optional[Sequence] = None) -> Optional[dict]:
         """execute a query and return the first row dict, or None"""
         async with self.pool.acquire() as conn:
             async with conn.cursor() as cur:
-                await cur.execute(query, params or None)
+                await cur.execute(query, _norm_params(params))
                 return await cur.fetchone()
 
     # -------------------------------------------------------------------------
-    #   layer 2 — raw escape hatch (you write the SQL, %s placeholders)
+    #   layer 2 - raw escape hatch (you write the SQL, %s placeholders)
 
     async def execute(self, query: str, params: Optional[Sequence] = None) -> int:
         """run a statement (INSERT/UPDATE/DELETE/DDL); return the affected rowcount
@@ -228,7 +227,7 @@ class MysqlDB:
         lastrowid, or reach for the raw pool.
         """
         try:
-            rowcount, _ = await self._run(query, params or ())
+            rowcount, _ = await self._run(query, params)
         except _DRIVER_ERRORS:
             log.exception("mysql.execute(): %s", query)
             raise
@@ -237,7 +236,7 @@ class MysqlDB:
     async def fetch(self, query: str, params: Optional[Sequence] = None) -> List[dict]:
         """run a query and return all rows as plain dicts (empty list = no rows)"""
         try:
-            return await self._fetchall(query, params or ())
+            return await self._fetchall(query, params)
         except _DRIVER_ERRORS:
             log.exception("mysql.fetch(): %s", query)
             raise
@@ -245,7 +244,7 @@ class MysqlDB:
     async def fetchone(self, query: str, params: Optional[Sequence] = None) -> Optional[dict]:
         """run a query and return the first row as a dict, or None if no rows"""
         try:
-            return await self._fetchone(query, params or ())
+            return await self._fetchone(query, params)
         except _DRIVER_ERRORS:
             log.exception("mysql.fetchone(): %s", query)
             raise
@@ -253,7 +252,7 @@ class MysqlDB:
     async def fetchval(self, query: str, params: Optional[Sequence] = None) -> Any:
         """run a query and return the first column of the first row, or None"""
         try:
-            row = await self._fetchone(query, params or ())
+            row = await self._fetchone(query, params)
         except _DRIVER_ERRORS:
             log.exception("mysql.fetchval(): %s", query)
             raise
@@ -262,25 +261,20 @@ class MysqlDB:
         return _first_value(row)
 
     def transaction(self):
-        """async context manager running a block of statements atomically
+        """async context manager running a block of statements atomically (see README)
 
-        usage:
-            async with db.transaction() as conn:
-                async with conn.cursor() as cur:
-                    await cur.execute("INSERT ...", (a,))
-                    await cur.execute("UPDATE ...", (b,))
         commits on clean exit, rolls back and re-raises on any error. `conn` is a raw
         aiomysql connection (autocommit disabled for the block).
         """
         return _Transaction(self.pool)
 
     # -------------------------------------------------------------------------
-    #   layer 1 — friendly portable verbs (identical to the psql lib)
+    #   layer 1 - friendly portable verbs (identical to the psql lib)
 
     async def create_database(self, name: str) -> None:
         """CREATE DATABASE IF NOT EXISTS name"""
         try:
-            await self._run(f"CREATE DATABASE IF NOT EXISTS {_quote_ident(name)}")
+            await self._run(f"CREATE DATABASE IF NOT EXISTS {_quote_ident_literal(name)}")
         except _DRIVER_ERRORS:
             log.exception("mysql.create_database(%s)", name)
             raise
@@ -290,12 +284,13 @@ class MysqlDB:
 
         schema maps column name -> its column definition, e.g.
         {"id": "int auto_increment primary key", "name": "varchar(255) not null"}. the
-        column type/constraints are caller-controlled SQL (not values), interpolated
-        as-is; only the column NAME is quoted. same schema-dict format as the psql lib.
+        column type/constraints are caller-controlled SQL interpolated as-is (a literal `%`
+        in a decl is sent unaltered - no params); only the column NAME is quoted. same
+        schema-dict format as the psql lib.
         """
-        cols = ", ".join(f"{_quote_ident(col)} {decl}" for col, decl in schema.items())
+        cols = ", ".join(f"{_quote_ident_literal(col)} {decl}" for col, decl in schema.items())
         try:
-            await self._run(f"CREATE TABLE IF NOT EXISTS {_quote_ident(name)} ({cols})")
+            await self._run(f"CREATE TABLE IF NOT EXISTS {_quote_ident_literal(name)} ({cols})")
         except _DRIVER_ERRORS:
             log.exception("mysql.create_table(%s)", name)
             raise
@@ -304,7 +299,7 @@ class MysqlDB:
         """DROP a table (table=True, default) or database (table=False), IF EXISTS"""
         kind = "TABLE" if table else "DATABASE"
         try:
-            await self._run(f"DROP {kind} IF EXISTS {_quote_ident(name)}")
+            await self._run(f"DROP {kind} IF EXISTS {_quote_ident_literal(name)}")
         except _DRIVER_ERRORS:
             log.exception("mysql.drop(%s)", name)
             raise
@@ -313,7 +308,7 @@ class MysqlDB:
         """INSERT one row from {column: value}; return the new row id (lastrowid)
 
         values are parameterized (%s). returns lastrowid for an auto-increment table, or
-        0 when there is no auto-increment key — the portable return shape shared with the
+        0 when there is no auto-increment key - the portable return shape shared with the
         psql lib (which returns the RETURNING rowcount).
         """
         cols = list(values.keys())
@@ -330,7 +325,7 @@ class MysqlDB:
     async def get(self, table: str, conditions: Optional[Dict[str, Any]] = None) -> List[dict]:
         """SELECT * rows matching equality `conditions` (col = val AND ...) as dicts
 
-        conditions=None/{} returns all rows. simple equality only — anything more complex
+        conditions=None/{} returns all rows. simple equality only - anything more complex
         goes through raw fetch().
         """
         where, params = _where(conditions)
@@ -377,16 +372,12 @@ class MysqlDB:
         return bool(_first_value(row)) if row else False
 
     async def upsert(self, table: str, values: Dict[str, Any], conflict: Sequence[str]) -> int:
-        """INSERT ... ON DUPLICATE KEY UPDATE — insert or update on unique/pk clash
+        """INSERT ... ON DUPLICATE KEY UPDATE - insert or update on unique/pk clash
 
-        `conflict` is the list of columns forming the unique/pk constraint. mysql upserts
-        on ANY unique-key clash (it does not name the constraint the way postgres does), so
-        `conflict` is accepted for call-signature parity with psql but the constraint is
-        whatever unique/pk key the row violates. returns the affected rowcount. emits the
-        `col = VALUES(col)` update form, deprecated since MySQL 8.0.20 (warning 1287, still
-        functional) and unaffected on MariaDB; a future MySQL-only build could probe
-        `SELECT VERSION()` and switch to alias syntax, not done here as a documented cost/
-        benefit call, not an oversight.
+        `conflict` is accepted for call-signature parity with psql, but mysql upserts on
+        ANY unique/pk clash (it does not name the constraint like postgres). returns the
+        affected rowcount. emits the `col = VALUES(col)` update form, deprecated since
+        MySQL 8.0.20 (warning 1287, still functional); unaffected on MariaDB.
         """
         cols = list(values.keys())
         placeholders = ", ".join(["%s"] * len(cols))
@@ -421,7 +412,7 @@ class _Transaction:
             await self._conn.begin()
         except BaseException:
             # __aexit__ never runs if __aenter__ raises, so begin() failing after acquire
-            # would otherwise leak the pooled connection — release it here instead.
+            # would otherwise leak the pooled connection - release it here instead.
             await self._pool.release(self._conn)
             self._conn = None
             raise