fix: correct wrong success predicates in upsert_document_field and create_documents

upsert_document_field returned False for an idempotent no-op upsert on an
existing document (modified_count=0, upserted_id=None) even though the doc
matched the requested state; switch to matched_count like its update_document_field
and update_document_operator siblings.

create_documents returned 0 on a partial insert_many failure, discarding the
BulkWriteError's nInserted count and inviting callers to retry the whole batch
on a wrongly-reported failure, duplicating documents that had already landed.
Catch BulkWriteError specifically and return e.details['nInserted'].

Bump to v0.1.7.

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.5
+mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v0.1.7
 ```
 
 Direct:
 
 ```bash
-pip install "mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v0.1.5"
+pip install "mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v0.1.7"
 ```
 
 Requires `motor` and `pymongo` (pulled transitively).
 
-Drop the `@v0.1.5` suffix from the line above to install the latest unpinned.
+Drop the `@v0.1.7` suffix from the line above to install the latest unpinned.
 
 ## Usage
 
@@ -87,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

pyproject.toml

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

src/mongo/mongo.py

@@ -44,6 +44,7 @@ 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,6 +54,10 @@ 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)
         self._db = self._client[database]
 
@@ -62,6 +67,10 @@ class MongoDB:
         motor connects lazily, so this is optional — call it to fail early on a bad
         URI/credentials rather than on the first real op (parallel to the trio's
         connect()). raises on a bad connection, unlike the swallowing wrapped methods.
+
+        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
@@ -109,13 +118,19 @@ class MongoDB:
     # -------------------------------------------------------------------------
     #   collection / index management
 
-    async def create_collection(self, collection: str, indexes=None) -> bool:
-        """create a collection, optionally seeding an index"""
+    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
+        compound index, NOT two). for multiple indexes call `create_index` per index.
+        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 indexes:
-                await self._db[collection].create_index(indexes)
-                log.info(f"created indexes for {collection}")
+            if index:
+                await self._db[collection].create_index(index)
+                log.info(f"created index for {collection}")
             return True
         except Exception:
             log.exception(f"db.create_collection() for {collection}")
@@ -171,10 +186,20 @@ class MongoDB:
     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 among
+        several documents) the driver raises BulkWriteError AFTER inserting the
+        non-failing documents; that count is read from `e.details['nInserted']`
+        so the return value stays honest — a caller retrying the whole batch on a
+        wrongly-reported 0 would 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
@@ -382,12 +407,18 @@ class MongoDB:
             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 the write
+        changed nothing (a `$set` to the identical value leaves `modified_count=0`);
+        use `matched_count` so an idempotent no-op upsert on an existing doc isn't
+        misread as a failure — mirrors update_document_field/update_document_operator.
+        """
         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