Docs and other suggestions by Florent

Co-authored-by: Florent Biville <florent.biville@neo4j.com>

Author: robsdedude

.editorconfig

@@ -10,11 +10,11 @@ charset = utf-8
 [*.{py,js,rst,txt,sh,bat}]
 trim_trailing_whitespace = true
 
-[{Makefile,Drockerfile}]
+[{Makefile,Dockerfile}]
 trim_trailing_whitespace = true
 
 [*.bat]
-end_of_line =crlf
+end_of_line = crlf
 
 [*.py]
 max_line_length = 79

.pre-commit-config.yaml

@@ -19,16 +19,6 @@ repos:
           - batch
       - id: trailing-whitespace
         args: [ --markdown-linebreak-ext=md ]
-#  - repo: https://github.com/pycqa/flake8
-#    rev: 4.0.1
-#    hooks:
-#      - id: flake8
-#        additional_dependencies:
-#          - flake8-bugbear
-#          - flake8-builtins
-#          - flake8-docstrings
-#          - flake8-quotes
-#          - pep8-naming
   - repo: https://github.com/pycqa/isort
     rev: 5.10.0
     hooks:

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 - Python 3.10 support added
 - Python 3.6 support has been dropped.
-- `Result`, `Session`, and `Transaction`, can no longer be imported from
+- `Result`, `Session`, and `Transaction` can no longer be imported from
   `neo4j.work`. They should've been imported from `neo4j` all along.
 - Experimental pipelines feature has been removed.
 - Experimental async driver has been added.

CONTRIBUTING.md

@@ -58,7 +58,7 @@ install the pre-commit hooks as described below insted. They will take care of
 updating the code if necessary.
 
 Setting up the development environment:
- * Install Python 3.6+
+ * Install Python 3.7+
  * Install the requirements
    ```bash
    $ python3 -m pip install -U pip
@@ -69,33 +69,14 @@ Setting up the development environment:
    ```bash
    $ pre-commit install
    ```
-   Note that this is not an auto-formatter. It will alter some code, but
-   mostly it will just complain about non-compliant code.  
-   You can disable a certain check for a single line of code if you think
-   your code-style if preferable. E.g.
-   ```python
-   assume_this_line(violates_rule_e123, and_w321)  # noqa: E123,W321
-   ```
-   Or use just `# noqa` to disable all checks for this line.  
-   If you use `# noqa` on its own line, it will disable *all* checks for the
-   whole file. Don't do that.  
-   To disable certain rules for a whole file, check out
-   `setup.cfg`.  
-   If you want to run the checks manually, you can do so:
-   ```bash
-   $ pre-commit run --all-files
-   # or
-   $ pre-commit run --file path/to/a/file
-   ```
-   For more details see [flake8](https://flake8.pycqa.org/).
 
 
 ## Got an idea for a new project?
 
 If you have an idea for a new tool or library, start by talking to other people in the community.
 Chances are that someone has a similar idea or may have already started working on it.
 The best software comes from getting like minds together to solve a problem.
-And we'll do our best to help you promote and co-ordinate your Neo ecosystem projects.
+And we'll do our best to help you promote and co-ordinate your Neo4j ecosystem projects.
 
 
 ## Further reading

docs/source/api.rst

@@ -17,7 +17,7 @@ The :class:`neo4j.Driver` construction is done via a `classmethod` on the :class
    :members: driver
 
 
-Example, driver creation:
+Driver creation example:
 
 .. code-block:: python
 
@@ -39,7 +39,7 @@ This will implicitly create a :class:`neo4j.Auth` with a ``scheme="basic"``.
 Other authentication methods are described under :ref:`auth-ref`.
 
 
-Example, with block context:
+``with`` block context example:
 
 .. code-block:: python
 
@@ -331,7 +331,8 @@ For example:
 
 Connection details held by the :class:`neo4j.Driver` are immutable.
 Therefore if, for example, a password is changed, a replacement :class:`neo4j.Driver` object must be created.
-More than one :class:`.Driver` may be required if connections to multiple databases, or connections as multiple users, are required.
+More than one :class:`.Driver` may be required if connections to multiple databases, or connections as multiple users, are required,
+unless when using impersonation (:ref:`impersonated-user-ref`).
 
 :class:`neo4j.Driver` objects are thread-safe but cannot be shared across processes.
 Therefore, ``multithreading`` should generally be preferred over ``multiprocessing`` for parallel database access.
@@ -371,7 +372,7 @@ All database activity is co-ordinated through two mechanisms: the :class:`neo4j.
 
 A :class:`neo4j.Session` is a logical container for any number of causally-related transactional units of work.
 Sessions automatically provide guarantees of causal consistency within a clustered environment but multiple sessions can also be causally chained if required.
-Sessions provide the top-level of containment for database activity.
+Sessions provide the top level of containment for database activity.
 Session creation is a lightweight operation and *sessions are not thread safe*.
 
 Connections are drawn from the :class:`neo4j.Driver` connection pool as required.

docs/source/async_api.rst

@@ -23,7 +23,7 @@ The :class:`neo4j.AsyncDriver` construction is done via a `classmethod` on the :
    :members: driver
 
 
-Example, driver creation:
+Driver creation example:
 
 .. code-block:: python
 
@@ -49,7 +49,7 @@ For basic authentication, ``auth`` can be a simple tuple, for example:
 This will implicitly create a :class:`neo4j.Auth` with a ``scheme="basic"``.
 Other authentication methods are described under :ref:`auth-ref`.
 
-Example, with block context:
+``with`` block context example:
 
 .. code-block:: python
 
@@ -197,7 +197,8 @@ For example:
 
 Connection details held by the :class:`neo4j.AsyncDriver` are immutable.
 Therefore if, for example, a password is changed, a replacement :class:`neo4j.AsyncDriver` object must be created.
-More than one :class:`.AsyncDriver` may be required if connections to multiple databases, or connections as multiple users, are required.
+More than one :class:`.AsyncDriver` may be required if connections to multiple databases, or connections as multiple users, are required,
+unless when using impersonation (:ref:`impersonated-user-ref`).
 
 :class:`neo4j.AsyncDriver` objects are safe to be used in concurrent coroutines.
 They are not thread-safe.
@@ -236,7 +237,7 @@ All database activity is co-ordinated through two mechanisms: the :class:`neo4j.
 
 A :class:`neo4j.AsyncSession` is a logical container for any number of causally-related transactional units of work.
 Sessions automatically provide guarantees of causal consistency within a clustered environment but multiple sessions can also be causally chained if required.
-Sessions provide the top-level of containment for database activity.
+Sessions provide the top level of containment for database activity.
 Session creation is a lightweight operation and *sessions cannot be shared between coroutines*.
 
 Connections are drawn from the :class:`neo4j.AsyncDriver` connection pool as required.

docs/source/transactions.rst

@@ -11,7 +11,7 @@ Sessions automatically provide guarantees of causal consistency within a cluster
 Sessions
 ========
 
-Sessions provide the top-level of containment for database activity.
+Sessions provide the top level of containment for database activity.
 Session creation is a lightweight operation and sessions are `not` thread safe.
 
 Connections are drawn from the :class:`neo4j.Driver` connection pool as required; an idle session will not hold onto a connection.

neo4j/_async/driver.py

@@ -40,8 +40,8 @@ class AsyncGraphDatabase:
 
     @classmethod
     @AsyncUtil.experimental_async(
-        "neo4j async is in experimental phase. It might be removed or change "
-        "its API at any time (including patch releases)."
+        "neo4j async is in experimental phase. It might be removed or changed "
+        "at any time (including patch releases)."
     )
     def driver(cls, uri, *, auth=None, **config):
         """Create a driver.

neo4j/_async/io/_bolt.py

@@ -350,7 +350,9 @@ async def route(self, database=None, imp_user=None, bookmarks=None):
         sent to the network, and a response is fetched.
 
         :param database: database for which to fetch a routing table
+            Requires Bolt 4.0+.
         :param imp_user: the user to impersonate
+            Requires Bolt 4.4+.
         :param bookmarks: iterable of bookmark values after which this
                           transaction should begin
         :return: dictionary of raw routing data
@@ -369,7 +371,9 @@ def run(self, query, parameters=None, mode=None, bookmarks=None,
         :param metadata: custom metadata dictionary to attach to the transaction
         :param timeout: timeout for transaction execution (seconds)
         :param db: name of the database against which to begin the transaction
+            Requires Bolt 4.0+.
         :param imp_user: the user to impersonate
+            Requires Bolt 4.4+.
         :param handlers: handler functions passed into the returned Response object
         :return: Response object
         """
@@ -407,7 +411,9 @@ def begin(self, mode=None, bookmarks=None, metadata=None, timeout=None,
         :param metadata: custom metadata dictionary to attach to the transaction
         :param timeout: timeout for transaction execution (seconds)
         :param db: name of the database against which to begin the transaction
+            Requires Bolt 4.0+.
         :param imp_user: the user to impersonate
+            Requires Bolt 4.4+
         :param handlers: handler functions passed into the returned Response object
         :return: Response object
         """

neo4j/_async_compat/concurrency.py

@@ -229,29 +229,3 @@ def notify_all(self):
 
 Condition = threading.Condition
 RLock = threading.RLock
-
-
-# async def main():
-#     lock = AsyncRLock()
-#
-#     async def say_after(delay, what):
-#         await asyncio.sleep(delay)
-#         print(what, repr(lock))
-#         async with lock:
-#             print(what, repr(lock))
-#             async with lock:
-#                 print(what, repr(lock))
-#                 await asyncio.sleep(delay)
-#                 print(what)
-#
-#     task_1 = asyncio.create_task(say_after(0.5, "1"))
-#     task_2 = asyncio.create_task(say_after(0.5, "2"))
-#     task_3 = asyncio.create_task(say_after(0.5, "3"))
-#
-#     await task_1
-#     await task_2
-#     await task_3
-#
-#
-# if __name__ == "__main__":
-#     asyncio.run(main())