From ede460adae01c1d775eb981ec8d3f91ba2dab5de Mon Sep 17 00:00:00 2001
From: Jon Michael Aanes <jonjmaa@gmail.com>
Date: Mon, 8 Jul 2024 18:59:21 +0200
Subject: [PATCH] Module Docstring

---
 pbcabi/__init__.py | 57 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 48 insertions(+), 9 deletions(-)

diff --git a/pbcabi/__init__.py b/pbcabi/__init__.py
index 18faac0..6d8486f 100644
--- a/pbcabi/__init__.py
+++ b/pbcabi/__init__.py
@@ -1,17 +1,56 @@
-'''
-Utility library for parsing and processing the PBC ABI format.
+"""# Partisia Blockchain ABI client.
 
-Follows the ABI specification quite closely. The full ABI specification can be found at:
+Utility library for parsing and processing the Partisia Blockchain ABI Format.
 
-    https://partisiablockchain.gitlab.io/documentation/abiv.html
-'''
+The format is specified here: [Partisia Blockchain's ABI format](https://partisiablockchain.gitlab.io/documentation/smart-contracts/smart-contract-binary-formats.html)..
 
+## Example usage
+
+This example is based upon the [Token Contract example contract](https://gitlab.com/partisiablockchain/language/example-contracts).
+It assumes a compiled ABI in `token.abi` and a blockchain state stored in `token_state.bin`.
+
+```py
+# Imports
+from pbcabi.binaryreader import BinaryReader
 import pbcabi.model
-import pbcabi.binaryreader
+
+# Read ABI
+with open('token.abi', 'rb') as f:
+    TOKEN_ABI = pbcabi.model.FileAbi.read_from(BinaryReader(f.read()))
+
+with open('token_state.bin', 'rb') as f:
+    state_bytes = f.read()
+
+# Read structure TokenState from state_bytes
+token_state = TOKEN_ABI.contract.read_state('TokenState', BinaryReader(state_bytes))
+
+# Inspect state as mostly Python-native types.
+my_address = BlockchainAddress.from_hex_hash("00e72e44eab933faaf1fd4ce94bb57e08bff98a1ed")
+
+print(token_state['name'])
+> MyToken
+print(token_state['balances'][my_address])
+> 213112
+```
+
+## Legalese
+
+This project is licensed under MIT Licence, see `LICENSE` for full text.
+
+This project is not associated with, nor supported by any of:
+
+- Partisia Applications A/S
+- Partisia Infrastructure A/S
+- Partisia Blockchain Foundation
+
+Use at own risk.
+"""
+
+__all__ = ['model', 'binaryreader', '__version__']
+
+from . import model, binaryreader
 from ._version import __version__
 
 def get_version():
-    """
-    Returns a PEP 386-compliant version number from __version__.
-    """
+    """Returns a PEP 386-compliant version number from __version__."""
     return __version__