Section 3.3 Using Existing Code and Libraries

A library is a collection of code written by other programmers that we can use in our own programs. Libraries have existing code that can quickly add functionality to our programs without having to write everything ourselves.

In Python, you can import libraries like random or turtle and then use the functions they provide. Single python files that are imported in are called modules, and a folder of these Python files is called a package. Libraries can be collections of modules or packages.

import random
# We can now use the randint() function from the random library
number = random.randint(1, 10)

import turtle
# We can now use the turtle library to draw shapes
turt = turtle.Turtle()
turt.forward(100)

Libraries often have documentation that explains how to use the code and what each function does. For example, https://docs.python.org/3/library/turtle.html#turtle-methods explains every function in the Turtle library. Unfortunately, not all of the Python Turtle functions work in this ebook, because it uses a browser implementation of Python.

We can also package our code into modules and packages for easier reuse. We can also include existing code from other sources, including Gen AI. When including code from other sources, it is important to check the license and to give credit to the original creator.

An application programming interface (API) is the set of rules or specification that specifies how to use a library or software component. These rules are spelled out in the library documentation. The API describes what inputs are accepted and what output is returned.

For example, the following documentation describes the API for the math function isqrt in the Python math module https://docs.python.org/3/library/math.html#math.isqrt:

math.isqrt(n)
Return the integer square root of the nonnegative integer n. 
This is the floor of the exact square root of n, or equivalently the greatest integer a 
such that a² <= n.

math.isqrt(n)
Return the integer square root of the nonnegative integer n.

Many web service or platforms, for example Google Maps, Youtube, Wikipedia, etc. have APIs that allow access to their service for programmers. This simplifies complex programming tasks and allows communication between different programs. For example, you can use the Google Maps API to embed a map in an app that you are creating.

We can often see a web platform’s API in action while using the platform. For example, go to https://www.google.com/maps and search for a location. Notice how the url (web address) changes. For example, if you search for "Philadelphia", the url changes to https://www.google.com/maps/place/Philadelphia followed by other geographic information, but just the city name is enough to get the map to show Philadelphia. This is an example of a web API in action. We now know the rule that we can take the base url and add "place/cityname" to get a map of that city. Try just changing the url to find the map of another city, for example Chicago.

When selecting libraries or existing code segments, it’s important to consider the following factors:

It is also important to cite the sources of any libraries or code segments you use in the comments of your code, and to test it.

If you were creating a calculator app and wanted to have a square root function, you could use the sqrt function from the Python math module. You would first look at its documentation at https://docs.python.org/3/library/math.html#math.sqrt to understand how to use it. After using it in your code, you would need to test it to make sure it works as expected on typical inputs and boundary cases, for example with positive numbers, zero, and negative numbers. The square root of a negative number is not defined in the real number system, so you would expect that to give an error.

In this project, you will use an API For a web service called https://dog.ceo/dog-api which provides free dog images by breed. In the documentation, https://dog.ceo/dog-api/documentation/random, you can find the url (web address) for fetching random dog images. You can also try it in your browser to see that https://dog.ceo/api/breeds/image/random returns some text like {"message":"https://images.dog.ceo/breeds/german-shepherd/n02106662_16342.jpg","status":"success"} and if we paste the embedded image link into a browser, we can see the image that it returns https://images.dog.ceo/breeds/german-shepherd/n02106662_16342.jpg. Try running the active code below to see the random images that it returns which is displayed in the web page using a hidden showImage function.

Now, take a look at the documentation for showing random dog images of a certain breed at https://dog.ceo/dog-api/breeds-list. Pull down the menu to see different breeds.

Let’s use this API to fetch images of a specific dog breed that the user chooses. First, create a list of at least 5 dog breeds that are in the API. Then, use a loop to print the list of dog breeds with their index number. Then, ask the user to input the index number of the dog breed they want to see. Finally, use the API to fetch a random image of that breed and display it on the web page using the showImage function.