Can you provide advanced examples of Python docstrings?

Can you provide advanced examples of Python docstrings?

Sure! Here’s an advanced example of a docstring for a function that calculates the factorial of a number:

def factorial(n: int) -> int:
    """
    Calculate the factorial of a non-negative integer.

    Parameters:
    n (int): A non-negative integer whose factorial is to be calculated.

    Returns:
    int: The factorial of the given number.

    Raises:
    ValueError: If n is negative.

    Examples:
    >>> factorial(5)
    120
    >>> factorial(0)
    1
    """
    if n < 0:
        raise ValueError("Input must be a non-negative integer.")
    result = 1
    for i in range(1, n + 1):
        result *= i
    return result

What are the key components of a good docstring?

A good docstring should include:

1. A brief description of the function's purpose.
2. Parameters section detailing input arguments.
3. Returns section explaining the output.
4. Raises section for exceptions that may be raised.
5. Examples of usage to illustrate how to use the function.

Can you show me another example?

Absolutely! Here’s an example for a class:

class Circle:
    """
    A class to represent a circle.

    Attributes:
    radius (float): The radius of the circle.

    Methods:
    area() -> float: Returns the area of the circle.
    circumference() -> float: Returns the circumference of the circle.
    """

    def __init__(self, radius: float):
        self.radius = radius

    def area(self) -> float:
        """Calculate the area of the circle."""
        return 3.14159 * (self.radius ** 2)

    def circumference(self) -> float:
        """Calculate the circumference of the circle."""
        return 2 * 3.14159 * self.radius