How to read Python function documentation

Question

I have a problem understanding some description of functions in Python. I understand simply functions like os.putenv(varname, value) but I have no idea how to use this: os.getenv(varname[, value]). How to pass arguments to that function, what does those square brackets mean?

Answer 1

Square brackets typically mean that the value is optional. Here, varname refers to the environment variable you want to get and value is an optional value that is return if the environment variable doesn't exist.

Answer 2

The square brackets indicate the argument is optional. Read the description:

Return the value of the environment variable varname if it exists, or value if it doesn’t. value defaults to None.

So you can call it like this:

os.getenv('NONEXISTANTVAR')

or like this:

os.getenv('NONEXISTANTVAR', u'my default')

This first is equivalent to os.getenv('NONEXISTANTVAR', None). In the specific case of getenv, the second argument is returned if the environment variable doesn't exist.

Typically, the documentation will tell you the default value if you don't provide one, either explicitly in the description or by placing an =somevalue directly in the signature. If it doesn't indicate a specific value, then it will at least describe the difference in behavior.

unicode gives us an example of the = in the signature:

unicode(object='')

Note that in Python, the only way for an argument to be optional is for it to have a default value.