Creating a Python Package

Before we implement the actual functionality of our package, we're going to create the folder structure and the files we'll need. Our code will go within a directory under the ~/packages/words/src/ directory, and we'll also need a setup.py at the root of our higher-level words directory (the project directory).

Run the following commands to set up the folder structure and files we need to create a fully installable Python package:

mkdir -p ~/packages/words/src/words

mv ~/generator.py ~/packages/words/src/words/

touch ~/packages/words/setup.py

touch ~/packages/words/src/words/__init__.py

Our words.generator module will hold both of the useful functions we need to write and already has a little bit of code to start. Here's what the file should look like before we begin:

~/packages/words/src/words/generator.py

from random import sample

# Do not modify or remove this
with open("/usr/share/dict/words", "r") as f:
    WORD_LIST = [w.strip("\n") for w in f.readlines()]

We need to utilize the sample function from the standard libraries random module to get a random list of words, and then we can write random_word to take the first item from a list returned from a call to random_words. Here's one way we can implement these functions:

~/packages/words/src/words/generator.py

from random import sample

# Do not modify or remove this
with open("/usr/share/dict/words", "r") as f:
    WORD_LIST = [w.strip("\n") for w in f.readlines()]

def random_word():
    return random_words(1)[0]

def random_words(length):
    return sample(WORD_LIST, length)

The using_packages.py file uses the random_words function without explicitly importing it from the words.generator package. Instead, it has from words import *. This means we need to import the random_words function into the __init__.py for our package and, optionally, we can explicitly make that available using the __all__ variable. Here's one way we can achieve this:

~/packages/words/src/words/__init__.py

__all__ = ["random_words"]

from .generator import *

Now, running from words import * when the package is installed will result in all the definitions from words.generator being loaded, but only random_words will get imported.

Our package now has all the functional code it needs, but it is not installable. We need to customize our setup.py using the setup function from setuptools. We could start with a starter file like this one from the PyPA example repository, or we can write a simple one from scratch. Here's the simplest version of this file:

~/packages/words/setup.py

from setuptools import find_packages, setup

setup(
    name="words",
    version="1.0.0",
    description="Helper library for working with random words",
    package_dir={"": "src"},
    packages=find_packages(where="src"),
)

Now we need to ensure wheel is installed and then build a wheel for our package using the bdist_wheel subcommand.

cd ~/packages/words

pip3.7 install --user --upgrade wheel

python3.7 setup.py bdist_wheel

Next, let's install our package using pip and then run the ~/using_packages.py script:

pip3.7 install --user ~/packages/words/dist/words-1.0.0-py3-none-any.whl

python3.7 using_packages.py