Merge pull request #293 from digital-asset/python-docs-fixes

python: Documentation fixes.

Author: da-tanabe

docs/index.rst

@@ -4,47 +4,43 @@
 dazl: DA client library for Python
 ==================================
 
-*Version: |release|*
+Version |release|
 
 Dependencies
 ------------
 
 You will need Python 3.6 or later and a Daml Ledger.
 
-
 Getting Started
 ---------------
 
 This section assumes that you already have a running ledger with the standard `daml new` model
 loaded, and have imported `dazl`.
 
-Connect to the ledger and submit a single command::
-
-    import dazl
-
-    async with dazl.connect(url='http://localhost:6865', act_as='Alice') as conn:
-        await conn.create('Main:Asset', {'issuer': 'Alice', 'owner': 'Alice', 'name': 'hello world!'})
+Connect to the ledger and submit a single command:
 
-Connect to the ledger as a single party, print all contracts, and close::
+.. literalinclude:: ../python/tests/unit/test_docs.py
+   :language: python
+   :pyobject: test_send_single_command
+   :lines: 2-
+   :dedent: 4
 
-    import dazl
+Connect to the ledger as a single party, print all contracts, and close:
 
-    async with dazl.connect(url='http://localhost:6865', read_as='Alice') as conn:
-        contracts = {}
-        async for event in conn.query():
-            contracts[event.cid] = event.cdata
-    print(contracts)
+.. literalinclude:: ../python/tests/unit/test_docs.py
+   :language: python
+   :pyobject: test_read
+   :lines: 2-
+   :dedent: 4
 
-Connect to the ledger using asynchronous callbacks::
+Connect to the ledger using asynchronous callbacks:
 
-    import dazl
+.. literalinclude:: ../python/tests/unit/test_docs.py
+   :language: python
+   :pyobject: test_read_using_callback
+   :lines: 2-
+   :dedent: 4
 
-    async with dazl.connect(url='http://localhost:6865', read_as='Alice') as conn:
-        contracts = {}
-        @conn.on_create
-        def _(event):
-            contracts[event.cid] = event.cdata
-    print(contracts)
 
 Code
 ----

python/tests/unit/test_docs.py

@@ -0,0 +1,39 @@
+# Copyright (c) 2017-2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# Note: These tests are not currently run since they hardcode URLs for documentation purposes.
+# But at the very least, they _are_ typechecked.
+
+
+async def test_send_single_command() -> None:
+    import dazl
+
+    async with dazl.connect(url="http://localhost:6865", act_as=dazl.Party("Alice")) as conn:
+        payload = {"issuer": "Alice", "owner": "Alice", "name": "hello world!"}
+        await conn.create("Main:Asset", payload)
+
+
+async def test_read() -> None:
+    import dazl
+
+    async with dazl.connect(url="http://localhost:6865", read_as=dazl.Party("Alice")) as conn:
+        contracts = {}
+        async with conn.query("Main:Asset") as stream:
+            async for event in stream.creates():
+                contracts[event.contract_id] = event.payload
+    print(contracts)
+
+
+async def test_read_using_callback() -> None:
+    import dazl
+
+    async with dazl.connect(url="http://localhost:6865", read_as=dazl.Party("Alice")) as conn:
+        contracts = {}
+        async with conn.query("Main:Asset") as stream:
+
+            @stream.on_create
+            def _(event):
+                contracts[event.contract_id] = event.payload
+
+            await stream.run()
+    print(contracts)