26. Libraries and Modules

../../_images/library.png

A library is a collection of code for functions and classes. Often, these libraries are written by someone else and brought into the project so that the programmer does not have to “reinvent the wheel.” In Python the term used to describe a library of code is module.

By using import arcade and import random, the programs created so far have already used modules. A library can be made up of multiple modules that can be imported. Often a library only has one module, so these words can sometimes be used interchangeably.

Modules are often organized into groups of similar functionality. In this class programs have already used functions from the math module, the random module, and the arcade library. Modules can be organized so that individual modules contain other modules. For example, the arcade module contains submodules for arcade.key, and arcade.color.

Modules are not loaded unless the program asks them to. This saves time and computer memory. This chapter shows how to create a module, and how to import and use that module.

26.1. Why Create a Library?

There are three major reasons for a programmer to create his or her own libraries:

  1. It breaks the code into smaller, easier to use parts.

  2. It allows multiple people to work on a program at the same time.

  3. The code written can be easily shared with other programmers.

Some of the programs already created in this book have started to get rather long. By separating a large program into several smaller programs, it is easier to manage the code. For example, in the prior chapter’s sprite example, a programmer could move the sprite class into a separate file. In a complex program, each sprite might be contained in its own file.

If multiple programmers work on the same project, it is nearly impossible to do so if all the code is in one file. However, by breaking the program into multiple pieces, it becomes easier. One programmer could work on developing an “Orc” sprite class. Another programmer could work on the “Goblin” sprite class. Since the sprites are in separate files, the programmers do not run into conflict.

Modern programmers rarely build programs from scratch. Often programs are built from parts of other programs that share the same functionality. If one programmer creates code that can handle a mortgage application form, that code will ideally go into a library. Then any other program that needs to manage a mortgage application form at that bank can call on that library.

26.2. Creating Your Own Module/Library File

Video: Libraries

In this example we will break apart a short program into multiple files. Here we have a function in a file named test.py, and a call to that function:

test.py with everything in it
1# Foo function
2def foo():
3    print("foo!")
4
5def main():
6    # Foo call
7    foo()
8
9main()

Yes, this program is not too long to be in one file. But if both the function and the main program code were long, it would be different. If we had several functions, each 100 lines long, it would be time consuming to manage that large of a file. But for this example we will keep the code short for clarity.

We can move the foo function out of this file. Then this file would be left with only the main program code. (In this example there is no reason to separate them, aside from learning how to do so.)

To do this, create a new file and copy the foo function into it. Save the new file with the name my_functions.py. The file must be saved to the same directory as test.py.

my_functions.py
1# Foo function
2def foo():
3    print("foo!")
test.py that doesn’t work
1def main():
2    # Foo call that doesn't work
3    foo()
4
5main()

Unfortunately it isn’t as simple as this. The file test.py does not know to go and look at the my_functions.py file and import it. We have to add the command to import it:

test.py that imports but still doesn’t work
1# Import the my_functions.py file
2import my_functions
3
4def main():
5    # Foo call that still doesn't work
6    foo()
7
8main()

That still doesn’t work. What are we missing? Just like when we import arcade, we have to put the package name in front of the function. Like this:

test.py that finally works
1# Import the my_functions.py file
2import my_functions
3
4def main():
5    # Foo call that does work
6    my_functions.foo()
7
8main()

This works because my_functions. is prepended to the function call.

26.3. Namespace

Video: Namespace

A program might have two library files that need to be used. What if the libraries had functions that were named the same? What if there were two functions named print_report, one that printed grades, and one that printed an account statement? For instance:

student_functions.py
1def print_report():
2    print("Student Grade Report:" )
financial_functions.py
1def print_report():
2    print("Financial Report:" )

How do you get a program to specify which function to call? Well, that is pretty easy. You specify the namespace. The namespace is the work that appears before the function name in the code below:

test.py that calls different print_report functions
1import student_functions
2import financial_functions
3
4def main():
5    student_functions.print_report()
6    financial_functions.print_report()
7
8main()

So now we can see why this might be needed. But what if you don’t have name collisions? Typing in a namespace each and every time can be tiresome. You can get around this by importing the library into the local namespace. The local namespace is a list of functions, variables, and classes that you don’t have to prepend with a namespace. Going back to the foo example, let’s remove the original import and replace it with a new type of import:

test.py
1# import foo
2from my_functions import *
3
4def main():
5    foo()
6
7main()

This works even without my_functions. prepended to the function call. The asterisk is a wildcard that will import all functions from my_functions. A programmer could import individual ones if desired by specifying the function name.

26.4. Third Party Libraries

When working with Python, it is possible to use many libraries that are built into Python. Take a look at all the libraries that are available here:

http://docs.python.org/3/py-modindex.html

It is possible to download and install other libraries. There are libraries that work with the web, complex numbers, databases, and more.

You can do analysis and create your own interactive notebook using Jupyter:

Some libraries we give examples of in this chapter:

A wonderful list of Python libraries and links to installers for them is available here:

You can search up some top packages/libraries and stand alone projects to get an idea of what you can do. There are many articles like Top 15 Python Libraries for Data Science in 2017.

26.4.1. Examples: OpenPyXL Library

This example uses a library called OpenPyXL to write an Excel file. It is also easy to read from an Excel file. You can install OpenPyXL from the Windows command prompt by typing pip install openpyxl. If you are on the Mac or a Linux machine, you can type sudo pip3 install openpyxl.

Note

When starting the command prompt, you might need to right-click on it and select “Run as administrator” if you get permission errors when installing. And if you are working on a lab computer, you might not have permission to install libraries.

openpyxl_example.py
 1"""
 2Example using OpenPyXL to create an Excel worksheet
 3"""
 4
 5from openpyxl import Workbook
 6import random
 7
 8# Create an Excel workbook
 9work_book = Workbook()
10
11# Grab the active worksheet
12work_sheet = work_book.active
13
14# Data can be assigned directly to cells
15work_sheet['A1'] = "This is a test"
16
17# Rows can also be appended
18for i in range(200):
19    work_sheet.append(["Random Number:", random.randrange(1000)])
20
21# Save the file
22work_book.save("sample.xlsx")

The output of this program is an Excel file:

../../_images/excel_example.png

26.4.2. Examples: Beautiful Soup Library

This example grabs information off a web page. You can install Beautiful Soup from the Windows command prompt by typing pip install bs4. If you are on the Mac or a Linux machine, you can type sudo pip3 install bs4.

bs4_example.py
 1"""
 2Example showing how to read in from a web page
 3"""
 4
 5from bs4 import BeautifulSoup
 6import urllib.request
 7
 8# Read in the web page
 9url_address = "http://simpson.edu"
10page = urllib.request.urlopen(url_address)
11
12# Parse the web page
13soup = BeautifulSoup(page.read(), "html.parser")
14
15# Get a list of level 1 headings in the page
16headings = soup.findAll("h1")
17
18# Loop through each row
19for heading in headings:
20    print(heading.text)

26.4.3. Examples: Matplotlib Library

Here is an example of what you can do with the third party library “Matplotlib.” You can install Matplotlib from the Windows command prompt by typing pip install matplotlib. If you are on the Mac or a Linux machine, you can type pip3 install matplotlib.

26.4.3.1. Example 1: Simple Plot

To start with, here is the code to create a simple line chart with four values:

../../_images/matplotlib_01.png

Simple Line Graph

Example 1
 1"""
 2Line chart with four values.
 3The x-axis defaults to start at zero.
 4"""
 5import matplotlib.pyplot as plt
 6
 7y = [1, 3, 8, 4]
 8
 9plt.plot(y)
10plt.ylabel('Element Value')
11plt.xlabel('Element Number')
12
13plt.show()

Note that you can zoom in, pan, and save the graph. You can even save the graph in vector formats like ps and svg that import into documents without loss of quality like raster graphics would have.

26.4.3.2. Example 2: Specify x Values

The x value for Example 1, defaults to start at zero. You can change this default and specify your own x values to go with the y values. See Example 2 below.

../../_images/matplotlib_02.png

Specifying the x values

Example 2
 1"""
 2Line chart with four values.
 3The x-axis values are specified as well.
 4"""
 5import matplotlib.pyplot as plt
 6
 7x = [1, 2, 3, 4]
 8y = [1, 3, 8, 4]
 9
10plt.plot(x, y)
11
12plt.ylabel('Element Value')
13plt.xlabel('Element')
14
15plt.show()

26.4.3.3. Example 3: Add A Second Data Series

It is trivial to add another data series to the graph.

../../_images/matplotlib_03.png

Graphing two data series

Example 3
 1"""
 2This example shows graphing two different series
 3on the same graph.
 4"""
 5import matplotlib.pyplot as plt
 6
 7x =  [1, 2, 3, 4]
 8y1 = [1, 3, 8, 4]
 9y2 = [2, 2, 3, 3]
10
11plt.plot(x, y1)
12plt.plot(x, y2)
13
14plt.ylabel('Element Value')
15plt.xlabel('Element')
16
17plt.show()
18

26.4.3.4. Example 4: Add A Legend

You can add a legend to the graph:

../../_images/matplotlib_04.png

Adding a legend

Example 4
 1
 2import matplotlib.pyplot as plt
 3
 4x =  [1, 2, 3, 4]
 5y1 = [1, 3, 8, 4]
 6y2 = [2, 2, 3, 3]
 7
 8plt.plot(x, y1, label = "Series 1")
 9plt.plot(x, y2, label = "Series 2")
10
11legend = plt.legend(loc='upper center', shadow=True, fontsize='x-large')
12legend.get_frame().set_facecolor('#00FFCC')
13
14plt.ylabel('Element Value')
15plt.xlabel('Element')
16
17plt.show()

26.4.3.5. Example 5: Add Annotations

You can add annotations to a graph:

../../_images/matplotlib_05.png

Adding annotations

Example 5
 1"""
 2Annotating a graph
 3"""
 4import matplotlib.pyplot as plt
 5
 6x = [1, 2, 3, 4]
 7y = [1, 3, 8, 4]
 8
 9plt.annotate('Here',
10             xy = (2, 3),
11             xycoords = 'data',
12             xytext = (-40, 20),
13             textcoords = 'offset points',
14             arrowprops = dict(arrowstyle="->",
15                               connectionstyle="arc,angleA=0,armA=30,rad=10"),
16             )
17
18plt.plot(x, y)
19
20plt.ylabel('Element Value')
21plt.xlabel('Element')
22
23plt.show()

26.4.3.6. Example 6: Change Line Styles

Don’t like the default lines styles for the graph? That can be changed by adding a third parameter to the plot command.

../../_images/matplotlib_06.png

Specifying the line style

Example 6
 1"""
 2This shows how to set line style and markers.
 3"""
 4import matplotlib.pyplot as plt
 5
 6x =  [1, 2, 3, 4]
 7y1 = [1, 3, 8, 4]
 8y2 = [2, 2, 3, 3]
 9
10# First character: Line style
11# One of '-', '--',  '-.', ':', 'None', ' ', "
12
13# Second character: color
14# http://matplotlib.org/1.4.2/api/colors_api.html
15
16# Third character: marker shape
17# http://matplotlib.org/1.4.2/api/markers_api.html
18
19plt.plot(x, y1, '-ro')
20plt.plot(x, y2, '--g^')
21
22plt.ylabel('Element Value')
23plt.xlabel('Element')
24
25plt.show()

26.4.3.7. Example 7: Bar Chart

A bar chart is as easy as changing plot to bar.

../../_images/matplotlib_07.png

Bar chart

Example 7
 1"""
 2How to do a bar chart.
 3"""
 4import matplotlib.pyplot as plt
 5
 6x = [1, 2, 3, 4]
 7y = [1, 3, 8, 4]
 8
 9plt.bar(x, y)
10
11plt.ylabel('Element Value')
12plt.xlabel('Element')
13
14plt.show()

26.4.3.8. Example 8: Axis Labels

You can add labels to axis values.

../../_images/matplotlib_08.png

X-axis labels

Example 8
 1"""
 2How to add x axis value labels.
 3"""
 4import matplotlib.pyplot as plt
 5
 6x = [1, 2, 3, 4]
 7y = [1, 3, 8, 4]
 8
 9plt.plot(x, y)
10
11labels = ['Frogs', 'Hogs', 'Bogs', 'Slogs']
12plt.xticks(x, labels)
13
14plt.ylabel('Element Value')
15plt.xlabel('Element')
16
17plt.show()

26.4.3.9. Example 9: Graph Functions

You can graph functions as well. This uses a different package called numpy to graph a sine function.

../../_images/matplotlib_09.png

Graphing a sine function

Example 9
 1"""
 2Using the numpy package to graph a function over
 3a range of values.
 4"""
 5import numpy
 6import matplotlib.pyplot as plt
 7
 8x = numpy.arange(0.0, 2.0, 0.001)
 9y = numpy.sin(2 * numpy.pi * x)
10
11plt.plot(x, y)
12
13plt.ylabel('Element Value')
14plt.xlabel('Element')
15
16plt.show()

26.4.3.10. Example 10: Graph Functions With Fill

You can fill in a graph if you like.

../../_images/matplotlib_10.png

Filling in a graph

Example 10
 1"""
 2Using 'fill' to fill in a graph
 3"""
 4import numpy
 5import matplotlib.pyplot as plt
 6
 7x = numpy.arange(0.0, 2.0, 0.001)
 8y = numpy.sin(2 * numpy.pi * x)
 9
10plt.plot(x, y)
11
12# 'b' means blue. 'alpha' is the transparency.
13plt.fill(x, y, 'b', alpha=0.3)
14
15plt.ylabel('Element Value')
16plt.xlabel('Element')
17
18plt.show()

26.4.3.11. Example 11: Pie Chart

Create a pie chart.

../../_images/matplotlib_11.png

Pie chart

Example 11
 1"""
 2Create a pie chart
 3"""
 4import matplotlib.pyplot as plt
 5
 6# Labels for the pie chart
 7labels = ['C', 'Java', 'Objective-C', 'C++', 'C#', 'PHP', 'Python']
 8
 9# Sizes for each label. We use this to make a percent
10sizes = [17, 14, 9, 6, 5, 3, 2.5]
11
12# For list of colors, see:
13# https://matplotlib.org/examples/color/named_colors.html
14colors = ['yellowgreen', 'gold', 'lightskyblue', 'lightcoral', 'darkcyan', 'aquamarine', 'rosybrown']
15
16# How far out to pull a slice. Normally zero.
17explode = (0, 0.0, 0, 0, 0, 0, 0.2)
18
19# Set aspect ratio to be equal so that pie is drawn as a circle.
20plt.axis('equal')
21
22# Finally, plot the chart
23plt.pie(sizes, explode=explode, labels=labels, colors=colors,
24        autopct='%1.1f%%', shadow=True, startangle=90)
25
26plt.show()

26.4.3.12. Example 12: Candlestick Chart

You can do really fancy things, like pull stock data from the web and create a candlestick graph for Apple Computer:

../../_images/matplotlib_12.png

Candlestick chart

Example 12
 1"""
 2Create a candlestick chart for a stock
 3"""
 4import matplotlib.pyplot as plt
 5from matplotlib.dates import DateFormatter, WeekdayLocator,\
 6     DayLocator, MONDAY
 7from matplotlib.finance import quotes_historical_yahoo_ohlc, candlestick_ohlc
 8
 9# Grab the stock data between these dates
10date1 = (2014, 10, 13)
11date2 = (2014, 11, 13)
12
13# Go to the web and pull the stock info
14quotes = quotes_historical_yahoo_ohlc('AAPL', date1, date2)
15if len(quotes) == 0:
16    raise SystemExit
17
18# Set up the graph
19fig, ax = plt.subplots()
20fig.subplots_adjust(bottom=0.2)
21
22# Major ticks on Mondays
23mondays = WeekdayLocator(MONDAY)
24ax.xaxis.set_major_locator(mondays)
25
26# Minor ticks on all days
27alldays = DayLocator()
28ax.xaxis.set_minor_locator(alldays)
29
30# Format the days
31weekFormatter = DateFormatter('%b %d')  # e.g., Jan 12
32ax.xaxis.set_major_formatter(weekFormatter)
33ax.xaxis_date()
34
35candlestick_ohlc(ax, quotes, width=0.6)
36
37ax.autoscale_view()
38plt.setp(plt.gca().get_xticklabels(), rotation=45, horizontalalignment='right')
39
40plt.show()

There are many more things that can be done with matplotlib. Take a look at the thumbnail gallery:

http://matplotlib.org/gallery.html