chore: bump to 1.1.0 (logging-discipline audit)

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

README.md

@@ -8,18 +8,18 @@ helpers for the common paths, with a raw escape hatch for everything else.
 `requirements.txt`:
 
 ```
-mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v0.1.6
+mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v1.0.0
 ```
 
 Direct:
 
 ```bash
-pip install "mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v0.1.6"
+pip install "mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v1.0.0"
 ```
 
 Requires `motor` and `pymongo` (pulled transitively).
 
-Drop the `@v0.1.6` suffix from the line above to install the latest unpinned.
+Drop the `@v1.0.0` suffix from the line above to install the latest unpinned.
 
 ## Usage
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mongo"
-version = "0.1.6"
+version = "1.1.0"
 description = "async mongodb wrapper over motor with a raw escape hatch"
 requires-python = ">=3.10"
 dependencies = [

src/mongo/__init__.py

@@ -1,18 +1,18 @@
+from importlib.metadata import PackageNotFoundError, version
+
 from .mongo import MongoDB, Mongo, init, instance
 
 __all__ = ["MongoDB", "Mongo", "init", "instance"]
 
+try:
+    __version__ = version("mongo")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
 
 def __getattr__(name: str):
-    """proxy bare package attribute access to the default instance (PEP 562)
+    """proxy bare attribute access to the default instance (PEP 562); needs
-
+    `import mongo`, not `from mongo import func` (resolved before init)"""
-    lets `import mongo; await mongo.get_documents(...)` work after init().
-    `from mongo import func` still won't see this (resolved before init).
-    note: the bare-proxy raw escape hatch is `mongo.collection(name)`, not
-    `mongo[name]` — module-level subscripting isn't a thing in python, so the proxy
-    can only forward named attributes. on a Mongo instance both `db[name]` and
-    `db.collection(name)` work.
-    """
     if not name.startswith("_") and hasattr(MongoDB, name):
         return getattr(instance(), name)
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/mongo/mongo.py

@@ -1,49 +1,24 @@
 """
-async mongodb wrapper over motor
+async mongodb wrapper over motor, with a raw escape hatch for anything not wrapped
 
-object (preferred), one client per process:
     from mongo import MongoDB
-    bot.db = MongoDB(conn_string, database)
+    db = MongoDB(conn_string, database)
-    await bot.db.connect()                    # optional: ping to fail-early
+    await db.get_documents("users", {"active": True})
-    await bot.db.get_documents("users", {"active": True})
-    bot.db.close()                            # on shutdown (sync)
 
-    # async with (guaranteed cleanup):
+`Mongo` is a back-compat alias of `MongoDB`. A module-proxy path also exists
-    async with MongoDB(conn_string, database) as db:
+(`mongo.init(...)` then bare `mongo.func(...)`) - see README for both usage patterns.
-        await db.get_documents("users", {})
 
-`Mongo` remains a back-compat alias of `MongoDB` — existing `Mongo(...)` call sites keep
+errors: wrapped methods log and swallow, returning a safe default (False / [] / {} / 0 /
-working unchanged.
+None). .collection(name) / db[name] return the raw motor collection: full driver surface,
-
+raises, nothing swallowed. mongo SWALLOWS by design, unlike the fail-loud redis/psql/mysql
-module proxy (back-compat), arm once then call bare:
+trio - kept so existing consumers' branch-on-result control flow doesn't break.
-    import mongo                              # not `from mongo import ...`
-    mongo.init(conn_string, database)
-    await mongo.get_documents("users", {"active": True})
-
-errors:
-    wrapped methods log and swallow, returning a safe default
-    (False / [] / {} / 0 / None). .collection(name) / db[name] return
-    the raw motor collection: full driver surface, raises, nothing swallowed.
-    NOTE: mongo SWALLOWS by design — this is the one deliberate difference from the
-    newer datastore trio (redis/psql/mysql), which is fail-loud. mongo's contract is
-    kept as-is so existing consumers' branch-on-result control flow doesn't break.
-
-naming consistency with the trio (all additive — old names still work):
-    - class is `MongoDB` (was `Mongo`, kept as alias)
-    - `connect()` / `async with` like the trio (motor connects lazily, so connect()
-      just pings to validate early)
-    - `exists()` aliases `check_document_exists()`; `delete()` aliases `delete_document()`
-
-notes:
-    - the proxy needs `import mongo`; `from mongo import func` resolves before init
-    - find_one_and_update returns the after-image by default
-    - bulk_write takes caller-built pymongo ops (UpdateOne/DeleteOne/...)
 """
 
 import logging
 from typing import Any, List, Optional
 
 from pymongo import ReturnDocument
+from pymongo.errors import BulkWriteError
 from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorCollection, AsyncIOMotorDatabase
 
 log = logging.getLogger(__name__)
@@ -53,23 +28,20 @@ class MongoDB:
     """async mongodb wrapper; one client per process, attach to bot as bot.db"""
 
     def __init__(self, connection_string: str, database: str):
-        # motor builds the client eagerly here (no network I/O yet). a syntactically
-        # malformed URI (e.g. "mongodb://") makes the driver raise InvalidURI at
-        # construction, before connect() — a deploy-time value, so it surfaces at startup
-        # either way and there is nothing to clean up.
         self._client = AsyncIOMotorClient(connection_string)
+        try:
             self._db = self._client[database]
+        except BaseException:
+            self._client.close()
+            raise
 
     async def connect(self) -> "MongoDB":
-        """validate the connection with a ping and return self
+        """validate the connection with a ping and return self; raises, unlike the
+        swallowing wrapped methods
 
-        motor connects lazily, so this is optional — call it to fail early on a bad
+        an instance is single-use: pymongo 4.x `close()` is irreversible and
-        URI/credentials rather than on the first real op (parallel to the trio's
+        connect() doesn't rebuild the client. construct a fresh MongoDB instead of
-        connect()). raises on a bad connection, unlike the swallowing wrapped methods.
+        reusing one after close()/`async with` exit.
-
-        an instance is single-use: pymongo 4.x `close()` is irreversible, and connect()
-        only pings (it does not rebuild the client). do not reuse an instance after
-        close()/`async with` exit — construct a fresh MongoDB.
         """
         await self._client.admin.command("ping")
         return self
@@ -78,10 +50,8 @@ class MongoDB:
         try:
             return await self.connect()
         except BaseException:
-            # connect()/ping failing here would otherwise leak the motor client (built
+            # __aexit__ isn't called when __aenter__ raises; close here so the
-            # eagerly in __init__ with a background topology monitor + pool) — __aexit__
+            # client built in __init__ doesn't leak
-            # is not called when __aenter__ raises. close it before propagating so a
-            # retry loop against a flapping server doesn't accumulate live clients.
             self.close()
             raise
 
@@ -111,7 +81,7 @@ class MongoDB:
             return False
 
     def close(self) -> None:
-        """close the client pool on shutdown (sync — motor's close() is synchronous)"""
+        """close the client pool on shutdown (sync - motor's close() is synchronous)"""
         self._client.close()
 
     # -------------------------------------------------------------------------
@@ -120,29 +90,27 @@ class MongoDB:
     async def create_collection(self, collection: str, index=None) -> bool:
         """create a collection, optionally seeding ONE index
 
-        `index` is a single index key-spec (e.g. `[("a", 1), ("b", 1)]` builds one
+        `index` is a single key-spec (e.g. `[("a", 1), ("b", 1)]` builds one compound
-        compound index, NOT two). for multiple indexes call `create_index` per index.
+        index, not two) - call create_index per index for multiples
-        renamed from `indexes` in v0.1.6 to reflect that it seeds a single index; pass it
-        positionally, or update a keyword call site from `indexes=` to `index=`.
         """
         try:
             await self._db.create_collection(collection)
             if index:
                 await self._db[collection].create_index(index)
-                log.info(f"created index for {collection}")
+                log.info("created index for %s", collection)
             return True
         except Exception:
-            log.exception(f"db.create_collection() for {collection}")
+            log.exception("db.create_collection() for %s", collection)
             return False
 
     async def create_index(self, collection: str, index, **kwargs) -> bool:
         """create an index; kwargs pass through (unique=True, name=..., etc)"""
         try:
             await self._db[collection].create_index(index, **kwargs)
-            log.info(f"created index for {collection}")
+            log.info("created index for %s", collection)
             return True
         except Exception:
-            log.exception(f"db.create_index() for {collection}")
+            log.exception("db.create_index() for %s", collection)
             return False
 
     async def drop_collection(self, collection: str) -> bool:
@@ -151,7 +119,7 @@ class MongoDB:
             await self._db.drop_collection(collection)
             return True
         except Exception:
-            log.exception(f"db.drop_collection() for {collection}")
+            log.exception("db.drop_collection() for %s", collection)
             return False
 
     async def check_collection_exists(self, collection: str) -> bool:
@@ -159,7 +127,7 @@ class MongoDB:
         try:
             return collection in await self._db.list_collection_names()
         except Exception:
-            log.exception(f"db.check_collection_exists() for {collection}")
+            log.exception("db.check_collection_exists() for %s", collection)
             return False
 
     async def list_collections(self) -> List[str]:
@@ -179,18 +147,27 @@ class MongoDB:
             await self._db[collection].insert_one(document)
             return True
         except Exception:
-            log.exception(f"db.create_document() on {collection}")
+            log.exception("db.create_document() on %s", collection)
             return False
 
     async def create_documents(
         self, collection: str, documents: List[dict], ordered: bool = True
     ) -> int:
-        """insert many documents, returning the inserted count"""
+        """insert many documents, returning the inserted count
+
+        on a partial failure (e.g. ordered=False with one duplicate key) the driver
+        raises BulkWriteError AFTER inserting the rest; count comes from
+        `e.details['nInserted']` so a caller retrying on a wrongly-reported 0 doesn't
+        re-insert documents that already landed.
+        """
         try:
             result = await self._db[collection].insert_many(documents, ordered=ordered)
             return len(result.inserted_ids)
+        except BulkWriteError as e:
+            log.exception("db.create_documents() on %s", collection)
+            return e.details.get("nInserted", 0)
         except Exception:
-            log.exception(f"db.create_documents() on {collection}")
+            log.exception("db.create_documents() on %s", collection)
             return 0
 
     # -------------------------------------------------------------------------
@@ -203,7 +180,7 @@ class MongoDB:
         try:
             return await self._db[collection].find_one(target, fields)
         except Exception:
-            log.exception(f"db.get_document() on {collection}")
+            log.exception("db.get_document() on %s", collection)
             return None
 
     async def get_documents(
@@ -214,7 +191,7 @@ class MongoDB:
             cursor = self._db[collection].find(target, fields)
             return [doc async for doc in cursor]
         except Exception:
-            log.exception(f"db.get_documents() on {collection}")
+            log.exception("db.get_documents() on %s", collection)
             return []
 
     async def get_documents_sorted(
@@ -232,7 +209,7 @@ class MongoDB:
             )
             return [doc async for doc in cursor]
         except Exception:
-            log.exception(f"db.get_documents_sorted() on {collection}")
+            log.exception("db.get_documents_sorted() on %s", collection)
             return []
 
     async def get_document_hashmap(self, collection: str, target: dict, key: str) -> dict:
@@ -245,7 +222,7 @@ class MongoDB:
             cursor = self._db[collection].find(target)
             return {doc[key]: doc async for doc in cursor if key in doc}
         except Exception:
-            log.exception(f"db.get_document_hashmap() on {collection}")
+            log.exception("db.get_document_hashmap() on %s", collection)
             return {}
 
     async def get_document_fields(
@@ -260,7 +237,7 @@ class MongoDB:
             cursor = self._db[collection].find(target, fields)
             return [doc[key] async for doc in cursor if key in doc]
         except Exception:
-            log.exception(f"db.get_document_fields() on {collection}")
+            log.exception("db.get_document_fields() on %s", collection)
             return []
 
     async def count_documents(self, collection: str, target: dict) -> int:
@@ -268,7 +245,7 @@ class MongoDB:
         try:
             return await self._db[collection].count_documents(target)
         except Exception:
-            log.exception(f"db.count_documents() on {collection}")
+            log.exception("db.count_documents() on %s", collection)
             return 0
 
     async def check_document_exists(self, collection: str, target: dict) -> bool:
@@ -276,7 +253,7 @@ class MongoDB:
         try:
             return await self._db[collection].count_documents(target, limit=1) > 0
         except Exception:
-            log.exception(f"db.check_document_exists() on {collection}")
+            log.exception("db.check_document_exists() on %s", collection)
             return False
 
     async def exists(self, collection: str, target: dict) -> bool:
@@ -288,7 +265,7 @@ class MongoDB:
         try:
             return await self._db[collection].count_documents({array_field: value})
         except Exception:
-            log.exception(f"db.count_value_in_array() on {collection}")
+            log.exception("db.count_value_in_array() on %s", collection)
             return 0
 
     async def exists_in_array(self, collection: str, array_field: str, value: str) -> bool:
@@ -297,7 +274,7 @@ class MongoDB:
             doc = await self._db[collection].find_one({array_field: value}, {"_id": 1})
             return doc is not None
         except Exception:
-            log.exception(f"db.exists_in_array() on {collection}")
+            log.exception("db.exists_in_array() on %s", collection)
             return False
 
     async def distinct(self, collection: str, field: str, target: Optional[dict] = None) -> List:
@@ -305,7 +282,7 @@ class MongoDB:
         try:
             return await self._db[collection].distinct(field, target or {})
         except Exception:
-            log.exception(f"db.distinct() on {collection}")
+            log.exception("db.distinct() on %s", collection)
             return []
 
     async def run_aggregation(
@@ -316,7 +293,7 @@ class MongoDB:
             stages = [{"$match": match_filter}, *pipeline] if match_filter else pipeline
             return await self._db[collection].aggregate(stages).to_list(length=None)
         except Exception:
-            log.exception(f"db.run_aggregation() on {collection}")
+            log.exception("db.run_aggregation() on %s", collection)
             return []
 
     async def search_documents(
@@ -327,7 +304,7 @@ class MongoDB:
             cursor = self._db[collection].find(search_query).sort(sort_key, sort_order)
             return [doc async for doc in cursor]
         except Exception:
-            log.exception(f"db.search_documents() on {collection}")
+            log.exception("db.search_documents() on %s", collection)
             return []
 
     async def search_indexes(self, collection: str, search_term: str) -> List[dict]:
@@ -339,7 +316,7 @@ class MongoDB:
             ).sort([("score", {"$meta": "textScore"})])
             return [doc async for doc in cursor]
         except Exception:
-            log.exception(f"db.search_indexes() on {collection}")
+            log.exception("db.search_indexes() on %s", collection)
             return []
 
     # -------------------------------------------------------------------------
@@ -353,7 +330,7 @@ class MongoDB:
             response = await self._db[collection].replace_one(target, document, upsert=upsert)
             return bool(response.matched_count or response.upserted_id)
         except Exception:
-            log.exception(f"db.update_document() on {collection}")
+            log.exception("db.update_document() on %s", collection)
             return False
 
     async def update_documents(self, collection: str, target: dict, values: dict) -> int:
@@ -362,21 +339,21 @@ class MongoDB:
             response = await self._db[collection].update_many(target, values)
             return response.modified_count
         except Exception:
-            log.exception(f"db.update_documents() on {collection}")
+            log.exception("db.update_documents() on %s", collection)
             return 0
 
     async def update_document_field(self, collection: str, target: dict, updates: dict) -> bool:
         """$set one or more fields on a single document
 
-        returns True when a document matched, even if the write changed nothing (a
+        returns True when a document matched, even if `$set` to an identical value
-        `$set` to the identical value leaves `modified_count=0`); use `matched_count`
+        leaves `modified_count=0` - uses `matched_count` so an idempotent no-op isn't
-        so an idempotent no-op on an existing doc isn't misread as a failure.
+        misread as a failure.
         """
         try:
             response = await self._db[collection].update_one(target, {"$set": updates})
             return response.matched_count > 0
         except Exception:
-            log.exception(f"db.update_document_field() on {collection}")
+            log.exception("db.update_document_field() on %s", collection)
             return False
 
     async def update_document_operator(
@@ -384,26 +361,30 @@ class MongoDB:
     ) -> bool:
         """apply raw update operators ($set/$inc/$unset/...) to a single document
 
-        returns True when a document matched, even if the operators changed nothing
+        returns True when a document matched, even if the operators changed nothing -
-        (e.g. `$set` to an identical value) — use `matched_count` so an idempotent
+        uses `matched_count` so an idempotent write isn't misread as a failure.
-        write on an existing doc isn't misread as a failure.
         """
         try:
             response = await self._db[collection].update_one(target, update_query)
             return response.matched_count > 0
         except Exception:
-            log.exception(f"db.update_document_operator() on {collection}")
+            log.exception("db.update_document_operator() on %s", collection)
             return False
 
     async def upsert_document_field(self, collection: str, target: dict, updates: dict) -> bool:
-        """$set fields on a single document, creating it if absent"""
+        """$set fields on a single document, creating it if absent
+
+        returns True when a document matched or was upserted, even if `$set` to an
+        identical value leaves `modified_count=0` - mirrors update_document_field's
+        matched_count-over-modified_count contract.
+        """
         try:
             response = await self._db[collection].update_one(
                 target, {"$set": updates}, upsert=True
             )
-            return bool(response.modified_count or response.upserted_id)
+            return bool(response.matched_count or response.upserted_id)
         except Exception:
-            log.exception(f"db.upsert_document_field() on {collection}")
+            log.exception("db.upsert_document_field() on %s", collection)
             return False
 
     async def update_documents_pipeline(
@@ -414,7 +395,7 @@ class MongoDB:
             response = await self._db[collection].update_many(target, pipeline)
             return response.modified_count
         except Exception:
-            log.exception(f"db.update_documents_pipeline() on {collection}")
+            log.exception("db.update_documents_pipeline() on %s", collection)
             return 0
 
     async def document_push_array(
@@ -422,15 +403,14 @@ class MongoDB:
     ) -> bool:
         """$push a value onto an array field
 
-        returns True when a document matched (consistent with the other single-doc
+        returns True when a document matched; $push always mutates, so matched_count
-        update helpers); $push always mutates, so matched_count and modified_count
+        and modified_count agree here in practice.
-        agree here in practice.
         """
         try:
             response = await self._db[collection].update_one(target, {"$push": {array: value}})
             return response.matched_count > 0
         except Exception:
-            log.exception(f"db.document_push_array() on {collection}")
+            log.exception("db.document_push_array() on %s", collection)
             return False
 
     async def document_push_and_set(
@@ -439,8 +419,7 @@ class MongoDB:
     ) -> bool:
         """$push to an array and $set a field in one update
 
-        returns True when a document matched (consistent with the other single-doc
+        returns True when a document matched (matched_count, not modified_count).
-        update helpers).
         """
         try:
             response = await self._db[collection].update_one(
@@ -449,7 +428,7 @@ class MongoDB:
             )
             return response.matched_count > 0
         except Exception:
-            log.exception(f"db.document_push_and_set() on {collection}")
+            log.exception("db.document_push_and_set() on %s", collection)
             return False
 
     async def document_pop_array(
@@ -457,15 +436,14 @@ class MongoDB:
     ) -> bool:
         """$pull a value from an array field
 
-        returns True when a document matched, even if nothing was pulled (the value
+        returns True when a document matched, even if the value was absent and
-        was absent) — use `matched_count` so a no-op pull on an existing doc isn't
+        nothing was pulled - uses `matched_count`, not `modified_count`.
-        misread as a failure.
         """
         try:
             response = await self._db[collection].update_one(target, {"$pull": {array: value}})
             return response.matched_count > 0
         except Exception:
-            log.exception(f"db.document_pop_array() on {collection}")
+            log.exception("db.document_pop_array() on %s", collection)
             return False
 
     async def find_one_and_update(
@@ -481,7 +459,7 @@ class MongoDB:
                 return_document=ReturnDocument.AFTER if return_after else ReturnDocument.BEFORE,
             )
         except Exception:
-            log.exception(f"db.find_one_and_update() on {collection}")
+            log.exception("db.find_one_and_update() on %s", collection)
             return None
 
     async def find_one_and_replace(
@@ -497,7 +475,7 @@ class MongoDB:
                 return_document=ReturnDocument.AFTER if return_after else ReturnDocument.BEFORE,
             )
         except Exception:
-            log.exception(f"db.find_one_and_replace() on {collection}")
+            log.exception("db.find_one_and_replace() on %s", collection)
             return None
 
     async def find_one_and_delete(
@@ -507,7 +485,7 @@ class MongoDB:
         try:
             return await self._db[collection].find_one_and_delete(target, projection=fields)
         except Exception:
-            log.exception(f"db.find_one_and_delete() on {collection}")
+            log.exception("db.find_one_and_delete() on %s", collection)
             return None
 
     # -------------------------------------------------------------------------
@@ -519,7 +497,7 @@ class MongoDB:
             response = await self._db[collection].delete_one(target)
             return response.deleted_count
         except Exception:
-            log.exception(f"db.delete_document() on {collection}")
+            log.exception("db.delete_document() on %s", collection)
             return 0
 
     async def delete(self, collection: str, target: dict) -> int:
@@ -532,17 +510,16 @@ class MongoDB:
             response = await self._db[collection].delete_many(target)
             return response.deleted_count
         except Exception:
-            log.exception(f"db.delete_documents() on {collection}")
+            log.exception("db.delete_documents() on %s", collection)
             return 0
 
     # -------------------------------------------------------------------------
     #   bulk / checks
 
     async def bulk_write(self, collection: str, operations: list, ordered: bool = True) -> dict:
-        """
+        """run a batch of pymongo write ops (InsertOne/UpdateOne/DeleteOne/...)
-        run a batch of pymongo write ops (InsertOne/UpdateOne/DeleteOne/...)
 
-        caller builds the ops from pymongo, e.g.:
+        caller builds the ops, e.g.:
             from pymongo import UpdateOne
             ops = [UpdateOne({'_id': i}, {'$set': {...}}, upsert=True) for i in ids]
         returns a summary dict of counts, or an empty dict on failure
@@ -557,14 +534,13 @@ class MongoDB:
                 "upserted": result.upserted_count,
             }
         except Exception:
-            log.exception(f"db.bulk_write() on {collection}")
+            log.exception("db.bulk_write() on %s", collection)
             return {}
 
     async def document_check_multi(
         self, collection: str, target: dict, checks: List[str], value: str
     ) -> bool:
-        """
+        """return whether a doc matching target has value in any of the given arrays
-        return whether a doc matching target has value in any of the given arrays
 
         target is a normal filter dict (merged into the query), not a bare _id
         """
@@ -575,7 +551,7 @@ class MongoDB:
             }
             return await self._db[collection].find_one(query) is not None
         except Exception:
-            log.exception(f"db.document_check_multi() on {collection}")
+            log.exception("db.document_check_multi() on %s", collection)
             return False
 
 
@@ -585,12 +561,9 @@ Mongo = MongoDB
 
 
 # -----------------------------------------------------------------------------
-#   backwards-compat module proxy
+#   backwards-compat module proxy: `import mongo; mongo.init(conn, db)` then
-#       - lets legacy call sites keep using `await mongo.get_documents(...)`
+#   bare `await mongo.func(...)`. needs `import mongo` - `from mongo import func`
-#         without an object, after a one-time `mongo.init(conn, db)`
+#   resolves at import time, before init() runs.
-#       - works with `import mongo; mongo.func(...)` (resolved at call time)
-#       - does NOT work with `from mongo import func` (resolved at import,
-#         before init runs) — switch those sites to `import mongo`
 
 _default: Optional[MongoDB] = None