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.6
+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.6"
+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.6` 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
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mongo"
-version = "0.1.6"
+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__)
@@ -185,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
@@ -396,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