README: update for new Python API

README.md

@@ -73,14 +73,22 @@ int main()
     return 0;
 }
 ```
+
 ### Python 3 example
+
+Install on Linux, macOS and Windows with:
+```sh
+pip install opendht
+```
+
+Using the simple, blocking API:
 ```python
 import opendht as dht
 
 node = dht.DhtRunner()
 node.run()
 
-# Join the network through any running node,
+# Join the DHT network through any running node,
 # here using a known bootstrap node.
 node.bootstrap("bootstrap.jami.net", "4222")
 
@@ -88,8 +96,36 @@ node.bootstrap("bootstrap.jami.net", "4222")
 node.put(dht.InfoHash.get("unique_key"), dht.Value(b'some binary data'))
 
 results = node.get(dht.InfoHash.get("unique_key"))
-for r in results:
-    print(r)
+for value in results:
+    print(value)
+```
+
+Or using asyncio:
+```python
+import opendht.aio as dht
+
+async with dht.DhtRunner() as node:
+    node.bootstrap("bootstrap.jami.net", "4222")
+
+    # put data, waiting for completion
+    await node.put(dht.InfoHash.get("unique_key"), dht.Value(b'tata data'))
+
+    # get all values at key
+    results = await node.getAll(dht.InfoHash.get("unique_key"))
+    for value in results:
+        print(value)
+    
+    # same operation, but stream values as they come from the network
+    with node.get(dht.InfoHash.get("unique_key")) as results:
+        async for value in results:
+            print(value)
+
+    # listen for changes of values at key
+    with node.listen(dht.InfoHash.get("unique_key")) as values:
+        async for value, expired in values:
+            print(value)
+            if value.data == b'tata data':
+                break
 ```
 
 ## Dependencies
@@ -100,7 +136,7 @@ for r in results:
 - (optional) restinio used for the REST API.
 - (optional) llhttp used for the REST API.
 - (optional) jsoncpp 1.7.4-3+, used for the REST API.
-- Build tested with GCC 7+ (GNU/Linux, Windows with MinGW), Clang/LLVM (GNU/Linux, Android, macOS, iOS).
+- Build tested with GCC 9+ (GNU/Linux, Windows with MinGW), Clang/LLVM (GNU/Linux, Android, macOS, iOS).
 - Build tested with Microsoft Visual Studio 2019, 2022
 
 ## Contact
@@ -118,4 +154,3 @@ See COPYING or https://www.gnu.org/licenses/gpl-3.0.en.html for the full GPLv3 l
 
 ## Acknowledgements
 This project was originally based on https://github.com/jech/dht by Juliusz Chroboczek.
-It is independent from another (now extinct) project called OpenDHT (Sean Rhea. Ph.D. Thesis, 2005).

python/README.md

@@ -13,15 +13,23 @@ OpenDHT is a lightweight Distributed Hash Table implementation providing an easy
 
 Every node in the network can read and write values to the store. Values are distributed over the network with redundancy.
 
+## Install
+
+Install on Linux, macOS and Windows with:
+```sh
+pip install opendht
+```
+
 ## Quick Example
 
+Using the simple, blocking API:
 ```python
 import opendht as dht
 
 node = dht.DhtRunner()
 node.run()
 
-# Join the network through any running node,
+# Join the DHT network through any running node,
 # here using a known bootstrap node.
 node.bootstrap("bootstrap.jami.net", "4222")
 
@@ -29,8 +37,36 @@ node.bootstrap("bootstrap.jami.net", "4222")
 node.put(dht.InfoHash.get("unique_key"), dht.Value(b'some binary data'))
 
 results = node.get(dht.InfoHash.get("unique_key"))
-for r in results:
-    print(r)
+for value in results:
+    print(value)
+```
+
+Or using asyncio:
+```python
+import opendht.aio as dht
+
+async with dht.DhtRunner() as node:
+    node.bootstrap("bootstrap.jami.net", "4222")
+
+    # put data, waiting for completion
+    await node.put(dht.InfoHash.get("unique_key"), dht.Value(b'tata data'))
+
+    # get all values at key
+    results = await node.getAll(dht.InfoHash.get("unique_key"))
+    for value in results:
+        print(value)
+    
+    # same operation, but stream values as they come from the network
+    with node.get(dht.InfoHash.get("unique_key")) as results:
+        async for value in results:
+            print(value)
+
+    # listen for changes of values at key
+    with node.listen(dht.InfoHash.get("unique_key")) as values:
+        async for value, expired in values:
+            print(value)
+            if value.data == b'tata data':
+                break
 ```
 
 ## Documentation