Python docstring

What is docstring?

• class, module, function, method 정의 시 사용되는 python documentation string

• python 객체의 _doc_ attribute 또는 help() function을 통해 접근할 수 있다.

• 개발된 기능을 사용하거나 개발에 기여하는 다른 개발자들의 이해를 돕기 위해 작성되는 주석

• class, module, function, method의 첫 줄에 위치한다.

• 예시: pandas

Formats of docstring

One line docstring

def square(a):
    '''Returned argument a is squared.'''
    return a**a

---

Multi line docstring

class Vehicle(object):
    '''
    The Vehicle object contains lots of vehicles
    :param arg: The arg is used for ...
    :type arg: str
    :param `*args`: The variable arguments are used for ...
    :param `**kwargs`: The variable arguments are used for ...
    :ivar arg: This is where we store arg
    :vartype arg: str
    '''

    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''
        We can't travel a certain distance in vehicles without fuels, so here's the fuels

        :param distance: The amount of distance traveled
        :type amount: int
        :param bool destinationReached: Should the fuels be refilled to cover required distance?
        :raises: :class:`RuntimeError`: Out of fuel

        :returns: A Car mileage
        :rtype: Cars
        '''
        pass

• roles

  • param: 필수적으로 명시해야 한다.

  • type: sphinx data type for param

  • return: returned object

  • rtype: type of object retured

---

Google style

class Vehicles(object):
    '''
    The Vehicle object contains a lot of vehicles

    Args:
        arg (str): The arg is used for...
        *args: The variable arguments are used for...
        **kwargs: The keyword arguments are used for...

    Attributes:
        arg (str): This is where we store arg,
    '''

    def __init__(self, arg, *args, **kwargs):
        self.arg = arg


def cars(self, distance, destination):
    '''We can't travel distance in vehicles without fuels, so here is the fuels

    Args:
        distance (int): The amount of distance traveled
        destination (bool): Should the fuels refilled to cover the distance?

    Raises:
        RuntimeError: Out of fuel

    Returns:
        cars: A car mileage
    '''
    pass

---

Numpy Style

class Vehicles(object):
    '''
    The Vehicles object contains lots of vehicles

    Parameters
    ----------
    arg : str
        The arg is used for ...
    *args
        The variable arguments are used for ...
    **kwargs
        The keyword arguments are used for ...

    Attributes
    ----------
    arg : str
        This is where we store arg,
    '''

    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Parameters
        ----------
        distance : int
            The amount of distance traveled
        destination : bool
            Should the fuels refilled to cover the distance?

        Raises
        ------
        RuntimeError
            Out of fuel

        Returns
        -------
        cars
            A car mileage
        '''
        pass