Add more usage guides

Author: cffls

Makefile

@@ -66,6 +66,7 @@ format: ## runs code style and formatter
 	poetry run black .
 
 docs: ## build the documentation
+	rm -r docs/build
 	poetry run sphinx-build docs/source docs/build/html
 	$(BROWSER) docs/build/html/index.html
 

docs/source/conf.py

@@ -30,13 +30,21 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_rtd_theme"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_rtd_theme",
+    "sphinx_copybutton",
+]
 
 master_doc = "index"
 
 napoleon_google_docstring = True
 napoleon_include_init_with_doc = False
 
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+
 autodoc_member_order = "bysource"
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/guides/address.rst

@@ -13,47 +13,48 @@ Payment key is usually used to sign transactions that involve funds transfers, w
 is usually used to sign transactions that involve staking-related activities, e.g. stake address registration,
 delegation. PyCardano provides APIs to create, save, and loads payment keys and stake keys.
 
-New payment keys and stake keys could be generated using class method `generate()`. Their corresponding
-verification (public) key could be created using class method `from_signing_key()`::
+New payment keys and stake keys could be generated using class method
+`generate <../api/pycardano.key.html#pycardano.key.SigningKey.generate>`_. Their corresponding
+verification (public) key could be created using class method
+`from_signing_key <../api/pycardano.key.html#pycardano.key.VerificationKey.from_signing_key>`_::
 
-    from pycardano import PaymentSigningKey, StakeSigningKey, PaymentVerificationKey, StakeVerificationKey
+    >>> from pycardano import PaymentSigningKey, StakeSigningKey, PaymentVerificationKey, StakeVerificationKey
+     
+    >>> payment_signing_key = PaymentSigningKey.generate()
+    >>> payment_verification_key = PaymentVerificationKey.from_signing_key(payment_signing_key)
 
-    payment_signing_key = PaymentSigningKey.generate()
-    payment_verification_key = PaymentVerificationKey.from_signing_key(payment_signing_key)
-
-
-    stake_signing_key = StakeSigningKey.generate()
-    stake_verification_key = StakeVerificationKey.from_signing_key(stake_signing_key)
+    >>> stake_signing_key = StakeSigningKey.generate()
+    >>> stake_verification_key = StakeVerificationKey.from_signing_key(stake_signing_key)
 
 
 Alternatively, a key pair (signing key + verification key) could be generated together::
 
-    from pycardano import PaymentKeyPair, StakeKeyPair
+    >>> from pycardano import PaymentKeyPair, StakeKeyPair
 
-    payment_key_pair = PaymentKeyPair.generate()
-    payment_signing_key = payment_key_pair.signing_key
-    payment_verification_key = payment_key_pair.verification_key
+    >>> payment_key_pair = PaymentKeyPair.generate()
+    >>> payment_signing_key = payment_key_pair.signing_key
+    >>> payment_verification_key = payment_key_pair.verification_key
 
-    stake_key_pair = StakeKeyPair.generate()
-    stake_signing_key = stake_key_pair.signing_key
-    stake_verification_key = stake_key_pair.verification_key
+    >>> stake_key_pair = StakeKeyPair.generate()
+    >>> stake_signing_key = stake_key_pair.signing_key
+    >>> stake_verification_key = stake_key_pair.verification_key
 
 
 A key could be saved to and loaded from a file::
 
-    # Save
-    payment_signing_key.save("payment.skey")
-    payment_verification_key.save("payment.vkey")
+    >>> # Save
+    >>> payment_signing_key.save("payment.skey")
+    >>> payment_verification_key.save("payment.vkey")
 
-    # Load
-    payment_signing_key = payment_signing_key.load("payment.skey")
-    payment_verification_key = payment_verification_key.load("payment.vkey")
+    >>> # Load
+    >>> payment_signing_key = payment_signing_key.load("payment.skey")
+    >>> payment_verification_key = payment_verification_key.load("payment.vkey")
 
 Signing keys can sign messages (in bytes)::
 
-    message = b"Hello world!"
-    print(payment_signing_key.signing_key.sign(b"Hello world!"))
-    # b'\xf1N\x96\x05\xe8[\xa3"g5\x95\x80\xca\x88\x93&\xefD\xc3\x9fXj{\xaf\x01mna\xa92+z\x08\x9d\x1eG\x9fN\xc2\xb8\xb1\xab\xbf\xee\xf7\xa6\x08\x87\xfa\xeb\x9bGW\xba\xb7\xd8\xb2\xbb\xe0\x9c"\x0b\xe0\x07'
+    >>> message = b"Hello world!"
+    >>> payment_signing_key.signing_key.sign(b"Hello world!")
+    b'\xf1N\x96\x05\xe8[\xa3"g5\x95\x80\xca\x88\x93&\xefD\xc3\x9fXj{\xaf\x01mna\xa92+z\x08\x9d\x1eG\x9fN\xc2\xb8\xb1\xab\xbf\xee\xf7\xa6\x08\x87\xfa\xeb\x9bGW\xba\xb7\xd8\xb2\xbb\xe0\x9c"\x0b\xe0\x07'
 
 This guide only covers address keys. There is another category of keys called "Node keys".
 You can learn more about keys `here <https://docs.cardano.org/core-concepts/cardano-keys>`_.
@@ -72,28 +73,28 @@ when creating an address.
 Base address is the most commonly used address type. It is generated from a payment verification key and
 a stake verification key::
 
-    from pycardano import Address, Network
+    >>> from pycardano import Address, Network
 
-    base_address = Address(payment_part=payment_verification_key.hash(),
-                           staking_part=stake_verification_key.hash(),
-                           network=Network.TESTNET)
+    >>> base_address = Address(payment_part=payment_verification_key.hash(),
+    ...                        staking_part=stake_verification_key.hash(),
+    ...                        network=Network.TESTNET)
 
-    print(base_address)
-    # addr_test1vr2p8st5t5cxqglyjky7vk98k7jtfhdpvhl4e97cezuhn0cqcexl7
+    >>> base_address
+    "addr_test1vr2p8st5t5cxqglyjky7vk98k7jtfhdpvhl4e97cezuhn0cqcexl7"
 
 An address object could also be created from an address string directly::
 
-    address = Address.from_primitive("addr_test1vr2p8st5t5cxqglyjky7vk98k7jtfhdpvhl4e97cezuhn0cqcexl7")
+    >>> address = Address.from_primitive("addr_test1vr2p8st5t5cxqglyjky7vk98k7jtfhdpvhl4e97cezuhn0cqcexl7")
 
 
 An enterprise address does not have staking functionalities, it is created from a payment verification key only::
 
-    enterprise_address = Address(payment_part=payment_verification_key.hash(),
-                                 network=Network.TESTNET)
+    >>> enterprise_address = Address(payment_part=payment_verification_key.hash(),
+    ...                              network=Network.TESTNET)
 
 
 A stake address does not have payment functionalities, it is created from a stake verification key only::
 
-    stake_address = Address(staking_part=payment_verification_key.hash(),
-                            network=Network.TESTNET)
+    >>> stake_address = Address(staking_part=payment_verification_key.hash(),
+    ...                         network=Network.TESTNET)
 

docs/source/guides/instance_creation.rst

@@ -0,0 +1,105 @@
+========================
+Instance/Object creation
+========================
+
+In PyCardano, most components and data structures are embedded in Python classes. To construct an instance, we need to
+start from its child components, and build everything from bottom up.
+
+For example, we need to create an instance of
+`TransactionId <../api/pycardano.hash.html#pycardano.hash.TransactionId>`_
+before creating a `TransactionInput <../api/pycardano.transaction.html#pycardano.transaction.TransactionInput>`_.
+Similarly, we need to provide an instance of
+`Address <../api/pycardano.address.html#pycardano.address.Address>`_
+before creating a `TransactionOutput <../api/pycardano.transaction.html#pycardano.transaction.TransactionOutput>`_::
+
+    >>> from pycardano import Address, TransactionId, TransactionInput, TransactionOutput
+    >>> tx_id_hex = "732bfd67e66be8e8288349fcaaa2294973ef6271cc189a239bb431275401b8e5"
+    >>> tx_id = TransactionId(bytes.fromhex(tx_id_hex))
+    >>> tx_in = TransactionInput(tx_id, 0)
+    >>> tx_in
+    {'index': 0,
+     'transaction_id': TransactionId(hex='732bfd67e66be8e8288349fcaaa2294973ef6271cc189a239bb431275401b8e5')}
+    >>> addr = Address.decode(
+    ...     "addr_test1vrm9x2zsux7va6w892g38tvchnzahvcd9tykqf3ygnmwtaqyfg52x"
+    ... )
+    >>> tx_out = TransactionOutput(addr, 100000000000)
+    >>> tx_out
+    {'address': addr_test1vrm9x2zsux7va6w892g38tvchnzahvcd9tykqf3ygnmwtaqyfg52x,
+     'amount': 100000000000,
+     'datum_hash': None}
+
+
+Another example is native asset::
+
+    >>> from pycardano import Asset, AssetName, MultiAsset, ScriptHash
+    >>> # Create an asset container
+    >>> my_asset = Asset()
+
+    >>> # Create names for our assets
+    >>> nft1 = AssetName(b"MY_NFT_1")
+    >>> nft2 = AssetName(b"MY_NFT_2")
+
+    >>> # Put assets into the asset container with a quantity of 1
+    >>> my_asset[nft1] = 1
+    >>> my_asset[nft2] = 1
+
+    >>> # Create a MultiAsset container
+    >>> my_nft = MultiAsset()
+
+    >>> # Create a policy id
+    >>> policy_id = ScriptHash(bytes.fromhex("9c83e0e86689ae56c0753c9a1714980e6b7603bca12530b0e19b0dae"))
+
+    >>> # Put assets into MultiAsset container.
+    >>> my_nft[policy_id] = my_asset
+    >>> my_nft
+    {ScriptHash(hex='9c83e0e86689ae56c0753c9a1714980e6b7603bca12530b0e19b0dae'): {AssetName(b'MY_NFT_1'): 1, AssetName(b'MY_NFT_2'): 2}}
+
+
+It is rather verbose and tedious to build an instance from ground up. To solve this problem, PyCardano provides an
+alternative way of constructing instances: directly constructing an instance from Python primitive types. Because
+Python is quite concise in terms of creating dictionary and list literals, we can simplify instance construction by
+leveraging this Python feature.
+
+Example of creating an equivalent ``TransactionInput`` and ``TransactionOutput`` from above::
+
+    >>> from pycardano import Address, TransactionId, TransactionInput, TransactionOutput
+    >>> tx_in = TransactionInput.from_primitive(
+    ...     [bytes.fromhex("732bfd67e66be8e8288349fcaaa2294973ef6271cc189a239bb431275401b8e5"), 0])
+    >>> tx_in
+        {'index': 0,
+         'transaction_id': TransactionId(hex='732bfd67e66be8e8288349fcaaa2294973ef6271cc189a239bb431275401b8e5')}
+
+    >>> tx_out = TransactionOutput.from_primitive(
+    ...     ["addr_test1vrm9x2zsux7va6w892g38tvchnzahvcd9tykqf3ygnmwtaqyfg52x", 100000000000])
+    >>> tx_out
+    {'address': addr_test1vrm9x2zsux7va6w892g38tvchnzahvcd9tykqf3ygnmwtaqyfg52x,
+     'amount': 100000000000,
+     'datum_hash': None}
+
+
+Example of creating an equivalent ``MultiAsset`` from above::
+
+    >>> my_nft_alternative = MultiAsset.from_primitive(
+    ...     {
+    ...         bytes.fromhex("9c83e0e86689ae56c0753c9a1714980e6b7603bca12530b0e19b0dae"): {
+    ...             b"MY_NFT_1": 1,
+    ...             b"MY_NFT_2": 1
+    ...         }
+    ...     }
+    ... )
+
+    >>> my_nft_alternative
+    {ScriptHash(hex='9c83e0e86689ae56c0753c9a1714980e6b7603bca12530b0e19b0dae'): {AssetName(b'MY_NFT_1'): 1, AssetName(b'MY_NFT_2'): 1}}
+
+
+All child classes of `CBORSerializable <../api/pycardano.serialization.html#pycardano.serialization.CBORSerializable>`_
+has a class method
+`from_primitive <../api/pycardano.serialization.html#pycardano.serialization.CBORSerializable.from_primitive>`_ that takes
+a `Primitive <../api/pycardano.serialization.html#pycardano.serialization.Primitive>`_ as input, which is usually a list
+or dictionary. It is not hard to tell that creating an instance using primitives is much more concise and easier than
+building it from ground up.
+
+.. note::
+    The opposite operation of ``from_primitive`` is
+    `to_primitive <../api/pycardano.serialization.html#pycardano.serialization.CBORSerializable.to_primitive>`_, which
+    is often used in debugging and internal logic of `serialization <serialization.html>`_.

docs/source/guides/serialization.rst

@@ -0,0 +1,63 @@
+=============
+Serialization
+=============
+
+
+Cardano uses Concise Binary Object Representation (`CBOR <https://cbor.io/>`_) to
+store on-chain data. Reading and writing data from/to blockchain requires serialization and deserialization of CBOR
+binaries.
+
+A core feature PyCardano provides is serialization. It can serialize Python objects into CBOR bytes and deserialize
+CBOR bytes back to Python objects. Most Classes in PyCardano are child class of
+`CBORSerializable <../api/pycardano.serialization.html#pycardano.serialization.CBORSerializable>`_, which provides two
+CBOR-related methods. `to_cbor <../api/pycardano.serialization.html#pycardano.serialization.CBORSerializable.to_cbor>`_
+generates CBOR bytes from an instance, and
+`from_cbor <../api/pycardano.serialization.html#pycardano.serialization.CBORSerializable.from_cbor>`_ restore an instance.
+
+Examples::
+
+    >>> from pycardano import (TransactionBody,
+    ...                        TransactionInput,
+    ...                        TransactionId,
+    ...                        TransactionOutput)
+    >>> 
+    >>> tx_id_hex = "732bfd67e66be8e8288349fcaaa2294973ef6271cc189a239bb431275401b8e5"
+    >>> tx_in = TransactionInput(TransactionId(bytes.fromhex(tx_id_hex)), 0)
+    >>> addr = Address.decode(
+    ...     "addr_test1vrm9x2zsux7va6w892g38tvchnzahvcd9tykqf3ygnmwtaqyfg52x"
+    ... )
+    >>> output1 = TransactionOutput(addr, 100000000000)
+    >>> output2 = TransactionOutput(addr, 799999834103)
+    >>> fee = 165897
+    >>> tx_body = TransactionBody(
+    ...     inputs=[tx_in],
+    ...     outputs=[output1, output2],
+    ...     fee=fee
+    ... )
+    >>> cbor_hex = tx_body.to_cbor()
+    a50081825820732bfd67e66be8e8288349fcaaa2294973ef6271cc189a239bb431275401b8e500018282581d60f6532850e1bccee9c72a9113ad98bcc5dbb30d2ac960262444f6e5f41b000000174876e80082581d60f6532850e1bccee9c72a9113ad98bcc5dbb30d2ac960262444f6e5f41b000000ba43b4b7f7021a000288090d800e80
+
+    >>> restored_tx_body = TransactionBody.from_cbor(cbor_hex)
+    >>> assert tx_body == restored_tx_body
+
+    >>> restored_tx_body
+    {'auxiliary_data_hash': None,
+    'certificates': None,
+    'collateral': [],
+    'fee': 165897,
+    'inputs': [{'index': 0,
+    'transaction_id': TransactionId(hex='732bfd67e66be8e8288349fcaaa2294973ef6271cc189a239bb431275401b8e5')}],
+    'mint': None,
+    'network_id': None,
+    'outputs': [{'address': addr_test1vrm9x2zsux7va6w892g38tvchnzahvcd9tykqf3ygnmwtaqyfg52x,
+    'amount': 100000000000,
+    'datum_hash': None},
+                {'address': addr_test1vrm9x2zsux7va6w892g38tvchnzahvcd9tykqf3ygnmwtaqyfg52x,
+    'amount': 799999834103,
+    'datum_hash': None}],
+    'required_signers': [],
+    'script_data_hash': None,
+    'ttl': None,
+    'update': None,
+    'validity_start': None,
+    'withdraws': None}