Docs for async

Author: robsdedude

bin/make-unasync

@@ -20,9 +20,9 @@
 
 import collections
 import errno
-from functools import reduce
 import os
 from pathlib import Path
+import re
 import sys
 import tokenize as std_tokenize
 
@@ -103,20 +103,86 @@ class CustomRule(unasync.Rule):
         super(CustomRule, self).__init__(*args, **kwargs)
         self.out_files = []
 
-    def _unasync_name(self, name):
-        # copy from unasync to customize renaming rules
+    def _unasync_tokens(self, tokens):
+        # copy from unasync to hook into string handling
         # https://github.com/python-trio/unasync
         # License: MIT and Apache2
-        if name in self.token_replacements:
-            return self.token_replacements[name]
+        # TODO __await__, ...?
+        used_space = None
+        for space, toknum, tokval in tokens:
+            if tokval in ["async", "await"]:
+                # When removing async or await, we want to use the whitespace
+                # that was before async/await before the next token so that
+                # `print(await stuff)` becomes `print(stuff)` and not
+                # `print( stuff)`
+                used_space = space
+            else:
+                if toknum == std_tokenize.NAME:
+                    tokval = self._unasync_name(tokval)
+                elif toknum == std_tokenize.STRING:
+                    if tokval[0] == tokval[1] and len(tokval) > 2:
+                        # multiline string (`"""..."""` or `'''...'''`)
+                        left_quote, name, right_quote = \
+                            tokval[:3], tokval[3:-3], tokval[-3:]
+                    else:
+                        # simple string (`"..."` or `'...'`)
+                        left_quote, name, right_quote = \
+                            tokval[:1], tokval[1:-1], tokval[-1:]
+                    tokval = \
+                        left_quote + self._unasync_string(name) + right_quote
+                if used_space is None:
+                    used_space = space
+                yield (used_space, tokval)
+                used_space = None
+
+    def _unasync_string(self, name):
+        start = 0
+        end = 1
+        out = ""
+        while end < len(name):
+            sub_name = name[start:end]
+            if sub_name.isidentifier():
+                end += 1
+            else:
+                if end == start + 1:
+                    out += sub_name
+                    start += 1
+                    end += 1
+                else:
+                    out += self._unasync_prefix(name[start:(end - 1)])
+                    start = end - 1
+
+        sub_name = name[start:]
+        if sub_name.isidentifier():
+            out += self._unasync_prefix(name[start:])
+        else:
+            out += sub_name
+
+        # very boiled down unasync version that removes "async" and "await"
+        # substrings.
+        out = re.subn(r"(^|\s+|(?<=\W))(?:async|await)\s+", r"\1", out,
+                      flags=re.MULTILINE)[0]
+        # Convert doc-reference names from 'async-xyz' to 'xyz'
+        out = re.subn(r":ref:`async-", ":ref:`", out)[0]
+        return out
+
+    def _unasync_prefix(self, name):
         # Convert class names from 'AsyncXyz' to 'Xyz'
-        elif len(name) > 5 and name.startswith("Async") and name[5].isupper():
+        if len(name) > 5 and name.startswith("Async") and name[5].isupper():
             return name[5:]
         # Convert variable/method/function names from 'async_xyz' to 'xyz'
         elif len(name) > 6 and name.startswith("async_"):
             return name[6:]
         return name
 
+    def _unasync_name(self, name):
+        # copy from unasync to customize renaming rules
+        # https://github.com/python-trio/unasync
+        # License: MIT and Apache2
+        if name in self.token_replacements:
+            return self.token_replacements[name]
+        return self._unasync_prefix(name)
+
     def _unasync_file(self, filepath):
         # copy from unasync to append file suffix to out path
         # https://github.com/python-trio/unasync

docs/source/api.rst

@@ -11,7 +11,7 @@ GraphDatabase
 Driver Construction
 ===================
 
-The :class:`neo4j.Driver` construction is via a `classmethod` on the :class:`neo4j.GraphDatabase` class.
+The :class:`neo4j.Driver` construction is done via a `classmethod` on the :class:`neo4j.GraphDatabase` class.
 
 .. autoclass:: neo4j.GraphDatabase
    :members: driver
@@ -24,18 +24,19 @@ Example, driver creation:
     from neo4j import GraphDatabase
 
     uri = "neo4j://example.com:7687"
-    driver = GraphDatabase.driver(uri, auth=("neo4j", "password"), max_connection_lifetime=1000)
+    driver = GraphDatabase.driver(uri, auth=("neo4j", "password"))
 
     driver.close()  # close the driver object
 
 
-For basic auth, this can be a simple tuple, for example:
+For basic authentication, `auth` can be a simple tuple, for example:
 
 .. code-block:: python
 
    auth = ("neo4j", "password")
 
-This will implicitly create a :class:`neo4j.Auth` with a ``scheme="basic"``
+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:
@@ -345,11 +346,9 @@ BoltDriver
 URI schemes:
     ``bolt``, ``bolt+ssc``, ``bolt+s``
 
-Driver subclass:
-    :class:`neo4j.BoltDriver`
+Will result in:
 
-..
-   .. autoclass:: neo4j.BoltDriver
+.. autoclass:: neo4j.BoltDriver
 
 
 .. _neo4j-driver-ref:
@@ -360,11 +359,9 @@ Neo4jDriver
 URI schemes:
     ``neo4j``, ``neo4j+ssc``, ``neo4j+s``
 
-Driver subclass:
-    :class:`neo4j.Neo4jDriver`
+Will result in:
 
-..
-   .. autoclass:: neo4j.Neo4jDriver
+.. autoclass:: neo4j.Neo4jDriver
 
 
 ***********************
@@ -604,7 +601,8 @@ Example:
 
     def create_person(driver, name):
         with driver.session(default_access_mode=neo4j.WRITE_ACCESS) as session:
-            result = session.run("CREATE (a:Person { name: $name }) RETURN id(a) AS node_id", name=name)
+            query = "CREATE (a:Person { name: $name }) RETURN id(a) AS node_id"
+            result = session.run(query, name=name)
             record = result.single()
             return record["node_id"]
 
@@ -665,13 +663,15 @@ Example:
             tx.close()
 
     def create_person_node(tx):
+        query = "CREATE (a:Person { name: $name }) RETURN id(a) AS node_id"
         name = "default_name"
-        result = tx.run("CREATE (a:Person { name: $name }) RETURN id(a) AS node_id", name=name)
+        result = tx.run(query, name=name)
         record = result.single()
         return record["node_id"]
 
     def set_person_name(tx, node_id, name):
-        result = tx.run("MATCH (a:Person) WHERE id(a) = $id SET a.name = $name", id=node_id, name=name)
+        query = "MATCH (a:Person) WHERE id(a) = $id SET a.name = $name"
+        result = tx.run(query, id=node_id, name=name)
         info = result.consume()
         # use the info for logging etc.
 
@@ -698,7 +698,8 @@ Example:
             node_id = session.write_transaction(create_person_tx, name)
 
     def create_person_tx(tx, name):
-        result = tx.run("CREATE (a:Person { name: $name }) RETURN id(a) AS node_id", name=name)
+        query = "CREATE (a:Person { name: $name }) RETURN id(a) AS node_id"
+        result = tx.run(query, name=name)
         record = result.single()
         return record["node_id"]
 
@@ -708,12 +709,6 @@ To exert more control over how a transaction function is carried out, the :func:
 
 
 
-
-
-
-
-
-
 ******
 Result
 ******