Skip to content

edit docstrings#2951

Merged
MichaelTrestman merged 23 commits intostagingfrom
update-docstrings-asyncsubtensor
Jul 9, 2025
Merged

edit docstrings#2951
MichaelTrestman merged 23 commits intostagingfrom
update-docstrings-asyncsubtensor

Conversation

@MichaelTrestman
Copy link
Contributor

@MichaelTrestman MichaelTrestman commented Jul 8, 2025

This PR makes systematic improvements to docstrings in async_subtensor, as the first step in an overall effort to improve these across the codebase.

@MichaelTrestman MichaelTrestman marked this pull request as ready for review July 8, 2025 16:47
@MichaelTrestman MichaelTrestman requested review from a team and basfroman July 8, 2025 18:37
@MichaelTrestman MichaelTrestman requested a review from a team July 8, 2025 23:58
@MichaelTrestman MichaelTrestman requested a review from basfroman July 9, 2025 02:21
Copy link
Collaborator

@basfroman basfroman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I predict you'll hate us soon, but I have to add this to the review that we use Google Docstrings Style as I mentioned in our previous conversations.

Example:

def add_stake(
    self,
    wallet: "Wallet",
    hotkey_ss58: Optional[str] = None,
    netuid: Optional[int] = None,
    amount: Optional[Balance] = None,
    wait_for_inclusion: bool = True,
    wait_for_finalization: bool = False,
    safe_staking: bool = False,
    allow_partial_stake: bool = False,
    rate_tolerance: float = 0.005,
    period: Optional[int] = None,
) -> bool:
    """
    Adds a stake from the specified wallet to the neuron identified by the SS58 address of its hotkey in specified
    subnet. Staking is a fundamental process in the Bittensor network that enables neurons to participate actively
    and earn incentives.

    Args:
        wallet: The wallet to be used for staking.
        hotkey_ss58: The SS58 address of the hotkey associated with the neuron to which you intend to delegate your
            stake. If not specified, the wallet's hotkey will be used. Defaults to ``None``.
        netuid: The unique identifier of the subnet to which the neuron belongs.
        amount: The amount of TAO to stake.
        wait_for_inclusion: Waits for the transaction to be included in a block. Defaults to ``True``.
        wait_for_finalization: Waits for the transaction to be finalized on the blockchain. Defaults to ``False``.
        safe_staking: If true, enables price safety checks to protect against fluctuating prices. The stake will
            only execute if the price change doesn't exceed the rate tolerance. Default is ``False``.
        allow_partial_stake: If true and safe_staking is enabled, allows partial staking when the full amount would
            exceed the price tolerance. If false, the entire stake fails if it would exceed the tolerance.
            Default is ``False``.
        rate_tolerance: The maximum allowed price change ratio when staking. For example,
            0.005 = 0.5% maximum price increase. Only used when safe_staking is True. Default is ``0.005``.
        period: The number of blocks during which the transaction will remain valid after it's submitted. If the
            transaction is not included in a block within that number of blocks, it will expire and be rejected. You
            can think of it as an expiration date for the transaction. Defaults to ``None``.

    Returns:
        bool: True if the staking is successful, False otherwise.

    This function enables neurons to increase their stake in the network, enhancing their influence and potential
    rewards in line with Bittensor's consensus and reward mechanisms.
    When safe_staking is enabled, it provides protection against price fluctuations during the time stake is
    executed and the time it is actually processed by the chain.
    """

As we can see from the allow_partial_stake: and period: arguments, the first line has a continuation of the description, but the following lines are indented by 4 spaces. To avoid double work, I suggest applying this rule everywhere.

@MichaelTrestman MichaelTrestman requested a review from basfroman July 9, 2025 13:56
@MichaelTrestman MichaelTrestman requested a review from basfroman July 9, 2025 13:56
Copy link
Collaborator

@basfroman basfroman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very good job! LGTM

@MichaelTrestman MichaelTrestman merged commit 8ac6605 into staging Jul 9, 2025
135 checks passed
@ibraheem-abe ibraheem-abe mentioned this pull request Jul 10, 2025
@basfroman basfroman deleted the update-docstrings-asyncsubtensor branch September 17, 2025 12:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants