Homework 02
===========

**Due Date: Thursday, Feb 25, by 11:00am CST**

The Containers and Repositories of Dr. Moreau
---------------------------------------------

This homework builds upon homework 01. You should have already written two
Python scripts: one for generating a JSON file of assembled animals
(``generate_animals.py``), and another for reading in and printing one animal at
random (``read_animals.py``).

You are almost ready to release this code into the wild for others to use. Your
aims in this homework are (1) write one new feature into the ``read_animals.py``
script, (2) write a unit test for your new feature in ``read_animals.py``, (3)
write a Dockerfile to containerize both scripts, (4) write a reasonable
``README.md`` for your repository.

More details on each of the requirements:

(1) New Feature
~~~~~~~~~~~~~~~

The ``read_animals.py`` script has a lot of room for improvement. The first
objective is to write some new functionality into the script. Some examples of
new features that could be added include:

* Pick two random animals and 'breed' them by mixing their elements to create a
  new animal, which is printed to screen along with its 'parents'
* Use the ``argparse`` library to take command line arguments and apply some
  error checking on the input
* Generate some summary statistics of all the animals read in and print it to
  screen

These suggestions are suggestions only - please be creative and write any new
feature into ``read_animals.py`` that you want.

(2) Unit Test
~~~~~~~~~~~~~

Use the Python ``unittest`` library to write at least one test for your new
functionality in ``read_animals.py``. (Remember, a single 'test' should probably
multiple 'checks' in it - see the section on Unit Testing for examples).

The test should be in a file like ``test_read_animals.py`` and should be
executable from the command line.

(3) Dockerfile
~~~~~~~~~~~~~~

The scripts we are writing should be runnable directly on ISP. They should also
be runnable within a container. (Users downloading your code may want to run
them directly, run them in a container, or both - it is usually good practice to
provide all these options.)

Write and provide a Dockerfile that encapsulates your Python scripts. Any output
generated by the scripts should be accessible outside of the container. You do
not need to containerize the unit tests.


(4) README.md
~~~~~~~~~~~~~

In the ``homework02`` folder of your class repository, create a file called
``README.md``. On GitHub, this README file will automatically render in the web
interface, and it serves as the landing page of your repository (specifically
of the homework02 subfolder of your repository). This is your opportunity to
describe to other users what code is here, what it does, and how to use it.

Your README file should have at a minimum the following sections and
instructions for users:

* A general description of the tool(s)
* Instructions on how to download and run the scripts directly
* Instructions on how to build an image with the Dockerfile provided
* Instructions on how to run the scripts inside a container
* Instructions on how to run the unit test(s)




What to Turn In
---------------

Your final homework should be turned in via GitHub. You should already have a
repository for this class with a ``homework01`` subfolder in it. Create a new
subfolder called ``homework02`` and put everything described above inside.

The TA will git clone your repository on the due date / time, navigate to your
``homework02`` folder, and inspect your code and files. We will be trying out
your new feature in ``read_animals.py``, we will be running the unit tests, we
will be building your Dockerfile and running the scripts in the container. The
instructions you provide in your README are the instructions we will follow to
do those things.



Additional Resources
--------------------

* `Markdown Cheat Sheet <https://www.markdownguide.org/cheat-sheet/>`_
* `README 101 <https://www.makeareadme.com/>`_