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>

.gitignore

@@ -1,5 +1,5 @@
 # claude
-CLAUDE.md
+.claude/
 
 # python
 __pycache__/

README.md

@@ -8,29 +8,39 @@ 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.0
+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.0"
+pip install "mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v1.0.0"
 ```
 
 Requires `motor` and `pymongo` (pulled transitively).
 
+Drop the `@v1.0.0` suffix from the line above to install the latest unpinned.
+
 ## Usage
 
 **Object (preferred)** — one client per process:
 
 ```python
-from mongo import Mongo
+from mongo import MongoDB
 
-db = Mongo(conn_string, database)          # attach as bot.db / app.db
+db = MongoDB(conn_string, database)         # attach as bot.db / app.db
+await db.connect()                          # optional: ping to fail-early on a bad URI
 users = await db.get_documents("users", {"active": True})
 db.close()                                  # on shutdown (sync)
+
+# or with guaranteed cleanup:
+async with MongoDB(conn_string, database) as db:
+    await db.get_documents("users", {"active": True})
 ```
 
+The class is `MongoDB`; **`Mongo` remains a back-compat alias** (`Mongo = MongoDB`), so
+existing `Mongo(...)` call sites keep working unchanged.
+
 **Module proxy (back-compat)** — arm once, then call bare:
 
 ```python
@@ -42,10 +52,26 @@ users = await mongo.get_documents("users", {"active": True})
 Both styles share one client. The proxy exists so legacy call sites keep working
 after a one-line `init()`; new code should use the object.
 
+## Naming consistency with the datastore trio
+
+mongo predates the `redis`/`psql`/`mysql` trio; this version makes it surface-consistent
+**without breaking anything** (all additive, every old name preserved):
+
+- class is **`MongoDB`** (with `Mongo` kept as an 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()` — old names still work, the trio-consistent names are now available
+
+The one deliberate difference that remains: **mongo swallows** (see below) where the trio
+is **fail-loud**. That's intentional — flipping it would break existing consumers' branch-
+on-result control flow.
+
 ## Error contract
 
 - **Wrapped methods** log-and-swallow exceptions and return a safe default
-  (`False` / `[]` / `{}` / `0` / `None`). Branch on the result.
+  (`False` / `[]` / `{}` / `0` / `None`). Branch on the result. (`connect()` is the
+  exception — it raises on a bad connection so you can fail-early.)
 - **`db.collection(name)`** (or `db[name]`) returns the raw motor collection:
   full driver surface, no swallowing, **raises**. Use it for anything not wrapped
   (`find_one_and_*` beyond what's exposed, change streams, complex bulk ops).
@@ -61,6 +87,9 @@ are included.
 
 - `from mongo import func` won't see the proxy (resolved at import, before `init`).
   Use `import mongo` then `mongo.func(...)`.
+- `create_collection(collection, index=...)` seeds **one** index (the param is `index`,
+  renamed from `indexes` in v0.1.6). A key-spec like `[("a",1),("b",1)]` builds one
+  compound index, not two — call `create_index` per index for multiples.
 - `find_one_and_update` returns the **after** image by default (`return_after=True`).
 - `bulk_write` takes pymongo ops the caller builds:
   ```python
@@ -71,4 +100,4 @@ are included.
 
 ## Versioning
 
-Tagged `vX.Y.Z`. Pin the tag in `requirements.txt`; bump deliberately.
+Releases are tagged `vX.Y.Z`. The install line above pins a release; drop the `@vX.Y.Z` suffix to install the latest unpinned. Pin deliberately for reproducible installs.

pyproject.toml

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

src/mongo/__init__.py

@@ -1,14 +1,18 @@
-from .mongo import Mongo, init, instance
+from importlib.metadata import PackageNotFoundError, version
 
-__all__ = ["Mongo", "init", "instance"]
+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().
+    if not name.startswith("_") and hasattr(MongoDB, name):
-    `from mongo import func` still won't see this (resolved before init)
-    """
-    if not name.startswith("_") and hasattr(Mongo, name):
         return getattr(instance(), name)
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/mongo/mongo.py

@@ -1,43 +1,62 @@
 """
-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
-    from mongo import Mongo
+    db = MongoDB(conn_string, database)
-    bot.db = Mongo(conn_string, database)
+    await db.get_documents("users", {"active": True})
-    await bot.db.get_documents("users", {"active": True})
-    bot.db.close()                            # on shutdown (sync)
 
-module proxy (back-compat), arm once then call bare:
+`Mongo` is a back-compat alias of `MongoDB`. A module-proxy path also exists
-    import mongo                              # not `from mongo import ...`
+(`mongo.init(...)` then bare `mongo.func(...)`) - see README for both usage patterns.
-    mongo.init(conn_string, database)
-    await mongo.get_documents("users", {"active": True})
 
-errors:
+errors: wrapped methods log and swallow, returning a safe default (False / [] / {} / 0 /
-    wrapped methods log and swallow, returning a safe default
+None). .collection(name) / db[name] return the raw motor collection: full driver surface,
-    (False / [] / {} / 0 / None). .collection(name) / db[name] return
+raises, nothing swallowed. mongo SWALLOWS by design, unlike the fail-loud redis/psql/mysql
-    the raw motor collection: full driver surface, raises, nothing swallowed.
+trio - kept so existing consumers' branch-on-result control flow doesn't break.
-
-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 motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorCollection
+from pymongo.errors import BulkWriteError
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorCollection, AsyncIOMotorDatabase
 
 log = logging.getLogger(__name__)
 
 
-class Mongo:
+class MongoDB:
     """async mongodb wrapper; one client per process, attach to bot as bot.db"""
 
     def __init__(self, connection_string: str, database: str):
         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; raises, unlike the
+        swallowing wrapped methods
+
+        an instance is single-use: pymongo 4.x `close()` is irreversible and
+        connect() doesn't rebuild the client. construct a fresh MongoDB instead of
+        reusing one after close()/`async with` exit.
+        """
+        await self._client.admin.command("ping")
+        return self
+
+    async def __aenter__(self) -> "MongoDB":
+        try:
+            return await self.connect()
+        except BaseException:
+            # __aexit__ isn't called when __aenter__ raises; close here so the
+            # client built in __init__ doesn't leak
+            self.close()
+            raise
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        self.close()
 
     def __getitem__(self, collection: str) -> AsyncIOMotorCollection:
         """raw collection access via subscript: bot.db['users'].aggregate(...)"""
@@ -48,7 +67,7 @@ class Mongo:
         return self._db[name]
 
     @property
-    def database(self):
+    def database(self) -> AsyncIOMotorDatabase:
         """raw motor database handle"""
         return self._db
 
@@ -62,19 +81,23 @@ class Mongo:
             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()
 
     # -------------------------------------------------------------------------
     #   collection / index management
 
-    async def create_collection(self, collection: str, indexes=None) -> bool:
+    async def create_collection(self, collection: str, index=None) -> bool:
-        """create a collection, optionally seeding an index"""
+        """create a collection, optionally seeding ONE index
+
+        `index` is a single key-spec (e.g. `[("a", 1), ("b", 1)]` builds one compound
+        index, not two) - call create_index per index for multiples
+        """
         try:
             await self._db.create_collection(collection)
-            if indexes:
+            if index:
-                await self._db[collection].create_index(indexes)
+                await self._db[collection].create_index(index)
-                log.info(f"created indexes for {collection}")
+                log.info(f"created index for {collection}")
             return True
         except Exception:
             log.exception(f"db.create_collection() for {collection}")
@@ -130,10 +153,19 @@ class Mongo:
     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(f"db.create_documents() on {collection}")
+            return e.details.get("nInserted", 0)
         except Exception:
             log.exception(f"db.create_documents() on {collection}")
             return 0
@@ -181,7 +213,11 @@ class Mongo:
             return []
 
     async def get_document_hashmap(self, collection: str, target: dict, key: str) -> dict:
-        """return matching documents keyed into a dict by the given field"""
+        """return matching documents keyed into a dict by the given field
+
+        documents missing `key` are skipped (not in the result); a later document
+        with a duplicate key value overwrites an earlier one.
+        """
         try:
             cursor = self._db[collection].find(target)
             return {doc[key]: doc async for doc in cursor if key in doc}
@@ -192,7 +228,11 @@ class Mongo:
     async def get_document_fields(
         self, collection: str, target: dict, key: str, fields: Optional[dict] = None
     ) -> List:
-        """return a flat list of one field's value across matching documents"""
+        """return a flat list of one field's value across matching documents
+
+        documents missing `key` are skipped, so the list length may be smaller than
+        the match count.
+        """
         try:
             cursor = self._db[collection].find(target, fields)
             return [doc[key] async for doc in cursor if key in doc]
@@ -208,6 +248,18 @@ class Mongo:
             log.exception(f"db.count_documents() on {collection}")
             return 0
 
+    async def check_document_exists(self, collection: str, target: dict) -> bool:
+        """return whether at least one document in collection matches target"""
+        try:
+            return await self._db[collection].count_documents(target, limit=1) > 0
+        except Exception:
+            log.exception(f"db.check_document_exists() on {collection}")
+            return False
+
+    async def exists(self, collection: str, target: dict) -> bool:
+        """trio-consistent alias of check_document_exists"""
+        return await self.check_document_exists(collection, target)
+
     async def count_value_in_array(self, collection: str, array_field: str, value: str) -> int:
         """count documents whose array field contains value"""
         try:
@@ -271,11 +323,11 @@ class Mongo:
     #   update
 
     async def update_document(
-        self, collection: str, target: dict, document: dict, do_upsert: bool = False
+        self, collection: str, target: dict, document: dict, upsert: bool = False
     ) -> bool:
         """replace a whole document, optionally upserting"""
         try:
-            response = await self._db[collection].replace_one(target, document, upsert=do_upsert)
+            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}")
@@ -291,10 +343,15 @@ class Mongo:
             return 0
 
     async def update_document_field(self, collection: str, target: dict, updates: dict) -> bool:
-        """$set one or more fields on a single document"""
+        """$set one or more fields on a single document
+
+        returns True when a document matched, even if `$set` to an identical value
+        leaves `modified_count=0` - uses `matched_count` so an idempotent no-op isn't
+        misread as a failure.
+        """
         try:
             response = await self._db[collection].update_one(target, {"$set": updates})
-            return response.modified_count > 0
+            return response.matched_count > 0
         except Exception:
             log.exception(f"db.update_document_field() on {collection}")
             return False
@@ -302,21 +359,30 @@ class Mongo:
     async def update_document_operator(
         self, collection: str, target: dict, update_query: dict
     ) -> bool:
-        """apply raw update operators ($set/$inc/$unset/...) to a single document"""
+        """apply raw update operators ($set/$inc/$unset/...) to a single document
+
+        returns True when a document matched, even if the operators changed nothing -
+        uses `matched_count` so an idempotent write isn't misread as a failure.
+        """
         try:
             response = await self._db[collection].update_one(target, update_query)
-            return response.modified_count > 0
+            return response.matched_count > 0
         except Exception:
             log.exception(f"db.update_document_operator() on {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}")
             return False
@@ -335,10 +401,14 @@ class Mongo:
     async def document_push_array(
         self, collection: str, target: dict, array: str, value: Any
     ) -> bool:
-        """$push a value onto an array field"""
+        """$push a value onto an array field
+
+        returns True when a document matched; $push always mutates, so matched_count
+        and modified_count agree here in practice.
+        """
         try:
             response = await self._db[collection].update_one(target, {"$push": {array: value}})
-            return response.modified_count > 0
+            return response.matched_count > 0
         except Exception:
             log.exception(f"db.document_push_array() on {collection}")
             return False
@@ -347,13 +417,16 @@ class Mongo:
         self, collection: str, target: dict, array: str, value: Any,
         field_to_set: str, set_value: Any,
     ) -> bool:
-        """$push to an array and $set a field in one update"""
+        """$push to an array and $set a field in one update
+
+        returns True when a document matched (matched_count, not modified_count).
+        """
         try:
             response = await self._db[collection].update_one(
                 target,
                 {"$push": {array: value}, "$set": {field_to_set: set_value}},
             )
-            return response.modified_count > 0
+            return response.matched_count > 0
         except Exception:
             log.exception(f"db.document_push_and_set() on {collection}")
             return False
@@ -361,24 +434,28 @@ class Mongo:
     async def document_pop_array(
         self, collection: str, target: dict, array: str, value: Any
     ) -> bool:
-        """$pull a value from an array field"""
+        """$pull a value from an array field
+
+        returns True when a document matched, even if the value was absent and
+        nothing was pulled - uses `matched_count`, not `modified_count`.
+        """
         try:
             response = await self._db[collection].update_one(target, {"$pull": {array: value}})
-            return response.modified_count > 0
+            return response.matched_count > 0
         except Exception:
             log.exception(f"db.document_pop_array() on {collection}")
             return False
 
     async def find_one_and_update(
         self, collection: str, target: dict, update: dict,
-        return_after: bool = True, do_upsert: bool = False, fields: Optional[dict] = None,
+        return_after: bool = True, upsert: bool = False, fields: Optional[dict] = None,
     ) -> Optional[dict]:
         """atomically update one doc and return it (after-image by default)"""
         try:
             return await self._db[collection].find_one_and_update(
                 target, update,
                 projection=fields,
-                upsert=do_upsert,
+                upsert=upsert,
                 return_document=ReturnDocument.AFTER if return_after else ReturnDocument.BEFORE,
             )
         except Exception:
@@ -387,14 +464,14 @@ class Mongo:
 
     async def find_one_and_replace(
         self, collection: str, target: dict, document: dict,
-        return_after: bool = True, do_upsert: bool = False, fields: Optional[dict] = None,
+        return_after: bool = True, upsert: bool = False, fields: Optional[dict] = None,
     ) -> Optional[dict]:
         """atomically replace one doc and return it (after-image by default)"""
         try:
             return await self._db[collection].find_one_and_replace(
                 target, document,
                 projection=fields,
-                upsert=do_upsert,
+                upsert=upsert,
                 return_document=ReturnDocument.AFTER if return_after else ReturnDocument.BEFORE,
             )
         except Exception:
@@ -423,6 +500,10 @@ class Mongo:
             log.exception(f"db.delete_document() on {collection}")
             return 0
 
+    async def delete(self, collection: str, target: dict) -> int:
+        """trio-consistent alias of delete_document (single-document delete)"""
+        return await self.delete_document(collection, target)
+
     async def delete_documents(self, collection: str, target: dict) -> int:
         """delete all matching documents, returning deleted count"""
         try:
@@ -436,10 +517,9 @@ class Mongo:
     #   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
@@ -460,8 +540,7 @@ class Mongo:
     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
         """
@@ -476,25 +555,27 @@ class Mongo:
             return False
 
 
+# back-compat alias: the class was historically `Mongo`; existing `Mongo(...)` call
+# sites keep working unchanged
+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[Mongo] = None
+_default: Optional[MongoDB] = None
 
 
-def init(connection_string: str, database: str) -> Mongo:
+def init(connection_string: str, database: str) -> MongoDB:
     """arm the module-level default instance and return it"""
     global _default
-    _default = Mongo(connection_string, database)
+    _default = MongoDB(connection_string, database)
     return _default
 
 
-def instance() -> Mongo:
+def instance() -> MongoDB:
     """return the default instance, raising if init() has not run"""
     if _default is None:
         raise RuntimeError("mongo not initialized; call mongo.init(conn, db) first")