all: add sphinx documentation generation, some documentation fixes

GitOrigin-RevId: 4a415414ce59b9baba01d71baf021779a7ef2b74

Author: kikengineering

.gitignore

@@ -1,3 +1,5 @@
 *.pyc
 .idea
 .coverage
+docs/build
+docs/rst

Makefile

@@ -15,3 +15,8 @@ test:
 .PHONY: coverage
 coverage:
 	python -m pytest --timeout=10 --cov=agora --cov-report term-missing tests .
+
+.PHONY: docs
+docs:
+	sphinx-apidoc agora/ -o docs/rst
+	sphinx-build -b html docs/ docs/build

agora/client/client.py

@@ -11,9 +11,9 @@
 from agora.client.environment import Environment
 from agora.client.utils import public_key_to_address, quarks_to_kin_str
 from agora.error import AccountExistsError, AccountNotFoundError, InvoiceError, InvoiceErrorReason, \
-    UnsupportedVersionError, TransactionMalformedError, SenderDoesNotExistError, \
-    DestinationDoesNotExistError, InsufficientBalanceError, InsufficientFeeError, BadNonceError, OperationInvoiceError, \
-    TransactionRejectedError, TransactionError, Error
+    UnsupportedVersionError, TransactionMalformedError, SenderDoesNotExistError, InsufficientBalanceError, \
+    DestinationDoesNotExistError, InsufficientFeeError, BadNonceError, \
+    OperationInvoiceError, TransactionRejectedError, TransactionError, Error
 from agora.model.earn import Earn
 from agora.model.invoice import InvoiceList
 from agora.model.memo import AgoraMemo
@@ -92,7 +92,7 @@ def get_transaction(self, tx_hash: bytes) -> TransactionData:
         """Retrieves a transaction.
 
         :param tx_hash: The hash of the transaction to retrieve
-        :return: a :class:`TransactionData <agora.transaction.TransactionData>` object.
+        :return: a :class:`TransactionData <agora.model.transaction.TransactionData>` object.
         """
         raise NotImplementedError("BaseClient is an abstract class. Subclasses must implement get_transaction")
 
@@ -109,7 +109,7 @@ def get_balance(self, public_key: bytes) -> int:
     def submit_payment(self, payment: Payment) -> bytes:
         """Submits a payment to the Kin blockchain.
 
-        :param payment: The :class:`Payment <agora.payment.Payment>` to submit.
+        :param payment: The :class:`Payment <agora.model.payment.Payment>` to submit.
 
         :raise: :exc:`UnsupportedVersionError <agora.error.UnsupportedVersionError>`
         :raise: :exc:`TransactionMalformedError <agora.error.TransactionMalformedError>`
@@ -140,7 +140,7 @@ def submit_earn_batch(
 
         :raise: :exc:`UnsupportedVersionError <agora.error.UnsupportedVersionError>`
 
-        :return a :class:`BatchEarnResult <agora.results.BatchEarnResult>`
+        :return: a :class:`BatchEarnResult <agora.model.result.BatchEarnResult>`
         """
         raise NotImplementedError("BaseClient is an abstract class. Subclasses must implement submit_earn_batch")
 
@@ -290,7 +290,7 @@ def submit_earn_batch(
     def _submit_payment_tx(self, payment: Payment) -> bytes:
         """ Submits a payment transaction.
 
-        :param payment: The :class:`Payment <agora.payment.Payment>` to submit.
+        :param payment: The :class:`Payment <agora.model.payment.Payment>` to submit.
         :return: The transaction hash.
         """
         tx_source = payment.source if payment.source else payment.sender
@@ -334,7 +334,7 @@ def _submit_earn_batch_tx(
         :param memo: (optional) The memo to include in the transaction. If set, none of the invoices included in earns
             will be applied.
 
-        :return a :class:`BatchEarnResult <agora.results.BatchEarnResult>`
+        :return: a list of :class:`BatchEarnResult <agora.model.result.EarnResult>` objects
         """
         if len(earns) > 100:
             raise ValueError("cannot send more than 100 earns")
@@ -429,11 +429,13 @@ def _submit_stellar_transaction(
     ) -> bytes:
         """Submit a stellar transaction to Agora.
         :param tx_bytes: The transaction envelope xdr, in bytes
-        :param invoice_list: (optional) An :class:`InvoiceList <agora.invoice.InvoiceList>` to associate with the
+        :param invoice_list: (optional) An :class:`InvoiceList <agora.model.invoice.InvoiceList>` to associate with the
             transaction
+        :raise: :exc:`TransactionRejectedError <agora.error.TransactionRejectedError>`: if the transaction was rejected
+            by the configured app's webhook
         :raise: :exc:`InvoiceError <agora.error.InvoiceError>`: if the transaction failed for a invoice-related reason.
-        :raise: :exc:`StellarTransactionError <agora.error.StellarTransactionError>`: if the transaction failed
-            upon submission to the blockchain.
+        :raise: :exc:`TransactionError <agora.error.TransactionError>`: if the transaction failed upon submission to the
+            blockchain.
         :return: The transaction hash
         """
 

agora/client/utils.py

@@ -10,7 +10,7 @@ def kin_to_quarks(kin: float) -> int:
     """Converts a kin amount to quarks, with rounding. Uses the ROUND_HALF_UP method.
 
     :param kin: An amount, in Kin.
-    :return A integer quark amount.
+    :return: A integer quark amount.
     """
     return int((decimal.Decimal(kin) * _KIN_TO_QUARKS).quantize(decimal.Decimal('0.00001'),
                                                                 rounding=decimal.ROUND_HALF_UP).to_integral_value())
@@ -20,7 +20,7 @@ def quarks_to_kin(quarks: int) -> float:
     """Converts an amount of quarks to kin.
 
     :param quarks: An amount, in quarks.
-    :return A float Kin amount.
+    :return: A float Kin amount.
     """
     return float((decimal.Decimal(quarks) / _KIN_TO_QUARKS))
 

agora/model/earn.py

@@ -8,7 +8,7 @@ class Earn(object):
 
     :param destination: The public key, in raw bytes, of the account the earn will be sent to.
     :param quarks: The amount being sent.
-    :param invoice: (optional) An :class:`Invoice <agora.invoice.Invoice>` object to associate with this earn.
+    :param invoice: (optional) An :class:`Invoice <agora.model.invoice.Invoice>` object to associate with this earn.
     """
 
     def __init__(self, destination: bytes, quarks: int, invoice: Optional[Invoice] = None):

agora/model/invoice.py

@@ -92,6 +92,6 @@ def to_proto(self) -> model_pb2.InvoiceList:
     def get_sha_224_hash(self) -> bytes:
         """Returns the SHA-224 of the marshaled protobuf form of this invoice.
 
-        :return the SHA-224 hash.
+        :return: the SHA-224 hash.
         """
         return hashlib.sha224(self.to_proto().SerializeToString()).digest()

agora/model/memo.py

@@ -31,7 +31,7 @@ def new(cls, version: int, tx_type: TransactionType, app_index: int, foreign_key
         """Returns an Agora memo containing the provided properties.
 
         :param version: The memo encoding version
-        :param tx_type: The :class:`TransactionType <agora.transaction_type.TransactionType>` of the transaction
+        :param tx_type: The :class:`TransactionType <agora.model.transaction_type.TransactionType>` of the transaction
         :param app_index: The index of the app the transaction relates to
         :param foreign_key: An identifier in an auxiliary service that contains additional data about what the
             transaction was for
@@ -119,7 +119,7 @@ def is_valid(self) -> bool:
         Stricter validation can be done via :meth:`AgoraMemo.is_valid_strict`. However,
         :meth:`AgoraMemo.is_valid_strict` is not as forward compatible.
 
-        :return A bool indicating whether the memo is valid
+        :return: A bool indicating whether the memo is valid
         """
         if self.val[0] & 0x3 != MAGIC_BYTE:
             return False
@@ -150,9 +150,9 @@ def version(self) -> int:
         return (self.val[0] & 0x1c) >> 2
 
     def tx_type(self) -> TransactionType:
-        """Returns the :class:`TransactionType <agora.transaction_type.TransactionType>` of this memo.
+        """Returns the :class:`TransactionType <agora.model.transaction_type.TransactionType>` of this memo.
 
-        :return: :class:`TransactionType <agora.transaction_type.TransactionType>`
+        :return: :class:`TransactionType <agora.model.transaction_type.TransactionType>`
         """
         try:
             return TransactionType(self.tx_type_raw())

agora/model/payment.py

@@ -15,16 +15,16 @@ class Payment(object):
 
     :param sender: The secret seed, in raw bytes, of the account from which funds will be sent.
     :param destination: The public key, in raw bytes, of the account to which funds will be sent.
-    :param payment_type: The :class:`TransactionType <agora.transaction_type.TransactionType>` of this payment.
+    :param payment_type: The :class:`TransactionType <agora.model.transaction_type.TransactionType>` of this payment.
     :param quarks: The amount being sent.
     :param source: (optional) The secret seed, in raw bytes, of the account that will act as the source of the
         transaction. If unset, the sender will be used as the transaction source.
 
         On Stellar, this is where the transaction fee and sequence number is taken/chosen from.
 
         On Solana, this is where the fee is taken from.
-    :param invoice: (optional) An :class:`Invoice <agora.invoice.Invoice>` to associate with this payment. Only one of
-        invoice or memo should be set.
+    :param invoice: (optional) An :class:`Invoice <agora.model.invoice.Invoice>` to associate with this payment. Only
+        one of invoice or memo should be set.
     :param memo: (optional) The text memo to include with the transaction. Only one of invoice or memo should be set.
     """
 
@@ -65,8 +65,8 @@ class ReadOnlyPayment(object):
     :param dest: The public key, in raw bytes, of the destination account.
     :param payment_type: The type of this payment.
     :param quarks: The amount of the payment.
-    :param invoice: (optional) The :class:`Invoice <agora.invoice.Invoice>` associated with this payment. Only one of
-    invoice or memo will be set.
+    :param invoice: (optional) The :class:`Invoice <agora.model.invoice.Invoice>` associated with this payment. Only one
+        of invoice or memo will be set.
     :param memo: (optional) The text memo associated with this transaction. Only one of invoice or memo will be set.
     """
 

agora/model/transaction.py

@@ -13,8 +13,8 @@ class TransactionData(object):
     transaction.
 
     :param tx_hash: The hash of the transaction.
-    :param payments: (optional) A list of :class:`ReadOnlyPayment <agora.payment.ReadOnlyPayment>` objects.
-    :param error: (optional)) A :class:`TransactionError <agora.error.TransactionError>` object that contians extra
+    :param payments: (optional) A list of :class:`ReadOnlyPayment <agora.model.payment.ReadOnlyPayment>` objects.
+    :param error: (optional)) A :class:`TransactionError <agora.error.TransactionError>` object that contains extra
         details about why a transaction failed. If present, it indicates that the transaction failed.
     """
 

agora/webhook/handler.py

@@ -29,7 +29,7 @@ def is_valid_signature(self, req_body: str, signature: str) -> bool:
 
         :param req_body: The request body that the provided signature is supposedly for.
         :param signature: The base64-encoded signature to verify for the corresponding `req_body`.
-        :return A bool indicating whether or not the signature is valid.
+        :return: A bool indicating whether or not the signature is valid.
         """
         decoded_sig = base64.b64decode(signature)
         calculated_sig = hmac.new(self.secret, req_body.encode(), hashlib.sha256).digest()

agora/webhook/sign_transaction.py

@@ -51,7 +51,7 @@ def from_json(cls, data: dict):
     def get_tx_hash(self) -> bytes:
         """Returns the transaction hash of the transaction being signed.
 
-        :return The transaction hash, in bytes.
+        :return: The transaction hash, in bytes.
         """
         return self.envelope.hash_meta()
 

docs/conf.py

@@ -0,0 +1,53 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Kin Python SDK'
+copyright = '2020, Kik Engineering'
+author = 'Kik Engineering'
+
+# The full version, including alpha/beta/rc tags
+release = '0.1.0'
+
+# -- General configuration ---
+
+# 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.viewcode',
+    'sphinx_autodoc_typehints'
+]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'

docs/index.rst

@@ -0,0 +1,20 @@
+.. Kin Python SDK documentation master file, created by
+   sphinx-quickstart on Sun Jul 26 23:37:08 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Kin Python SDK's documentation!
+==========================================
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

requirements.dev.txt

@@ -1,6 +1,8 @@
+Flask==1.1.2
+grpcio-testing==1.30.0
 pytest==5.4.3
 pytest-cov==2.10.0
 pytest-mock==3.2.0
 pytest-timeout==1.4.1
-grpcio-testing==1.30.0
-Flask==1.1.2
+sphinx==3.1.2
+sphinx-autodoc-typehints==1.11.0