From dade948dc3a48bfe616b58e934c552c5ccc65f19 Mon Sep 17 00:00:00 2001 From: Jon Pipitone Date: Fri, 1 Feb 2013 13:08:26 -0500 Subject: [PATCH] Conversion of all rst to corresponding markdown files We use git-flavoured markdown W. Trevor King: I dropped everything from the original 4ba1cf2 except for the python/sw_engineering/ modifications. Conflicts: LICENSE.md python/data_structures/Readme.md python/documentation/Readme.md python/documentation/close_line.md python/flow_control/Readme.md python/functions_and_modules/Readme.md python/scipy/Readme.md shell/Readme.md version-control/git/remote/Readme.md --- python/sw_engineering/README.md | 54 ++++++++++++++++++ python/sw_engineering/README.rst | 54 ------------------ python/sw_engineering/dev_notes.md | 87 +++++++++++++++++++++++++++++ python/sw_engineering/dev_notes.rst | 83 --------------------------- 4 files changed, 141 insertions(+), 137 deletions(-) create mode 100644 python/sw_engineering/README.md delete mode 100644 python/sw_engineering/README.rst create mode 100644 python/sw_engineering/dev_notes.md delete mode 100644 python/sw_engineering/dev_notes.rst diff --git a/python/sw_engineering/README.md b/python/sw_engineering/README.md new file mode 100644 index 0000000..423c18b --- /dev/null +++ b/python/sw_engineering/README.md @@ -0,0 +1,54 @@ +Building a Library of Code you Trust +==================================== + +Suppose we're going to be dealing a lot with these animal count files, +and doing many different kinds of analysis with them. In the +introduction to Python lesson we wrote a function that reads these files +but it's stuck off in an IPython notebook. We could copy and paste it +into a new notebook every time we want to use it but that gets tedious +and makes it difficult to add features to the function. The ideal +solution would be to keep the function in one spot and use it over and +over again from many different places. Python modules to the rescue! + +We're going to move beyond the IPython notebook. Most Python code is +stored in `.py` files and then used in other `.py` files where it +has been pulled in using an `import` statement. Today we'll show you +how to do that. + +Exercises +========= + +Exercise 1 +---------- + +Make a new text file called `animals.py`. Copy the file reading +function from yesterday's IPython notebook into the file and modify it +so that it returns the columns of the file as lists (instead of printing +certain lines). + +Exercise 2 +---------- + +We're going to make a function to calculate the mean of all the values +in a list, but we're going to write the tests for it first. Make a new +text file called `test\_animals.py`. Make a function called +`test\_mean` that runs your theoretical mean function through several +tests. + +Exercise 3 +---------- + +Write the mean function in `animals.py` and verify that it passes your +tests. + +Exercise 4 +---------- + +Write tests for a function that will take a file name and animal name as +arguments, and return the average number of animals per sighting. + +Exercise 5 +---------- + +Write a function that takes a file name and animal name and returns the +average number of animals per sighting. Make sure it passes your tests. diff --git a/python/sw_engineering/README.rst b/python/sw_engineering/README.rst deleted file mode 100644 index 7f175b4..0000000 --- a/python/sw_engineering/README.rst +++ /dev/null @@ -1,54 +0,0 @@ -==================================== -Building a Library of Code you Trust -==================================== - -Suppose we're going to be dealing a lot with these animal count files, -and doing many different kinds of analysis with them. In the introduction -to Python lesson we wrote a function that reads these files but it's stuck -off in an IPython notebook. We could copy and paste it into a new notebook -every time we want to use it but that gets tedious and makes it difficult to -add features to the function. The ideal solution would be to keep the -function in one spot and use it over and over again from many different places. -Python modules to the rescue! - -We're going to move beyond the IPython notebook. Most Python code is -stored in `.py` files and then used in other `.py` files where it has been -pulled in using an `import` statement. Today we'll show you how to do that. - -========= -Exercises -========= - -Exercise 1 ----------- - -Make a new text file called `animals.py`. Copy the file reading -function from yesterday's IPython notebook into the file and modify it so -that it returns the columns of the file as lists (instead of printing -certain lines). - -Exercise 2 ----------- - -We're going to make a function to calculate the mean of all the -values in a list, but we're going to write the tests for it first. -Make a new text file called `test_animals.py`. Make a function called -`test_mean` that runs your theoretical mean function through several tests. - -Exercise 3 ----------- - -Write the mean function in `animals.py` and verify that it passes -your tests. - -Exercise 4 ----------- - -Write tests for a function that will take a file name and -animal name as arguments, and return the average number of animals per sighting. - -Exercise 5 ----------- - -Write a function that takes a file name and animal name and returns -the average number of animals per sighting. Make sure it passes your tests. diff --git a/python/sw_engineering/dev_notes.md b/python/sw_engineering/dev_notes.md new file mode 100644 index 0000000..123dff6 --- /dev/null +++ b/python/sw_engineering/dev_notes.md @@ -0,0 +1,87 @@ +Dev Notes +========= + +Things we want to demonstrate: + +- write lots of small tools (functions) +- document your code +- test your code, including TDD +- debugging + - build in a crash somewhere and explain tracebacks + - do an import pdb; pdb.set_trace() + +Create a few utilities to work with the `*animal.txt` files from +introductory Python. + +Put all the functionality in one file and make small scripts that import +from that file, parse command line arguments, and do stuff. + +- average number of an animal seen per sighting + +Students may want an IPython notebook open as a scratch pad. + +Lesson Plan +----------- + +We're going to make a command line script that will print the average +group size in a given file for a given animal. + +0. Discuss libraries and re-using code. +1. Demonstrate importing a module (maybe `math` or `glob`), then + demonstrate putting a function in a file and importing it. + + Exercise: Make a new text file called `animals.py`. Copy the file + reading function from yesterday's IPython notebook into the file and + modify it so that it returns the columns of the file as lists (instead + of printing certain lines). (They may want to develop the function in + the IPython notebook and then copy it over.) + +2. Go over the exercise and talk about documentation as you do. +3. How do we know the function works correctly? Try importing and + running it on a small file. +4. But what if we want to make changes and make sure it still works + afterward, or we want to make sure it isn't broken when we add new + stuff later? + - Demonstrate a potential test solution comparing output in an `if` and + printing a message if something doesn't match. + - Explain `assert` and demonstrate + - Explain unit tests and show how to run with nosetests. + +5. Explain test driven development. + Exercise: We're going to make a function to calculate the mean of all + the values in a list, but we're going to write the tests for it first. + Make a new text file called `test_animals.py`. Make a function called + `test_mean` that runs your theoretical mean function through several + tests. + +6. When going over this with the students, put in a test with an empty + list. Also put in tests with lists that contain all ints. + + Exercise: Write the mean function in `animals.py` and verify that it + passes your tests. + +7. When going over this with the students do not put in a test for an + empty list. The error when running the tests will give a chance to + teach tracebacks. Also do not put in any coercion to float so some + means will be wrong due to integer truncation. More debugging, + `--pdb-failure`. + +8. The last piece we'll need is a function that takes the output of the + file reader function and returns only the data relevant to a given + animal. Write this function as a live exercise with the students + participating, though they can do it on their own if they want. + + Exercise: Write tests for a function that will take a file name and + animal name as arguments, and return the average number of animals per + sighting. + + Exercise: Write a function that takes a file name and animal name and + returns the average number of animals per sighting. Make sure it passes + your tests. + +9. After going over exercises, conclude by showing how to make a + command line script that takes a file name and animal name as + arguments and prints the average number of animals per sighting. + +10. If time permits, could demonstrate `pdb.set_trace()` somewhere in + the script execution. diff --git a/python/sw_engineering/dev_notes.rst b/python/sw_engineering/dev_notes.rst deleted file mode 100644 index 4d86738..0000000 --- a/python/sw_engineering/dev_notes.rst +++ /dev/null @@ -1,83 +0,0 @@ -Dev Notes -========= - -Things we want to demonstrate: - -- write lots of small tools (functions) -- document your code -- test your code, including TDD -- debugging - - - build in a crash somewhere and explain tracebacks - - do an import pdb; pdb.set_trace() - -Create a few utilities to work with the `*animal.txt` files from -introductory Python. - -Put all the functionality in one file and make small scripts that import -from that file, parse command line arguments, and do stuff. - -- average number of an animal seen per sighting - -Students may want an IPython notebook open as a scratch pad. - -Lesson Plan ------------ - -We're going to make a command line script that will print the average group -size in a given file for a given animal. - -0. Discuss libraries and re-using code. -1. Demonstrate importing a module (maybe `math` or `glob`), then demonstrate - putting a function in a file and importing it. - -Exercise: Make a new text file called `animals.py`. Copy the file reading -function from yesterday's IPython notebook into the file and modify it so -that it returns the columns of the file as lists (instead of printing -certain lines). (They may want to develop the function in the IPython -notebook and then copy it over.) - -2. Go over the exercise and talk about documentation as you do. -3. How do we know the function works correctly? Try importing and running it - on a small file. -4. But what if we want to make changes and make sure it still works afterward, - or we want to make sure it isn't broken when we add new stuff later? - - - Demonstrate a potential test solution comparing output in an `if` and - printing a message if something doesn't match. - - Explain `assert` and demonstrate - - Explain unit tests and show how to run with nosetests. - -5. Explain test driven development. - -Exercise: We're going to make a function to calculate the mean of all the -values in a list, but we're going to write the tests for it first. -Make a new text file called `test_animals.py`. Make a function called -`test_mean` that runs your theoretical mean function through several tests. - -6. When going over this with the students, put in a test with an empty list. - Also put in tests with lists that contain all ints. - -Exercise: Write the mean function in `animals.py` and verify that it passes -your tests. - -7. When going over this with the students do not put in a test for an empty - list. The error when running the tests will give a chance to teach - tracebacks. Also do not put in any coercion to float so some means will - be wrong due to integer truncation. More debugging, `--pdb-failure`. -8. The last piece we'll need is a function that takes the output of the file - reader function and returns only the data relevant to a given animal. - Write this function as a live exercise with the students participating, - though they can do it on their own if they want. - -Exercise: Write tests for a function that will take a file name and -animal name as arguments, and return the average number of animals per sighting. - -Exercise: Write a function that takes a file name and animal name and returns -the average number of animals per sighting. Make sure it passes your tests. - -9. After going over exercises, conclude by showing how to make a command line - script that takes a file name and animal name as arguments and prints - the average number of animals per sighting. -10. If time permits, could demonstrate `pdb.set_trace()` somewhere in the - script execution. -- 2.26.2