Collection Maintenance (#367)

* Adding missing truncate parameters

* Removing unused parameter

* Minor adjustments

* Removing note that is no longer relevant.

* Update arango/collection.py

Co-authored-by: Anthony Mahanna <[email protected]>

* Update arango/collection.py

Co-authored-by: Anthony Mahanna <[email protected]>

---------

Co-authored-by: Anthony Mahanna <[email protected]>

Author: apetenchea

arango/collection.py

@@ -566,15 +566,31 @@ def response_handler(resp: Response) -> bool:
 
         return self._execute(request, response_handler)
 
-    def truncate(self) -> Result[bool]:
+    def truncate(
+        self,
+        sync: Optional[bool] = None,
+        compact: Optional[bool] = None,
+    ) -> Result[bool]:
         """Delete all documents in the collection.
 
+        :param sync: Block until deletion operation is synchronized to disk.
+        :type sync: bool | None
+        :param compact: Whether to compact the collection after truncation.
+        :type compact: bool | None
         :return: True if collection was truncated successfully.
         :rtype: bool
         :raise arango.exceptions.CollectionTruncateError: If operation fails.
         """
+        params: Json = {}
+        if sync is not None:
+            params["waitForSync"] = sync
+        if compact is not None:
+            params["compact"] = compact
+
         request = Request(
-            method="put", endpoint=f"/_api/collection/{self.name}/truncate"
+            method="put",
+            endpoint=f"/_api/collection/{self.name}/truncate",
+            params=params,
         )
 
         def response_handler(resp: Response) -> bool:
@@ -1747,14 +1763,6 @@ def insert_many(
             successfully (returns document metadata) and which were not
             (returns exception object).
 
-        .. note::
-
-            In edge/vertex collections, this method does NOT provide the
-            transactional guarantees and validations that single insert
-            operation does for graphs. If these properties are required, see
-            :func:`arango.database.StandardDatabase.begin_batch_execution`
-            for an alternative approach.
-
         :param documents: List of new documents to insert. If they contain the
             "_key" or "_id" fields, the values are used as the keys of the new
             documents (auto-generated otherwise). Any "_rev" field is ignored.
@@ -1876,14 +1884,6 @@ def update_many(
             (returns exception object). Alternatively, you can rely on
             setting **raise_on_document_error** to True (defaults to False).
 
-        .. note::
-
-            In edge/vertex collections, this method does NOT provide the
-            transactional guarantees and validations that single update
-            operation does for graphs. If these properties are required, see
-            :func:`arango.database.StandardDatabase.begin_batch_execution`
-            for an alternative approach.
-
         :param documents: Partial or full documents with the updated values.
             They must contain the "_id" or "_key" fields.
         :type documents: [dict]
@@ -1995,14 +1995,6 @@ def update_match(
     ) -> Result[int]:
         """Update matching documents.
 
-        .. note::
-
-            In edge/vertex collections, this method does NOT provide the
-            transactional guarantees and validations that single update
-            operation does for graphs. If these properties are required, see
-            :func:`arango.database.StandardDatabase.begin_batch_execution`
-            for an alternative approach.
-
         :param filters: Document filters.
         :type filters: dict
         :param body: Full or partial document body with the updates.
@@ -2085,14 +2077,6 @@ def replace_many(
             successfully (returns document metadata) and which were not
             (returns exception object).
 
-        .. note::
-
-            In edge/vertex collections, this method does NOT provide the
-            transactional guarantees and validations that single replace
-            operation does for graphs. If these properties are required, see
-            :func:`arango.database.StandardDatabase.begin_batch_execution`
-            for an alternative approach.
-
         :param documents: New documents to replace the old ones with. They must
             contain the "_id" or "_key" fields. Edge documents must also have
             "_from" and "_to" fields.
@@ -2187,14 +2171,6 @@ def replace_match(
     ) -> Result[int]:
         """Replace matching documents.
 
-        .. note::
-
-            In edge/vertex collections, this method does NOT provide the
-            transactional guarantees and validations that single replace
-            operation does for graphs. If these properties are required, see
-            :func:`arango.database.StandardDatabase.begin_batch_execution`
-            for an alternative approach.
-
         :param filters: Document filters.
         :type filters: dict
         :param body: New document body.
@@ -2263,14 +2239,6 @@ def delete_many(
             successfully (returns document metadata) and which were not
             (returns exception object).
 
-        .. note::
-
-            In edge/vertex collections, this method does NOT provide the
-            transactional guarantees and validations that single delete
-            operation does for graphs. If these properties are required, see
-            :func:`arango.database.StandardDatabase.begin_batch_execution`
-            for an alternative approach.
-
         :param documents: Document IDs, keys or bodies. Document bodies must
             contain the "_id" or "_key" fields.
         :type documents: [str | dict]
@@ -2354,14 +2322,6 @@ def delete_match(
     ) -> Result[int]:
         """Delete matching documents.
 
-        .. note::
-
-            In edge/vertex collections, this method does NOT provide the
-            transactional guarantees and validations that single delete
-            operation does for graphs. If these properties are required, see
-            :func:`arango.database.StandardDatabase.begin_batch_execution`
-            for an alternative approach.
-
         :param filters: Document filters.
         :type filters: dict
         :param limit: Max number of documents to delete. If the limit is lower
@@ -2428,14 +2388,6 @@ def import_bulk(
             This method is faster than :func:`arango.collection.Collection.insert_many`
             but does not return as many details.
 
-        .. note::
-
-            In edge/vertex collections, this method does NOT provide the
-            transactional guarantees and validations that single insert
-            operation does for graphs. If these properties are required, see
-            :func:`arango.database.StandardDatabase.begin_batch_execution`
-            for an alternative approach.
-
         :param documents: List of new documents to insert. If they contain the
             "_key" or "_id" fields, the values are used as the keys of the new
             documents (auto-generated otherwise). Any "_rev" field is ignored.
@@ -2757,7 +2709,6 @@ def update(
             "returnNew": return_new,
             "returnOld": return_old,
             "ignoreRevs": not check_rev,
-            "overwrite": not check_rev,
             "silent": silent,
         }
         if sync is not None:

arango/utils.py

@@ -64,11 +64,11 @@ def get_doc_id(doc: Union[str, Json]) -> str:
 
 
 def is_none_or_int(obj: Any) -> bool:
-    """Check if obj is None or an integer.
+    """Check if obj is None or a positive integer.
 
     :param obj: Object to check.
     :type obj: Any
-    :return: True if object is None or an integer.
+    :return: True if object is None or a positive integer.
     :rtype: bool
     """
     return obj is None or (isinstance(obj, int) and obj >= 0)
@@ -128,11 +128,11 @@ def build_filter_conditions(filters: Json) -> str:
     return "FILTER " + " AND ".join(conditions)
 
 
-def validate_sort_parameters(sort: Sequence[Json]) -> bool:
+def validate_sort_parameters(sort: Jsons) -> bool:
     """Validate sort parameters for an AQL query.
 
     :param sort: Document sort parameters.
-    :type sort: Sequence[Json]
+    :type sort: Jsons
     :return: Validation success.
     :rtype: bool
     :raise arango.exceptions.SortValidationError: If sort parameters are invalid.

tests/test_collection.py

@@ -136,6 +136,8 @@ def test_collection_misc_methods(col, bad_col, cluster):
     # Test truncate collection
     assert col.truncate() is True
     assert len(col) == 0
+    assert col.truncate(sync=True, compact=False) is True
+    assert len(col) == 0
 
     # Test truncate with bad collection
     with assert_raises(CollectionTruncateError) as err: