finish v1

Author: professor-ben

README.md

@@ -33,75 +33,236 @@ A CLI is a program that is run from the command-line and provides a text-based
 interface to allow you to carry out various tasks. While the functionality of
 CLIs is limited by the capabilities of Terminal (in Mac OS) and Command
 Shell/Powershell (in Windows), _everything you have learned in Phase 3 can be
-carries out through a CLI._
+carried out through a CLI._
 
 ***
 
-## Lesson Section
+## Building a Simple CLI
 
-Lorem ipsum dolor sit amet. Ut velit fugit et porro voluptas quia sequi quo
-libero autem qui similique placeat eum velit autem aut repellendus quia. Et
-Quis magni ut fugit obcaecati in expedita fugiat est iste rerum qui ipsam
-ducimus et quaerat maxime sit eaque minus. Est molestias voluptatem et nostrum
-recusandae qui incidunt Quis 33 ipsum perferendis sed similique architecto.
+Before we dive into best practices for Python CLIs, let's build a very simple
+CLI. Fork this lesson from GitHub and open up `lib/grade_reports.py` to follow
+along.
+
+The first thing that we need to do is scaffold our CLI so that it can be run
+from the command line. To do this, we'll need to create a script. There are two
+pieces we know are going into the script regardless of the particulars: the
+**shebang** and our `if __name__ = '__main__'` block:
 
 ```py
-# python code block
-print("statement")
-# => statement
+#!/usr/bin/env python3
+
+if __name__ == '__main__':
+    pass
 ```
 
-```js
-// javascript code block
-console.log("use these for comparisons between languages.")
-// => use these for comparisons between languages.
+Remember that the shebang tells the command line that this program should be
+executed using the Python 3 interpreter. We can technically still run this as a
+script without it, but that would require us to write
+`python lib/grade_reports.py` every time we wanted to do so. Since other
+programmers using your CLI might not know about this requirement, you should
+always include the shebang. Run `chmod +x lib/grade_reports.py` to make your
+script executable.
+
+The `if __name__ == '__main__'` block tells the interpreter that this script
+should only be run if `lib/grade_reports.py` itself is being called from the
+command line. This is important if you want to import any objects from
+`lib/grade_reports.py` into other modules- if you don't include this code block,
+the full script will be run whenever your other module runs the import. That's
+not likely to be a helpful feature in your CLI.
+
+Let's start to add some very simple functionality to our CLI. We want to
+produce a grade report a full class of students; we're going to use Python's
+`input()` and `open()` functions to do so.
+
+```py
+#!/usr/bin/env python3
+
+def create_grade_report(student_grades):
+    with open('reports/grade_report.txt', 'w') as gr:
+        gr.write(student_grades)
+
+if __name__ == '__main__':
+    student_grades = input("Student name, grade: ")
+    create_grade_report(student_grades)
 ```
 
+Run `lib/grade_reports.py` to execute your script:
+
 ```console
-echo "bash/zshell statement"
-# => bash/zshell statement
+Student name, grade: Ben, F
+```
+
+Check the `reports` directory- you should see that `grade_report.txt` has
+been generated and contains your input! Still, this is not really useful for
+generating grade reports. Let's use a `while` loop to continue collecting
+student grades until there are no more to enter and a `for` loop to write the
+grades line-by-line:
+
+```py
+#!/usr/bin/env python3
+
+def create_grade_report(student_grades):
+    with open('reports/grade_report.txt', 'w') as gr:
+        for grade in student_grades:
+            # add '\n' to write grades on separate lines
+            gr.write(grade + '\n')
+
+if __name__ == '__main__':
+    student_grades = []
+
+    grade = input("Student name, grade: ")
+    while grade:
+        student_grades.append(grade)
+        # end when no grade is entered
+        grade = input("Student name, grade: ")
+
+    create_grade_report(student_grades)
 ```
 
 <details>
   <summary>
-    <em>Check for understanding text goes here! <code>Code statements go here.</code></em>
+    <em>Which mode would we set <code>open()</code> to if we wanted to update
+        <code>grade_report.txt</code>, rather than overwrite it?</em>
   </summary>
 
-  <h3>Answer.</h3>
-  <p>Elaboration on answer.</p>
+  <h3><code>'a'</code> for "append".</h3>
 </details>
 <br/>
 
+Now let's enter a classroom's worth of grades:
+
+```console
+Student name, grade: Ben, F
+Student name, grade: Prabhdip, A
+Student name, grade: Alvee, A
+Student name, grade: Jeff, B
+Student name, grade: Jerrica, A
+Student name, grade: Gustave, F
+Student name, grade: Katie, A
+Student name, grade:             # hit enter to complete
+```
+
+Check the `reports` directory again- nowyou should see that `grade_report.txt`
+has been regenerated and contains grades for all of your students!
+
+There are still, of course, many ways to improve this CLI. The instructions
+for the end user could certainly be much clearer. Maybe you want to be able to
+toggle between updating and generating new grade reports-
+[`argparse`](https://docs.python.org/3/library/argparse.html) would be
+helpful for that. Maybe you want timestamps for your grade reports to help you
+keep them organized- [`datetime`](https://docs.python.org/3/library/datetime.html)
+would be very helpful there. Maybe you're (rightfully) biased against `.txt`
+files and want to keep your data in a spreadsheet-
+[`csv`](https://docs.python.org/3/library/csv.html) would be the right module
+to import there.
+
 ***
 
-## Instructions
+## Best Practices in CLI Design
+
+Building a simple CLI doesn't take up too much code, but when you start to
+include a wide range of functionality in a single CLI, it can start to get
+messy. To make your life easier, keep a few things in mind as you work on
+your Phase 3 project:
 
-This is a **test-driven lab**. Run `pipenv install` to create your virtual
-environment and `pipenv shell` to enter the virtual environment. Then run
-`pytest -x` to run your tests. Use these instructions and `pytest`'s error
-messages to complete your work in the `lib/` folder.
+### Separate User Input from Functionality
 
-Instructions begin here:
+A CLI depends on user input and a lot of code to act on it, but that doesn't
+mean it all has to be in the same place. As with any other Python program,
+your CLI should be grouped into classes and functions. Your scripted code- that
+is, the code inside of your `if __name__ == '__main__'` block- should _only
+include user input and calls to classes and functions._
 
-- Make sure to specify any class, method, variable, module, package names
-  that `pytest` will check for.
-- Any other instructions go here.
+Let's take a look:
 
-Once all of your tests are passing, commit and push your work using `git` to
-submit.
+```py
+#!/usr/bin/env python3
+
+class MyClass:
+    def __init__(self, user_input)
+        self.value = user_input
+
+def my_function(my_object):
+    # returns a final value for the CLI workflow
+
+if __name__ == '__main__':
+    user_input = input("Enter something here: ")
+    my_object = MyClass(user_input)
+    print(my_function(my_object))
+```
+
+Here, we've factored most of our code into a class `MyClass` and a function
+`my_function()`. The scripted portion of the CLI only takes user input, calls
+`MyClass` and `my_function()`, and outputs the final value of the workflow. You
+may find it necessary at times to include `for` loops, `while` loops, and
+`if/elif/else` statements in this portion of the CLI, but make sure to separate
+and organize your code into classes and functions whenever possible.
+
+### Validate User Input
+
+You may have noticed in our `grade_reports` CLI that we did _not_ validate user
+input. If you wanted to enter a number or a nonsensical string, not only could
+you have done so, but it would have been written to `grade_report.txt`!
+
+A good CLI will check the format of user input before using it to perform any
+actions. This can be carried out using regular expressions through the [`re`
+module](https://docs.python.org/3/library/re.html), the built-in `type()` and
+`isinstance()` functions, the various Python operators, and more.
+
+<details>
+  <summary>
+    <em>What two arguments does <code>isinstance()</code> take?</em>
+  </summary>
+
+  <h3>An object and a class.</h3>
+  <p><code>isinstance()</code> will check to see if an object is an instance of
+     a specific class.</p>
+</details>
+<br/>
+
+### Keep the End User Informed
+
+You may have noticed while using Pipenv that many things are printed to the
+command line while external libraries are added to your virtual environment.
+This lets you know that Pipenv is doing its job. Most importantly, Pipenv
+finishes with a message as to what was installed, where it was installed, and
+how to access it later on.
+
+Compare this with our `grade_reports` CLI. What do we see when the script
+finishes execution? We can find our new file in the `reports` directory, but
+how would someone who downloaded your CLI from PyPI know that?
+
+A CLI should always inform the end user of what it is doing and where to find
+output. This should always happen through the CLI itself, but it's often
+helpful to store the messages from a session in a `logs` directory as well.
+
+### Use External Libraries to Standardize Your Code
+
+While we at Flatiron encourage you to show us as much of your amazing
+hand-written code as possible, it's often best to use popular external libraries
+to handle common programming tasks. This makes it easier to "onboard" new
+developers to your application if you ever need to hire a team to maintain it.
+
+Two popular libraries that will help you make amazing CLIs are
+[`Click`](https://click.palletsprojects.com/en/8.1.x/) and
+[`Fire`](https://google.github.io/python-fire/guide/). While we won't require
+you to use these in your Phase 3 project, we strongly recommend that you use
+one. (It's another library to add to your resumé!)
 
 ***
 
 ## Conclusion
 
-Conclusion summary paragraph. Include common misconceptions and what students
-will be able to do moving forward.
+CLIs are a helpful tool for managing the data on your computer and on remote
+servers. A well-built CLI will allow you to let non-technical users complete
+many of the same tasks with your application that you can from the Python shell
+without very much training at all. Consider the best practices for building CLIs
+as you work through the Phase 3 project this week- make sure to look back at
+the earlier modules, too!
 
 ***
 
 ## Resources
 
-- [Resource 1](https://www.python.org/doc/essays/blurb/)
-- [Reused Resource][reused resource]
-
-[reused resource]: https://docs.python.org/3/
+- [Click documentation](https://click.palletsprojects.com/en/8.1.x/)
+- [The Python Fire Guide](https://google.github.io/python-fire/guide/)

lib/grade_reports.py

@@ -0,0 +1,4 @@
+#!/usr/bin/env python3
+
+if __name__ == '__main__':
+    pass