Merge pull request #58 from kinecosystem/fix_docs

Fix docstrings

Author: Ron Serruya

kin/account.py

@@ -70,7 +70,7 @@ def get_balance(self):
         :return: the kin balance
         :rtype: float
 
-        :raises: :class:`KinErrors.AccountNotFoundError`: if the account does not exist.
+        :raises: KinErrors.AccountNotFoundError if the account does not exist.
         """
         return self._client.get_account_balance(self.keypair.public_address)
 
@@ -79,16 +79,17 @@ def get_data(self):
         Gets this KinAccount's data
 
         :return: account data
-        :rtype: :class:`kin.AccountData`
+        :rtype: kin.blockchain.horizon_models.AccountData
 
-        :raises: :class:`KinErrors.AccountNotFoundError`: if the account does not exist.
+        :raises: KinErrors.AccountNotFoundError if the account does not exist.
         """
         return self._client.get_account_data(self.keypair.public_address)
 
     def get_status(self, verbose=False):
         """
         Get the config and status of this KinAccount object
         :param bool verbose: Should the channels status be verbose
+        :return: The config and status of this KinAccount object
         :rtype dict
         """
         account_status = {
@@ -125,7 +126,7 @@ def get_transaction_builder(self, fee):
         """
         Get a transaction builder using this account
         :param int fee: The fee that will be used for the transaction
-        :return: Kin.Builder
+        :return: kin.Builder
         """
         return Builder(self._client.environment.name, self.horizon, fee, self.keypair.secret_seed)
 
@@ -144,8 +145,8 @@ def create_account(self, address, starting_balance, fee, memo_text=None):
         :rtype: str
 
         :raises: KinErrors.StellarAddressInvalidError: if the provided address has a wrong format.
-        :raises: :class:`KinErrors.AccountExistsError`: if the account already exists.
-        :raises: :class:`KinErrors.NotValidParamError`: if the memo is longer than MEMO_CAP characters
+        :raises: KinErrors.AccountExistsError if the account already exists.
+        :raises: KinErrors.NotValidParamError if the memo is longer than MEMO_CAP characters
         :raises: KinErrors.NotValidParamError: if the amount is too precise
         :raises: KinErrors.NotValidParamError: if the fee is not valid
         """
@@ -176,9 +177,9 @@ def send_kin(self, address, amount, fee, memo_text=None):
         :raises: KinErrors.StellarAddressInvalidError: if the provided address has a wrong format.
         :raises: ValueError: if the amount is not positive.
         :raises: KinErrors.NotValidParamError: if the amount is too precise
-        :raises: :class:`KinErrors.AccountNotFoundError`: if the account does not exist.
-        :raises: :class:`KinErrors.LowBalanceError`: if there is not enough KIN to send and pay transaction fee.
-        :raises: :class:`KinErrors.NotValidParamError`: if the memo is longer than MEMO_CAP characters
+        :raises: KinErrors.AccountNotFoundError if the account does not exist.
+        :raises: KinErrors.LowBalanceError if there is not enough KIN to send and pay transaction fee.
+        :raises: KinErrors.NotValidParamError if the memo is longer than MEMO_CAP characters
         :raises: KinErrors.NotValidParamError: if the fee is not valid
         """
         builder = self.build_send_kin(address, amount, fee, memo_text)
@@ -202,7 +203,7 @@ def build_create_account(self, address, starting_balance, fee, memo_text=None):
         :param int fee: fee to be deducted for the tx
 
         :return: a transaction builder object
-        :rtype: :class: `Kin.Builder`
+        :rtype: kin.Builder
 
         :raises: KinErrors.StellarAddressInvalidError: if the supplied address has a wrong format.
         """
@@ -230,7 +231,7 @@ def build_send_kin(self, address, amount, fee, memo_text=None):
         :param int fee: fee to be deducted for the tx
 
         :return: a transaction builder
-        :rtype: Kin.Builder
+        :rtype: kin.Builder
 
         :raises: KinErrors.StellarAddressInvalidError: if the provided address has a wrong format.
         :raises: ValueError: if the amount is not positive.
@@ -277,10 +278,10 @@ def monitor_payments(self, callback_fn):
         NOTE: the function starts a background thread.
 
         :param callback_fn: the function to call on each received payment as `callback_fn(address, tx_data, monitor)`.
-        :type: callable[str,:class:`kin.TransactionData`,:class:`kin.SingleMonitor`]
+        :type: callable[str,kin.transactions.SimplifiedTransaction,kin.monitors.SingleMonitor]
 
         :return: a monitor instance
-        :rtype: :class:`kin.SingleMonitor`
+        :rtype: kin.monitors.SingleMonitor
         """
         return self._client.monitor_account_payments(self.keypair.public_address, callback_fn)
 

kin/blockchain/builder.py

@@ -16,7 +16,7 @@ def __init__(self, network_name, horizon, fee, secret):
         """
         Create a new transaction builder
         :param str network_name: The name of the network
-        :param Kin.Horizon horizon: The horizon instance to use
+        :param kin.Horizon horizon: The horizon instance to use
         :param int fee: Fee for the transaction
         :param str secret: The seed to be used
         """
@@ -60,7 +60,7 @@ def next(self):
     def set_channel(self, channel_seed):
         """
         Set a channel to be used for this transaction
-        :param channel_seed: Seed to use as the channel
+        :param str channel_seed: Seed to use as the channel
         """
         self.keypair = Keypair.from_seed(channel_seed)
         self.address = self.keypair.address().decode()

kin/blockchain/channel_manager.py

@@ -64,7 +64,8 @@ def get_status(self, verbose=False):
         """
         Return the current status of the channel manager
         :param bool verbose: Include all channel seeds and their statuses in the response
-        :return: dict
+        :return: The status of the channel manager
+        :rtype dict
         """
         free_channels = len(self.channel_pool.get_free_channels())
         status = {

kin/blockchain/environment.py

@@ -19,9 +19,7 @@ def __init__(self, name, horizon_endpoint_uri, network_passphrase, friendbot_url
         :param str network_passphrase: The passphrase/network_id of the environment.
         :param str friendbot_url: a url to a friendbot service
         :return: An instance of the Environment class.
-        :rtype: :class: `kin.Environment`
-
-        :raises: ValueError: is the kin_issuer is invalid
+        :rtype: kin.Environment
         """
         # Add the network to the kin_base network list.
         NETWORKS[name.upper()] = network_passphrase

kin/blockchain/errors.py

@@ -12,8 +12,7 @@ class ChannelsFullError(Exception):
 
 
 HORIZON_NS_PREFIX = 'https://stellar.org/horizon-errors/'
-
-'''
+"""
 Horizon error example:
 
 {
@@ -37,7 +36,8 @@ class ChannelsFullError(Exception):
     },
     'type': 'https://stellar.org/horizon-errors/transaction_failed'
 }
-'''
+
+"""
 
 
 class HorizonError(HTTPProblemDetails, Exception):

kin/blockchain/keypair.py

@@ -15,7 +15,7 @@ class Keypair:
     def __init__(self, seed=None):
         """
         # Create an instance of Keypair.
-        :param seed: (Optional) The secret seed of an account
+        :param str seed: (Optional) The secret seed of an account
         """
         self.secret_seed = seed or self.generate_seed()
         if not is_valid_secret_key(self.secret_seed):
@@ -29,10 +29,10 @@ def __init__(self, seed=None):
 
     def sign(self, data):
         """
-        Sign any data using the keypair private key
+        Sign any data using the keypair's private key
         :param bytes data: any data to sign
         :return: a decorated signature
-        :rtype :class: DecoratedSignature
+        :rtype kin_base.stellarxdr.StellarXDR_type.DecoratedSignature
         """
         signature = self._signing_key.sign(data)
         return DecoratedSignature(self._hint, signature)
@@ -41,8 +41,9 @@ def sign(self, data):
     def address_from_seed(seed):
         """
         Get a public address from a secret seed.
-        :param seed: The secret seed of an account.
+        :param str seed: The secret seed of an account.
         :return: A public address.
+        :rtype str
         """
         return BaseKeypair.from_seed(seed).address().decode()
 
@@ -51,16 +52,18 @@ def generate_seed():
         """
         Generate a random secret seed.
         :return: A secret seed.
+        :rtype str
         """
         return BaseKeypair.random().seed().decode()
 
     @staticmethod
     def generate_hd_seed(base_seed, salt):
         """
         Generate a highly deterministic seed from a base seed + salt
-        :param base_seed: The base seed to generate a seed from
-        :param salt: A unique string that will be used to generate the seed
+        :param str base_seed: The base seed to generate a seed from
+        :param str salt: A unique string that will be used to generate the seed
         :return: a new seed.
+        :rtype str
         """
         # Create a new raw seed from this hash
         raw_seed = sha256((base_seed + salt).encode()).digest()

kin/client.py

@@ -25,10 +25,10 @@ class KinClient(object):
 
     def __init__(self, environment):
         """Create a new instance of the KinClient to query the Kin blockchain.
-        :param `kin.Environment` environment: an environment for the client to point to.
+        :param kin.Environment environment: an environment for the client to point to.
 
         :return: An instance of the KinClient.
-        :rtype: :class:`KinErrors.KinClient`
+        :rtype: KinErrors.KinClient
         """
 
         self.environment = environment
@@ -41,12 +41,12 @@ def kin_account(self, seed, channel_secret_keys=None, app_id=ANON_APP_ID):
         """
         Create a new instance of a KinAccount to perform authenticated operations on the blockchain.
         :param str seed: The secret seed of the account that will be used
-        :param list of str channel_secret_keys: A list of seeds to be used as channels
+        :param list[str] channel_secret_keys: A list of seeds to be used as channels
         :param str app_id: the unique id of your app
         :return: An instance of KinAccount
         :rtype: kin.KinAccount
 
-        :raises: :class:`KinErrors.AccountNotFoundError`: if SDK wallet or channel account is not yet created.
+        :raises: KinErrors.AccountNotFoundError if SDK wallet or channel account is not yet created.
         """
 
         # Create a new kin account, using self as the KinClient to be used
@@ -101,7 +101,7 @@ def get_account_balance(self, address):
         :rtype: float
 
         :raises: StellarAddressInvalidError: if the provided address has the wrong format.
-        :raises: :class:`KinErrors.AccountNotFoundError`: if the account does not exist.
+        :raises: KinErrors.AccountNotFoundError if the account does not exist.
         """
 
         if not is_valid_address(address):
@@ -119,7 +119,7 @@ def does_account_exists(self, address):
         :return: does the account exists on the blockchain
         :rtype boolean
 
-        :raises: :class:`KinErrors.StellarAddressInvalidError`: if the address is not valid.
+        :raises: KinErrors.StellarAddressInvalidError if the address is not valid.
         """
 
         if not is_valid_address(address):
@@ -137,7 +137,7 @@ def get_account_data(self, address):
         :param str address: the public address of the account to query.
 
         :return: account data
-        :rtype: :class:`kin.AccountData`
+        :rtype: kin.blockchain.horizon_models.AccountData
 
         :raises: StellarAddressInvalidError: if the provided address has a wrong format.
         :raises: :class:`KinErrors.AccountNotFoundError`: if the account does not exist.
@@ -161,7 +161,7 @@ def get_transaction_data(self, tx_hash, simple=True):
         :param boolean simple: (optional) returns a simplified transaction object
 
         :return: transaction data
-        :rtype: :class:`kin.TransactionData` or `kin.SimplifiedTransaction`
+        :rtype: kin.transactions.RawTransaction | kin.transactions.SimplifiedTransaction
 
         :raises: ValueError: if the provided hash is invalid.
         :raises: :class:`KinErrors.ResourceNotFoundError`: if the transaction does not exist.
@@ -189,7 +189,7 @@ def get_account_tx_history(self, address, amount=10, descending=True, cursor=Non
         :param int cursor: The horizon paging token
         :param bool simple: Should the returned txs be simplified, if True, complicated txs will be ignored
         :return: A list of transactions
-        :rtype: list
+        :rtype: list[kin.transactions.RawTransaction | kin.transactions.SimplifiedTransaction]
         """
 
         if not is_valid_address(address):
@@ -264,13 +264,14 @@ def friendbot(self, address):
         """
         Use the friendbot service to create and fund an account
         :param str address: The address to create and fund
-        :return: the hash of the friendobt transaction
+
+        :return: the hash of the friendbot transaction
         :rtype str
 
         :raises ValueError: if no friendbot service was provided
         :raises ValueError: if the address is invalid
-        :raises :class: `KinErrors.AccountExistsError`: if the account already exists
-        :raises :class: `KinErrors.FriendbotError`: If the friendbot request failed
+        :raises KinErrors.AccountExistsError if the account already exists
+        :raises KinErrors.FriendbotError If the friendbot request failed
         """
 
         if self.environment.friendbot_url is None:
@@ -294,14 +295,14 @@ def monitor_account_payments(self, address, callback_fn):
         :param str address: the address of the account to query.
 
         :param callback_fn: the function to call on each received payment as `callback_fn(address, tx_data, monitor)`.
-        :type: callable[str,:class:`kin.TransactionData`,:class:`kin.SingleMonitor`]
+        :type: callable[str,kin.transactions.SimplifiedTransaction, kin.SingleMonitor]
 
         :return: a monitor instance
-        :rtype: :class:`kin.SingleMonitor`
+        :rtype: kin.monitors.SingleMonitor
 
         :raises: ValueError: when no address is given.
         :raises: ValueError: if the address is in the wrong format
-        :raises: :class:`KinErrors.AccountNotActivatedError`: if the account given is not activated
+        :raises: KinErrors.AccountNotActivatedError if the account given is not activated
         """
 
         return SingleMonitor(self, address, callback_fn)
@@ -313,14 +314,14 @@ def monitor_accounts_payments(self, addresses, callback_fn):
         :param str addresses: the addresses of the accounts to query.
 
         :param callback_fn: the function to call on each received payment as `callback_fn(address, tx_data, monitor)`.
-        :type: callable[str,:class:`kin.TransactionData`,:class:`kin.MultiMonitor`]
+        :type: callable[str,kin.transactions.SimplifiedTransaction ,kin.monitors.MultiMonitor]
 
         :return: a monitor instance
-        :rtype: :class:`kin.MultiMonitor`
+        :rtype: kin.monitors.MultiMonitor
 
         :raises: ValueError: when no address is given.
         :raises: ValueError: if the addresses are in the wrong format
-        :raises: :class:`KinErrors.AccountNotActivatedError`: if the accounts given are not activated
+        :raises: KinErrors.AccountNotActivatedError if the accounts given are not activated
         """
 
         return MultiMonitor(self, addresses, callback_fn)

kin/monitors.py

@@ -16,9 +16,10 @@ class SingleMonitor:
     def __init__(self, kin_client, address, callback_fn):
         """
         Monitors a single account for kin payments
-        :param kin_client: a kin client directed to the correct network
-        :param address: address to watch
-        :param callback_fn: function to callback when the payment is found
+        :param kin.KinClient kin_client: a kin client directed to the correct network
+        :param str address: address to watch
+        :param callback_fn: the function to call on each received payment as `callback_fn(address, tx_data, monitor)`.
+        :type: callable[str,kin.transactions.SimplifiedTransaction ,kin.monitors.MultiMonitor]
         """
         self.kin_client = kin_client
         self.callback_fn = callback_fn
@@ -57,7 +58,7 @@ def __init__(self, kin_client, address, callback_fn):
     def event_processor(self, stop_event):
         """
         Method to filter through SSE events and find kin payments for an account
-        :param stop_event: an event that can be used to stop this method
+        :param threading.Event stop_event: an event that can be used to stop this method
         """
         import json
         try:
@@ -108,9 +109,10 @@ class MultiMonitor:
     def __init__(self, kin_client, addresses, callback_fn):
         """
         Monitors multiple accounts for kin payments
-        :param kin_client: a kin client directed to the correct network
-        :param addresses: addresses to watch
-        :param callback_fn: function to callback when the payment is found
+        :param kin.KinClient kin_client: a kin client directed to the correct network
+        :param str addresses: addresses to watch
+        :param callback_fn: the function to call on each received payment as `callback_fn(address, tx_data, monitor)`.
+        :type: callable[str,kin.transactions.SimplifiedTransaction ,kin.monitors.MultiMonitor]
         """
         self.kin_client = kin_client
         self.callback_fn = callback_fn
@@ -148,7 +150,7 @@ def __init__(self, kin_client, addresses, callback_fn):
     def event_processor(self, stop_event):
         """
         Method to filter through SSE events and find kin payments for an account
-        :param stop_event: an event that can be used to stop this method
+        :param threading.Event stop_event: an event that can be used to stop this method
         """
         import json
         try: