fix: add check_document_exists; rename do_upsert -> upsert

added check_document_exists(collection, target) -> bool (count_documents(target, limit=1) > 0) — it existed only in the talos origin and was not carried over, but the talos caller relies on it. renamed the do_upsert param to upsert on update_document/find_one_and_update/find_one_and_replace, standardizing on motor's name (the talos caller already passes upsert=). param rename is breaking; patch is fine under the no-consumer policy. bump to v0.1.1.

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

README.md

@@ -8,13 +8,13 @@ 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@v0.1.1
 ```
 
 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@v0.1.1"
 ```
 
 Requires `motor` and `pymongo` (pulled transitively).

pyproject.toml

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

src/mongo/mongo.py

@@ -208,6 +208,14 @@ 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 count_value_in_array(self, collection: str, array_field: str, value: str) -> int:
         """count documents whose array field contains value"""
         try:
@@ -271,11 +279,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}")
@@ -371,14 +379,14 @@ class Mongo:
 
     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 +395,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: