Merge pull request #1890 from rajkaramchedu/rajk/docs-list-delegate-lite

Docstrings updates for list delegate lite feature

bittensor/chain_data.py

@@ -693,24 +693,49 @@ def fix_decoded_values(cls, prometheus_info_decoded: Dict) -> "PrometheusInfo":
 
 @dataclass
 class DelegateInfoLite:
-    """Dataclass for DelegateLiteInfo."""
+    """
+    Dataclass for DelegateLiteInfo. This is a lighter version of :func:`DelegateInfo`.
+
+    Args:
+        delegate_ss58 (str): Hotkey of the delegate for which the information is being fetched.
+        take (float): Take of the delegate as a percentage.
+        nominators (int): Count of the nominators of the delegate.
+        owner_ss58 (str): Coldkey of the owner.
+        registrations (list[int]): List of subnets that the delegate is registered on.
+        validator_permits (list[int]): List of subnets that the delegate is allowed to validate on.
+        return_per_1000 (int): Return per 1000 TAO, for the delegate over a day.
+        total_daily_return (int): Total daily return of the delegate.
+
+    """
 
     delegate_ss58: str  # Hotkey of delegate
     take: float  # Take of the delegate as a percentage
-    nominators: int  # List of nominators of the delegate and their stake
+    nominators: int  # Count of the nominators of the delegate.
     owner_ss58: str  # Coldkey of owner
     registrations: list[int]  # List of subnets that the delegate is registered on
     validator_permits: list[
         int
     ]  # List of subnets that the delegate is allowed to validate on
-    return_per_1000: int  # Return per 1000 tao of the delegate over a day
+    return_per_1000: int  # Return per 1000 tao for the delegate over a day
     total_daily_return: int  # Total daily return of the delegate
 
 
 @dataclass
 class DelegateInfo:
     r"""
-    Dataclass for delegate info.
+    Dataclass for delegate information. For a lighter version of this class, see :func:`DelegateInfoLite`.
+
+    Args:
+        hotkey_ss58 (str): Hotkey of the delegate for which the information is being fetched.
+        total_stake (int): Total stake of the delegate.
+        nominators (list[Tuple[str, int]]): List of nominators of the delegate and their stake.
+        take (float): Take of the delegate as a percentage.
+        owner_ss58 (str): Coldkey of the owner.
+        registrations (list[int]): List of subnets that the delegate is registered on.
+        validator_permits (list[int]): List of subnets that the delegate is allowed to validate on.
+        return_per_1000 (int): Return per 1000 TAO, for the delegate over a day.
+        total_daily_return (int): Total daily return of the delegate.
+
     """
 
     hotkey_ss58: str  # Hotkey of delegate

bittensor/commands/delegates.py

@@ -49,7 +49,40 @@ def _get_coldkey_wallets_for_path(path: str) -> List["bittensor.wallet"]:
 def show_delegates_lite(
     delegates_lite: List["bittensor.DelegateInfoLite"], width: Optional[int] = None
 ):
-    """Outputs a list of lite version delegates to the console."""
+    """
+    This method is a lite version of the :func:`show_delegates`. This method displays a formatted table of Bittensor network delegates with detailed statistics to the console.
+
+    The table is sorted by total stake in descending order and provides
+    a snapshot of delegate performance and status, helping users make informed decisions for staking or nominating.
+
+    This helper function is not intended to be used directly in user code unless specifically required.
+
+    Args:
+        delegates_lite (List[bittensor.DelegateInfoLite]): A list of delegate information objects to be displayed.
+        width (Optional[int]): The width of the console output table. Defaults to ``None``, which will make the table expand to the maximum width of the console.
+
+    The output table contains the following columns. To display more columns, use the :func:`show_delegates` function.
+
+    - INDEX: The numerical index of the delegate.
+    - DELEGATE: The name of the delegate.
+    - SS58: The truncated SS58 address of the delegate.
+    - NOMINATORS: The number of nominators supporting the delegate.
+    - VPERMIT: Validator permits held by the delegate for the subnets.
+    - TAKE: The percentage of the delegate's earnings taken by the network.
+    - DELEGATE/(24h): The earnings of the delegate in the last 24 hours.
+    - Desc: A brief description provided by the delegate.
+
+    Usage:
+        This function is typically used within the Bittensor CLI to show current delegate options to users who are considering where to stake their tokens.
+
+    Example usage::
+
+        show_delegates_lite(delegates_lite, width=80)
+
+    Note:
+        This function is primarily for display purposes within a command-line interface and does not return any values. It relies on the `rich <https://github.com/Textualize/rich>`_ Python library to render
+        the table in the console.
+    """
 
     registered_delegate_info: Optional[
         Dict[str, DelegatesDetails]
@@ -135,13 +168,11 @@ def show_delegates(
     to be used directly in user code unless specifically required.
 
     Args:
-        - delegates (List[bittensor.DelegateInfo]): A list of delegate information objects to be displayed.
-        - prev_delegates (Optional[List[bittensor.DelegateInfo]]): A list of delegate information objects from a
-            previous state, used to calculate changes in stake. Defaults to ``None``.
-        - width (Optional[int]): The width of the console output table. Defaults to ``None``, which will make the table
-            expand to the maximum width of the console.
+        delegates (List[bittensor.DelegateInfo]): A list of delegate information objects to be displayed.
+        prev_delegates (Optional[List[bittensor.DelegateInfo]]): A list of delegate information objects from a previous state, used to calculate changes in stake. Defaults to ``None``.
+        width (Optional[int]): The width of the console output table. Defaults to ``None``, which will make the table expand to the maximum width of the console.
 
-    The output table includes the following columns:
+    The output table contains the following columns:
 
     - INDEX: The numerical index of the delegate.
     - DELEGATE: The name of the delegate.
@@ -150,15 +181,14 @@ def show_delegates(
     - DELEGATE STAKE(τ): The stake that is directly delegated to the delegate.
     - TOTAL STAKE(τ): The total stake held by the delegate, including nominators' stake.
     - CHANGE/(4h): The percentage change in the delegate's stake over the past 4 hours.
-    - SUBNETS: A list of subnets the delegate is registered with.
     - VPERMIT: Validator permits held by the delegate for the subnets.
+    - TAKE: The percentage of the delegate's earnings taken by the network.
     - NOMINATOR/(24h)/kτ: The earnings per 1000 τ staked by nominators in the last 24 hours.
     - DELEGATE/(24h): The earnings of the delegate in the last 24 hours.
     - Desc: A brief description provided by the delegate.
 
     Usage:
-        This function is typically used within the Bittensor CLI to show current delegate
-        options to users who are considering where to stake their tokens.
+        This function is typically used within the Bittensor CLI to show current delegate options to users who are considering where to stake their tokens.
 
     Example usage::
 
@@ -577,10 +607,9 @@ def check_config(config: "bittensor.config"):
 
 class ListDelegatesLiteCommand:
     """
-    Displays a formatted table of Bittensor network delegates, providing a comprehensive overview of delegate statistics
-    and information.
+    Displays a formatted table of Bittensor network delegates, providing a lite overview of delegate statistics and information. For a more detailed view, use the :func:`ListDelegatesCommand` class.
 
-    This table helps users make informed decisions on which delegates to allocate their Tao stake.
+    This table helps users make informed decisions on which delegates to allocate their TAO stake.
 
     Optional Arguments:
         - ``wallet.name``: The name of the wallet to use for the command.
@@ -592,28 +621,21 @@ class ListDelegatesLiteCommand:
     - DELEGATE: The name of the delegate.
     - SS58: The delegate's unique SS58 address (truncated for display).
     - NOMINATORS: The count of nominators backing the delegate.
-    - DELEGATE STAKE(τ): The amount of delegate's own stake (not the TAO delegated from any nominators).
-    - TOTAL STAKE(τ): The delegate's cumulative stake, including self-staked and nominators' stakes.
-    - CHANGE/(4h): The percentage change in the delegate's stake over the last four hours.
-    - SUBNETS: The subnets to which the delegate is registered.
     - VPERMIT: Indicates the subnets for which the delegate has validator permits.
-    - NOMINATOR/(24h)/kτ: The earnings per 1000 τ staked by nominators in the last 24 hours.
+    - TAKE: The percentage of the delegate's earnings taken by the network.
     - DELEGATE/(24h): The total earnings of the delegate in the last 24 hours.
     - DESCRIPTION: A brief description of the delegate's purpose and operations.
 
-    Sorting is done based on the ``TOTAL STAKE`` column in descending order. Changes in stake are highlighted:
-    increases in green and decreases in red. Entries with no previous data are marked with ``NA``. Each delegate's name
-    is a hyperlink to their respective URL, if available.
+    Sorting is done based on the ``TOTAL STAKE`` column in descending order. Changes in stake are highlighted as follows: Increases are indicated in green and decreases are indicated in red. Entries with no previous data are marked with ``NA``. Each delegate's name is a hyperlink to their respective URL, if available.
 
     Example usage::
 
-        btcli root list_delegates
-        btcli root list_delegates --wallet.name my_wallet
-        btcli root list_delegates --subtensor.network finney # can also be `test` or `local`
+        btcli root list_delegates_lite
+        btcli root list_delegates_lite --wallet.name my_wallet
+        btcli root list_delegates_lite --subtensor.network finney # can also be `test` or `local`
 
     Note:
-        This function is part of the Bittensor CLI tools and is intended for use within a console application. It prints
-        directly to the console and does not return any value.
+        This function is part of the Bittensor CLI tools and is intended for use within a console application. It prints directly to the console and does not return any value.
     """
 
     @staticmethod
@@ -660,10 +682,9 @@ def check_config(config: "bittensor.config"):
 
 class ListDelegatesCommand:
     """
-    Displays a formatted table of Bittensor network delegates, providing a comprehensive overview of delegate statistics
-    and information.
+    Displays a formatted table of Bittensor network delegates, providing a comprehensive overview of delegate statistics and information. Use the :func:`ListDelegatesLiteCommand` class for a lighter version of this class.
 
-    This table helps users make informed decisions on which delegates to allocate their Tao stake.
+    This table helps users make informed decisions on which delegates to allocate their TAO stake.
 
     Optional Arguments:
         - ``wallet.name``: The name of the wallet to use for the command.

bittensor/subtensor.py

@@ -3532,17 +3532,18 @@ def make_substrate_call_with_retry(encoded_hotkey: List[int]):
 
     def get_delegates_lite(self, block: Optional[int] = None) -> List[DelegateInfoLite]:
         """
-        Retrieves a list of all delegate neurons within the Bittensor network. This function provides an
-        overview of the neurons that are actively involved in the network's delegation system. Lite version.
+        Retrieves a lighter list of all delegate neurons within the Bittensor network. This function provides an overview of the neurons that are actively involved in the network's delegation system.
+
+        Analyzing the delegate population offers insights into the network's governance dynamics and the distribution of trust and responsibility among participating neurons.
+
+        This is a lighter version of :func:`get_delegates`.
 
         Args:
             block (Optional[int], optional): The blockchain block number for the query.
 
         Returns:
-            List[DelegateInfoLite]: A list of DelegateInfoLite objects detailing each delegate's characteristics.
+            List[DelegateInfoLite]: A list of ``DelegateInfoLite`` objects detailing each delegate's characteristics.
 
-        Analyzing the delegate population offers insights into the network's governance dynamics and the
-        distribution of trust and responsibility among participating neurons.
         """
 
         @retry(delay=1, tries=3, backoff=2, max_delay=4, logger=logger)
@@ -3566,17 +3567,18 @@ def make_substrate_call_with_retry():
 
     def get_delegates(self, block: Optional[int] = None) -> List[DelegateInfo]:
         """
-        Retrieves a list of all delegate neurons within the Bittensor network. This function provides an
-        overview of the neurons that are actively involved in the network's delegation system.
+        Retrieves a list of all delegate neurons within the Bittensor network. This function provides an overview of the neurons that are actively involved in the network's delegation system.
+
+        Analyzing the delegate population offers insights into the network's governance dynamics and the distribution of trust and responsibility among participating neurons.
+
+        For a lighter version of this function, see :func:`get_delegates_lite`.
 
         Args:
             block (Optional[int], optional): The blockchain block number for the query.
 
         Returns:
             List[DelegateInfo]: A list of DelegateInfo objects detailing each delegate's characteristics.
 
-        Analyzing the delegate population offers insights into the network's governance dynamics and the
-        distribution of trust and responsibility among participating neurons.
         """
 
         @retry(delay=1, tries=3, backoff=2, max_delay=4, logger=logger)