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
"""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
""" 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 line
2. 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.
class ClassName: """Class Docstring goes here.""" // class attribures def class_method(): """Class method docstring goes here.""" // class method declaration
The 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:
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)
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.
"""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())
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 –