python-arango 8.1.3__tar.gz → 8.1.5__tar.gz

{python_arango-8.1.3 → python_arango-8.1.5}/.circleci/config.yml

@@ -11,8 +11,7 @@ workflows:
           name:  Python (<< matrix.python_version >>) - ArangoDB (<< matrix.arangodb_license >>, << matrix.arangodb_version >> << matrix.arangodb_config >>)
           matrix:
             parameters:
-              # TODO: Revisit why pyenv doesn't recognize 3.12
-              python_version: ["3.8", "3.9", "3.10", "3.11"] # "3.12"
+              python_version: ["3.9", "3.10", "3.11", "3.12"]
               arangodb_config: ["single", "cluster"]
               arangodb_license: ["community", "enterprise"]
               arangodb_version: ["3.11", "latest"]

{python_arango-8.1.3 → python_arango-8.1.5}/.gitignore

@@ -124,3 +124,6 @@ arango/version.py
 
 # test results
 *_results.txt
+
+# devcontainers
+.devcontainer

{python_arango-8.1.3 → python_arango-8.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: python-arango
-Version: 8.1.3
+Version: 8.1.5
 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>
@@ -33,14 +33,13 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Documentation :: Sphinx
 Classifier: Typing :: Typed
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: urllib3>=1.26.0
@@ -88,7 +87,7 @@ database natively supporting documents, graphs and search.
 ## Requirements
 
 - ArangoDB version 3.11+
-- Python version 3.8+
+- Python version 3.9+
 
 ## Installation
 

{python_arango-8.1.3 → python_arango-8.1.5}/README.md

@@ -22,7 +22,7 @@ database natively supporting documents, graphs and search.
 ## Requirements
 
 - ArangoDB version 3.11+
-- Python version 3.8+
+- Python version 3.9+
 
 ## Installation
 

{python_arango-8.1.3 → python_arango-8.1.5}/arango/aql.py

@@ -144,6 +144,36 @@ class AQLQueryCache(ApiGroup):
 
         return self._execute(request, response_handler)
 
+    def plan_entries(self) -> Result[Jsons]:
+        """Return a list of all AQL query plan cache entries.
+
+        :return: List of AQL query plan cache entries.
+        :rtype: list
+        :raise arango.exceptions.AQLCacheEntriesError: If retrieval fails.
+        """
+        request = Request(method="get", endpoint="/_api/query-plan-cache")
+
+        def response_handler(resp: Response) -> Jsons:
+            if not resp.is_success:
+                raise AQLCacheEntriesError(resp, request)
+            result: Jsons = resp.body
+            return result
+
+        return self._execute(request, response_handler)
+
+    def clear_plan(self) -> Result[None]:
+        """Clear the AQL query plan cache.
+
+        :raises arango.exceptions.AQLCacheClearError: If clearing the cache fails.
+        """
+        request = Request(method="delete", endpoint="/_api/query-plan-cache")
+
+        def response_handler(resp: Response) -> None:
+            if not resp.is_success:
+                raise AQLCacheClearError(resp, request)
+
+        return self._execute(request, response_handler)
+
 
 class AQL(ApiGroup):
     """AQL (ArangoDB Query Language) API wrapper.
@@ -264,7 +294,7 @@ class AQL(ApiGroup):
         cache: Optional[bool] = None,
         memory_limit: int = 0,
         fail_on_warning: Optional[bool] = None,
-        profile: Optional[bool] = None,
+        profile: Optional[Union[bool, int]] = None,
         max_transaction_size: Optional[int] = None,
         max_warning_count: Optional[int] = None,
         intermediate_commit_count: Optional[int] = None,
@@ -277,6 +307,7 @@ class AQL(ApiGroup):
         allow_dirty_read: bool = False,
         allow_retry: bool = False,
         force_one_shard_attribute_value: Optional[str] = None,
+        use_plan_cache: Optional[bool] = None,
     ) -> Result[Cursor]:
         """Execute the query and return the result cursor.
 
@@ -317,8 +348,12 @@ class AQL(ApiGroup):
             this behaviour, so it does not need to be set per-query.
         :type fail_on_warning: bool
         :param profile: Return additional profiling details in the cursor,
-            unless the query cache is used.
-        :type profile: bool
+            unless the query cache is used. If set to True or 1, then query profiling
+            information can be fetched with `cursor.profile()`. If set to 2, additional
+            execution stats per query plan node are included via "nodes" in
+            `cursor.statistics()`, as well as a the query plan which can be fetched
+            with `cursor.plan()`.
+        :type profile: bool | int
         :param max_transaction_size: Transaction size limit in bytes.
         :type max_transaction_size: int
         :param max_warning_count: Max number of warnings returned.
@@ -384,6 +419,8 @@ class AQL(ApiGroup):
             shipped to a wrong DB server and may not return results
             (i.e. empty result set). Use at your own risk.
         :param force_one_shard_attribute_value: str | None
+        :param use_plan_cache: If set to True, the query plan cache is used.
+        :param use_plan_cache: bool | None
         :return: Result cursor.
         :rtype: arango.cursor.Cursor
         :raise arango.exceptions.AQLQueryExecuteError: If execute fails.
@@ -395,8 +432,6 @@ class AQL(ApiGroup):
             data["ttl"] = ttl
         if bind_vars is not None:
             data["bindVars"] = bind_vars
-        if cache is not None:
-            data["cache"] = cache
         if memory_limit is not None:
             data["memoryLimit"] = memory_limit
 
@@ -433,6 +468,10 @@ class AQL(ApiGroup):
             options["allowRetry"] = allow_retry
         if force_one_shard_attribute_value is not None:
             options["forceOneShardAttributeValue"] = force_one_shard_attribute_value
+        if cache is not None:
+            options["cache"] = cache
+        if use_plan_cache is not None:
+            options["usePlanCache"] = use_plan_cache
 
         if options:
             data["options"] = options

{python_arango-8.1.3 → python_arango-8.1.5}/arango/collection.py

@@ -50,11 +50,13 @@ from arango.result import Result
 from arango.typings import Fields, Headers, Json, Jsons, Params
 from arango.utils import (
     build_filter_conditions,
+    build_sort_expression,
     get_batches,
     get_doc_id,
     is_none_or_bool,
     is_none_or_int,
     is_none_or_str,
+    validate_sort_parameters,
 )
 
 
@@ -753,6 +755,7 @@ class Collection(ApiGroup):
         skip: Optional[int] = None,
         limit: Optional[int] = None,
         allow_dirty_read: bool = False,
+        sort: Optional[Jsons] = None,
     ) -> Result[Cursor]:
         """Return all documents that match the given filters.
 
@@ -764,13 +767,18 @@ class Collection(ApiGroup):
         :type limit: int | None
         :param allow_dirty_read: Allow reads from followers in a cluster.
         :type allow_dirty_read: bool
+        :param sort: Document sort parameters
+        :type sort: Jsons | None
         :return: Document cursor.
         :rtype: arango.cursor.Cursor
         :raise arango.exceptions.DocumentGetError: If retrieval fails.
+        :raise arango.exceptions.SortValidationError: If sort parameters are invalid.
         """
         assert isinstance(filters, dict), "filters must be a dict"
         assert is_none_or_int(skip), "skip must be a non-negative int"
         assert is_none_or_int(limit), "limit must be a non-negative int"
+        if sort:
+            validate_sort_parameters(sort)
 
         skip_val = skip if skip is not None else 0
         limit_val = limit if limit is not None else "null"
@@ -778,9 +786,9 @@ class Collection(ApiGroup):
             FOR doc IN @@collection
                 {build_filter_conditions(filters)}
                 LIMIT {skip_val}, {limit_val}
+                {build_sort_expression(sort)}
                 RETURN doc
         """
-
         bind_vars = {"@collection": self.name}
 
         request = Request(

{python_arango-8.1.3 → python_arango-8.1.5}/arango/cursor.py

@@ -40,6 +40,7 @@ class Cursor:
         "_count",
         "_cached",
         "_stats",
+        "_plan",
         "_profile",
         "_warnings",
         "_has_more",
@@ -63,6 +64,7 @@ class Cursor:
         self._count: Optional[int] = None
         self._cached = None
         self._stats = None
+        self._plan = None
         self._profile = None
         self._warnings = None
         self._next_batch_id: Optional[str] = None
@@ -132,12 +134,18 @@ class Cursor:
                 self._warnings = extra["warnings"]
                 result["warnings"] = extra["warnings"]
 
+            if "plan" in extra:
+                self._plan = extra["plan"]
+                result["plan"] = extra["plan"]
+
             if "stats" in extra:
                 stats = extra["stats"]
                 if "writesExecuted" in stats:
                     stats["modified"] = stats.pop("writesExecuted")
                 if "writesIgnored" in stats:
                     stats["ignored"] = stats.pop("writesIgnored")
+                if "documentLookups" in stats:
+                    stats["lookups"] = stats.pop("documentLookups")
                 if "scannedFull" in stats:
                     stats["scanned_full"] = stats.pop("scannedFull")
                 if "scannedIndex" in stats:
@@ -159,6 +167,9 @@ class Cursor:
                 if "peakMemoryUsage" in stats:
                     stats["peak_memory_usage"] = stats.pop("peakMemoryUsage")
 
+                if "intermediateCommits" in stats:
+                    stats["intermediate_commits"] = stats.pop("intermediateCommits")
+
                 self._stats = stats
                 result["statistics"] = stats
 
@@ -239,6 +250,14 @@ class Cursor:
         """
         return self._warnings
 
+    def plan(self) -> Optional[Json]:
+        """Return query execution plan.
+
+        :return: Query execution plan.
+        :rtype: dict
+        """
+        return self._plan
+
     def empty(self) -> bool:
         """Check if the current batch is empty.
 
@@ -313,7 +332,6 @@ class Cursor:
             smaller than the batch size).
         :rtype: bool | None
         :raise arango.exceptions.CursorCloseError: If operation fails.
-        :raise arango.exceptions.CursorStateError: If cursor ID is not set.
         """
         if self._id is None:
             return None