hive-nectar 0.0.11__py3-none-any.whl → 0.1.0__py3-none-any.whl

nectar/amount.py

@@ -5,10 +5,15 @@ from nectar.asset import Asset
 from nectar.instance import shared_blockchain_instance
 
 
-def check_asset(other, self, stm):
+def check_asset(other, self, hv):
+    """
+    Assert that two asset representations refer to the same asset.
+
+    If both `other` and `self` are dicts containing an "asset" key, each asset id is wrapped in an Asset using the provided blockchain instance and compared for equality. Otherwise the two values are compared directly. Raises AssertionError if the values do not match.
+    """
     if isinstance(other, dict) and "asset" in other and isinstance(self, dict) and "asset" in self:
-        if not Asset(other["asset"], blockchain_instance=stm) == Asset(
-            self["asset"], blockchain_instance=stm
+        if not Asset(other["asset"], blockchain_instance=hv) == Asset(
+            self["asset"], blockchain_instance=hv
         ):
             raise AssertionError()
     else:
@@ -31,16 +36,16 @@ class Amount(dict):
     :param list args: Allows to deal with different representations of an amount
     :param float amount: Let's create an instance with a specific amount
     :param str asset: Let's you create an instance with a specific asset (symbol)
-    :param boolean fixed_point_arithmetic: when set to True, all operation are fixed
+    :param boolean fixed_point_arithmetic: when set to True, all operations are fixed
         point operations and the amount is always be rounded down to the precision
-    :param Steem steem_instance: Steem instance
+    :param Blockchain blockchain_instance: Blockchain instance
     :returns: All data required to represent an Amount/Asset
     :rtype: dict
     :raises ValueError: if the data provided is not recognized
 
     Way to obtain a proper instance:
 
-        * ``args`` can be a string, e.g.:  "1 SBD"
+        * ``args`` can be a string, e.g.:  "1 HBD"
         * ``args`` can be a dictionary containing ``amount`` and ``asset_id``
         * ``args`` can be a dictionary containing ``amount`` and ``asset``
         * ``args`` can be a list of a ``float`` and ``str`` (symbol)
@@ -60,9 +65,9 @@ class Amount(dict):
 
         from nectar.amount import Amount
         from nectar.asset import Asset
-        a = Amount("1 STEEM")
-        b = Amount(1, "STEEM")
-        c = Amount("20", Asset("STEEM"))
+        a = Amount("1 HIVE")
+        b = Amount(1, "HIVE")
+        c = Amount("20", Asset("HIVE"))
         a + b
         a * 2
         a += b
@@ -70,8 +75,8 @@ class Amount(dict):
 
     .. testoutput::
 
-        2.000 STEEM
-        2.000 STEEM
+        2.000 HIVE
+        2.000 HIVE
 
     """
 
@@ -84,15 +89,38 @@ class Amount(dict):
         blockchain_instance=None,
         **kwargs,
     ):
+        """
+        Initialize an Amount object representing a quantity of a specific blockchain asset.
+
+        The constructor accepts many input formats and normalizes them into internal keys:
+        - amount may be another Amount, a three-element list [amount, precision, asset],
+          a new appbase-format dict with keys ("amount", "nai", "precision"), a legacy dict
+          with ("amount", "asset_id") or ("amount", "asset"), a string like "1.000 HIVE",
+          or a numeric value (int, float, Decimal) paired with an `asset` argument.
+        - asset may be an Asset instance, an asset dict, or a symbol string; when omitted,
+          the asset will be inferred from the provided `amount` representation.
+
+        After parsing, the instance stores:
+        - "amount" as a Decimal (or quantized Decimal when fixed-point mode is enabled),
+        - "symbol" as the asset symbol,
+        - "asset" as an Asset-like object.
+
+        Parameters:
+            amount: Various accepted formats (see description) representing the quantity.
+            asset: Asset instance, asset dict, or asset symbol string used when `amount`
+                is a bare numeric value or when explicit asset resolution is required.
+            fixed_point_arithmetic (bool): When True, the numeric amount is quantized
+                to the asset's precision using floor rounding.
+            new_appbase_format (bool): Indicates whether to prefer the new appbase JSON
+                format when producing serialized representations.
+
+        Raises:
+            ValueError: If `amount` and `asset` do not match any supported input format.
+        """
         self["asset"] = {}
         self.new_appbase_format = new_appbase_format
         self.fixed_point_arithmetic = fixed_point_arithmetic
 
-        if blockchain_instance is None:
-            if kwargs.get("steem_instance"):
-                blockchain_instance = kwargs["steem_instance"]
-            elif kwargs.get("hive_instance"):
-                blockchain_instance = kwargs["hive_instance"]
         self.blockchain = blockchain_instance or shared_blockchain_instance()
 
         if amount and asset is None and isinstance(amount, Amount):
@@ -221,8 +249,14 @@ class Amount(dict):
 
     @property
     def asset(self):
-        """Returns the asset as instance of :class:`steem.asset.Asset`"""
-        if not self["asset"]:
+        """
+        Return the Asset object for this Amount, constructing it lazily if missing.
+
+        If the internal 'asset' entry is falsy, this creates a nectar.asset.Asset using the stored symbol
+        and this Amount's blockchain instance, stores it in 'asset', and returns it. Always returns an
+        Asset instance.
+        """
+        if not isinstance(self["asset"], Asset):
             self["asset"] = Asset(self["symbol"], blockchain_instance=self.blockchain)
         return self["asset"]
 
@@ -381,9 +415,20 @@ class Amount(dict):
         return self
 
     def __idiv__(self, other):
+        """
+        In-place division: divide this Amount by another Amount or numeric value and return self.
+
+        If `other` is an Amount, asserts asset compatibility and divides this object's internal amount by the other's amount. If `other` is numeric, divides by Decimal(other). When `fixed_point_arithmetic` is enabled, the result is quantized to this asset's precision.
+
+        Returns:
+            self (Amount): The mutated Amount instance.
+
+        Raises:
+            AssertionError: If `other` is an Amount with a different asset (via check_asset).
+        """
         if isinstance(other, Amount):
             check_asset(other["asset"], self["asset"], self.blockchain)
-            return self["amount"] / other["amount"]
+            self["amount"] = self["amount"] / other["amount"]
         else:
             self["amount"] /= Decimal(other)
         if self.fixed_point_arithmetic:
@@ -442,18 +487,33 @@ class Amount(dict):
             return quant_amount == quantize((other or 0), self["asset"]["precision"])
 
     def __ne__(self, other):
+        """
+        Return True if this Amount is not equal to `other`.
+
+        Compares values after quantizing both sides to this amount's asset precision. If `other` is an Amount, its asset must match this Amount's asset (an assertion is raised on mismatch) and the comparison uses both amounts quantized to the shared precision. If `other` is numeric or None, it is treated as a numeric value (None → 0) and compared after quantization.
+
+        Returns:
+                bool: True when the quantized values differ, False otherwise.
+        """
         quant_amount = quantize(self["amount"], self["asset"]["precision"])
         if isinstance(other, Amount):
             check_asset(other["asset"], self["asset"], self.blockchain)
-            return self["amount"] != quantize(other["amount"], self["asset"]["precision"])
+            return quantize(self["amount"], self["asset"]["precision"]) != quantize(
+                other["amount"], self["asset"]["precision"]
+            )
         else:
             return quant_amount != quantize((other or 0), self["asset"]["precision"])
 
     def __ge__(self, other):
+        """
+        Return True if this Amount is greater than or equal to `other`.
+
+        Performs comparison after quantizing both values to this Amount's asset precision. If `other` is an Amount, its asset must match this Amount's asset (an AssertionError is raised on mismatch). If `other` is None, it is treated as zero. Returns a boolean.
+        """
         quant_amount = quantize(self["amount"], self["asset"]["precision"])
         if isinstance(other, Amount):
             check_asset(other["asset"], self["asset"], self.blockchain)
-            return self["amount"] >= quantize(other["amount"], self["asset"]["precision"])
+            return quant_amount >= quantize(other["amount"], self["asset"]["precision"])
         else:
             return quant_amount >= quantize((other or 0), self["asset"]["precision"])
 
@@ -467,4 +527,5 @@ class Amount(dict):
 
     __repr__ = __str__
     __truediv__ = __div__
+    __itruediv__ = __idiv__
     __truemul__ = __mul__

nectar/asset.py

@@ -9,8 +9,7 @@ class Asset(BlockchainObject):
     :param str Asset: Symbol name or object id of an asset
     :param bool lazy: Lazy loading
     :param bool full: Also obtain bitasset-data and dynamic asset dat
-    :param Steem steem_instance: Steem
-        instance
+    :param Blockchain blockchain_instance: Blockchain instance
     :returns: All data of an asset
 
     .. note:: This class comes with its own caching function to reduce the

nectar/block.py

@@ -14,7 +14,7 @@ class Block(BlockchainObject):
     """Read a single block from the chain
 
     :param int block: block number
-    :param Steem steem_instance: Steem
+    :param Hive blockchain_instance: Hive
         instance
     :param bool lazy: Use lazy loading
     :param bool only_ops: Includes only operations, when set to True (default: False)
@@ -51,15 +51,16 @@ class Block(BlockchainObject):
         blockchain_instance=None,
         **kwargs,
     ):
-        """Initilize a block
+        """
+        Initialize a Block object representing a single blockchain block.
 
-        :param int block: block number
-        :param Steem steem_instance: Steem
-            instance
-        :param bool lazy: Use lazy loading
-        :param bool only_ops: Includes only operations, when set to True (default: False)
-        :param bool only_virtual_ops: Includes only virtual operations (default: False)
+        block may be an integer (block number), a float (will be converted to int), or a dict containing block data (which will be parsed). Controls:
+        - only_ops: load only operations from the block.
+        - only_virtual_ops: load only virtual operations.
+        - full: if True, populate full block data; if False, keep a minimal representation.
+        - lazy: if True, defer fetching full data until needed.
 
+        If no identifier is present after initialization, the block's identifier is set to its numeric block number.
         """
         self.full = full
         self.lazy = lazy
@@ -317,7 +318,7 @@ class BlockHeader(BlockchainObject):
     """Read a single block header from the chain
 
     :param int block: block number
-    :param Steem steem_instance: Steem
+    :param Hive blockchain_instance: Hive
         instance
     :param bool lazy: Use lazy loading
 
@@ -333,13 +334,19 @@ class BlockHeader(BlockchainObject):
     """
 
     def __init__(self, block, full=True, lazy=False, blockchain_instance=None, **kwargs):
-        """Initilize a block
+        """
+        Initialize a BlockHeader.
 
-        :param int block: block number
-        :param Steem steem_instance: Steem
-            instance
-        :param bool lazy: Use lazy loading
+        One-line summary:
+            Create a BlockHeader wrapper for a block header, optionally in lazy or full mode.
 
+        Parameters:
+            block (int | float | dict): Block number (floats are converted to int) or a header dict.
+            full (bool): If True, populate the object with full header data; otherwise keep a minimal representation.
+            lazy (bool): If True, delay API fetching until data is accessed.
+
+        Notes:
+            If no blockchain_instance is provided, the module's shared blockchain instance is used.
         """
         self.full = full
         self.lazy = lazy
@@ -410,8 +417,8 @@ class Blocks(list):
     :param list name_list: list of accounts to fetch
     :param int count: (optional) maximum number of accounts
         to fetch per call, defaults to 100
-    :param Steem/Hive blockchain_instance: Steem() or Hive() instance to use when
-        accessing a RPCcreator = Account(creator, blockchain_instance=self)
+    :param Hive blockchain_instance: Hive() instance to use when
+        accessing RPC
     """
 
     def __init__(
@@ -421,13 +428,18 @@ class Blocks(list):
         lazy=False,
         full=True,
         blockchain_instance=None,
-        **kwargs,
     ):
-        if blockchain_instance is None:
-            if kwargs.get("steem_instance"):
-                blockchain_instance = kwargs["steem_instance"]
-            elif kwargs.get("hive_instance"):
-                blockchain_instance = kwargs["hive_instance"]
+        """
+        Initialize a Blocks collection by fetching a contiguous range of blocks from the chain and populating the list with Block objects.
+
+        If a blockchain_instance is provided it is used; otherwise the shared blockchain instance is used. If the chosen instance is not connected, the initializer returns early and the Blocks object remains empty.
+
+        Parameters:
+            starting_block_num (int): First block number to retrieve.
+            count (int, optional): Number of consecutive blocks to fetch. Defaults to 1000.
+            lazy (bool, optional): If True, create Block objects in lazy mode (defer full parsing). Defaults to False.
+            full (bool, optional): If True, create Block objects with full data loaded (subject to lazy). Defaults to True.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
 
         if not self.blockchain.is_connected():

nectar/blockchain.py

@@ -9,7 +9,6 @@ from queue import Queue
 from threading import Event, Thread
 from time import sleep
 
-import nectar as stm
 from nectar.instance import shared_blockchain_instance
 from nectarapi.exceptions import UnknownTransaction
 
@@ -181,7 +180,7 @@ class Blockchain(object):
     """This class allows to access the blockchain and read data
     from it
 
-    :param Steem/Hive blockchain_instance: Steem or Hive instance
+    :param Blockchain blockchain_instance: Blockchain instance
     :param str mode: (default) Irreversible block (``irreversible``) or
         actual head block (``head``)
     :param int max_block_wait_repetition: maximum wait repetition for next block
@@ -235,11 +234,18 @@ class Blockchain(object):
         data_refresh_time_seconds=900,
         **kwargs,
     ):
-        if blockchain_instance is None:
-            if kwargs.get("steem_instance"):
-                blockchain_instance = kwargs["steem_instance"]
-            elif kwargs.get("hive_instance"):
-                blockchain_instance = kwargs["hive_instance"]
+        """
+        Initialize the Blockchain helper.
+
+        Sets the underlying blockchain connection (uses shared instance if none provided), configures mode to map to the underlying RPC key ("last_irreversible_block_num" or "head_block_number"), sets max_block_wait_repetition (default 3), and reads the chain's block interval.
+
+        Parameters:
+            mode (str): "irreversible" to operate against the last irreversible block, or "head" to operate against the chain head.
+            max_block_wait_repetition (int, optional): Number of times to retry waiting for a block before giving up; defaults to 3.
+
+        Raises:
+            ValueError: If `mode` is not "irreversible" or "head".
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
 
         if mode == "irreversible":
@@ -434,23 +440,34 @@ class Blockchain(object):
         only_ops=False,
         only_virtual_ops=False,
     ):
-        """Yields blocks starting from ``start``.
-
-        :param int start: Starting block
-        :param int stop: Stop at this block
-        :param int max_batch_size: only for appbase nodes. When not None, batch calls of are used.
-            Cannot be combined with threading
-        :param bool threading: Enables threading. Cannot be combined with batch calls
-        :param int thread_num: Defines the number of threads, when `threading` is set.
-        :param bool only_ops: Only yield operations (default: False).
-            Cannot be combined with ``only_virtual_ops=True``.
-        :param bool only_virtual_ops: Only yield virtual operations (default: False)
-
-        .. note:: If you want instant confirmation, you need to instantiate
-                  class:`nectar.blockchain.Blockchain` with
-                  ``mode="head"``, otherwise, the call will wait until
-                  confirmed in an irreversible block.
-
+        """
+        Yield Block objects from `start` up to `stop` (or the chain head).
+
+        This generator retrieves blocks from the connected blockchain instance and yields them as Block objects. It supports three retrieval modes:
+        - Single-threaded sequential fetching (default).
+        - Threaded parallel fetching across multiple blockchain instances when `threading=True`.
+        - Batched RPC calls for appbase-compatible nodes when `max_batch_size` is set (cannot be combined with `threading`).
+
+        Parameters:
+            start (int, optional): First block number to fetch. If omitted, defaults to the current block.
+            stop (int, optional): Last block number to fetch. If omitted, the generator follows the chain head indefinitely.
+            max_batch_size (int, optional): Use batched RPC calls (appbase only). Cannot be used with `threading`.
+            threading (bool): If True, fetch blocks in parallel using `thread_num` workers.
+            thread_num (int): Number of worker threads to use when `threading=True`.
+            only_ops (bool): If True, blocks will contain only regular operations (no block metadata).
+                Mutually exclusive with `only_virtual_ops=True`.
+            only_virtual_ops (bool): If True, yield only virtual operations.
+
+        Yields:
+            Block: A Block object for each fetched block (may contain only ops or only virtual ops depending on flags).
+
+        Exceptions:
+            OfflineHasNoRPCException: Raised if batched mode is requested while offline (no RPC available).
+            BatchedCallsNotSupported: Raised if the node does not support batched calls when `max_batch_size` is used.
+
+        Notes:
+            - For instant (non-irreversible) confirmations, initialize the Blockchain with mode="head"; otherwise this method will wait for irreversible blocks.
+            - `max_batch_size` requires appbase-compatible RPC; threaded mode creates additional blockchain instances for parallel RPC calls.
         """
         # Let's find out how often blocks are generated!
         current_block = self.get_current_block()
@@ -467,7 +484,7 @@ class Blockchain(object):
             nodelist = self.blockchain.rpc.nodes.export_working_nodes()
             for i in range(thread_num - 1):
                 blockchain_instance.append(
-                    stm.Steem(
+                    self.blockchain.__class__(
                         node=nodelist,
                         num_retries=self.blockchain.rpc.num_retries,
                         num_retries_call=self.blockchain.rpc.num_retries_call,
@@ -794,63 +811,33 @@ class Blockchain(object):
         return ops_stat
 
     def stream(self, opNames=[], raw_ops=False, *args, **kwargs):
-        """Yield specific operations (e.g. comments) only
-
-        :param array opNames: List of operations to filter for
-        :param bool raw_ops: When set to True, it returns the unmodified operations (default: False)
-        :param int start: Start at this block
-        :param int stop: Stop at this block
-        :param int max_batch_size: only for appbase nodes. When not None, batch calls of are used.
-            Cannot be combined with threading
-        :param bool threading: Enables threading. Cannot be combined with batch calls
-        :param int thread_num: Defines the number of threads, when `threading` is set.
-        :param bool only_ops: Only yield operations (default: False)
-            Cannot be combined with ``only_virtual_ops=True``
-        :param bool only_virtual_ops: Only yield virtual operations (default: False)
-
-        The dict output is formated such that ``type`` carries the
-        operation type. Timestamp and block_num are taken from the
-        block the operation was stored in and the other keys depend
-        on the actual operation.
-
-        .. note:: If you want instant confirmation, you need to instantiate
-                  class:`nectar.blockchain.Blockchain` with
-                  ``mode="head"``, otherwise, the call will wait until
-                  confirmed in an irreversible block.
-
-        output when `raw_ops=False` is set:
-
-        .. code-block:: js
-
-            {
-                'type': 'transfer',
-                'from': 'johngreenfield',
-                'to': 'thundercurator',
-                'amount': '0.080 SBD',
-                'memo': 'https://steemit.com/lofi/@johngreenfield/lofi-joji-yeah-right',
-                '_id': '6d4c5f2d4d8ef1918acaee4a8dce34f9da384786',
-                'timestamp': datetime.datetime(2018, 5, 9, 11, 23, 6, tzinfo=<UTC>),
-                'block_num': 22277588, 'trx_num': 35, 'trx_id': 'cf11b2ac8493c71063ec121b2e8517ab1e0e6bea'
-            }
-
-        output when `raw_ops=True` is set:
-
-        .. code-block:: js
-
-            {
-                'block_num': 22277588,
-                'op':
-                    [
-                        'transfer',
-                            {
-                                'from': 'johngreenfield', 'to': 'thundercurator',
-                                'amount': '0.080 SBD',
-                                'memo': 'https://steemit.com/lofi/@johngreenfield/lofi-joji-yeah-right'
-                            }
-                    ],
-                    'timestamp': datetime.datetime(2018, 5, 9, 11, 23, 6, tzinfo=<UTC>)
-            }
-
+        """
+        Yield blockchain operations filtered by type, normalizing several node event formats into a consistent output.
+
+        Parameters:
+            opNames (list): Operation type names to filter for (e.g., ['transfer', 'comment']). If empty, all operations are yielded.
+            raw_ops (bool): If True, yield raw operation tuples with minimal metadata; if False (default), yield a flattened dict with operation fields and metadata.
+            *args, **kwargs: Passed through to self.blocks(...) (e.g., start, stop, max_batch_size, threading, thread_num, only_ops, only_virtual_ops).
+
+        Yields:
+            dict: When raw_ops is False, yields a dictionary with at least:
+                - 'type': operation name
+                - operation fields (e.g., 'from', 'to', 'amount', ...)
+                - '_id': deterministic operation hash
+                - 'timestamp': block timestamp
+                - 'block_num': block number
+                - 'trx_num': transaction index within the block
+                - 'trx_id': transaction id
+
+            dict: When raw_ops is True, yields a compact dictionary:
+                - 'block_num': block number
+                - 'trx_num': transaction index
+                - 'op': [op_type, op_payload]
+                - 'timestamp': block timestamp
+
+        Notes:
+            - The method accepts the same control parameters as blocks(...) via kwargs. The block stream determines timestamps and block-related metadata.
+            - Operation events from different node formats (lists, legacy dicts, appbase-style dicts) are normalized by this method before yielding.
         """
         for block in self.blocks(**kwargs):
             if "transactions" in block:
@@ -1052,23 +1039,20 @@ class Blockchain(object):
             skip_first = True
 
     def get_similar_account_names(self, name, limit=5):
-        """Returns limit similar accounts with name as list
-
-        :param str name: account name to search similars for
-        :param int limit: limits the number of accounts, which will be returned
-        :returns: Similar account names as list
-        :rtype: list
+        """
+        Return a list of accounts with names similar to the given name.
 
-        .. code-block:: python
+        Performs an RPC call to fetch accounts starting at `name`. If the underlying node uses the
+        appbase API this returns the raw `accounts` list from the `list_accounts` response (list of
+        account objects/dicts). If using the legacy API this returns the list of account names
+        returned by `lookup_accounts`. If the local blockchain connection is offline, returns None.
 
-            >>> from nectar.blockchain import Blockchain
-            >>> from nectar import Steem
-            >>> stm = Steem("https://api.steemit.com")
-            >>> blockchain = Blockchain(blockchain_instance=stm)
-            >>> ret = blockchain.get_similar_account_names("test", limit=5)
-            >>> len(ret) == 5
-            True
+        Parameters:
+            name (str): Prefix or starting account name to search for.
+            limit (int): Maximum number of accounts to return.
 
+        Returns:
+            list or None: A list of account names or account objects (depending on RPC), or None if offline.
         """
         if not self.blockchain.is_connected():
             return None
@@ -1083,22 +1067,18 @@ class Blockchain(object):
             return self.blockchain.rpc.lookup_accounts(name, limit)
 
     def find_rc_accounts(self, name):
-        """Returns the RC parameters of one or more accounts.
-
-        :param str name: account name to search rc params for (can also be a list of accounts)
-        :returns: RC params
-        :rtype: list
+        """
+        Return resource credit (RC) parameters for one or more accounts.
 
-        .. code-block:: python
+        If given a single account name (str), returns the RC parameters for that account as a dict.
+        If given a list of account names, returns a list of RC-parameter dicts in the same order.
+        Returns None when the underlying blockchain RPC is not connected or if the RPC returns no data.
 
-            >>> from nectar.blockchain import Blockchain
-            >>> from nectar import Steem
-            >>> stm = Steem("https://api.steemit.com")
-            >>> blockchain = Blockchain(blockchain_instance=stm)
-            >>> ret = blockchain.find_rc_accounts(["test"])
-            >>> len(ret) == 1
-            True
+        Parameters:
+            name (str | list): An account name or a list of account names.
 
+        Returns:
+            dict | list | None: RC parameters for the account(s), or None if offline or no result.
         """
         if not self.blockchain.is_connected():
             return None
@@ -1113,29 +1093,21 @@ class Blockchain(object):
                 return account["rc_accounts"][0]
 
     def list_change_recovery_account_requests(self, start="", limit=1000, order="by_account"):
-        """List pending `change_recovery_account` requests.
-
-        :param str/list start: Start the listing from this entry.
-            Leave empty to start from the beginning. If `order` is set
-            to `by_account`, `start` has to be an account name. If
-            `order` is set to `by_effective_date`, `start` has to be a
-            list of [effective_on, account_to_recover],
-            e.g. `start=['2018-12-18T01:46:24', 'bott']`.
-        :param int limit: maximum number of results to return (default
-            and maximum: 1000).
-        :param str order: valid values are "by_account" (default) or
-            "by_effective_date".
-        :returns: list of `change_recovery_account` requests.
-        :rtype: list
+        """
+        Return pending change_recovery_account requests from the blockchain.
 
-        .. code-block:: python
+        If the local blockchain connection is offline, returns None.
 
-            >>> from nectar.blockchain import Blockchain
-            >>> from nectar import Steem
-            >>> stm = Steem("https://api.steemit.com")
-            >>> blockchain = Blockchain(blockchain_instance=stm)
-            >>> ret = blockchain.list_change_recovery_account_requests(limit=1)
+        Parameters:
+            start (str or list): Starting point for the listing.
+                - For order="by_account": an account name (string).
+                - For order="by_effective_date": a two-item list [effective_on, account_to_recover]
+                  e.g. ['2018-12-18T01:46:24', 'bott'].
+            limit (int): Maximum number of results to return (default and max: 1000).
+            order (str): Index to iterate: "by_account" (default) or "by_effective_date".
 
+        Returns:
+            list or None: A list of change_recovery_account request entries, or None if offline.
         """
         if not self.blockchain.is_connected():
             return None
@@ -1147,23 +1119,19 @@ class Blockchain(object):
             return requests["requests"]
 
     def find_change_recovery_account_requests(self, accounts):
-        """Find pending `change_recovery_account` requests for one or more
-        specific accounts.
+        """
+        Find pending change_recovery_account requests for one or more accounts.
 
-        :param str/list accounts: account name or list of account
-            names to find `change_recovery_account` requests for.
-        :returns: list of `change_recovery_account` requests for the
-            given account(s).
-        :rtype: list
+        Accepts a single account name or a list of account names and queries the connected node for pending
+        change_recovery_account requests. Returns the list of matching request entries, or None if the
+        local blockchain instance is not connected or the RPC returned no data.
 
-        .. code-block:: python
-
-            >>> from nectar.blockchain import Blockchain
-            >>> from nectar import Steem
-            >>> stm = Steem("https://api.steemit.com")
-            >>> blockchain = Blockchain(blockchain_instance=stm)
-            >>> ret = blockchain.find_change_recovery_account_requests('bott')
+        Parameters:
+            accounts (str | list): Account name or list of account names to search for.
 
+        Returns:
+            list | None: List of change_recovery_account request objects for the given account(s), or
+            None if offline or no requests were returned.
         """
         if not self.blockchain.is_connected():
             return None