diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index b1327dc0..96428663 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -29,7 +29,7 @@ We're pretty open about how people contribute to PyOTA, but there are a few thin - Please do not post support requests here. Use the ``#python`` channel on `Discord`_ - Please do not propose new API methods here. There are multiple IOTA API libraries out there, and they must all have the same functionality. - - That said, if you have an idea for a new API method, please share it on the ``#developers`` channel in `Discord`_ so that IOTA Foundation members can evaluate it! + - That said, if you have an idea for a new API method, please share it on the ``#clients-discussion`` channel in `Discord`_ so that IOTA Foundation members can evaluate it! Need Some Inspiration? diff --git a/README.rst b/README.rst index e143fd21..a3a89889 100644 --- a/README.rst +++ b/README.rst @@ -26,9 +26,9 @@ Dependencies ============ PyOTA is compatible with Python 3.7, 3.6, 3.5 and 2.7 -============ -Installation -============ +============= +Install PyOTA +============= To install the latest version:: pip install pyota diff --git a/docs/api.rst b/docs/api.rst index 2d14977f..e74743e6 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,485 +1,59 @@ -Core API -======== - -The Core API includes all of the core API calls that are made -available by the current `IOTA Reference -Implementation `__. - -These methods are "low level" and generally do not need to be called -directly. - -For the full documentation of all the Core API calls, please refer -to the `official documentation `__. - -Extended API -============ - -The Extended API includes a number of "high level" commands to perform -tasks such as sending and receiving transfers. - -``broadcast_and_store`` ------------------------ - -Broadcasts and stores a set of transaction trytes. - -Parameters -~~~~~~~~~~ - -- ``trytes: Iterable[TransactionTrytes]``: Transaction trytes. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``trytes: List[TransactionTrytes]``: Transaction trytes that were - broadcast/stored. Should be the same as the value of the ``trytes`` - parameter. - -``broadcast_bundle`` ------------------------ - -Re-broadcasts all transactions in a bundle given the tail transaction hash. -It might be useful when transactions did not properly propagate, -particularly in the case of large bundles. - -Parameters -~~~~~~~~~~ - -- ``tail_hash: TransactionHash``: Transaction hash of the tail transaction - of the bundle. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``trytes: List[TransactionTrytes]``: Transaction trytes that were - broadcast. - -``find_transaction_objects`` ----------------------------- - -A more extensive version of the core API ``find_transactions`` that returns -transaction objects instead of hashes. - -Effectively, this is ``find_transactions`` + ``get_trytes`` + converting -the trytes into transaction objects. It accepts the same parameters -as ``find_transactions`` - -Find the transactions which match the specified input. -All input values are lists, for which a list of return values -(transaction hashes), in the same order, is returned for all -individual elements. Using multiple of these input fields returns the -intersection of the values. - -Parameters -~~~~~~~~~~ - -- ``bundles: Optional[Iterable[BundleHash]]``: List of bundle IDs. -- ``addresses: Optional[Iterable[Address]]``: List of addresses. -- ``tags: Optional[Iterable[Tag]]``: List of tags. -- ``param: Optional[Iterable[TransactionHash]]``: List of approvee - transaction IDs. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``transactions: List[Transaction]``: List of Transaction objects that - match the input - -``get_account_data`` --------------------- - -More comprehensive version of ``get_transfers`` that returns addresses -and account balance in addition to bundles. - -This function is useful in getting all the relevant information of your -account. - -Parameters -~~~~~~~~~~ - -- ``start: int``: Starting key index. - -- ``stop: Optional[int]``: Stop before this index. Note that this - parameter behaves like the ``stop`` attribute in a ``slice`` object; - the stop index is *not* included in the result. - -- If ``None`` (default), then this method will check every address - until it finds one without any transfers. - -- ``inclusion_states: bool`` Whether to also fetch the inclusion states - of the transfers. This requires an additional API call to the node, - so it is disabled by default. - -Return -~~~~~~ - -This method returns a dict with the following items: - -- ``addresses: List[Address]``: List of generated addresses. Note that - this list may include unused addresses. - -- ``balance: int``: Total account balance. Might be 0. - -- ``bundles: List[Bundles]``: List of bundles with transactions to/from - this account. - -``get_bundles`` ---------------- - -Given a ``TransactionHash``, returns the bundle(s) associated with it. - -Parameters -~~~~~~~~~~ - -- ``transaction: TransactionHash``: Hash of a tail transaction. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``bundles: List[Bundle]``: List of matching bundles. Note that this - value is always a list, even if only one bundle was found. - -``get_inputs`` +PyOTA API Classes +================= + +**PyOTA offers you the Python API to interact with the IOTA network. +The available methods can be grouped into two categories:** + ++------------------------------------+------------------------------------+ +| Core API | Extended API | ++====================================+====================================+ +| | | +| | | Builds on top of the Core API to | +| | API commands for direct | | perform more complex operations, | +| | interaction with a node. | | and abstract away low-level IOTA | +| | | specific procedures. | +| | | ++------------------------------------+------------------------------------+ + +To use the API in your Python application or script, declare an +API instance of any of the two above. +**Since the Extended API incorporates the Core API, usually you end up only +using the Extended API,** but if for some reason you need only the core +functionality, the library is there to help you. + +.. code-block:: + :linenos: + :emphasize-lines: 3,4 + + from iota import Iota, StrictIota + + # This is how you declare an Extended API, use the methods of this object. + api = Iota('adapter-specification') + + # This is how you declare a Core API, use the methods of this object. + api = StrictIota('adapter-specification') + +.. py:module:: iota + +The PyOTA speific :py:class:`StrictIota` class implements the Core API, +while :py:class:`Iota` implements the Extended API. From a Python +implementation point of view, :py:class:`Iota` is a subclass of +:py:class:`StrictIota`, therefore it inherits every method and attribute +the latter has. + +Take a look on the class definitions and notice that :py:class:`Iota` +has a :py:class:`Seed` attribute. This is becasue the Extended API is able +to generate private keys, addresses and signatures from your seed. +**Your seed never leaves the library and your machine!** + +Core API Class -------------- -Gets all possible inputs of a seed and returns them with the total -balance. - -This is either done deterministically (by generating all addresses until -``find_transactions`` returns an empty result), or by providing a key -range to search. - -Parameters -~~~~~~~~~~ - -- ``start: int``: Starting key index. Defaults to 0. -- ``stop: Optional[int]``: Stop before this index. -- Note that this parameter behaves like the ``stop`` attribute in a - ``slice`` object; the stop index is *not* included in the result. -- If ``None`` (default), then this method will not stop until it finds - an unused address. -- ``threshold: Optional[int]``: If set, determines the minimum - threshold for a successful result: -- As soon as this threshold is reached, iteration will stop. -- If the command runs out of addresses before the threshold is reached, - an exception is raised. -- If ``threshold`` is 0, the first address in the key range with a - non-zero balance will be returned (if it exists). -- If ``threshold`` is ``None`` (default), this method will return - **all** inputs in the specified key range. - -Note that this method does not attempt to "optimize" the result (e.g., -smallest number of inputs, get as close to ``threshold`` as possible, -etc.); it simply accumulates inputs in order until the threshold is met. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``inputs: List[Address]``: Addresses with nonzero balances that can - be used as inputs. -- ``totalBalance: int``: Aggregate balance of all inputs found. - -``get_latest_inclusion`` ------------------------- - -Fetches the inclusion state for the specified transaction hashes, as of -the latest milestone that the node has processed. - -Parameters -~~~~~~~~~~ - -- ``hashes: Iterable[TransactionHash]``: Iterable of transaction - hashes. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``: bool``: Inclusion state for a single - transaction. - -There will be one item per transaction hash in the ``hashes`` parameter. - -``get_new_addresses`` ---------------------- - -Generates one or more new addresses from the seed. - -Parameters -~~~~~~~~~~ - -- ``index: int``: Specify the index of the new address (must be >= 1). -- ``count: Optional[int]``: Number of addresses to generate (must be >= - 1). -- If ``None``, this method will scan the Tangle to find the next - available unused address and return that. -- ``security_level: int``: Number of iterations to use when generating - new addresses. Lower values generate addresses faster, higher values - result in more secure signatures in transactions. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``addresses: List[Address]``: The generated address(es). Note that - this value is always a list, even if only one address was generated. - -``get_transaction_objects`` ---------------------------- -Returns a list of transaction objects given a list of transaction hashes. -This is effectively calling ``get_trytes`` and converting the trytes to -transaction objects. -Similar to ``find_transaction_objects``, but input is list of hashes. - -Parameters -~~~~~~~~~~ - -- ``hashes``: List of transaction hashes that should be fetched. - -Return -~~~~~~ - -Returns a ``dict`` with the following items: - -- ``transactions: List[Transaction]``: List of transaction objects. - -``get_transfers`` ------------------ - -Returns all transfers associated with the seed. - -Parameters -~~~~~~~~~~ - -- ``start: int``: Starting key index. -- ``stop: Optional[int]``: Stop before this index. -- Note that this parameter behaves like the ``stop`` attribute in a - ``slice`` object; the stop index is *not* included in the result. -- If ``None`` (default), then this method will check every address - until it finds one without any transfers. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``bundles: List[Bundle]``: Matching bundles, sorted by tail - transaction timestamp. - -``is_promotable`` -------------------- - -This extended API function helps you to determine whether a tail transaction -(bundle) is promotable. -Example usage could be to determine if a transaction can be promoted or you -should reattach (``replay_bundle``). - -The method takes a list of tail transaction hashes, calls ``check_consistency`` -to verify consistency. If successful, fetches the transaction trytes from the -Tangle and checks if ``attachment_timestamp`` is within reasonable limits. - -Parameters -~~~~~~~~~~ - -- ``tails: List[TransactionHash]``: Tail transaction hashes to check. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``promotable: bool``: ``True``, if: - - - Tails are consistent. - See `API Reference `_. - - ``attachment_timestamp`` for all transactions are less than current time - and attachement happened no earlier than ``depth`` milestones. - By default, ``depth`` = 6. - - parameter is ``False`` otherwise. - -- ``info: Optional(List[String])``: If ``promotable`` is ``False``, contains information - about the error. - -``is_reattachable`` -------------------- - -This API function helps you to determine whether you should replay a -transaction or make a new one (either with the same input, or a -different one). - -This method takes one or more input addresses (i.e. from spent -transactions) as input and then checks whether any transactions with a -value transferred are confirmed. - -If yes, it means that this input address has already been successfully -used in a different transaction, and as such you should no longer replay -the transaction. - -Parameters -~~~~~~~~~~ - -- ``address: Iterable[Address]``: List of addresses. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``reattachable: List[Bool]``: Always a list, even if only one address - was queried. - -``prepare_transfer`` --------------------- - -Prepares transactions to be broadcast to the Tangle, by generating the -correct bundle, as well as choosing and signing the inputs (for value -transfers). - -Parameters -~~~~~~~~~~ - -- ``transfers: Iterable[ProposedTransaction]``: Transaction objects to - prepare. -- ``inputs: Optional[Iterable[Address]]``: List of addresses used to - fund the transfer. Ignored for zero-value transfers. -- If not provided, addresses will be selected automatically by scanning - the Tangle for unspent inputs. -- ``change_address: Optional[Address]``: If inputs are provided, any - unspent amount will be sent to this address. -- If not specified, a change address will be generated automatically. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``trytes: List[TransactionTrytes]``: Raw trytes for the transactions - in the bundle, ready to be provided to ``send_trytes``. - -``promote_transaction`` ------------------------ - -Promotes a transaction by adding spam on top of it. - -- ``transaction: TransactionHash``: Transaction hash. Must be a tail. -- ``depth: int``: Depth at which to attach the bundle. -- ``min_weight_magnitude: Optional[int]``: Min weight magnitude, used - by the node to calibrate Proof of Work. -- If not provided, a default value will be used. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``bundle: Bundle``: The newly-published bundle. - -``replay_bundle`` ------------------ - -Takes a tail transaction hash as input, gets the bundle associated with -the transaction and then replays the bundle by attaching it to the -Tangle. - -Parameters -~~~~~~~~~~ - -- ``transaction: TransactionHash``: Transaction hash. Must be a tail. -- ``depth: int``: Depth at which to attach the bundle. -- ``min_weight_magnitude: Optional[int]``: Min weight magnitude, used - by the node to calibrate Proof of Work. -- If not provided, a default value will be used. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``trytes: List[TransactionTrytes]``: Raw trytes that were published - to the Tangle. - -``send_transfer`` ------------------ - -Prepares a set of transfers and creates the bundle, then attaches the -bundle to the Tangle, and broadcasts and stores the transactions. - -Parameters -~~~~~~~~~~ - -- ``depth: int``: Depth at which to attach the bundle. -- ``transfers: Iterable[ProposedTransaction]``: Transaction objects to - prepare. -- ``inputs: Optional[Iterable[Address]]``: List of addresses used to - fund the transfer. Ignored for zero-value transfers. -- If not provided, addresses will be selected automatically by scanning - the Tangle for unspent inputs. -- ``change_address: Optional[Address]``: If inputs are provided, any - unspent amount will be sent to this address. -- If not specified, a change address will be generated automatically. -- ``min_weight_magnitude: Optional[int]``: Min weight magnitude, used - by the node to calibrate Proof of Work. -- If not provided, a default value will be used. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``bundle: Bundle``: The newly-published bundle. - -``send_trytes`` ---------------- - -Attaches transaction trytes to the Tangle, then broadcasts and stores -them. - -Parameters -~~~~~~~~~~ - -- ``trytes: Iterable[TransactionTrytes]``: Transaction trytes to - publish. -- ``depth: int``: Depth at which to attach the bundle. -- ``min_weight_magnitude: Optional[int]``: Min weight magnitude, used - by the node to calibrate Proof of Work. -- If not provided, a default value will be used. - -Return -~~~~~~ - -This method returns a ``dict`` with the following items: - -- ``trytes: List[TransactionTrytes]``: Raw trytes that were published - to the Tangle. - -``traverse_bundle`` -------------------- - -Given a tail ``TransactionHash``, returns the bundle(s) associated with it. -Unlike ``get_bundles``, this command does not validate the fetched bundle(s). - -Parameters -~~~~~~~~~~ - -- ``tail_hash: TransactionHash``: Hash of a tail transaction. - -Return -~~~~~~ +.. autoclass:: StrictIota + :members: set_local_pow -This method returns a ``dict`` with the following items: +Extended API Class +------------------ -- ``bundles: List[Bundle]``: List of matching bundles. Note that this - value is always a list, even if only one bundle was found. +.. autoclass:: Iota + :members: set_local_pow diff --git a/docs/conf.py b/docs/conf.py index b524b3cb..9a66bd0d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,7 +31,7 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = [] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosectionlabel'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/core_api.rst b/docs/core_api.rst new file mode 100644 index 00000000..37d4d5d0 --- /dev/null +++ b/docs/core_api.rst @@ -0,0 +1,87 @@ +Core API Methods +================ + +The Core API includes all of the core API calls that are made +available by the current `IOTA Reference +Implementation `__. + +These methods are "low level" and generally do not need to be called +directly. + +For the full documentation of all the Core API calls, please refer +to the `official documentation `__. + +.. py:currentmodule:: iota + +``add_neighbors`` +----------------- +.. automethod:: Iota.add_neighbors + +``attach_to_tangle`` +-------------------- +.. automethod:: Iota.attach_to_tangle + +``broadcast_transactions`` +-------------------------- +.. automethod:: Iota.broadcast_transactions + +``check_consistency`` +--------------------- +.. automethod:: Iota.check_consistency + +``find_transactions`` +--------------------- +.. automethod:: Iota.find_transactions + +``get_balances`` +---------------- +.. automethod:: Iota.get_balances + +``get_inclusion_states`` +------------------------ +.. automethod:: Iota.get_inclusion_states + +``get_missing_transactions`` +---------------------------- +.. automethod:: Iota.get_missing_transactions + +``get_neighbors`` +----------------- +.. automethod:: Iota.get_neighbors + +``get_node_api_configuration`` +------------------------------ +.. automethod:: Iota.get_node_api_configuration + +``get_node_info`` +----------------- +.. automethod:: Iota.get_node_info + +``get_tips`` +------------ +.. automethod:: Iota.get_tips + +``get_transactions_to_approve`` +------------------------------- +.. automethod:: Iota.get_transactions_to_approve + +``get_trytes`` +-------------- +.. automethod:: Iota.get_trytes + +``interrupt_attaching_to_tangle`` +--------------------------------- +.. automethod:: Iota.interrupt_attaching_to_tangle + +``remove_neighbors`` +-------------------- +.. automethod:: Iota.remove_neighbors + +``store_transactions`` +---------------------- +.. automethod:: Iota.store_transactions + +``were_addresses_spent_from`` +----------------------------- +.. automethod:: Iota.were_addresses_spent_from \ No newline at end of file diff --git a/docs/extended_api.rst b/docs/extended_api.rst new file mode 100644 index 00000000..59b23b85 --- /dev/null +++ b/docs/extended_api.rst @@ -0,0 +1,80 @@ +Extended API Methods +==================== + +The Extended API includes a number of "high level" commands to perform +tasks such as sending and receiving transfers. + +.. py:currentmodule:: iota + +``broadcast_and_store`` +----------------------- +.. automethod:: Iota.broadcast_and_store + +``broadcast_bundle`` +-------------------- +.. automethod:: Iota.broadcast_bundle + +``find_transaction_objects`` +---------------------------- +.. automethod:: Iota.find_transaction_objects + +``get_account_data`` +-------------------- +.. automethod:: Iota.get_account_data + +``get_bundles`` +--------------- +.. automethod:: Iota.get_bundles + +``get_inputs`` +-------------- +.. automethod:: Iota.get_inputs + +``get_latest_inclusion`` +------------------------ +.. automethod:: Iota.get_latest_inclusion + +``get_new_addresses`` +--------------------- +.. automethod:: Iota.get_new_addresses + +``get_transaction_objects`` +--------------------------- +.. automethod:: Iota.get_transaction_objects + +``get_transfers`` +----------------- +.. automethod:: Iota.get_transfers + +``is_promotable`` +----------------- +.. automethod:: Iota.is_promotable + +``is_reattachable`` +------------------- +.. automethod:: Iota.is_reattachable + +``prepare_transfer`` +-------------------- +.. automethod:: Iota.prepare_transfer + +``promote_transaction`` +----------------------- +.. automethod:: Iota.promote_transaction + +``replay_bundle`` +----------------- +.. automethod:: Iota.replay_bundle + +``send_transfer`` +----------------- +.. automethod:: Iota.send_transfer + +``send_trytes`` +--------------- +.. automethod:: Iota.send_trytes + +``traverse_bundle`` +------------------- +.. automethod:: Iota.traverse_bundle + diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 0602b179..7eb8d1a5 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -15,6 +15,10 @@ Install PyOTA using `pip`: This extension boosts the performance of certain crypto operations significantly (speedups of 60x are common). +.. py:currentmodule:: iota.Iota + +.. _pow-label: + .. note:: The ``[pow]`` extra installs the optional `PyOTA-PoW extension`_. @@ -27,8 +31,8 @@ Install PyOTA using `pip`: api = Iota('https://nodes.thetangle.org:443', local_pow=True) - Or the ``set_local_pow`` method of the api class to dynamically enable/disable - the local proof-of-work feature. + Or the :py:meth:`set_local_pow` method of the api class to dynamically + enable/disable the local proof-of-work feature. Getting Started =============== diff --git a/docs/index.rst b/docs/index.rst index ba7b24bd..9f1dab8d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,8 @@ adapters addresses api + core_api + extended_api multisig .. include:: ../README.rst diff --git a/iota/api.py b/iota/api.py index 956bef58..47dcb7b8 100644 --- a/iota/api.py +++ b/iota/api.py @@ -64,17 +64,45 @@ class StrictIota(object): References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference + + :param AdapterSpec adapter: + URI string or BaseAdapter instance. + + :param Optional[bool] testnet: + Whether to use testnet settings for this instance. + On the testnet, minimum weight magnitude is set to 9, on mainnet + it is 1 by default. + + :param Optional[bool] local_pow: + Whether to perform proof-of-work locally by redirecting all calls + to :py:meth:`attach_to_tangle` to + `ccurl pow interface `_. + + See :ref:`Optional Local Pow` for more info and + :ref:`find out` how to use it. + """ commands = discover_commands('iota.commands.core') def __init__(self, adapter, testnet=False, local_pow=False): # type: (AdapterSpec, bool, bool) -> None """ - :param adapter: + :param AdapterSpec adapter: URI string or BaseAdapter instance. - :param testnet: + :param bool testnet: Whether to use testnet settings for this instance. + On the testnet, minimum weight magnitude is set to 9, on mainnet + it is 1 by default. + + :param Optional[bool] local_pow: + Whether to perform proof-of-work locally by redirecting all calls + to :py:meth:`attach_to_tangle` to + `ccurl pow interface `_. + + See :ref:`Optional Local Pow` for more info and + :ref:`find out` how to use it. + """ super(StrictIota, self).__init__() @@ -106,7 +134,7 @@ def __getattr__(self, command): If you want to execute an arbitrary API command, use :py:meth:`create_command`. - :param command: + :param Text command: The name of the command to create. References: @@ -145,20 +173,29 @@ def create_command(self, command): This method is useful for invoking undocumented or experimental methods, or if you just want to troll your node for awhile. - :param command: + :param Text command: The name of the command to create. + """ return CustomCommand(self.adapter, command) def set_local_pow(self, local_pow): # type: (bool) -> None """ - Sets the local_pow attribute of the adapter of the api instance. - If it is true, attach_to_tangle command calls external interface - to perform pow, instead of sending the request to a node. - By default, it is set to false. + Sets the :py:attr:`local_pow` attribute of the adapter of the api + instance. If it is ``True``, :py:meth:`attach_to_tangle` command calls + external interface to perform proof of work, instead of sending the + request to a node. + + By default, :py:attr:`local_pow` is set to ``False``. This particular method is needed if one wants to change local_pow behavior dynamically. + + :param bool local_pow: + Whether to perform pow locally. + + :returns: None + """ self.adapter.set_local_pow(local_pow) @@ -177,7 +214,7 @@ def add_neighbors(self, uris): Add one or more neighbors to the node. Lasts until the node is restarted. - :param uris: + :param Iterable[Text] uris: Use format ``://:``. Example: ``add_neighbors(['udp://example.com:14265'])`` @@ -186,6 +223,16 @@ def add_neighbors(self, uris): weird things will happen if you specify a node's HTTP API URI here). + :return: + ``dict`` with the following structure:: + + { + 'addedNeighbors': int, + Total number of added neighbors. + 'duration': int, + Number of milliseconds it took to complete the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#addneighbors @@ -205,12 +252,33 @@ def attach_to_tangle( doing Proof of Work. You need to supply branchTransaction as well as trunkTransaction (basically the tips which you're going to validate and reference with this transaction) - both of which - you'll get through the getTransactionsToApprove API call. + you'll get through the :py:meth:`get_transactions_to_approve` API call. The returned value is a different set of tryte values which you can input into :py:meth:`broadcast_transactions` and :py:meth:`store_transactions`. + :param TransactionHash trunk_transaction: + Trunk transaction hash. + + :param TransactionHash branch_transaction: + Branch transaction hash. + + :param Iterable[TransactionTrytes] trytes: + List of transaction trytes in the bundle to be attached. + + :param Optional[int] min_weight_magnitude: + Minimum weight magnitude to be used for attaching trytes. + 14 by default on mainnet, 9 on testnet/devnet. + + :return: + ``dict`` with the following structure:: + + { + 'trytes': List[TransactionTrytes], + Transaction trytes that include a valid nonce field. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#attachtotangle @@ -233,6 +301,17 @@ def broadcast_transactions(self, trytes): The input trytes for this call are provided by :py:meth:`attach_to_tangle`. + :param Iterable[TransactionTrytes] trytes: + List of transaction trytes to be broadcast. + + :return: + ``dict`` with the following structure:: + + { + 'duration': int, + Number of milliseconds it took to complete the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#broadcasttransactions @@ -243,7 +322,7 @@ def check_consistency(self, tails): # type: (Iterable[TransactionHash]) -> dict """ Used to ensure tail resolves to a consistent ledger which is - necessary to validate before attempting promotionChecks + necessary to validate before attempting promotion. Checks transaction hashes for promotability. This is called with a pending transaction (or more of them) and @@ -252,18 +331,17 @@ def check_consistency(self, tails): one) to be confirmed, or not (because it conflicts with another already confirmed transaction). - :param tails: + :param Iterable[TransactionHash] tails: Transaction hashes. Must be tail transactions. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'state': bool, - - 'info': str, - This field will only exist set if ``state`` is - ``False``. + Whether tails resolve to consistent ledger. + 'info': Text, + This field will only exist if 'state' is ``False``. } References: @@ -293,18 +371,26 @@ def find_transactions( Using multiple of these input fields returns the intersection of the values. - :param bundles: + :param Optional[Iterable[BundleHash] bundles: List of bundle IDs. - :param addresses: + :param Optional[Iterable[Address]] addresses: List of addresses. - :param tags: + :param Optional[Iterable[Tag]] tags: List of tags. - :param approvees: + :param Optional[Iterable[TransactionHash]] approvees: List of approvee transaction IDs. + :return: + ``dict`` with the following structure:: + + { + 'hashes': List[TransationHash], + Found transactions. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#findtransactions @@ -333,15 +419,33 @@ def get_balances( determined. The balances are returned as a list in the same order as the addresses were provided as input. - :param addresses: + :param Iterable[Address] addresses: List of addresses to get the confirmed balance for. - :param threshold: + :param int threshold: Confirmation threshold between 0 and 100. - :param tips: + :param Optional[Iterable[TransactionHash]] tips: Tips whose history of transactions to traverse to find the balance. + :return: + ``dict`` with the following structure:: + + { + 'balances': List[int], + List of balances in the same order as the addresses + parameters that were passed to the endpoint. + 'references': List[TransactionHash], + The referencing tips. If no tips parameter was passed + to the endpoint, this field contains the hash of the + latest milestone that confirmed the balance. + 'milestoneIndex': int, + The index of the milestone that confirmed the most + recent balance. + 'duration': int, + Number of milliseconds it took to process the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#getbalances @@ -360,14 +464,26 @@ def get_inclusion_states(self, transactions, tips): network or not. You can search for multiple tips (and thus, milestones) to get past inclusion states of transactions. - :param transactions: + :param Iterable[TransactionHash] transactions: List of transactions you want to get the inclusion state for. - :param tips: + :param Iterable[TransactionHash] tips: List of tips (including milestones) you want to search for the inclusion state. + :return: + ``dict`` with the following structure:: + + { + 'states': List[bool], + List of boolean values in the same order as the + transactions parameters. A ``True`` value means the + transaction was confirmed. + 'duration': int, + Number of milliseconds it took to process the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#getinclusionstates @@ -383,6 +499,16 @@ def get_missing_transactions(self): Returns all transaction hashes that a node is currently requesting from its neighbors. + :return: + ``dict`` with the following structure:: + + { + 'hashes': List[TransactionHash], + Array of missing transaction hashes. + 'duration': int, + Number of milliseconds it took to process the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#getmissingtransactions @@ -397,6 +523,25 @@ def get_neighbors(self): The activity counter is reset after restarting IRI. + :return: + ``dict`` with the following structure:: + + { + 'neighbors': List[dict], + Array of objects, including the following fields with + example values: + "address": "/8.8.8.8:14265", + "numberOfAllTransactions": 158, + "numberOfRandomTransactionRequests": 271, + "numberOfNewTransactions": 956, + "numberOfInvalidTransactions": 539, + "numberOfStaleTransactions": 663, + "numberOfSentTransactions": 672, + "connectiontype": "TCP" + 'duration': int, + Number of milliseconds it took to process the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#getneighbors @@ -408,8 +553,21 @@ def get_node_api_configuration(self): """ Returns a node's API configuration settings. + :return: + ``dict`` with the following structure:: + + { + '': type, + Configuration parameters for a node. + ... + ... + ... + + } + References: + - https://docs.iota.org/docs/node-software/0.1/iri/references/iri-configuration-options - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#getnodeapiconfiguration """ return core.GetNodeAPIConfigurationCommand(self.adapter)() @@ -419,6 +577,54 @@ def get_node_info(self): """ Returns information about the node. + :return: + ``dict`` with the following structure:: + + { + 'appName': Text, + Name of the IRI network. + 'appVersion': Text, + Version of the IRI. + 'jreAvailableProcessors': int, + Available CPU cores on the node. + 'jreFreeMemory': int, + Amount of free memory in the Java virtual machine. + 'jreMaxMemory': int, + Maximum amount of memory that the Java virtual machine + can use, + 'jreTotalMemory': int, + Total amount of memory in the Java virtual machine. + 'jreVersion': Text, + The version of the Java runtime environment. + 'latestMilestone': TransactionHash + Transaction hash of the latest milestone. + 'latestMilestoneIndex': int, + Index of the latest milestone. + 'latestSolidSubtangleMilestone': TransactionHash, + Transaction hash of the latest solid milestone. + 'latestSolidSubtangleMilestoneIndex': int, + Index of the latest solid milestone. + 'milestoneStartIndex': int, + Start milestone for the current version of the IRI. + 'neighbors': int, + Total number of connected neighbor nodes. + 'packetsQueueSize': int, + Size of the packet queue. + 'time': int, + Current UNIX timestamp. + 'tips': int, + Number of tips in the network. + 'transactionsToRequest': int, + Total number of transactions that the node is missing in + its ledger. + 'features': List[Text], + Enabled configuration options. + 'coordinatorAddress': Address, + Address (Merkle root) of the Coordinator. + 'duration': int, + Number of milliseconds it took to process the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#getnodeinfo @@ -431,6 +637,16 @@ def get_tips(self): Returns the list of tips (transactions which have no other transactions referencing them). + :return: + ``dict`` with the following structure:: + + { + 'hashes': List[TransactionHash], + List of tip transaction hashes. + 'duration': int, + Number of milliseconds it took to complete the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#gettips @@ -444,19 +660,30 @@ def get_transactions_to_approve(self, depth, reference=None): Tip selection which returns ``trunkTransaction`` and ``branchTransaction``. - :param depth: - Determines how many bundles to go back to when finding the - transactions to approve. + :param int depth: + Number of milestones to go back to start the tip selection algorithm. The higher the depth value, the more "babysitting" the node will perform for the network (as it will confirm more transactions that way). - :param reference: + :param TransactionHash reference: Transaction hash from which to start the weighted random walk. Use this parameter to make sure the returned tip transaction hashes approve a given reference transaction. + :return: + ``dict`` with the following structure:: + + { + 'trunkTransaction': TransactionHash, + Valid trunk transaction hash. + 'branchTransaction': TransactionHash, + Valid branch transaction hash. + 'duration': int, + Number of milliseconds it took to complete the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#gettransactionstoapprove @@ -472,6 +699,22 @@ def get_trytes(self, hashes): Returns the raw transaction data (trytes) of one or more transactions. + :return: + ``dict`` with the following structure:: + + { + 'trytes': List[TransactionTrytes], + List of transaction trytes for the given transaction + hashes (in the same order as the parameters). + 'duration': int, + Number of milliseconds it took to complete the request. + } + + .. note:: + If a node doesn't have the trytes for a given transaction hash in + its ledger, the value at the index of that transaction hash is either + ``null`` or a string of 9s. + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#gettrytes @@ -484,6 +727,14 @@ def interrupt_attaching_to_tangle(self): Interrupts and completely aborts the :py:meth:`attach_to_tangle` process. + :return: + ``dict`` with the following structure:: + + { + 'duration': int, + Number of milliseconds it took to complete the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#interruptattachingtotangle @@ -496,10 +747,20 @@ def remove_neighbors(self, uris): Removes one or more neighbors from the node. Lasts until the node is restarted. - :param uris: + :param Text uris: Use format ``://:``. Example: `remove_neighbors(['udp://example.com:14265'])` + :return: + ``dict`` with the following structure:: + + { + 'removedNeighbors': int, + Total number of removed neighbors. + 'duration': int, + Number of milliseconds it took to complete the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#removeneighbors @@ -509,11 +770,24 @@ def remove_neighbors(self, uris): def store_transactions(self, trytes): # type: (Iterable[TryteString]) -> dict """ - Store transactions into local storage. + Store transactions into local storage of the node. The input trytes for this call are provided by :py:meth:`attach_to_tangle`. + :param TransactionTrytes trytes: + Valid transaction trytes returned by :py:meth:`attach_to_tangle`. + + :return: + ``dict`` with the following structure:: + + { + 'trytes': TransactionTrytes, + Stored trytes. + 'duration': int, + Number of milliseconds it took to complete the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#storetransactions @@ -526,9 +800,23 @@ def were_addresses_spent_from(self, addresses): Check if a list of addresses was ever spent from, in the current epoch, or in previous epochs. - :param addresses: + If an address has a pending transaction, it's also considered 'spent'. + + :param Iterable[Address] addresses: List of addresses to check. + :return: + ``dict`` with the following structure:: + + { + 'states': List[bool], + States of the specified addresses in the same order as + the values in the addresses parameter. A ``True`` value + means that the address has been spent from. + 'duration': int, + Number of milliseconds it took to complete the request. + } + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#wereaddressesspentfrom @@ -543,6 +831,32 @@ class Iota(StrictIota): Implements the core API, plus additional wrapper methods for common operations. + :param AdapterSpec adapter: + URI string or BaseAdapter instance. + + :param Optional[Seed] seed: + Seed used to generate new addresses. + If not provided, a random one will be generated. + + .. note:: + This value is never transferred to the node/network. + + :param Optional[bool] testnet: + Whether to use testnet settings for this instance. + On the testnet, minimum weight magnitude is decreased, on mainnet + it is 14 by default. + + For more info on the Mainnet and the Devnet, visit + `the official docs site`. + + :param Optional[bool] local_pow: + Whether to perform proof-of-work locally by redirecting all calls + to :py:meth:`attach_to_tangle` to + `ccurl pow interface `_. + + See :ref:`Optional Local Pow` for more info and + :ref:`find out` how to use it. + References: - https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference @@ -570,8 +884,11 @@ def broadcast_and_store(self, trytes): """ Broadcasts and stores a set of transaction trytes. + :param Iterable[TransactionTrytes] trytes: + Transaction trytes to broadcast and store. + :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'trytes': List[TransactionTrytes], @@ -592,11 +909,11 @@ def broadcast_bundle(self, tail_transaction_hash): It might be useful when transactions did not properly propagate, particularly in the case of large bundles. - :param tail_transaction_hash: + :param TransactionHash tail_transaction_hash: Tail transaction hash of the bundle. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'trytes': List[TransactionTrytes], @@ -622,30 +939,38 @@ def find_transaction_objects( A more extensive version of :py:meth:`find_transactions` that returns transaction objects instead of hashes. - Effectively, this is ``find_transactions`` + ``get_trytes`` + - converting the trytes into transaction objects. + Effectively, this is :py:meth:`find_transactions` + + :py:meth:`get_trytes` + converting the trytes into + transaction objects. + + It accepts the same parameters as :py:meth:`find_transactions`. - It accepts the same parameters as :py:meth:`find_transactions` + Find the transactions which match the specified input. + All input values are lists, for which a list of return values + (transaction hashes), in the same order, is returned for all + individual elements. Using multiple of these input fields returns the + intersection of the values. - :param bundles: + :param Optional[Iterable[BundleHash]] bundles: List of bundle IDs. - :param addresses: + :param Optional[Iterable[Address]] addresses: List of addresses. - :param tags: + :param Optional[Iterable[Tag]] tags: List of tags. - :param approvees: + :param Optional[Iterable[TransactionHash]] approvees: List of approvee transaction IDs. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'transactions': List[Transaction], List of Transaction objects that match the input. } + """ return extended.FindTransactionObjectsCommand(self.adapter)( bundles=bundles, @@ -663,10 +988,10 @@ def get_account_data(self, start=0, stop=None, inclusion_states=False, security_ This function is useful in getting all the relevant information of your account. - :param start: + :param int start: Starting key index. - :param stop: + :param Optional[int] stop: Stop before this index. Note that this parameter behaves like the ``stop`` attribute @@ -676,13 +1001,13 @@ def get_account_data(self, start=0, stop=None, inclusion_states=False, security_ If ``None`` (default), then this method will check every address until it finds one without any transfers. - :param inclusion_states: + :param bool inclusion_states: Whether to also fetch the inclusion states of the transfers. This requires an additional API call to the node, so it is disabled by default. - :param security_level: + :param Optional[int] security_level: Number of iterations to use when generating new addresses (see :py:meth:`get_new_addresses`). @@ -692,7 +1017,7 @@ def get_account_data(self, start=0, stop=None, inclusion_states=False, security_ :py:attr:`AddressGenerator.DEFAULT_SECURITY_LEVEL`. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'addresses': List[Address], @@ -708,6 +1033,7 @@ def get_account_data(self, start=0, stop=None, inclusion_states=False, security_ List of bundles with transactions to/from this account. } + """ return extended.GetAccountDataCommand(self.adapter)( seed=self.seed, @@ -723,11 +1049,11 @@ def get_bundles(self, transaction): Returns the bundle(s) associated with the specified transaction hash. - :param transaction: + :param TransactionHash transaction: Transaction hash. Must be a tail transaction. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'bundles': List[Bundle], @@ -761,11 +1087,11 @@ def get_inputs( addresses until :py:meth:`find_transactions` returns an empty result), or by providing a key range to search. - :param start: + :param int start: Starting key index. Defaults to 0. - :param stop: + :param Optional[int] stop: Stop before this index. Note that this parameter behaves like the ``stop`` attribute @@ -775,7 +1101,7 @@ def get_inputs( If ``None`` (default), then this method will not stop until it finds an unused address. - :param threshold: + :param Optional[int] threshold: If set, determines the minimum threshold for a successful result: @@ -795,7 +1121,7 @@ def get_inputs( If ``threshold`` is ``None`` (default), this method will return **all** inputs in the specified key range. - :param security_level: + :param Optional[int] security_level: Number of iterations to use when generating new addresses (see :py:meth:`get_new_addresses`). @@ -805,7 +1131,7 @@ def get_inputs( :py:attr:`AddressGenerator.DEFAULT_SECURITY_LEVEL`. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'inputs': List[Address], @@ -816,8 +1142,8 @@ def get_inputs( Aggregate balance from all matching addresses. } - Note that each Address in the result has its ``balance`` - attribute set. + Note that each :py:class:`Address` in the result has its + :py:attr:`Address.balance` attribute set. Example: @@ -850,19 +1176,21 @@ def get_latest_inclusion(self, hashes): Fetches the inclusion state for the specified transaction hashes, as of the latest milestone that the node has processed. - Effectively, this is ``getNodeInfo`` + ``getInclusionStates``. + Effectively, this is :py:meth:`get_node_info` + + :py:meth:`get_inclusion_states`. - :param hashes: - Iterable of transaction hashes. + :param Iterable[TransactionHash] hashes: + List of transaction hashes. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { "states": Dict[TransactionHash, bool] - Dict with one boolean per transaction hash in + ``dict`` with one boolean per transaction hash in ``hashes``. } + """ return extended.GetLatestInclusionCommand(self.adapter)(hashes=hashes) @@ -873,26 +1201,26 @@ def get_new_addresses( security_level=AddressGenerator.DEFAULT_SECURITY_LEVEL, checksum=False, ): - # type: (int, Optional[int], int, bool) -> dict + # type: (int, int, int, bool) -> dict """ Generates one or more new addresses from the seed. - :param index: + :param int index: The key index of the first new address to generate (must be - >= 1). + >= 0). - :param count: + :param int count: Number of addresses to generate (must be >= 1). .. tip:: - This is more efficient than calling ``get_new_address`` + This is more efficient than calling :py:meth:`get_new_addresses` inside a loop. If ``None``, this method will progressively generate addresses and scan the Tangle until it finds one that has no transactions referencing it. - :param security_level: + :param int security_level: Number of iterations to use when generating new addresses. Larger values take longer, but the resulting signatures are @@ -900,18 +1228,18 @@ def get_new_addresses( This value must be between 1 and 3, inclusive. - :param checksum: + :param bool checksum: Specify whether to return the address with the checksum. Defaults to ``False``. :return: - Dict with the following structure:: + ``dict`` with the following structure:: - { - 'addresses': List[Address], - Always a list, even if only one address was - generated. - } + { + 'addresses': List[Address], + Always a list, even if only one address was + generated. + } References: @@ -934,17 +1262,17 @@ def get_transaction_objects( Fetches transaction objects from the Tangle given their transaction IDs (hashes). - Effectively, this is ``get_trytes`` + + Effectively, this is :py:meth:`get_trytes` + converting the trytes into transaction objects. Similar to :py:meth:`find_transaction_objects`, but accepts - list of trnsaction hashes as input. + list of transaction hashes as input. - :param hashes: + :param Iterable[TransactionHash] hashes: List of transaction IDs (transaction hashes). :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'transactions': List[Transaction], @@ -960,10 +1288,10 @@ def get_transfers(self, start=0, stop=None, inclusion_states=False): """ Returns all transfers associated with the seed. - :param start: + :param int start: Starting key index. - :param stop: + :param Optional[int] stop: Stop before this index. Note that this parameter behaves like the ``stop`` attribute @@ -973,14 +1301,14 @@ def get_transfers(self, start=0, stop=None, inclusion_states=False): If ``None`` (default), then this method will check every address until it finds one without any transfers. - :param inclusion_states: + :param bool inclusion_states: Whether to also fetch the inclusion states of the transfers. This requires an additional API call to the node, so it is disabled by default. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'bundles': List[Bundle], @@ -1009,25 +1337,25 @@ def is_promotable( # type: (Iterable(TransactionHash)] -> dict """ Checks if tail transaction(s) is promotable by calling - :py:meth:`check_consistency` and verifying that `attachmentTimestamp` + :py:meth:`check_consistency` and verifying that ``attachmentTimestamp`` is above a lower bound. Lower bound is calculated based on number of milestones issued since transaction attachment. - :param tails: + :param Iterable(TransactionHash) tails: List of tail transaction hashes. :return: The return type mimics that of :py:meth:`check_consistency`. - Dict with the following structure:: + ``dict`` with the following structure:: { 'promotable': bool, - If true, all tails are promotable. If false, see `info` - field. + If ``True``, all tails are promotable. If ``False``, see + `info` field. - 'info': Optional(List[String]) - If `promotable` is false, this contains info about what + 'info': Optional(List[Text]) + If `promotable` is ``False``, this contains info about what went wrong. } @@ -1052,10 +1380,10 @@ def prepare_transfer( generating the correct bundle, as well as choosing and signing the inputs (for value transfers). - :param transfers: + :param Iterable[ProposedTransaction] transfers: Transaction objects to prepare. - :param inputs: + :param Optional[Iterable[Address]] inputs: List of addresses used to fund the transfer. Ignored for zero-value transfers. @@ -1064,14 +1392,14 @@ def prepare_transfer( many transfers you've already sent with your seed, this process could take awhile. - :param change_address: + :param Optional[Address] change_address: If inputs are provided, any unspent amount will be sent to this address. If not specified, a change address will be generated automatically. - :param security_level: + :param Optional[int] security_level: Number of iterations to use when generating new addresses (see :py:meth:`get_new_addresses`). @@ -1081,7 +1409,7 @@ def prepare_transfer( :py:attr:`AddressGenerator.DEFAULT_SECURITY_LEVEL`. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'trytes': List[TransactionTrytes], @@ -1111,21 +1439,21 @@ def promote_transaction( """ Promotes a transaction by adding spam on top of it. - :param transaction: + :param TransactionHash transaction: Transaction hash. Must be a tail transaction. - :param depth: + :param int depth: Depth at which to attach the bundle. Defaults to 3. - :param min_weight_magnitude: + :param Optional[int] min_weight_magnitude: Min weight magnitude, used by the node to calibrate Proof of Work. If not provided, a default value will be used. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'bundle': Bundle, @@ -1153,21 +1481,21 @@ def replay_bundle( associated with the transaction and then replays the bundle by attaching it to the Tangle. - :param transaction: + :param TransactionHash transaction: Transaction hash. Must be a tail. - :param depth: + :param int depth: Depth at which to attach the bundle. Defaults to 3. - :param min_weight_magnitude: + :param Optional[int] min_weight_magnitude: Min weight magnitude, used by the node to calibrate Proof of Work. If not provided, a default value will be used. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'trytes': List[TransactionTrytes], @@ -1202,31 +1530,31 @@ def send_transfer( attaches the bundle to the Tangle, and broadcasts and stores the transactions. - :param transfers: + :param Iterable[ProposedTransaction] transfers: Transfers to include in the bundle. - :param depth: + :param int depth: Depth at which to attach the bundle. Defaults to 3. - :param inputs: + :param Optional[Iterable[Address]] inputs: List of inputs used to fund the transfer. Not needed for zero-value transfers. - :param change_address: + :param Optional[Address] change_address: If inputs are provided, any unspent amount will be sent to this address. If not specified, a change address will be generated automatically. - :param min_weight_magnitude: + :param Optional[int] min_weight_magnitude: Min weight magnitude, used by the node to calibrate Proof of Work. If not provided, a default value will be used. - :param security_level: + :param Optional[int] security_level: Number of iterations to use when generating new addresses (see :py:meth:`get_new_addresses`). @@ -1236,7 +1564,7 @@ def send_transfer( :py:attr:`AddressGenerator.DEFAULT_SECURITY_LEVEL`. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'bundle': Bundle, @@ -1266,21 +1594,21 @@ def send_trytes(self, trytes, depth=3, min_weight_magnitude=None): Attaches transaction trytes to the Tangle, then broadcasts and stores them. - :param trytes: + :param Iterable[TransactionTrytes] trytes: Transaction encoded as a tryte sequence. - :param depth: + :param int depth: Depth at which to attach the bundle. Defaults to 3. - :param min_weight_magnitude: + :param Optional[int] min_weight_magnitude: Min weight magnitude, used by the node to calibrate Proof of Work. If not provided, a default value will be used. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'trytes': List[TransactionTrytes], @@ -1315,16 +1643,17 @@ def is_reattachable(self, addresses): successfully used in a different transaction, and as such you should no longer replay the transaction. - :param addresses: + :param Iterable[Address] addresses: List of addresses. :return: - Dict with the following structure:: + ``dict`` with the following structure:: { 'reattachable': List[bool], Always a list, even if only one address was queried. } + """ return extended.IsReattachableCommand(self.adapter)( addresses=addresses @@ -1338,20 +1667,21 @@ def traverse_bundle(self, tail_hash): Recursively traverse the Tangle, collecting transactions until we hit a new bundle. - This method is (usually) faster than ``findTransactions``, and + This method is (usually) faster than :py:meth:`find_transactions`, and it ensures we don't collect transactions from replayed bundles. - :param tail_hash: + :param TransactionHash tail_hash: Tail transaction hash of the bundle. :return: - Dict with the following structure:: + ``dict`` with the following structure:: + + { + 'bundle': List[Bundle], + List of matching bundles. Note that this value is + always a list, even if only one bundle was found. + } - { - 'bundle': List[Bundle], - List of matching bundles. Note that this value is - always a list, even if only one bundle was found. - } """ return extended.TraverseBundleCommand(self.adapter)( transaction=tail_hash diff --git a/iota/transaction/types.py b/iota/transaction/types.py index b92da789..a76bea19 100644 --- a/iota/transaction/types.py +++ b/iota/transaction/types.py @@ -34,6 +34,9 @@ class Fragment(TryteString): A signature/message fragment in a transaction. """ LEN = FRAGMENT_LENGTH + """ + Length of a fragment in trytes. + """ def __init__(self, trytes): # type: (TrytesCompatible) -> None @@ -57,6 +60,9 @@ class TransactionTrytes(TryteString): A TryteString representation of a Transaction. """ LEN = 2673 + """ + Length of a transaction in trytes. + """ def __init__(self, trytes): # type: (TrytesCompatible) -> None @@ -80,6 +86,9 @@ class Nonce(TryteString): A TryteString that acts as a transaction nonce. """ LEN = 27 + """ + Length of a nonce in trytes. + """ def __init__(self, trytes): # type: (TrytesCompatible) -> None