python-arango 8.1.6__tar.gz → 8.2.0__tar.gz

{python_arango-8.1.6 → python_arango-8.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: python-arango
-Version: 8.1.6
+Version: 8.2.0
 Summary: Python Driver for ArangoDB
 Author-email: Joohwan Oh <joohwan.oh@outlook.com>
 Maintainer-email: Joohwan Oh <joohwan.oh@outlook.com>, Alexandru Petenchea <alex.petenchea@gmail.com>, Anthony Mahanna <anthony.mahanna@arangodb.com>
@@ -62,6 +62,7 @@ Requires-Dist: sphinx; extra == "dev"
 Requires-Dist: sphinx_rtd_theme; extra == "dev"
 Requires-Dist: types-requests; extra == "dev"
 Requires-Dist: types-setuptools; extra == "dev"
+Dynamic: license-file
 
 ![Logo](https://user-images.githubusercontent.com/2701938/108583516-c3576680-72ee-11eb-883f-2d9b52e74e45.png)
 
@@ -84,6 +85,8 @@ Requires-Dist: types-setuptools; extra == "dev"
 Python driver for [ArangoDB](https://www.arangodb.com), a scalable multi-model
 database natively supporting documents, graphs and search.
 
+If you're interested in using asyncio, please check [python-arango-async](https://github.com/arangodb/python-arango-async).
+
 ## Requirements
 
 - ArangoDB version 3.11+
@@ -130,7 +133,7 @@ cursor = db.aql.execute("FOR doc IN students RETURN doc")
 student_names = [document["name"] for document in cursor]
 ```
 
-Another example with [graphs](https://www.arangodb.com/docs/stable/graphs.html):
+Another example with [graphs](https://docs.arangodb.com/stable/graphs/):
 
 ```python
 from arango import ArangoClient

{python_arango-8.1.6 → python_arango-8.2.0}/README.md

@@ -19,6 +19,8 @@
 Python driver for [ArangoDB](https://www.arangodb.com), a scalable multi-model
 database natively supporting documents, graphs and search.
 
+If you're interested in using asyncio, please check [python-arango-async](https://github.com/arangodb/python-arango-async).
+
 ## Requirements
 
 - ArangoDB version 3.11+
@@ -65,7 +67,7 @@ cursor = db.aql.execute("FOR doc IN students RETURN doc")
 student_names = [document["name"] for document in cursor]
 ```
 
-Another example with [graphs](https://www.arangodb.com/docs/stable/graphs.html):
+Another example with [graphs](https://docs.arangodb.com/stable/graphs/):
 
 ```python
 from arango import ArangoClient

{python_arango-8.1.6 → python_arango-8.2.0}/arango/collection.py

@@ -566,15 +566,31 @@ class Collection(ApiGroup):
 
         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:
@@ -1736,6 +1752,7 @@ class Collection(ApiGroup):
         merge: Optional[bool] = None,
         refill_index_caches: Optional[bool] = None,
         version_attribute: Optional[str] = None,
+        raise_on_document_error: bool = False,
     ) -> Result[Union[bool, List[Union[Json, ArangoServerError]]]]:
         """Insert multiple documents.
 
@@ -1745,15 +1762,8 @@ class Collection(ApiGroup):
             returned as an object in the result list. It is up to you to
             inspect the list to determine which documents were inserted
             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.
+            (returns exception object). Alternatively, you can rely on
+            setting **raise_on_document_error** to True (defaults to False).
 
         :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
@@ -1793,6 +1803,11 @@ class Collection(ApiGroup):
         :param version_attribute: support for simple external versioning to
             document operations.
         :type version_attribute: str
+        :param raise_on_document_error: Whether to raise if a DocumentRevisionError
+            or a DocumentInsertError is encountered on an individual document,
+            as opposed to returning the error as an object in the result list.
+            Defaults to False.
+        :type raise_on_document_error: bool
         :return: List of document metadata (e.g. document keys, revisions) and
             any exception, or True if parameter **silent** was set to True.
         :rtype: [dict | ArangoServerError] | bool
@@ -1845,7 +1860,12 @@ class Collection(ApiGroup):
                     results.append(body)
                 else:
                     sub_resp = self._conn.prep_bulk_err_response(resp, body)
-                    results.append(DocumentInsertError(sub_resp, request))
+                    error = DocumentInsertError(sub_resp, request)
+
+                    if raise_on_document_error:
+                        raise error
+
+                    results.append(error)
 
             return results
 
@@ -1876,14 +1896,6 @@ class Collection(ApiGroup):
             (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 +2007,6 @@ class Collection(ApiGroup):
     ) -> 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 +2089,6 @@ class Collection(ApiGroup):
             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 +2183,6 @@ class Collection(ApiGroup):
     ) -> 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.
@@ -2252,6 +2240,7 @@ class Collection(ApiGroup):
         sync: Optional[bool] = None,
         silent: bool = False,
         refill_index_caches: Optional[bool] = None,
+        raise_on_document_error: bool = False,
     ) -> Result[Union[bool, List[Union[Json, ArangoServerError]]]]:
         """Delete multiple documents.
 
@@ -2263,14 +2252,6 @@ class Collection(ApiGroup):
             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]
@@ -2288,6 +2269,11 @@ class Collection(ApiGroup):
             index caches if document operations affect the edge index or
             cache-enabled persistent indexes.
         :type refill_index_caches: bool | None
+        :param raise_on_document_error: Whether to raise if a DocumentRevisionError
+            or a DocumentDeleteError is encountered on an individual document,
+            as opposed to returning the error as an object in the result list.
+            Defaults to False.
+        :type raise_on_document_error: bool
         :return: List of document metadata (e.g. document keys, revisions) and
             any exceptions, or True if parameter **silent** was set to True.
         :rtype: [dict | ArangoServerError] | bool
@@ -2339,6 +2325,10 @@ class Collection(ApiGroup):
                         error = DocumentRevisionError(sub_resp, request)
                     else:
                         error = DocumentDeleteError(sub_resp, request)
+
+                    if raise_on_document_error:
+                        raise error
+
                     results.append(error)
 
             return results
@@ -2354,14 +2344,6 @@ class Collection(ApiGroup):
     ) -> 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 +2410,6 @@ class Collection(ApiGroup):
             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 +2731,6 @@ class StandardCollection(Collection):
             "returnNew": return_new,
             "returnOld": return_old,
             "ignoreRevs": not check_rev,
-            "overwrite": not check_rev,
             "silent": silent,
         }
         if sync is not None:
@@ -3035,9 +3008,8 @@ class VertexCollection(Collection):
         self,
         vertex: Json,
         sync: Optional[bool] = None,
-        silent: bool = False,
         return_new: bool = False,
-    ) -> Result[Union[bool, Json]]:
+    ) -> Result[Json]:
         """Insert a new vertex document.
 
         :param vertex: New vertex document to insert. If it has "_key" or "_id"
@@ -3046,20 +3018,16 @@ class VertexCollection(Collection):
         :type vertex: dict
         :param sync: Block until operation is synchronized to disk.
         :type sync: bool | None
-        :param silent: If set to True, no document metadata is returned. This
-            can be used to save resources.
-        :type silent: bool
         :param return_new: Include body of the new document in the returned
             metadata. Ignored if parameter **silent** is set to True.
         :type return_new: bool
-        :return: Document metadata (e.g. document key, revision), or True if
-            parameter **silent** was set to True.
-        :rtype: bool | dict
+        :return: Document metadata (e.g. document key, revision).
+        :rtype: dict
         :raise arango.exceptions.DocumentInsertError: If insert fails.
         """
         vertex = self._ensure_key_from_id(vertex)
 
-        params: Params = {"silent": silent, "returnNew": return_new}
+        params: Params = {"returnNew": return_new}
         if sync is not None:
             params["waitForSync"] = sync
 
@@ -3071,11 +3039,9 @@ class VertexCollection(Collection):
             write=self.name,
         )
 
-        def response_handler(resp: Response) -> Union[bool, Json]:
+        def response_handler(resp: Response) -> Json:
             if not resp.is_success:
                 raise DocumentInsertError(resp, request)
-            if silent:
-                return True
             return format_vertex(resp.body)
 
         return self._execute(request, response_handler)
@@ -3086,10 +3052,9 @@ class VertexCollection(Collection):
         check_rev: bool = True,
         keep_none: bool = True,
         sync: Optional[bool] = None,
-        silent: bool = False,
         return_old: bool = False,
         return_new: bool = False,
-    ) -> Result[Union[bool, Json]]:
+    ) -> Result[Json]:
         """Update a vertex document.
 
         :param vertex: Partial or full vertex document with updated values. It
@@ -3103,18 +3068,14 @@ class VertexCollection(Collection):
         :type keep_none: bool | None
         :param sync: Block until operation is synchronized to disk.
         :type sync: bool | None
-        :param silent: If set to True, no document metadata is returned. This
-            can be used to save resources.
-        :type silent: bool
         :param return_old: Include body of the old document in the returned
             metadata. Ignored if parameter **silent** is set to True.
         :type return_old: bool
         :param return_new: Include body of the new document in the returned
             metadata. Ignored if parameter **silent** is set to True.
         :type return_new: bool
-        :return: Document metadata (e.g. document key, revision) or True if
-            parameter **silent** was set to True.
-        :rtype: bool | dict
+        :return: Document metadata (e.g. document key, revision).
+        :rtype: dict
         :raise arango.exceptions.DocumentUpdateError: If update fails.
         :raise arango.exceptions.DocumentRevisionError: If revisions mismatch.
         """
@@ -3123,7 +3084,6 @@ class VertexCollection(Collection):
         params: Params = {
             "keepNull": keep_none,
             "overwrite": not check_rev,
-            "silent": silent,
             "returnNew": return_new,
             "returnOld": return_old,
         }
@@ -3139,13 +3099,11 @@ class VertexCollection(Collection):
             write=self.name,
         )
 
-        def response_handler(resp: Response) -> Union[bool, Json]:
+        def response_handler(resp: Response) -> Json:
             if resp.status_code == 412:  # pragma: no cover
                 raise DocumentRevisionError(resp, request)
             elif not resp.is_success:
                 raise DocumentUpdateError(resp, request)
-            if silent is True:
-                return True
             return format_vertex(resp.body)
 
         return self._execute(request, response_handler)
@@ -3155,10 +3113,9 @@ class VertexCollection(Collection):
         vertex: Json,
         check_rev: bool = True,
         sync: Optional[bool] = None,
-        silent: bool = False,
         return_old: bool = False,
         return_new: bool = False,
-    ) -> Result[Union[bool, Json]]:
+    ) -> Result[Json]:
         """Replace a vertex document.
 
         :param vertex: New vertex document to replace the old one with. It must
@@ -3169,25 +3126,20 @@ class VertexCollection(Collection):
         :type check_rev: bool
         :param sync: Block until operation is synchronized to disk.
         :type sync: bool | None
-        :param silent: If set to True, no document metadata is returned. This
-            can be used to save resources.
-        :type silent: bool
         :param return_old: Include body of the old document in the returned
             metadata. Ignored if parameter **silent** is set to True.
         :type return_old: bool
         :param return_new: Include body of the new document in the returned
             metadata. Ignored if parameter **silent** is set to True.
         :type return_new: bool
-        :return: Document metadata (e.g. document key, revision) or True if
-            parameter **silent** was set to True.
-        :rtype: bool | dict
+        :return: Document metadata (e.g. document key, revision).
+        :rtype: dict
         :raise arango.exceptions.DocumentReplaceError: If replace fails.
         :raise arango.exceptions.DocumentRevisionError: If revisions mismatch.
         """
         vertex_id, headers = self._prep_from_body(vertex, check_rev)
 
         params: Params = {
-            "silent": silent,
             "returnNew": return_new,
             "returnOld": return_old,
         }
@@ -3203,13 +3155,11 @@ class VertexCollection(Collection):
             write=self.name,
         )
 
-        def response_handler(resp: Response) -> Union[bool, Json]:
+        def response_handler(resp: Response) -> Json:
             if resp.status_code == 412:  # pragma: no cover
                 raise DocumentRevisionError(resp, request)
             elif not resp.is_success:
                 raise DocumentReplaceError(resp, request)
-            if silent is True:
-                return True
             return format_vertex(resp.body)
 
         return self._execute(request, response_handler)
@@ -3353,9 +3303,8 @@ class EdgeCollection(Collection):
         self,
         edge: Json,
         sync: Optional[bool] = None,
-        silent: bool = False,
         return_new: bool = False,
-    ) -> Result[Union[bool, Json]]:
+    ) -> Result[Json]:
         """Insert a new edge document.
 
         :param edge: New edge document to insert. It must contain "_from" and
@@ -3365,20 +3314,16 @@ class EdgeCollection(Collection):
         :type edge: dict
         :param sync: Block until operation is synchronized to disk.
         :type sync: bool | None
-        :param silent: If set to True, no document metadata is returned. This
-            can be used to save resources.
-        :type silent: bool
         :param return_new: Include body of the new document in the returned
             metadata. Ignored if parameter **silent** is set to True.
         :type return_new: bool
-        :return: Document metadata (e.g. document key, revision) or True if
-            parameter **silent** was set to True.
-        :rtype: bool | dict
+        :return: Document metadata (e.g. document key, revision).
+        :rtype: dict
         :raise arango.exceptions.DocumentInsertError: If insert fails.
         """
         edge = self._ensure_key_from_id(edge)
 
-        params: Params = {"silent": silent, "returnNew": return_new}
+        params: Params = {"returnNew": return_new}
         if sync is not None:
             params["waitForSync"] = sync
 
@@ -3390,11 +3335,9 @@ class EdgeCollection(Collection):
             write=self.name,
         )
 
-        def response_handler(resp: Response) -> Union[bool, Json]:
+        def response_handler(resp: Response) -> Json:
             if not resp.is_success:
                 raise DocumentInsertError(resp, request)
-            if silent:
-                return True
             return format_edge(resp.body)
 
         return self._execute(request, response_handler)
@@ -3405,10 +3348,9 @@ class EdgeCollection(Collection):
         check_rev: bool = True,
         keep_none: bool = True,
         sync: Optional[bool] = None,
-        silent: bool = False,
         return_old: bool = False,
         return_new: bool = False,
-    ) -> Result[Union[bool, Json]]:
+    ) -> Result[Json]:
         """Update an edge document.
 
         :param edge: Partial or full edge document with updated values. It must
@@ -3422,18 +3364,14 @@ class EdgeCollection(Collection):
         :type keep_none: bool | None
         :param sync: Block until operation is synchronized to disk.
         :type sync: bool | None
-        :param silent: If set to True, no document metadata is returned. This
-            can be used to save resources.
-        :type silent: bool
         :param return_old: Include body of the old document in the returned
             metadata. Ignored if parameter **silent** is set to True.
         :type return_old: bool
         :param return_new: Include body of the new document in the returned
             metadata. Ignored if parameter **silent** is set to True.
         :type return_new: bool
-        :return: Document metadata (e.g. document key, revision) or True if
-            parameter **silent** was set to True.
-        :rtype: bool | dict
+        :return: Document metadata (e.g. document key, revision).
+        :rtype: dict
         :raise arango.exceptions.DocumentUpdateError: If update fails.
         :raise arango.exceptions.DocumentRevisionError: If revisions mismatch.
         """
@@ -3442,7 +3380,6 @@ class EdgeCollection(Collection):
         params: Params = {
             "keepNull": keep_none,
             "overwrite": not check_rev,
-            "silent": silent,
             "returnNew": return_new,
             "returnOld": return_old,
         }
@@ -3458,13 +3395,11 @@ class EdgeCollection(Collection):
             write=self.name,
         )
 
-        def response_handler(resp: Response) -> Union[bool, Json]:
+        def response_handler(resp: Response) -> Json:
             if resp.status_code == 412:  # pragma: no cover
                 raise DocumentRevisionError(resp, request)
             if not resp.is_success:
                 raise DocumentUpdateError(resp, request)
-            if silent is True:
-                return True
             return format_edge(resp.body)
 
         return self._execute(request, response_handler)
@@ -3474,10 +3409,9 @@ class EdgeCollection(Collection):
         edge: Json,
         check_rev: bool = True,
         sync: Optional[bool] = None,
-        silent: bool = False,
         return_old: bool = False,
         return_new: bool = False,
-    ) -> Result[Union[bool, Json]]:
+    ) -> Result[Json]:
         """Replace an edge document.
 
         :param edge: New edge document to replace the old one with. It must
@@ -3489,25 +3423,20 @@ class EdgeCollection(Collection):
         :type check_rev: bool
         :param sync: Block until operation is synchronized to disk.
         :type sync: bool | None
-        :param silent: If set to True, no document metadata is returned. This
-            can be used to save resources.
-        :type silent: bool
         :param return_old: Include body of the old document in the returned
             metadata. Ignored if parameter **silent** is set to True.
         :type return_old: bool
         :param return_new: Include body of the new document in the returned
             metadata. Ignored if parameter **silent** is set to True.
         :type return_new: bool
-        :return: Document metadata (e.g. document key, revision) or True if
-            parameter **silent** was set to True.
-        :rtype: bool | dict
+        :return: Document metadata (e.g. document key, revision).
+        :rtype: dict
         :raise arango.exceptions.DocumentReplaceError: If replace fails.
         :raise arango.exceptions.DocumentRevisionError: If revisions mismatch.
         """
         edge_id, headers = self._prep_from_body(edge, check_rev)
 
         params: Params = {
-            "silent": silent,
             "returnNew": return_new,
             "returnOld": return_old,
         }
@@ -3523,13 +3452,11 @@ class EdgeCollection(Collection):
             write=self.name,
         )
 
-        def response_handler(resp: Response) -> Union[bool, Json]:
+        def response_handler(resp: Response) -> Json:
             if resp.status_code == 412:  # pragma: no cover
                 raise DocumentRevisionError(resp, request)
             if not resp.is_success:
                 raise DocumentReplaceError(resp, request)
-            if silent is True:
-                return True
             return format_edge(resp.body)
 
         return self._execute(request, response_handler)
@@ -3602,9 +3529,8 @@ class EdgeCollection(Collection):
         to_vertex: Union[str, Json],
         data: Optional[Json] = None,
         sync: Optional[bool] = None,
-        silent: bool = False,
         return_new: bool = False,
-    ) -> Result[Union[bool, Json]]:
+    ) -> Result[Json]:
         """Insert a new edge document linking the given vertices.
 
         :param from_vertex: "From" vertex document ID or body with "_id" field.
@@ -3617,21 +3543,17 @@ class EdgeCollection(Collection):
         :type data: dict | None
         :param sync: Block until operation is synchronized to disk.
         :type sync: bool | None
-        :param silent: If set to True, no document metadata is returned. This
-            can be used to save resources.
-        :type silent: bool
         :param return_new: Include body of the new document in the returned
             metadata. Ignored if parameter **silent** is set to True.
         :type return_new: bool
-        :return: Document metadata (e.g. document key, revision) or True if
-            parameter **silent** was set to True.
-        :rtype: bool | dict
+        :return: Document metadata (e.g. document key, revision).
+        :rtype: dict
         :raise arango.exceptions.DocumentInsertError: If insert fails.
         """
         edge = {"_from": get_doc_id(from_vertex), "_to": get_doc_id(to_vertex)}
         if data is not None:
             edge.update(self._ensure_key_from_id(data))
-        return self.insert(edge, sync=sync, silent=silent, return_new=return_new)
+        return self.insert(edge, sync=sync, return_new=return_new)
 
     def edges(
         self,