Docstrings Python Function when parameters are package objects like Pandas DataFrame

Question

i want to know how documentation a python function when one of parameters is a object of package for example a pandas DataFrame.

i use this method but PyCharm(python IDE) doesn't understand it.

def foo(df , no , l_int):
'''
Parameters
-------------
df:Pandas DataFrame
no:int 
l_int:list of int

Returns
-------------
'''

in PyCharm it show this:

def foo(df: Any,
        no: int,
        l_int: list[int]) -> None

Is it a Standard way to solve this issue. thank you.

Answer 1

Let me tell you a general rule of thumb. If your parameters are encapsulated data as you have in the case of DataFrame then give an example by showing the internal structure of the datatype of the parameter or return datatype e.g.

"""
Parameters
-------------
df:Pandas DataFrame : (here some explanation)
no:int 
l_int:list of int

Examples:

df: 
{
 Give a detailed example by showing the internal data of the datatype so that anyone reading the docstring knows exactly what is encapsulated by this datatype
}

-------------
"""

Code layout

• Always use four spaces to indent code. Do not use tabs, tabs introduce confusion and are best left out.
• Wrap your code so that lines don’t exceed 79 characters. This helps users with small displays and makes it possible to have several code files open side by side on larger displays.
• When vertical aligning text, there should be no arguments on the first line

Whitespace

• Use 2 blank lines around top-level functions and classes.
• Use 1 blank line to separate large blocks of code inside functions.
• 1 blank line before class method definitions.
• Avoid extraneous whitespace.
• Use blank lines sparingly.
• Always surround binary operators with a space on either side but group them sensibly.
• Don’t use spaces in keyword arguments or default parameter values.
• Don’t use whitespace to line up operators.
• Multiple statements on the same line are discouraged.
• Avoid trailing whitespace anywhere

Comments

• Comments should be complete sentences in most cases.
• Keep comments up to date
• Write in “Strunk & White “English
• Inline comments should be separated by at least two spaces from
• the statement and must start with ‘#’ and a single space.
• Block comments should be indented to the same level as the code
• that follows them.
• Each line in block comments starts with ‘#’.
• Write docstrings for all public modules, functions, classes and
• methods.
• Docstrings start and end with """ e.g """ A Docstring. """.
• Single line docstrings can all be on the same line.
• Docstrings should describe the method or function’s effect as a
• command.
• Docstrings should end in a period.
• When documenting a class, insert a blank line after the docstring.
• The last """ should be on a line by itself

For further detail on this topic. Please read PEP 257 or it summary by here

Answer 2

This is the standard way since Python 3.5 though it has evolved quite a bit since it was introduced.

One thing I would do is change the type of df to pandas.DataFrame to make it more expressive.

Also, it looks like PyCharm understood your method just fine. The reformatting was simply to add the type declarations.

Answer 3

Any is not a descriptive type annotation. You want a Pandas dataframe specifically, or pd.DataFrame, but PyCharm doesn't seem to be able to infer that.

The function header should read:

import pandas as pd
def foo(df: pd.DataFrame,
        no: int,
        l_int: list[int]) -> None