Add async support to neomodel

.gitignore

@@ -15,7 +15,6 @@ development.env
 .ropeproject
 \#*\#
 .eggs
-bin
 lib
 .vscode
 pyvenv.cfg

.pre-commit-config.yaml

@@ -1,17 +1,18 @@
 repos:
-  - repo: https://github.com/psf/black
-    rev: 22.3.0
-    hooks:
-      - id: black
   - repo: https://github.com/PyCQA/isort
     rev: 5.11.5
     hooks:
       - id: isort
-  # - repo: local
-  #   hooks:
-  #     - id: pylint
-  #       name: pylint
-  #       entry: pylint neomodel/
-  #       language: system
-  #       always_run: true
-  #       pass_filenames: false
+        args: ["--profile", "black"]
+  - repo: https://github.com/psf/black
+    rev: 23.3.0
+    hooks:
+      - id: black
+  - repo: local
+    hooks:
+      - id: unasync
+        name: unasync
+        entry: bin/make-unasync
+        language: python
+        files: "^(neomodel/async_|test/async_)/.*"
+        additional_dependencies: [unasync, isort, black]

README.md

@@ -34,7 +34,7 @@ GitHub repo found at <https://github.com/neo4j-contrib/neomodel/>.
 
 # Documentation
 
-(Needs an update, but) Available on
+Available on
 [readthedocs](http://neomodel.readthedocs.org).
 
 # Upcoming breaking changes notice - \>=5.3
@@ -47,7 +47,7 @@ support for Python 3.12.
 
 Another source of upcoming breaking changes is the addition async support to
 neomodel. No date is set yet, but the work has progressed a lot in the past weeks ;
-and it will be part of a major release (potentially 6.0 to avoid misunderstandings).
+and it will be part of a major release.
 You can see the progress in [this branch](https://github.com/neo4j-contrib/neomodel/tree/task/async).
 
 Finally, we are looking at refactoring some standalone methods into the
@@ -67,6 +67,15 @@ To install from github:
 
     $ pip install git+git://github.com/neo4j-contrib/neomodel.git@HEAD#egg=neomodel-dev
 
+# Performance comparison
+
+You can find some performance tests made using Locust [in this repo](https://github.com/mariusconjeaud/neomodel-locust).
+
+Two learnings from this :
+
+* The wrapping of the driver made by neomodel is very thin performance-wise : it does not add a lot of overhead ;
+* When used in a concurrent fashion, async neomodel is faster than concurrent sync neomodel, and a lot of faster than serial queries.
+
 # Contributing
 
 Ideas, bugs, tests and pull requests always welcome. Please use
@@ -112,3 +121,42 @@ against all supported Python interpreters and neo4j versions: :
 
     # in the project's root folder:
     $ sh ./tests-with-docker-compose.sh
+
+## Developing with async
+
+### Transpiling async -> sync
+
+We use [this great library](https://github.com/python-trio/unasync) to automatically transpile async code into its sync version.
+
+In other words, when contributing to neomodel, only update the `async` code in `neomodel/async_`, then run : :
+
+    bin/make-unasync
+    isort .
+    black .
+
+Note that you can also use the pre-commit hooks for this.
+
+### Specific async/sync code
+This transpiling script mainly does two things :
+
+- It removes the await keywords, and the Async prefixes in class names
+- It does some specific replacements, like `adb`->`db`, `mark_async_test`->`mark_sync_test`
+
+It might be that your code should only be run for `async`, or `sync` ; or you want different stubs to be run for `async` vs `sync`.
+You can use the following utility function for this - taken from the official [Neo4j python driver code](https://github.com/neo4j/neo4j-python-driver) :
+
+    # neomodel/async_/core.py
+    from neomodel._async_compat.util import AsyncUtil
+
+    # AsyncUtil.is_async_code is always True
+    if AsyncUtil.is_async_code:
+        # Specific async code
+        # This one gets run when in async mode
+        assert await Coffee.nodes.check_contains(2)
+    else:
+        # Specific sync code
+        # This one gest run when in sync mode
+        assert 2 in Coffee.nodes
+
+You can check [test_match_api](test/async_/test_match_api.py) for some good examples, and how it's transpiled into sync.
+