From 045b4f1e22b240ef238c4e4db32f57808e4dcf8e Mon Sep 17 00:00:00 2001 From: Alex Petenchea Date: Thu, 8 Jun 2023 16:51:33 +0300 Subject: [PATCH] Updated documentation --- README.md | 2 +- docs/contributing.rst | 12 ++++----- docs/index.rst | 3 ++- docs/overload.rst | 58 +++++++++++++++++++++++++++++++++++++++++++ docs/specs.rst | 9 +++++++ 5 files changed, 76 insertions(+), 8 deletions(-) create mode 100644 docs/overload.rst diff --git a/README.md b/README.md index f57a1fad..151d39ab 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ database natively supporting documents, graphs and search. ## Requirements -- ArangoDB version 3.7+ +- ArangoDB version 3.9+ - Python version 3.8+ ## Installation diff --git a/docs/contributing.rst b/docs/contributing.rst index 18e74ed2..35a72657 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -40,7 +40,7 @@ To ensure PEP8_ compliance, run flake8_: .. code-block:: bash ~$ pip install flake8 - ~$ git clone https://github.com/joowani/python-arango.git + ~$ git clone https://github.com/ArangoDB-Community/python-arango.git ~$ cd python-arango ~$ flake8 @@ -57,7 +57,7 @@ To run the test suite (use your own host, port and root password): .. code-block:: bash ~$ pip install pytest - ~$ git clone https://github.com/joowani/python-arango.git + ~$ git clone https://github.com/ArangoDB-Community/python-arango.git ~$ cd python-arango ~$ py.test --complete --host=127.0.0.1 --port=8529 --passwd=passwd @@ -66,7 +66,7 @@ To run the test suite with coverage report: .. code-block:: bash ~$ pip install coverage pytest pytest-cov - ~$ git clone https://github.com/joowani/python-arango.git + ~$ git clone https://github.com/ArangoDB-Community/python-arango.git ~$ cd python-arango ~$ py.test --complete --host=127.0.0.1 --port=8529 --passwd=passwd --cov=kq @@ -82,9 +82,9 @@ Sphinx_. To build an HTML version on your local machine: .. code-block:: bash ~$ pip install sphinx sphinx_rtd_theme - ~$ git clone https://github.com/joowani/python-arango.git - ~$ cd python-arango/docs - ~$ sphinx-build . build # Open build/index.html in a browser + ~$ git clone https://github.com/ArangoDB-Community/python-arango.git + ~$ cd python-arango + ~$ python -m sphinx -b html -W docs docs/_build/ # Open build/index.html in a browser As always, thank you for your contribution! diff --git a/docs/index.rst b/docs/index.rst index 75ee65bf..232103b0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,7 @@ Welcome to the documentation for **python-arango**, a Python driver for ArangoDB Requirements ============= -- ArangoDB version 3.7+ +- ArangoDB version 3.9+ - Python version 3.8+ Installation @@ -38,6 +38,7 @@ Contents cursor async batch + overload transaction admin user diff --git a/docs/overload.rst b/docs/overload.rst new file mode 100644 index 00000000..25724663 --- /dev/null +++ b/docs/overload.rst @@ -0,0 +1,58 @@ +Overload API Execution +---------------------- +:ref:`OverloadControlDatabase` is designed to handle time-bound requests. It allows setting a maximum server-side +queuing time for client requests via the *max_queue_time_seconds* parameter. If the server's queueing time for a +request surpasses this defined limit, the request will be rejected. This mechanism provides you with more control over +request handling, enabling your application to react effectively to potential server overloads. + +Additionally, the response from ArangoDB will always include the most recent request queuing/dequeuing time from the +server's perspective. This can be accessed via the :attr:`~.OverloadControlDatabase.last_queue_time` property. + +**Example:** + +.. testcode:: + + from arango import errno + from arango import ArangoClient + from arango.exceptions import OverloadControlExecutorError + + # Initialize the ArangoDB client. + client = ArangoClient() + + # Connect to "test" database as root user. + db = client.db('test', username='root', password='passwd') + + # Begin controlled execution. + controlled_db = db.begin_controlled_execution(max_queue_time_seconds=7.5) + + # All requests surpassing the specified limit will be rejected. + controlled_aql = controlled_db.aql + controlled_col = controlled_db.collection('students') + + # On API execution, the last_queue_time property gets updated. + controlled_col.insert({'_key': 'Neal'}) + + # Retrieve the last recorded queue time. + assert controlled_db.last_queue_time >= 0 + + try: + controlled_aql.execute('RETURN 100000') + except OverloadControlExecutorError as err: + assert err.http_code == errno.HTTP_PRECONDITION_FAILED + assert err.error_code == errno.QUEUE_TIME_REQUIREMENT_VIOLATED + + # Retrieve the maximum allowed queue time. + assert controlled_db.max_queue_time == 7.5 + + # Adjust the maximum allowed queue time. + controlled_db.adjust_max_queue_time(0.0001) + + # Disable the maximum allowed queue time. + controlled_db.adjust_max_queue_time(None) + +.. note:: + Setting *max_queue_time_seconds* to 0 or a non-numeric value will cause ArangoDB to ignore the header. + +See :ref:`OverloadControlDatabase` for API specification. +See the `official documentation `_ for +details on ArangoDB's overload control options. diff --git a/docs/specs.rst b/docs/specs.rst index 0e2d3b13..b4f61854 100644 --- a/docs/specs.rst +++ b/docs/specs.rst @@ -135,6 +135,15 @@ HTTPClient .. autoclass:: arango.http.HTTPClient :members: +.. _OverloadControlDatabase: + +OverloadControlDatabase +======================= + +.. autoclass:: arango.database.OverloadControlDatabase + :inherited-members: + :members: + .. _Pregel: Pregel