Python Project Iteration Cheat Sheet

14.10. Python Project Iteration Cheat Sheet#

Script files#

To have some Python code that processes data or runs some task, the simplest method is to write a Python script file.

  1. Create a file with a .py extension, such as run_analysis.py.

  2. Add Python code to the file. Use sys.argv to access any input arguments. For example, you might write run_analysis.py to take in two arguments representing a data file to process and a results file to write to. If you run run_analysis.py data.csv results.csv, then in your Python script code, sys.argv[1] will be "data.csv" and sys.argv[2] will be "results.csv". Use those inputs to change how your script runs.

  3. Run the script using the python command. If you have a uv environment set up (which you do if there is a uv.sync file in your current directory), use uv run to make sure that the environment is used. For example, you could run uv run python run_analysis.py.

Installed script commands#

A more flexible solution is to install a new script command. This makes it so you can run Python code from the terminal without having to indicate the exact path to the file with the Python code. Instead, you just write the name of the installed command.

  1. In a Python module in your Python package, define a function that has the code you want to run. Use either sys.argv or Click to access any inputs you need from the user, such as the data file to process.

  2. In pyproject.toml, add a line to the [project.scripts] table indicating how your new command will be defined. For example, if you want to run a function called basic_analysis in the project.analysis module and make a command called analyze, you could add analyze = "project:analysis.basic_analysis".

  3. Run the command using the name that you defined in pyproject.toml. For example, you could run uv run analyze data.csv.

Using unit tests to ensure code correctness#

To test out different features of a Python project and make sure they run correctly, you can define unit tests using pytest.

  1. Create a directory in your main project directory called tests. Under the tests directory, add .py files that start with test. For example, you might have files named tests/test_data_cleaning.py and tests/test_analysis.py with test code.

  2. Add pytest as a development dependency for your project by running uv add --dev pytest in the terminal.

  3. Add functions whose names start with test to any of your test .py files. In each function, use assert statements to check if a given condition is true, and raise an error otherwise.

  4. To run all your tests, in the terminal run uv run pytest. It will try running all functions and let you know if any of the tests failed (that is, raised an error), and if so what code caused an error to be thrown.

  5. Rerun your tests periodically to check whether any bugs have been introduced by changes in your code or dependencies.

Debugging#

It can be frustrating when code isn’t working, but you aren’t sure why.

  1. Read the error message carefully. Make sure you read the whole message, as important information is sometimes shown at the end.

  2. Think carefully through what your code is doing. Do you understand each command? Would writing more comments help you to break down what is happening?

  3. If you are running complicated code, consider adding a breakpoint and running the code again. This will allow you to inspect the values of any variables, which may help you understand what is going wrong. IDEs usually have tools to help with debugging.

Contents