Python Package Example

2. Python Package Example#

The following is an example of on how to use and distribute your project as a Python package using the example template. Remember mix and match to yout project’s requirements.

2.1. Usage#

Unlike the previous example, where the source code was contained on the Jupyter notebook itself, we (re)use a Python package - the template Python package - which will let us (re)use any attributes and methods in the following example.

Let’s start by importing WorldBankIndicatorsAPI, a Python API wrapper class created to facilitate the usage of the World Bank Indicators API.

from template.indicators import WorldBankIndicatorsAPI

Let’s continue by creating the API object.

api = WorldBankIndicatorsAPI()

The api wrapper object is now ready to use! We will invoke its query method to retrieve data from the World Bank Indicators API. To learn how to use it, such as information about method signature, valid parameters and return value, we read help. Since PEP 257, Python offers doctrings, which are an easy and standard to create code documentation and it is a good practice adopt it. Documentating the source code is crucial to create a maintainable reliable and reproducicle code base and project.

Let’s see the query method’s docstring as shown below.

help(api.query)

The query method allows us to select an indicator (e.g, World Development Indicators), a list of countries and query parameters. Note that contrary to the previous example, the method expects a list of country names and converts them to ISO 3166-1 alpha-3 automatically.

Let’s invoke the query method and retrieve the results for SP.POP.TOTL for the BRICS (as before).

df = api.query(
    "SP.POP.TOTL", country=["Brazil", "China", "India", "Russia", "South Africa"]
)

Voilà! We just (re)used the template Python package in our example delegating the maintenance and logic, making the notebook easier to understand and reproduce.

Tip

In addition, the <span style="color:#3EACAD">template</span> makes any Python package automatically pip installable and accessible to anyone and from anywhere!

To install from source:

pip install git+https://github.com/worldbank/template.git

To install from version:

pip install git+https://github.com/worldbank/template.git@v0.1.0

When distributing a project release, it is strongly recommended to adhere to release management good practices. It is recommended to create checklists, adopt versioning (e.g, semantic versioning and to release on Python Package Index (instead of GitHub).

Tip

The template will automatically find and install any local src packages as long as the setup.cfg file is up-to-date.

Caution

The template Python package should be used for demonstration purposes only. For support, please see the World Bank Indicators API Documentation.

Finally, let’s take a look at the retrieved data.

df

2.2. Visualization#

As before, let’s now plot the data as a time series using Bokeh.

output_notebook()

# instantiating the figure object
p = figure(title="Population, total (World Bank)", width=700, height=600)

# colors
colors = itertools.cycle(Spectral6)

# plotting the line graph
for column, color in zip(df.columns, colors):
    p.line(
        df.index,
        df[column],
        legend_label=column,
        color=color,
        line_width=2,
    )

p.legend.location = "right"
p.legend.click_policy = "mute"
p.title.text_font_size = "12pt"

p.xaxis.axis_label = "Year"
p.yaxis.axis_label = "Population, total (in millions)"

show(p)
Contents