Updated March 24, 2023
Introduction to Python Docstring
Python Doctstring is the documentation string that occurs at class, method, module or function level. A docstring is simply a multi-line string that is not assigned to anything. It is specified in the source code that is used to document a specific segment of code. It is generally the first statement in the respective areas, and the code follows after it. The docstring for any particular python object can be accessed by using a doc attribute for that object.
Types of Python Docstring
Various types of Docstrings are given below:
1. Based on the Number of Lines
The following are the different types of Docstrings based on a number of lines:
a. Single-Lined Docstring
Syntax:
"""This is an example of single line docstring."""Single line docstrings should be enclosed within triple quotes.
b. Multi-Lined Docstring
When we have to write a detailed explanation of the code, then we use a multi-lined docstring.
The following are its components:
- Single Line Summary Line
- Blank Line Before the Summary
- Summary for Code Explanation
- Blank Line After the Summary
Syntax:
""" This is the first line of single line docstring.
It is the summary of the docstring. Here we elaborately discuss about the docstring. It is generally multiline comment."""
# Code commences from this line2. Based on Functionality
The following are the different types of Docstrings based on functionality:
a. Class Docstrings
Class Docstrings are the documentation for the class and its relevant methods. The purpose of the class docstring is to provide a clear understanding of the class and its methods to users who are using the class. These docstrings are placed below the class and method declaration, respectively, with one unit of indentation.
Syntax:
class ClassName:
"""Class Docstring goes here."""
// class attribures
def class_method():
"""Class method docstring goes here."""
// class method declarationThe following information should be present in a class docstring:
- An overview of the class in general.
- Description of all the methods in detail.
- Description of the class attributes.
- Description of both mandatory and optional arguments.
- Any exceptions and restrictions that are imposed on the class.
Let us look at an example of Class docstring:
Code:
class Vehicle:
"""The following class is about a vehicle
Attributes
-------------
name : str
the name of the vehicle
manufacturer : str
the name of the manufacturer of the vehicle
price : float64
the showroom price of the vehicle
manufacturing_year : int64
the year of manufacturing of the vehicle
Methods
---------------
"""
def __init__(self,name,manufacturer,price,manufacturing_year):
self.name = name,
self.manufacturer = manufacturer,
self.price = price,
self.manufacturing_year = manufacturing_year
"""
Parameters
------------
name : str
the name of the vehicle
manufacturer : str
the name of the manufacturer of the vehicle
price : float64
the showroom price of the vehicle
manufacturing_year : int64
the year of manufacturing of the vehicle
"""
vehicle = Vehicle("SX4","Suzuki",450000,2010)
print("Name of the vehicle :",vehicle.name)
print("Manufacturer Name :",vehicle.manufacturer)
print("Price of vehicle :",vehicle.price)
print("Manufacturing year :",vehicle.manufacturing_year)Output:
b. Package Docstrings
The package docstrings are used to highlight the sub-packages and modules that are used in the package. These are placed at the very top before any imports are done.
The following information should be present in the package docstring:
- Description of the package with its purpose.
- List of classes, exceptions, and objects that are exported by the package.
- Description About arguments that are passed.
- Any exception or restriction imposed on the function methods.
The docstring of any python module can be considered as an example of package docstring. You can refer to the documentation of the panda’s package for this.
c. Script Docstrings
Scripts are single-file executables that can be executed from the console. Script docstrings are used for users to understand the functionality and usage of the script fully. Any custom imports that are used in the scripts need to be mentioned as a part of the script docstring.
Let us see an example of Python Script Docstring where we define a function to show the information about the columns present in CSV files provided we are giving the CSV file path.
Code:
"""CSV file info
The following script allows the user to print to the console all the information of the columns in the
spreadsheet.
This script accepts comma separated value files (.csv)
Pre-requisite :
pandas package to be installed within the Python runtime environment
"""
import pandas as pd
def get_csv_info(file_location):
"""Gets and prints the information about the columns of the csv file
Parameters
----------
file_location : str
The file location of the csv file
Returns
-------
list
The information about all the columns of the csv file
"""
file_data = pd.read_excel(file_location)
return(file_data.info())Output:
Recommended Articles
This is a guide to Python Docstring. Here we discuss the basics of Docstrings in Python along with syntax and examples of different Docstrings. You may also look at the following articles to learn more –
