Table of Contents

1. Challenge

   Create the Folder Structure for the `words` Package within the `~/packages` Directory

   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
   

2. Challenge

   Write the `random_word` and `random_words` Functions within the `words.generator` Module

   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)
   

3. Challenge

   Customize `~/packages/words/src/words/__init__.py` to Provide the `random_words` Function

   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.

4. Challenge

   Write the `setup.py`, Build a Wheel, and Install the Package Using `pip`

   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