From 0139e7a2d46adbc271772992907d476a4e7d2f8a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adrien=20B=C3=A9raud?= <adrien.beraud@savoirfairelinux.com>
Date: Thu, 4 Sep 2025 23:22:10 -0400
Subject: [PATCH] update README.md

---
 README.md        | 49 ++++++++++++++++++++++++++++--------------------
 python/README.md | 47 +++++++++++++++++++++++++++-------------------
 2 files changed, 57 insertions(+), 39 deletions(-)

diff --git a/README.md b/README.md
index 752829b6..4f56cc37 100644
--- a/README.md
+++ b/README.md
@@ -23,12 +23,12 @@ See the wiki: <https://github.com/savoirfairelinux/opendht/wiki>
 
 #### How to run a node
 
-You can help contributing to the public network by running a stable node with a public IP address.
+You can help contribute to the public network by running a stable node with a public IP address.
 https://github.com/savoirfairelinux/opendht/wiki/Running-a-node-with-dhtnode
 
 #### How-to build and install
 
-Build instructions: <https://github.com/savoirfairelinux/opendht/wiki/Build-the-library>
+Build instructions: see [BUILD.md](BUILD.md)
 
 ## Examples
 ### C++ example
@@ -102,30 +102,39 @@ for value in results:
 
 Or using asyncio:
 ```python
+import asyncio
 import opendht.aio as dht
 
-async with dht.DhtRunner() as node:
-    node.bootstrap("bootstrap.jami.net", "4222")
+async def dht_async_demo(key_str: str):
+    # Start a new node using an async context manager.
+    # It is also possible to call run()/await shutdown() manually.
+    async with dht.DhtRunner(
+        bootstrap=(("bootstrap.jami.net", "4222"),)
+    ) as node:
+        # compute key hash
+        key = dht.InfoHash.get(key_str)
 
-    # put data, waiting for completion
-    await node.put(dht.InfoHash.get("unique_key"), dht.Value(b'tata data'))
+        # put data, waiting for completion
+        await node.put(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:
+        # get all values at key
+        results = await node.getAll(key)
+        for value in results:
             print(value)
+        
+        # same operation, but stream values as they come from the network
+        with node.get(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
+        # listen for change of values at key
+        with node.listen(key) as values:
+            async for value, expired in values:
+                print(value)
+                if value.data == b'tata data':
+                    break
+
+asyncio.run(dht_async_demo("unique_key"))
 ```
 
 ## Dependencies
diff --git a/python/README.md b/python/README.md
index eec6f1de..a9f21487 100644
--- a/python/README.md
+++ b/python/README.md
@@ -13,7 +13,7 @@ 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
+## Installation
 
 Install on Linux, macOS and Windows with:
 ```sh
@@ -43,30 +43,39 @@ for value in results:
 
 Or using asyncio:
 ```python
+import asyncio
 import opendht.aio as dht
 
-async with dht.DhtRunner() as node:
-    node.bootstrap("bootstrap.jami.net", "4222")
+async def dht_async_demo(key_str: str):
+    # Start a new node using an async context manager.
+    # It is also possible to call run()/await shutdown() manually.
+    async with dht.DhtRunner(
+        bootstrap=(("bootstrap.jami.net", "4222"),)
+    ) as node:
+        # compute key hash
+        key = dht.InfoHash.get(key_str)
 
-    # put data, waiting for completion
-    await node.put(dht.InfoHash.get("unique_key"), dht.Value(b'tata data'))
+        # put data, waiting for completion
+        await node.put(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:
+        # get all values at key
+        results = await node.getAll(key)
+        for value in results:
             print(value)
+        
+        # same operation, but stream values as they come from the network
+        with node.get(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
+        # listen for change of values at key
+        with node.listen(key) as values:
+            async for value, expired in values:
+                print(value)
+                if value.data == b'tata data':
+                    break
+
+asyncio.run(dht_async_demo("unique_key"))
 ```
 
 ## Documentation