Session 16: Documentation

Session 16: Documentation#

Introduction#

There will often be times in which we are not sure quite how a specific function or feature of a programming language or package works. When this happens, we turn to what is known as that software’s documentation (often abbreviated to “docs”), which contains a technical description of how the program or language works (usually with examples).

Reading and understanding how to apply documentation is an essential skill for anyone writing code. In this session, we’ll explore how to navigate and understand Python’s official documentation, as well as documentation for external libraries.

Part 1: Python Standard Library#

Task 1#

  1. Visit the official Python documentation at https://docs.python.org.

  2. Locate the documentation for the version of Python you are currently using.

    • If you don’t remember, you can enter python -V or python --version into a terminal window.

  3. Find the section about built-in functions and read a couple of entries of functions you’ve already come across (e.g., len(), range()).

    • It will be under Library reference and then Built-in functions

    • You can use the search function to find exactly what you are looking for more quickly!

  4. Have a look around at other parts of the Python Standard Library documentation

Analysis#

Using float() as an example, how can we use the documentation to help us?

  • The first thing we see is the function signature

    class float(number=0.0, /)
class float(string, /)

    • This tells us that float() is technically also a class, and it can take either a number or a string as a parameter (input).

    • The / tells us that this is the end of the so-called positional parameters (i.e. ones whose order matters). This will be relevant to more complex functions that you come across later.

  • Next we have a short description of what the function does in relatively simple terms.

  • Finally we have examples and some additional relevant information.

    • There will often be more information than you need in the documentation. This is by design. You will not need it most of the time, but in that rare occasion that you do, you’ll be happy it’s there!

  • Remember that you can also use the help() function within a REPL shell to give you some documentation as well.

    # Example: Accessing built-in function docs from the interpreter
help(float)

Task 2#

  1. Navigate to the built-in time library documentation page.

  2. Read the entries on strftime() and localtime().

  3. Create a file called print_time.py and paste in the following code.

    import time

# Get the current local time
current_time = time.localtime()

# Format the time string
formatted_time = time.strftime("%H:%M:%S - %A, %B %dth, %Y", current_time)

# Print the formatted time
print(formatted_time)

  4. Run the code and read the output.

Analysis#

Using the time library documentation, we can understand how to manipulate and format time-related data in Python.

  • In our case, the localtime() function returns a struct_time variable type of the current local time.

  • The strftime() function formats current_time as a string according to the specified format. This is useful for creating human-readable time strings.

  • By reading the documentation, we have learned the specific format codes used in strftime(). This allows us to customize the output format of the time string:

    • %H for the hour (24-hour clock)

    • %M for minutes

    • %S for seconds

    • %A for the full weekday name

    • %B for the full month name

    • %d for the day of the month

    • %Y for the year.

  • If you play around with strftime() a lot, you might find this cheatsheet useful: https://strftime.org

Part 2: Using Documentation for Other Packages#

For this part, we will be exploring documentation for external packages. While the Python documentation is excellent, it is written in a particular format, and it is useful to understand how other documentation may be presented.

We will be covering external libraries in more detail in a future session, so don’t worry too much about the details of the packages themselves. The aim here is to gain some exposure of different documentation styles.

While the packages discussed in this module will usually have good documentation available, you might encounter some which is a bit barebones. This is unavoidable sometimes, and it highlights the importance of following good coding practices as discussed previously, especially surrounding comments and docstrings.

Task 3#

  1. Navigate to the numpy.mean() documentation page available here: https://numpy.org/doc/2.2/reference/generated/numpy.mean.html

  2. Read through the page and have a look through the examples at the bottom of the page.

    • You will likely not understand a lot of what is going on - don’t be discouraged by this, it is completely normal to feel this way at this point!

  3. See if you can think how you might use this function to find the average value of an array or an array of arrays.

Analysis#

There is a lot going on here, so let’s break things down a little bit.

  • Function signature

    • Here we see the numpy.mean() parameters, and compared to our previous examples, the list is suddenly very long!

    • There are 2 types of parameters here, the first one is our positional parameter, a, which is simply an array that we input into the function.

    • All the other parameters are known as keyword parameters, where they are defined as parameter=DefaultValue

      • The keyword is the string before the =, and the default value used (if not defined when using the function) is given after.

      • For example, if we just used numpy.mean([1,2]), then the keyword parameter axis will have a value of None, as described in the function signature.

    • If you look to the right of the signature, you will see a [Source] link; this will take you directly to the source code where the function is defined. You can literally see how the code works in practice, although it might look a bit odd or complicated compared to what you have seen so far!

Summary#

  • Recognizing function signatures, parameters, and return types can help save time.

  • Documentation often provides usage examples, which can clarify ambiguous details.

Programming Challenge

Using the Standard Python Library documentation as a reference, write a program that takes an input of 3 numbers from the user as a comma-separated list (e.g. 1,2,3) and finds the absolute value of the last number subtracted by the first number.

Hint

You might find the abs() and str.split() built-in functions a useful starting point!

Contents