Python Docstring (Document String) is a string literal that is the first statement in a module, function, class, or method. <\/p>\n\n\n\n
\n\n\n\n
How to Write a Python Docstring?<\/h2>\n\n\n\n
Python docstring is surrounded by a pair of triple double-quotes (“””). Let’s look at some examples of writing docstrings in Python.<\/p>\n\n\n\n
\n\n\n\n
1. Python Function Docstring Example<\/h3>\n\n\n
\ndef multiply(a, b):\n """This method multiplies the given two numbers.\n\n Input Arguments: a, b must be numbers.\n Returns: Multiplication of a and b.\n """\n return a * b\n<\/pre><\/div>\n\n\n\n\n\n\n
2. Python Class Docstring Example<\/h3>\n\n\n
\nclass Employee:\n """Employee class is used to hold employee object data.\n\n Methods:\n __init__(self, emp_id, emp_name)\n print()\n """\n\n def __init__(self, emp_id, emp_name):\n """Employee Class Constructor to initialize the object.\n\n Input Arguments: emp_id must be int, emp_name must be str\n """\n self.id = emp_id\n self.name = emp_name\n\n def print(self):\n """This method prints the employee information in a user friendly way."""\n print(f'Employee[{self.id}, {self.name}]')\n<\/pre><\/div>\n\n\n\n\n\n\n
3. Python Module Docstring Example<\/h3>\n\n\n\n
Let’s say we have defined the above function and class in docstrings.py<\/code> file. Every Python script is also a module. We can define this module docstring as:<\/p>\n\n\n
\n"""\nThis module shows some examples of Python Docstrings\n\nClasses: Employee\nFunctions: multiply(a, b)\n"""\n<\/pre><\/div>\n\n\n\n\n\n\n
How to Access Python Docstrings?<\/h2>\n\n\n\n
We can access the docstring value from a special attribute __doc__. Let’s see how to access docstring values defined above.<\/p>\n\n\n\n
\n\n\n\n
1. Accessing Python Function Docstring<\/h3>\n\n\n
We will have to import the docstrings module. Then we can access its Docstring value using the __doc__ attribute. We have commented above print statements before importing the docstrings module to avoid executing the print() statements. <\/p>\n\n\n
\n$ python ls\ndocstrings.py\n$ python \n$ python python3.7\nPython 3.7.3 (v3.7.3:ef4ec6ed12, Mar 25 2019, 16:52:21) \n[Clang 6.0 (clang-600.0.57)] on darwin\nType "help", "copyright", "credits" or "license" for more information.\n>>> \n>>> import docstrings\n>>> \n>>> docstrings.__doc__\n'\\nThis module shows some examples of Python Docstrings\\n\\nClasses: Employee\\nFunctions: multiply(a, b)\\n'\n>>> \n>>> docstrings.Employee.__doc__\n'Employee class is used to hold employee object data.\\n\\n Methods:\\n __init__(self, emp_id, emp_name)\\n print()\\n '\n>>> \n>>> \n>>> docstrings.multiply.__doc__\n'This method multiplies the given two numbers.\\n\\n Input Arguments: a, b must be numbers.\\n Returns: Multiplication of a and b.\\n '\n>>> \n>>> \n>>> docstrings.Employee.print.__doc__\n'This method prints the employee information in a user friendly way.'\n>>> \n<\/pre><\/div>\n\n\nPython Module Docstring<\/figcaption><\/figure>\n\n\n\n\n\n\n\n
Python One-liner Docstring<\/h2>\n\n\n\n
When the python docstring is defined in a single line, it’s called a one-line docstring. <\/li>
The opening quotes and closing quotes are on the same line.<\/li>
There is no blank line before or after the docstring value.<\/li>
The best practice is to end the docstring with a period.<\/li>
It’s best suited for small utility functions where we don’t need to specify many things.<\/li>
Provide meaningful docstring to specify the function details and the output. For example:<\/li><\/ul>\n\n\n
\ndef reverse_str(s):\n """Reverses the input string and returns it."""\n pass\n<\/pre><\/div>\n\n\n\n\n\n\n
Python Multi-line Docstring<\/h2>\n\n\n\n
When the Docstring value spans into multiple lines, it’s called multi-line docstring.<\/li>
The best practice for multi-line docstring is to start with a summary line, then a blank line followed by a more detailed explanation.<\/li>
The summary line can be on the same line as the opening quotes or the next line.<\/li>
The entire multi-line docstring is indented the same as the quotes in its first line.<\/li><\/ul>\n\n\n\n\n\n\n\n
Python Docstring Best Practices<\/h2>\n\n\n\n
The docstring of a Python script should specify how to use it. It should be printed when the script is executed with missing or wrong parameters.<\/li>
Python module docstring should list all the classes, functions, exceptions, and dependencies on other modules. <\/li>
Python function docstring should specify the behavior, input arguments, return types, and exceptions. If there are specific restrictions when the function can be called, it should be specified in the function docstring.<\/li>
The docstring of a class should list all the methods and attributes. If it’s inheriting from a superclass, the details should be provided.<\/li>
If a class method is overriding the superclass method, it should be specified.<\/li>
Python is case-sensitive. So keep the function argument names exactly the same as in the function definition.<\/li><\/ol>\n\n\n\n\n\n\n\n
Python Docstring Format<\/h2>\n\n\n\n
There are no rules associated with the format of the docstring. But, following a specific style will make your code look good. There are two popular docstring formats.<\/p>\n\n\n\n
1. Epytext format<\/h3>\n\n\n\n
This is very similar to javadoc style comments. It contains method description, params, return, and details about exceptions raised.<\/p>\n\n\n
\ndef multiply(a, b):\n """This method multiplies the given two numbers.\n\n @param a: this is the first param\n @param b: this is the second param\n @return: returns after multiplying a with b\n @raise TypeError: raised when any of the params is not a number\n """\n\n return a * b\n<\/pre><\/div>\n\n\n
![\"Python](\"https:\/\/www.askpython.com\/wp-content\/uploads\/2019\/05\/python-docstring-example-function.png\")
![\"Python](\"https:\/\/www.askpython.com\/wp-content\/uploads\/2019\/05\/python-class-method-docstring-example-1008x1024.png\")
![\"Python](\"https:\/\/www.askpython.com\/wp-content\/uploads\/2019\/05\/python-module-docstring-example-1024x383.png\")