Skip to content

Commit

Permalink
Add example of using docstring info
Browse files Browse the repository at this point in the history
  • Loading branch information
@davewhipp
davewhipp committed Sep 24, 2024
1 parent 6b9ed65 commit 12ab6b0
Show file tree
Hide file tree
Showing 2 changed files with 127 additions and 13 deletions.
16 changes: 15 additions & 1 deletion source/part1/chapter-02/md/05-functions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -394,6 +394,7 @@ More information about namespaces and variables scopes can be found, for example
## Documenting functions with docstrings

A documentation string, or *{term}`docstring`*, is a block of text that describes what a specific function, library, or script does and how to use it. Although the format of docstrings can vary, there are certain elements of a docstring that are needed for it to function properly. Let's look at an example using one of our functions created earlier in this section.
<!-- #endregion -->

```python
def kelvins_to_celsius(temp_kelvins):
Expand Down Expand Up @@ -429,8 +430,21 @@ def kelvins_to_celsius(temp_kelvins):

Here you can now see more information about the expected values for the parameters and what will be returned when using the function. This level of documentation is not needed for every function, but clearly it can be useful, especially when you have multiple parameters. Note here that the suggested format with multiple lines in a docstring is to have the quotation marks on their own separate lines.

Perhaps the most valuable thing about adding the docstring is that it provides a way to easily see what a function does and how it works. We can do this using the `help()` function,

```python
help(kelvins_to_celsius)
```

or by typing the name of the function followed by `?`.

```python
kelvins_to_celsius?
```

As you can see, we now have easy access to information about the function that has been included in the docstring. This means you can remind yourself about how functions you have written work, or look up information about functions from libraries, as discussed later in this chapter.

Additional information about formatting docstrings can be found in the [Python style guide PEP 8](https://peps.python.org/pep-0008/#documentation-strings) [^pep8_docstring] and the [docstring convention guide PEP 257](https://peps.python.org/pep-0257/) [^pep257].
<!-- #endregion -->

<!-- #region editable=true slideshow={"slide_type": ""} -->
## Footnotes
Expand Down
124 changes: 112 additions & 12 deletions source/part1/chapter-02/nb/05-functions.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1170,23 +1170,39 @@
"source": [
"## Documenting functions with docstrings\n",
"\n",
"A documentation string, or *{term}`docstring`*, is a block of text that describes what a specific function, library, or script does and how to use it. Although the format of docstrings can vary, there are certain elements of a docstring that are needed for it to function properly. Let's look at an example using one of our functions created earlier in this section.\n",
"\n",
"```python\n",
"A documentation string, or *{term}`docstring`*, is a block of text that describes what a specific function, library, or script does and how to use it. Although the format of docstrings can vary, there are certain elements of a docstring that are needed for it to function properly. Let's look at an example using one of our functions created earlier in this section."
]
},
{
"cell_type": "code",
"execution_count": 39,
"metadata": {},
"outputs": [],
"source": [
"def kelvins_to_celsius(temp_kelvins):\n",
" \"\"\"Converts temperature in Kelvins to degrees Celsius.\"\"\"\n",
" return temp_kelvins - 273.15\n",
"```\n",
"\n",
" return temp_kelvins - 273.15"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Here you can see a short bit of text explaining in clear language what this function does. In this case our function is quite simple, but the docstring still helps remove uncertainty about what it can be used to do. So, what can we see in this example?\n",
"\n",
"- A docstring is always the first statement in a module or a function.\n",
"- Docstrings are enclosed in `\"\"\"triple double quotation marks\"\"\"`.\n",
"- Short docstrings [can be written on a single line](https://peps.python.org/pep-0257/#one-line-docstrings) [^pep257_one_line].\n",
"\n",
"Seems simple enough, right? However, we can also provide more detailed docstrings, which can be particularly helpful when using functions with multiple parameters. Let's expand the docstring above to provide more information about this function.\n",
"\n",
"```python\n",
"Seems simple enough, right? However, we can also provide more detailed docstrings, which can be particularly helpful when using functions with multiple parameters. Let's expand the docstring above to provide more information about this function."
]
},
{
"cell_type": "code",
"execution_count": 40,
"metadata": {},
"outputs": [],
"source": [
"def kelvins_to_celsius(temp_kelvins):\n",
" \"\"\"\n",
" Converts temperature in Kelvins to degrees Celsius.\n",
Expand All @@ -1201,11 +1217,95 @@
" <float>\n",
" Converted temperature.\n",
" \"\"\"\n",
" return temp_kelvins - 273.15\n",
"```\n",
"\n",
" return temp_kelvins - 273.15"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Here you can now see more information about the expected values for the parameters and what will be returned when using the function. This level of documentation is not needed for every function, but clearly it can be useful, especially when you have multiple parameters. Note here that the suggested format with multiple lines in a docstring is to have the quotation marks on their own separate lines.\n",
"\n",
"Perhaps the most valuable thing about adding the docstring is that it provides a way to easily see what a function does and how it works. We can do this using the `help()` function,"
]
},
{
"cell_type": "code",
"execution_count": 41,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Help on function kelvins_to_celsius in module __main__:\n",
"\n",
"kelvins_to_celsius(temp_kelvins)\n",
" Converts temperature in Kelvins to degrees Celsius.\n",
"\n",
" Parameters\n",
" ----------\n",
" temp_kelvins: <numerical>\n",
" Temperature in Kelvins\n",
"\n",
" Returns\n",
" -------\n",
" <float>\n",
" Converted temperature.\n",
"\n"
]
}
],
"source": [
"help(kelvins_to_celsius)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"or by typing the name of the function followed by `?`."
]
},
{
"cell_type": "code",
"execution_count": 42,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"\u001b[0;31mSignature:\u001b[0m \u001b[0mkelvins_to_celsius\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mtemp_kelvins\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
"\u001b[0;31mDocstring:\u001b[0m\n",
"Converts temperature in Kelvins to degrees Celsius.\n",
"\n",
"Parameters\n",
"----------\n",
"temp_kelvins: <numerical>\n",
" Temperature in Kelvins\n",
"\n",
"Returns\n",
"-------\n",
"<float>\n",
" Converted temperature.\n",
"\u001b[0;31mFile:\u001b[0m /var/folders/lp/cjwc88bd3w10sg327y_4ghg0fsk7jj/T/ipykernel_76562/3878566787.py\n",
"\u001b[0;31mType:\u001b[0m function"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"kelvins_to_celsius?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As you can see, we now have easy access to information about the function that has been included in the docstring. This means you can remind yourself about how functions you have written work, or look up information about functions from libraries, as discussed later in this chapter.\n",
"\n",
"Additional information about formatting docstrings can be found in the [Python style guide PEP 8](https://peps.python.org/pep-0008/#documentation-strings) [^pep8_docstring] and the [docstring convention guide PEP 257](https://peps.python.org/pep-0257/) [^pep257]. "
]
},
Expand Down

0 comments on commit 12ab6b0

Please sign in to comment.