Update README.md (#1904)

python/README.md

@@ -1,4 +1,4 @@
-# Bacalhau Python SDK
+# Bacalhau Python SDK :snake:
 
 This is the official Python SDK for Bacalhau, named `bacalhau-sdk`.
 It is a **high-level** SDK that ships the client-side logic (e.g. signing requests) needed to query the endpoints.
@@ -8,13 +8,13 @@ Under the hood, this SDK uses [`bacalhau-apiclient`](../clients) (autogenerated
 Please make sure to use this SDK library in your Python projects, instead of the lower level `bacalhau-apiclient`.
 The latter is listed as a dependency of this SDK and will be installed automatically when you follow the installation instructions below.
 
-#### Features
+## Features
 
-* List, create and inspect Bacalhau jobs
+* List, create and inspect Bacalhau jobs using Python objects :balloon:
 * Use the production network, or set the following environment variables to target any Bacalhau network out there:
     * `BACALHAU_API_HOST`
     * `BACALHAU_API_PORT`
-* Generate a key pair used to sign requests stored in the path specifified by the `BACALHAU_DIR` env var (default: your home folder)
+* Generate a key pair used to sign requests stored in the path specified by the `BACALHAU_DIR` env var (default: `~/.bacalhau`)
 ## Install
 
 Clone the public repository:
@@ -32,11 +32,16 @@ $ pip install .
 
 ## Initalize
 
-Likewise the Bacalhau CLI, this SDK requires a key pair to be stored in `BACALHAU_DIR` used for signing requests.
+Likewise the Bacalhau CLI, this SDK uses a key pair to be stored in `BACALHAU_DIR` used for signing requests.
+If a key pair is not found there, it will create one for you.
+
 
 ## Example Use
 
 Let's submit a Hello World job and then fetch its output data's CID.
+We start by importing this sdk, namely `bacalhau_sdk`, used to create and submit a job create request.
+Then we import `bacalhau_apiclient` (installed automatically with this sdk), it provides various object models that compose a job create request.
+These are used to populate a simple python dictionary that will be passed over to the `submit` util method. 
 
 ```python
 import pprint
@@ -116,15 +121,15 @@ The script above prints the following object, the `job.metadata.id` value is our
                                   'RequesterPublicKey': 'CAASpgIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDVRKPgCfY2fgfrkHkFjeWcqno+MDpmp8DgVaY672BqJl/dZFNU9lBg2P8Znh8OTtHPPBUBk566vU3KchjW7m3uK4OudXrYEfSfEPnCGmL6GuLiZjLf+eXGEez7qPaoYqo06gD8ROdD8VVse27E96LlrpD1xKshHhqQTxKoq1y6Rx4DpbkSt966BumovWJ70w+Nt9ZkPPydRCxVnyWS1khECFQxp5Ep3NbbKtxHNX5HeULzXN5q0EQO39UN6iBhiI34eZkH7PoAm3Vk5xns//FjTAvQw6wZUu8LwvZTaihs+upx2zZysq6CEBKoeNZqed9+Tf+qHow0P5pxmiu+or+DAgMBAAE='}}}}
 ```
 
-We can use the results method to fetch, among other fields, the output data's CID.
+We can then use the `results` method to fetch, among other fields, the output data's CID.
 
 ```python
 from bacalhau_sdk.api import results
 
 print(results(job_id="710a0bc2-81d1-4025-8f80-5327ca3ce170"))
 ```
 
-The line above prints  the following object:
+The line above prints the following dictionary:
 
 ```python
 {'results': [{'data': {'cid': 'QmYEqqNDdDrsRhPRShKHzsnZwBq3F59Ti3kQmv9En4i5Sw',
@@ -139,7 +144,7 @@ The line above prints  the following object:
 ```
 
 Congrats, that was a good start! 🎈
-Please find more code snippets in [the examples folder](./examples).
+Please find more code snippets in [the examples folder](./examples) (more examples published in the near future).
 
 ## Devstack