diff --git a/.github/ISSUE_TEMPLATE/issue_with_content.md b/.github/ISSUE_TEMPLATE/issue_with_content.md new file mode 100644 index 000000000..09d7ed751 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/issue_with_content.md @@ -0,0 +1,24 @@ +--- +name: Lesson content issue template +about: Let us about an issue you found with the material +title: '' +labels: +assignees: '' + +--- + +
+Instructions + +Thanks for taking the time to report an issue with the lesson! :heart: + +Please let us know about: + +- Technical issues or out of date screenshots and package/python versions +- Inconsistencies or errors in the material +- Missing references or links to external resources +- How material can be reworded to avoid confusion +- Problems with building or rendering the lesson material locally, with a concise step-by-step procedure to replicate the issue +- Any other issues + +
diff --git a/README.md b/README.md index 6888c702f..e7197543e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,7 @@ [![DOI](https://zenodo.org/badge/257930838.svg)](https://zenodo.org/badge/latestdoi/257930838) -``` -Note that the lesson material can change at any point - if you are planning a workshop using this material, -either let the maintainers know or make sure you use your own fork of the lesson. -``` +**Note that the lesson material can change at any point - if you are planning a workshop using this material, +either let the maintainers know or make sure you use your own fork of the lesson.** # Intermediate Research Software Development Skills In Python diff --git a/_episodes/10-section1-intro.md b/_episodes/10-section1-intro.md index e3efdddee..0c7b91409 100644 --- a/_episodes/10-section1-intro.md +++ b/_episodes/10-section1-intro.md @@ -52,7 +52,7 @@ and [`pip`](https://pip.pypa.io/en/stable/) to set up a Python virtual development environment and isolate our software project from other Python projects we may work on. -**Note:** *some Windows users experience the issue where Python hangs from Git Bash +***Note:** some Windows users experience the issue where Python hangs from Git Bash (i.e. typing `python` causes it to just hang with no error message or output) - [see the solution to this issue](../common-issues/index.html#python-hangs-in-git-bash).* diff --git a/_episodes/12-virtual-environments.md b/_episodes/12-virtual-environments.md index 2554d696c..e21c83a38 100644 --- a/_episodes/12-virtual-environments.md +++ b/_episodes/12-virtual-environments.md @@ -17,8 +17,8 @@ keypoints: - "Use `pip` to install and manage Python external (third-party) libraries." - "`pip` allows you to declare all dependencies for a project in a separate file (by convention called `requirements.txt`) which can be shared with collaborators/users and used to replicate a virtual environment." -- "Use `pip3 freeze > requirements.txt` to take snapshot of your project's dependencies." -- "Use `pip3 install -r requirements.txt` to replicate someone else's virtual environment on your machine from +- "Use `python3 -m pip freeze > requirements.txt` to take snapshot of your project's dependencies." +- "Use `python3 -m pip install -r requirements.txt` to replicate someone else's virtual environment on your machine from the `requirements.txt` file." --- @@ -196,6 +196,17 @@ From XKCD (Creative Commons Let us have a look at how we can create and manage virtual environments from the command line using `venv` and manage packages using `pip`. +> ## Making Sure You Can Invoke Python +> You can test your Python installation from the command line with: +> ~~~ +> $ python3 --version # on Mac/Linux +> $ python --version # on Windows — Windows installation comes with a python.exe file rather than a python3.exe file +> ~~~ +> {: .language-bash} +> If you are using Windows and invoking `python` command causes your Git Bash terminal to hang with no error message or output, you may +need to create an alias for the python executable `python.exe`, as explained in the [troubleshooting section](../common-issues/index.html#python-hangs-in-git-bash). +{: .prereq} + ### Creating Virtual Environments Using `venv` Creating a virtual environment with `venv` is done by executing the following command: @@ -209,6 +220,21 @@ conventionally within your software project so they are co-located. This will create the target directory for the virtual environment (and any parent directories that don’t exist already). +> ## What is `-m` Flag in `python3` Command? +> The Python `-m` flag means "module" and tells the Python interpreter to treat what follows `-m` +> as the name of a module and not as a single, executable program with the same name. +> Some modules (such as `venv` or `pip`) have main entry points +> and the `-m` flag can be used to invoke them on the command line via the `python` command. +> The main difference between running such modules as standalone programs +> (e.g. executing "venv" by running the `venv` command directly) +> versus using `python3 -m` command seems to be that +> with latter you are in full control of which Python module will be invoked +> (the one that came with your environment's Python interpreter vs. +> some other version you may have on your system). +> This makes it a more reliable way to set things up correctly +> and avoid issues that could prove difficult to trace and debug. +{: .callout} + For our project let's create a virtual environment called "venv". First, ensure you are within the project root directory, then: @@ -355,93 +381,87 @@ To install the latest version of a package with `pip` you use pip's `install` command and specify the package’s name, e.g.: ~~~ -(venv) $ pip3 install numpy -(venv) $ pip3 install matplotlib +(venv) $ python3 -m pip install numpy +(venv) $ python3 -m pip install matplotlib ~~~ {: .language-bash} or like this to install multiple packages at once for short: ~~~ -(venv) $ pip3 install numpy matplotlib +(venv) $ python3 -m pip install numpy matplotlib ~~~ {: .language-bash} -> ## How About `python3 -m pip install`? -> Why are we not using `pip` as an argument to `python3` command, -> in the same way we did with `venv` -> (i.e. `python3 -m venv`)? -> `python3 -m pip install` should be used according to the -> [official Pip documentation](https://pip.pypa.io/en/stable/user_guide/#running-pip); -> other official documentation still seems to have a mixture of usages. -> Core Python developer Brett Cannon offers a +> ## How About `pip3 install ` Command? +> You may have seen or used the `pip3 install ` command in the past, which is shorter +> and perhaps more intuitive than `python3 -m pip install`. However, the +> [official Pip documentation](https://pip.pypa.io/en/stable/user_guide/#running-pip) recommends +> `python3 -m pip install` and core Python developer Brett Cannon offers a > [more detailed explanation](https://snarky.ca/why-you-should-use-python-m-pip/) -> of edge cases when the two options may produce different results -> and recommends `python3 -m pip install`. -> We kept the old-style command (`pip3 install`) -> as it seems more prevalent among developers at the moment - -> but it may be a convention that will soon change and certainly something you should consider. +> of edge cases when the two commands may produce different results and why `python3 -m pip install` +> is recommended. In this material, we will use `python3 -m` whenever we have to invoke a Python +> module from command line. {: .callout} -If you run the `pip3 install` command on a package that is already installed, +If you run the `python3 -m pip install` command on a package that is already installed, `pip` will notice this and do nothing. To install a specific version of a Python package give the package name followed by `==` and the version number, -e.g. `pip3 install numpy==1.21.1`. +e.g. `python3 -m pip install numpy==1.21.1`. To specify a minimum version of a Python package, -you can do `pip3 install numpy>=1.20`. +you can do `python3 -m pip install numpy>=1.20`. -To upgrade a package to the latest version, e.g. `pip3 install --upgrade numpy`. +To upgrade a package to the latest version, e.g. `python3 -m pip install --upgrade numpy`. To display information about a particular installed package do: ~~~ -(venv) $ pip3 show numpy +(venv) $ python3 -m pip show numpy ~~~ {: .language-bash} ~~~ Name: numpy -Version: 1.21.2 -Summary: NumPy is the fundamental package for array computing with Python. -Home-page: https://www.numpy.org +Version: 1.26.2 +Summary: Fundamental package for array computing in Python +Home-page: https://numpy.org Author: Travis E. Oliphant et al. -Author-email: None -License: BSD -Location: /Users/alex/work/SSI/Carpentries/python-intermediate-inflammation/inflammation/lib/python3.9/site-packages -Requires: -Required-by: matplotlib +Author-email: +License: Copyright (c) 2005-2023, NumPy Developers. +All rights reserved. +... +Required-by: contourpy, matplotlib ~~~ {: .output} To list all packages installed with `pip` (in your current virtual environment): ~~~ -(venv) $ pip3 list +(venv) $ python3 -m pip list ~~~ {: .language-bash} ~~~ Package Version --------------- ------- -cycler 0.11.0 -fonttools 4.28.1 -kiwisolver 1.3.2 -matplotlib 3.5.0 -numpy 1.21.4 -packaging 21.2 -Pillow 8.4.0 -pip 21.1.3 -pyparsing 2.4.7 +contourpy 1.2.0 +cycler 0.12.1 +fonttools 4.45.0 +kiwisolver 1.4.5 +matplotlib 3.8.2 +numpy 1.26.2 +packaging 23.2 +Pillow 10.1.0 +pip 23.0.1 +pyparsing 3.1.1 python-dateutil 2.8.2 -setuptools 57.0.0 -setuptools-scm 6.3.2 +setuptools 67.6.1 six 1.16.0 -tomli 1.2.2 ~~~ {: .output} -To uninstall a package installed in the virtual environment do: `pip3 uninstall package-name`. +To uninstall a package installed in the virtual environment do: `python3 -m pip uninstall `. You can also supply a list of packages to uninstall at the same time. ### Exporting/Importing Virtual Environments Using `pip` @@ -453,27 +473,26 @@ and everyone can replicate equivalent virtual environments on their machines. `pip` has a handy way of exporting, saving and sharing virtual environments. To export your active environment - -use `pip3 freeze` command to produce a list of packages installed in the virtual environment. +use `python3 -m pip freeze` command to produce a list of packages installed in the virtual environment. A common convention is to put this list in a `requirements.txt` file: ~~~ -(venv) $ pip3 freeze > requirements.txt +(venv) $ python3 -m pip freeze > requirements.txt (venv) $ cat requirements.txt ~~~ {: .language-bash} ~~~ -cycler==0.11.0 -fonttools==4.28.1 -kiwisolver==1.3.2 -matplotlib==3.5.0 -numpy==1.21.4 -packaging==21.2 -Pillow==8.4.0 -pyparsing==2.4.7 +contourpy==1.2.0 +cycler==0.12.1 +fonttools==4.45.0 +kiwisolver==1.4.5 +matplotlib==3.8.2 +numpy==1.26.2 +packaging==23.2 +Pillow==10.1.0 +pyparsing==3.1.1 python-dateutil==2.8.2 -setuptools-scm==6.3.2 six==1.16.0 -tomli==1.2.2 ~~~ {: .output} @@ -489,7 +508,7 @@ They can then replicate your environment and install all the necessary packages from the project root as follows: ~~~ -(venv) $ pip3 install -r requirements.txt +(venv) $ python3 -m pip install -r requirements.txt ~~~ {: .language-bash} diff --git a/_episodes/13-ides.md b/_episodes/13-ides.md index d9c6b0c26..0d0b4a168 100644 --- a/_episodes/13-ides.md +++ b/_episodes/13-ides.md @@ -109,7 +109,7 @@ terminal (the command line within PyCharm) and a TODO list. Select the `inflammation-analysis.py` file in the project navigator on the left so that its contents are displayed in the editor window. You may notice a warning about the missing Python interpreter -at the top of the editor panelshowing `inflammation-analysis.py` file - +at the top of the editor panel showing `inflammation-analysis.py` file - this is one of the first things you will have to configure for your project before you can do any work. @@ -130,7 +130,7 @@ from the command line and PyCharm is clever enough to understand it. #### Adding a Python Interpreter -1. Select either `PyCharm` > `Preferences` (Mac) or `File` > `Settings` (Linux, Windows). +1. Select either `PyCharm` > `Settings` (Mac) or `File` > `Settings` (Linux, Windows). 2. In the preferences window that appears, select `Project: python-intermediate-inflammation` > `Python Interpreter` from the left. You'll see a number of Python packages displayed as a list, and importantly above that, @@ -139,8 +139,8 @@ and PyCharm is clever enough to understand it. or possibly the default version of Python installed on your system, e.g. `Python 2.7 /usr/bin/python2.7`, which we do not want to use in this instance. -3. Select the cog-like button in the top right, then `Add Local...` - (or `Add...` depending on your PyCharm version). +3. Select the cog-like button in the top right, then `Add...` + (or `Add Local...` depending on your PyCharm version). An `Add Python Interpreter` window will appear. 4. Select `Virtualenv Environment` from the list on the left and ensure that `Existing environment` checkbox is selected within the popup window. @@ -155,15 +155,15 @@ and PyCharm is clever enough to understand it. 5. Select `Make available to all projects` checkbox so we can also use this environment for other projects if we wish. 6. Select `OK` in the `Add Python Interpreter` window. - Back in the `Preferences` window, you should select "Python 3.9 (python-intermediate-inflammation)" + Back in the `Preferences` window, you should select "Python 3.11 (python-intermediate-inflammation)" or similar (that you've just added) from the `Project Interpreter` drop-down list. Note that a number of external libraries have magically appeared under the -"Python 3.9 (python-intermediate-inflammation)" interpreter, +"Python 3.11 (python-intermediate-inflammation)" interpreter, including `numpy` and `matplotlib`. PyCharm has recognised the virtual environment we created from the command line using `venv` and has added these libraries effectively replicating our virtual environment in PyCharm -(referred to as "Python 3.9 (python-intermediate-inflammation)"). +(referred to as "Python 3.11 (python-intermediate-inflammation)"). ![Packages Currently Installed in a Virtual Environment in PyCharm](../fig/pycharm-installed-packages.png){: .image-with-shadow width="800px"} @@ -183,110 +183,106 @@ Let's see this in action through the following exercise. >> ## Solution >> From the previous episode, >> you may remember that we can get the list of packages in the current virtual environment ->> using the `pip3 list` command: +>> using `pip`: >> ~~~ ->> (venv) $ pip3 list +>> (venv) $ python3 -m pip list >> ~~~ >> {: .language-bash} >> ~~~ ->> Package Version ->> --------------- ------- ->> cycler 0.11.0 ->> fonttools 4.28.1 ->> kiwisolver 1.3.2 ->> matplotlib 3.5.0 ->> numpy 1.21.4 ->> packaging 21.2 ->> Pillow 8.4.0 ->> pip 21.1.3 ->> pyparsing 2.4.7 ->> python-dateutil 2.8.2 ->> setuptools 57.0.0 ->> setuptools-scm 6.3.2 ->> six 1.16.0 ->> tomli 1.2.2 +Package Version +--------------- ------- +contourpy 1.2.0 +cycler 0.12.1 +fonttools 4.45.0 +kiwisolver 1.4.5 +matplotlib 3.8.2 +numpy 1.26.2 +packaging 23.2 +Pillow 10.1.0 +pip 23.0.1 +pyparsing 3.1.1 +python-dateutil 2.8.2 +setuptools 67.6.1 +six 1.16.0 >> ~~~ >> {: .output} ->> However, `pip3 list` shows all the packages in the virtual environment - +>> However, `python3 -m pip list` shows all the packages in the virtual environment - >> if we want to see only the list of packages that we installed, ->> we can use the `pip3 freeze` command instead: +>> we can use the `python3 -m pip freeze` command instead: >> ~~~ ->> (venv) $ pip3 freeze +>> (venv) $ python3 -m pip freeze >> ~~~ >> {: .language-bash} >> ~~~ ->> cycler==0.11.0 ->> fonttools==4.28.1 ->> kiwisolver==1.3.2 ->> matplotlib==3.5.0 ->> numpy==1.21.4 ->> packaging==21.2 ->> Pillow==8.4.0 ->> pyparsing==2.4.7 ->> python-dateutil==2.8.2 ->> setuptools-scm==6.3.2 ->> six==1.16.0 ->> tomli==1.2.2 +contourpy==1.2.0 +cycler==0.12.1 +fonttools==4.45.0 +kiwisolver==1.4.5 +matplotlib==3.8.2 +numpy==1.26.2 +packaging==23.2 +Pillow==10.1.0 +pyparsing==3.1.1 +python-dateutil==2.8.2 +six==1.16.0 >> ~~~ >> {: .output} ->> We see `pip` in `pip3 list` but not in `pip3 freeze` as we did not install it using `pip`. ->> Remember that we use `pip3 freeze` to update our `requirements.txt` file, +>> We see the `pip` package in `python3 -m pip list` but not in `python3 -m pip freeze` +>> as we did not install it using `pip`. +>> Remember that we use `python3 -m pip freeze` to update our `requirements.txt` file, >> to keep a list of the packages our virtual environment includes. >> Python will not do this automatically; >> we have to manually update the file when our requirements change using: >> ~~~ ->> pip3 freeze > requirements.txt +>> python3 -m pip freeze > requirements.txt >> ~~~ >> {: .language-bash} >> >> If we want, we can also see the list of packages directly in the following subdirectory of `venv`: >> ~~~ ->> (venv) $ ls -l venv/lib/python3.9/site-packages +>> (venv) $ ls -l venv/lib/python3.11/site-packages >> ~~~ >> {: .language-bash} >> >> ~~~ ->> total 1088 ->> drwxr-xr-x 103 alex staff 3296 17 Nov 11:55 PIL ->> drwxr-xr-x 9 alex staff 288 17 Nov 11:55 Pillow-8.4.0.dist-info ->> drwxr-xr-x 6 alex staff 192 17 Nov 11:55 __pycache__ ->> drwxr-xr-x 5 alex staff 160 17 Nov 11:53 _distutils_hack ->> drwxr-xr-x 8 alex staff 256 17 Nov 11:55 cycler-0.11.0.dist-info ->> -rw-r--r-- 1 alex staff 14519 17 Nov 11:55 cycler.py ->> drwxr-xr-x 14 alex staff 448 17 Nov 11:55 dateutil ->> -rw-r--r-- 1 alex staff 152 17 Nov 11:53 distutils-precedence.pth ->> drwxr-xr-x 31 alex staff 992 17 Nov 11:55 fontTools ->> drwxr-xr-x 9 alex staff 288 17 Nov 11:55 fonttools-4.28.1.dist-info ->> drwxr-xr-x 8 alex staff 256 17 Nov 11:55 kiwisolver-1.3.2.dist-info ->> -rwxr-xr-x 1 alex staff 216968 17 Nov 11:55 kiwisolver.cpython-39-darwin.so ->> drwxr-xr-x 92 alex staff 2944 17 Nov 11:55 matplotlib ->> -rw-r--r-- 1 alex staff 569 17 Nov 11:55 matplotlib-3.5.0-py3.9-nspkg.pth ->> drwxr-xr-x 20 alex staff 640 17 Nov 11:55 matplotlib-3.5.0.dist-info ->> drwxr-xr-x 7 alex staff 224 17 Nov 11:55 mpl_toolkits ->> drwxr-xr-x 39 alex staff 1248 17 Nov 11:55 numpy ->> drwxr-xr-x 11 alex staff 352 17 Nov 11:55 numpy-1.21.4.dist-info ->> drwxr-xr-x 15 alex staff 480 17 Nov 11:55 packaging ->> drwxr-xr-x 10 alex staff 320 17 Nov 11:55 packaging-21.2.dist-info ->> drwxr-xr-x 8 alex staff 256 17 Nov 11:53 pip ->> drwxr-xr-x 10 alex staff 320 17 Nov 11:53 pip-21.1.3.dist-info ->> drwxr-xr-x 7 alex staff 224 17 Nov 11:53 pkg_resources ->> -rw-r--r-- 1 alex staff 90 17 Nov 11:55 pylab.py ->> drwxr-xr-x 8 alex staff 256 17 Nov 11:55 pyparsing-2.4.7.dist-info ->> -rw-r--r-- 1 alex staff 273365 17 Nov 11:55 pyparsing.py ->> drwxr-xr-x 9 alex staff 288 17 Nov 11:55 python_dateutil-2.8.2.dist-info ->> drwxr-xr-x 41 alex staff 1312 17 Nov 11:53 setuptools ->> drwxr-xr-x 11 alex staff 352 17 Nov 11:53 setuptools-57.0.0.dist-info ->> drwxr-xr-x 19 alex staff 608 17 Nov 11:55 setuptools_scm ->> drwxr-xr-x 10 alex staff 320 17 Nov 11:55 setuptools_scm-6.3.2.dist-info ->> drwxr-xr-x 8 alex staff 256 17 Nov 11:55 six-1.16.0.dist-info ->> -rw-r--r-- 1 alex staff 34549 17 Nov 11:55 six.py ->> drwxr-xr-x 8 alex staff 256 17 Nov 11:55 tomli ->> drwxr-xr-x 7 alex staff 224 17 Nov 11:55 tomli-1.2.2.dist-info +total 88 +drwxr-xr-x 105 alex staff 3360 20 Nov 15:34 PIL +drwxr-xr-x 9 alex staff 288 20 Nov 15:34 Pillow-10.1.0.dist-info +drwxr-xr-x 4 alex staff 128 20 Nov 15:34 __pycache__ +drwxr-xr-x 5 alex staff 160 20 Nov 15:32 _distutils_hack +drwxr-xr-x 16 alex staff 512 20 Nov 15:34 contourpy +drwxr-xr-x 7 alex staff 224 20 Nov 15:34 contourpy-1.2.0.dist-info +drwxr-xr-x 5 alex staff 160 20 Nov 15:34 cycler +drwxr-xr-x 8 alex staff 256 20 Nov 15:34 cycler-0.12.1.dist-info +drwxr-xr-x 14 alex staff 448 20 Nov 15:34 dateutil +-rw-r--r-- 1 alex staff 151 20 Nov 15:32 distutils-precedence.pth +drwxr-xr-x 33 alex staff 1056 20 Nov 15:34 fontTools +drwxr-xr-x 9 alex staff 288 20 Nov 15:34 fonttools-4.45.0.dist-info +drwxr-xr-x 8 alex staff 256 20 Nov 15:34 kiwisolver +drwxr-xr-x 8 alex staff 256 20 Nov 15:34 kiwisolver-1.4.5.dist-info +drwxr-xr-x 150 alex staff 4800 20 Nov 15:34 matplotlib +drwxr-xr-x 20 alex staff 640 20 Nov 15:34 matplotlib-3.8.2.dist-info +drwxr-xr-x 5 alex staff 160 20 Nov 15:34 mpl_toolkits +drwxr-xr-x 43 alex staff 1376 20 Nov 15:34 numpy +drwxr-xr-x 9 alex staff 288 20 Nov 15:34 numpy-1.26.2.dist-info +drwxr-xr-x 18 alex staff 576 20 Nov 15:34 packaging +drwxr-xr-x 9 alex staff 288 20 Nov 15:34 packaging-23.2.dist-info +drwxr-xr-x 9 alex staff 288 20 Nov 15:32 pip +drwxr-xr-x 10 alex staff 320 20 Nov 15:33 pip-23.0.1.dist-info +drwxr-xr-x 6 alex staff 192 20 Nov 15:32 pkg_resources +-rw-r--r-- 1 alex staff 90 20 Nov 15:34 pylab.py +drwxr-xr-x 15 alex staff 480 20 Nov 15:34 pyparsing +drwxr-xr-x 7 alex staff 224 20 Nov 15:34 pyparsing-3.1.1.dist-info +drwxr-xr-x 9 alex staff 288 20 Nov 15:34 python_dateutil-2.8.2.dist-info +drwxr-xr-x 49 alex staff 1568 20 Nov 15:32 setuptools +drwxr-xr-x 10 alex staff 320 20 Nov 15:32 setuptools-67.6.1.dist-info +drwxr-xr-x 8 alex staff 256 20 Nov 15:34 six-1.16.0.dist-info +-rw-r--r-- 1 alex staff 34549 20 Nov 15:34 six.py >> ~~~ >> {: .output} >> >> Finally, if you look at both the contents of ->> `venv/lib/python3.9/site-packages` and `requirements.txt` +>> `venv/lib/python3.11/site-packages` and `requirements.txt` >> and compare that with the packages shown in PyCharm's Python Interpreter Configuration - >> you will see that they all contain equivalent information. > {: .solution} @@ -300,7 +296,7 @@ However, we will need library `pytest` soon to implement tests for our code. We will use this opportunity to install it from PyCharm in order to see an alternative way of doing this and how it propagates to the command line. -1. Select either `PyCharm` > `Preferences` (Mac) or `File` > `Settings` (Linux, Windows). +1. Select either `PyCharm` > `Settings` (Mac) or `File` > `Settings` (Linux, Windows). 2. In the preferences window that appears, select `Project: python-intermediate-inflammation` > `Project Interpreter` from the left. 3. Select the `+` icon at the top of the window. @@ -314,7 +310,7 @@ an alternative way of doing this and how it propagates to the command line. It may take a few minutes for PyCharm to install it. After it is done, the `pytest` library is added to our virtual environment. You can also verify this from the command line by -listing the `venv/lib/python3.9/site-packages` subdirectory. +listing the `venv/lib/python3.11/site-packages` subdirectory. Note, however, that `requirements.txt` is not updated - as we mentioned earlier this is something you have to do manually. Let's do this as an exercise. @@ -325,31 +321,28 @@ Let's do this as an exercise. >> Let's verify first that the newly installed library `pytest` is appearing in our virtual environment >> but not in `requirements.txt`. First, let's check the list of installed packages: >> ~~~ ->> (venv) $ pip3 list +>> (venv) $ python3 -m pip list >> ~~~ >> {: .language-bash} >> ~~~ ->> Package Version ->> --------------- ------- ->> attrs 21.4.0 ->> cycler 0.11.0 ->> fonttools 4.28.5 ->> iniconfig 1.1.1 ->> kiwisolver 1.3.2 ->> matplotlib 3.5.1 ->> numpy 1.22.0 ->> packaging 21.3 ->> Pillow 9.0.0 ->> pip 20.0.2 ->> pluggy 1.0.0 ->> py 1.11.0 ->> pyparsing 3.0.7 ->> pytest 6.2.5 ->> python-dateutil 2.8.2 ->> setuptools 44.0.0 ->> six 1.16.0 ->> toml 0.10.2 ->> tomli 2.0.0 +Package Version +--------------- ------- +contourpy 1.2.0 +cycler 0.12.1 +fonttools 4.45.0 +iniconfig 2.0.0 +kiwisolver 1.4.5 +matplotlib 3.8.2 +numpy 1.26.2 +packaging 23.2 +Pillow 10.1.0 +pip 23.0.1 +pluggy 1.3.0 +pyparsing 3.1.1 +pytest 7.4.3 +python-dateutil 2.8.2 +setuptools 67.6.1 +six 1.16.0 >> ~~~ >> {: .output} >> We can see the `pytest` library appearing in the listing above. However, if we do: @@ -358,45 +351,40 @@ Let's do this as an exercise. >> ~~~ >> {: .language-bash} >> ~~~ ->> cycler==0.11.0 ->> fonttools==4.28.1 ->> kiwisolver==1.3.2 ->> matplotlib==3.5.0 ->> numpy==1.21.4 ->> packaging==21.2 ->> Pillow==8.4.0 ->> pyparsing==2.4.7 ->> python-dateutil==2.8.2 ->> setuptools-scm==6.3.2 ->> six==1.16.0 ->> tomli==1.2.2 +contourpy==1.2.0 +cycler==0.12.1 +fonttools==4.45.0 +kiwisolver==1.4.5 +matplotlib==3.8.2 +numpy==1.26.2 +packaging==23.2 +Pillow==10.1.0 +pyparsing==3.1.1 +python-dateutil==2.8.2 +six==1.16.0 >> ~~~ >> {: .output} >> `pytest` is missing from `requirements.txt`. To add it, we need to update the file by repeating the command: >> ~~~ ->> (venv) $ pip3 freeze > requirements.txt +>> (venv) $ python3 -m pip freeze > requirements.txt >> ~~~ >> {: .language-bash} >> `pytest` is now present in `requirements.txt`: >> ~~~ ->> attrs==21.2.0 ->> cycler==0.11.0 ->> fonttools==4.28.1 ->> iniconfig==1.1.1 ->> kiwisolver==1.3.2 ->> matplotlib==3.5.0 ->> numpy==1.21.4 ->> packaging==21.2 ->> Pillow==8.4.0 ->> pluggy==1.0.0 ->> py==1.11.0 ->> pyparsing==2.4.7 ->> pytest==6.2.5 ->> python-dateutil==2.8.2 ->> setuptools-scm==6.3.2 ->> six==1.16.0 ->> toml==0.10.2 ->> tomli==1.2.2 +contourpy==1.2.0 +cycler==0.12.1 +fonttools==4.45.0 +iniconfig==2.0.0 +kiwisolver==1.4.5 +matplotlib==3.8.2 +numpy==1.26.2 +packaging==23.2 +Pillow==10.1.0 +pluggy==1.3.0 +pyparsing==3.1.1 +pytest==7.4.3 +python-dateutil==2.8.2 +six==1.16.0 >> ~~~ > {: .solution} {: .challenge} @@ -413,7 +401,7 @@ This is done by adding a **Run Configuration** to a project: and find and select `inflammation-analysis.py`. This tells PyCharm which script to run (i.e. what the main entry point to our application is). ![Run Configuration Popup in PyCharm](../fig/pycharm-run-configuration-popup.png){: .image-with-shadow width="800px" } -4. In the same window, select "Python 3.9 (python-intermediate-inflammation)" +4. In the same window, select "Python 3.11 (python-intermediate-inflammation)" (i.e. the virtual environment and interpreter you configured earlier in this episode) in the `Python interpreter` field. 5. You can give this run configuration a name at the top of the window if you like - @@ -431,9 +419,9 @@ This is done by adding a **Run Configuration** to a project: > but with different external libraries - > this is helpful when you need to develop different types of applications. > For example, you can create one virtual environment -> based on Python 3.9 to develop Django Web applications +> based on Python 3.11 to develop Django Web applications > and another virtual environment -> based on the same Python 3.9 to work with scientific libraries. +> based on the same Python 3.11 to work with scientific libraries. > > **Run Configurations** in PyCharm are named sets of startup properties > that define what to execute and what parameters @@ -490,7 +478,7 @@ including: type definition of variables, fields or any other symbols - Quick Documentation - inline documentation ([*docstrings*](../15-coding-conventions/index.html#documentation-strings-aka-docstrings) - for any symbol created in accordance with [PEP-257](https://peps.python.org/pep-0257/) + for any symbol created in accordance with [PEP-257](https://peps.python.org/pep-0257/)) - Parameter Info - the names and expected types of parameters in method and function calls. Use this when cursor is on the argument of a function call. diff --git a/_episodes/14-collaboration-using-git.md b/_episodes/14-collaboration-using-git.md index 642ed2cba..1adc31c0b 100644 --- a/_episodes/14-collaboration-using-git.md +++ b/_episodes/14-collaboration-using-git.md @@ -448,7 +448,7 @@ Let's make a small modification to `inflammation/models.py` in PyCharm, and, say, change the spelling of "2d" to "2D" in docstrings for functions `daily_mean()`, `daily_max()` and -`daily_min()`. +`daily_min()` to see updating branches in action. If we do: diff --git a/_episodes/15-coding-conventions.md b/_episodes/15-coding-conventions.md index 3b94d62ae..a30d9cbeb 100644 --- a/_episodes/15-coding-conventions.md +++ b/_episodes/15-coding-conventions.md @@ -628,7 +628,7 @@ The docstring for a function or a module is returned when calling the `help` function and passing its name - for example from the interactive Python console/terminal available from the command line or when rendering code documentation online -(e.g. see [Python documentation](https://docs.python.org/3.8/library/index.html)). +(e.g. see [Python documentation](https://docs.python.org/3.11/library/index.html)). PyCharm also displays the docstring for a function/module in a little help popup window when using tab-completion. diff --git a/_episodes/16-verifying-code-style-linters.md b/_episodes/16-verifying-code-style-linters.md index e30c42f5e..adf314c8d 100644 --- a/_episodes/16-verifying-code-style-linters.md +++ b/_episodes/16-verifying-code-style-linters.md @@ -34,23 +34,14 @@ $ git switch style-fixes Pylint is just a Python package so we can install it in our virtual environment using: ~~~ -$ pip3 install pylint -$ pylint --version +$ python3 -m pip install pylint ~~~ {: .language-bash} -We should see the version of Pylint, something like: - -~~~ -pylint 2.13.3 -... -~~~ -{: .output} - We should also update our `requirements.txt` with this new addition: ~~~ -$ pip3 freeze > requirements.txt +$ python3 -m pip freeze > requirements.txt ~~~ {: .language-bash} diff --git a/_episodes/21-automatically-testing-software.md b/_episodes/21-automatically-testing-software.md index 6456d63a2..be5e68829 100644 --- a/_episodes/21-automatically-testing-software.md +++ b/_episodes/21-automatically-testing-software.md @@ -89,8 +89,7 @@ a common term we use to refer to sets of tests - that we'll use for our test wri ~~~ $ git switch develop -$ git branch test-suite -$ git switch test-suite +$ git branch -c test-suite ~~~ {: .language-bash} @@ -435,7 +434,7 @@ but what you learn can scale to more complex functional testing for applications > > A common challenge, particularly at the intermediate level, is the selection of a suitable tool from many alternatives > for a given task. Once you've become accustomed to object-oriented programming you may find unittest a better fit -> for a particular project or team, so you may want to revisit it at a later date! +> for a particular project or team, so you may want to revisit it at a later date. {: .callout} @@ -457,7 +456,7 @@ exit the Python console first (either with `Ctrl-D` or by typing `exit()`), then do: ~~~ -$ pip3 install pytest +$ python3 -m pip install pytest ~~~ {: .language-bash} @@ -471,38 +470,37 @@ our virtual environment will now have the `pytest` package installed for use. Now we can run these tests using `pytest`: ~~~ -$ python -m pytest tests/test_models.py +$ python3 -m pytest tests/test_models.py ~~~ {: .language-bash} -Here, we use `-m` to invoke the `pytest` installed module, +Here, we use `-m` flag of the `python3` command to invoke the `pytest` module, and specify the `tests/test_models.py` file to run the tests in that file explicitly. -> ## Why Run Pytest Using `python -m` and Not `pytest` ? +> ## Why Run Pytest Using `python3 -m pytest` and Not `pytest`? > -> Another way to run `pytest` is via its own command, -> so we *could* try to use `pytest tests/test_models.py` on the command line instead, -> but this would lead to a `ModuleNotFoundError: No module named 'inflammation'`. -> This is because using the `python -m pytest` method -> adds the current directory to its list of directories to search for modules, -> whilst using `pytest` does not - -> the `inflammation` subdirectory's contents are not 'seen', -> hence the `ModuleNotFoundError`. -> There are ways to get around this with -> [various methods](https://stackoverflow.com/questions/71297697/modulenotfounderror-when-running-a-simple-pytest), -> but we've used `python -m` for simplicity. +> `pytest` is another Python module that can be run via its own command but this is a good example +> why invoking Python modules via `python3 -m` may be better (recall the [explanation of Python interpreter's `-m` flag](../12-virtual-environments/index.html#what-is--m-flag-in-python3-command)). +> Had we used `pytest tests/test_models.py` command directly, +> this would have led to a "ModuleNotFoundError: No module named 'inflammation'" error. This is +> because `pytest` command (unlike `python3 -m pytest`) does not add the current directory to its list of +> directories to search for modules, hence the `inflammation` subdirectory's contents are not being +> 'seen' by `pytest` causing the `ModuleNotFoundError`. There are ways to work around this problem +> but `python3 -m pytest` ensures it does not happen in the first place. +> +> {: .callout} ~~~ -============================================== test session starts ===================================================== -platform darwin -- Python 3.9.6, pytest-6.2.5, py-1.11.0, pluggy-1.0.0 -rootdir: /Users/alex/python-intermediate-inflammation -plugins: anyio-3.3.4 -collected 2 items +============================================== test session starts ================================= +platform darwin -- Python 3.11.4, pytest-7.4.3, pluggy-1.3.0 +rootdir: /Users/alex/work/SSI/training/lessons/python-intermediate-inflammation +plugins: anyio-4.0.0 +collected 2 items -tests/test_models.py .. [100%] +tests/test_models.py .. [100%] -=============================================== 2 passed in 0.79s ====================================================== +=============================================== 2 passed in 0.79s ================================== ~~~ {: .output} @@ -516,8 +514,8 @@ Notice the `..` after our test script: The error is included in the output so we can see what went wrong. So if we have many tests, we essentially get a report indicating which tests succeeded or failed. -Going back to our list of requirements (the bullets under [Using a Testing -Framework](#using-a-testing-framework)), +Going back to our list of requirements (the bullet points under [Using a Testing +Framework](#using-a-testing-framework) section), do we think these results are easy to understand? > ## Exercise: Write Some Unit Tests @@ -604,7 +602,7 @@ Since we've installed `pytest` to our environment, we should also regenerate our `requirements.txt`: ~~~ -$ pip3 freeze > requirements.txt +$ python3 -m pip freeze > requirements.txt ~~~ {: .language-bash} diff --git a/_episodes/22-scaling-up-unit-testing.md b/_episodes/22-scaling-up-unit-testing.md index 0c537673c..b8b6df58a 100644 --- a/_episodes/22-scaling-up-unit-testing.md +++ b/_episodes/22-scaling-up-unit-testing.md @@ -143,13 +143,12 @@ so that we force the code we're testing to execute in all the different ways it to ensure our tests have a high degree of **code coverage**. A simple way to check the code coverage for a set of tests is -to use `pytest` to tell us how many statements in our code are being tested. -By installing a Python package to our virtual environment called `pytest-cov` -that is used by Pytest and using that, we can find this out: +to install an additional package `pytest-cov` to our virtual environment, +which is used by `pytest` to tell us how many statements in our code are being tested. ~~~ -$ pip3 install pytest-cov -$ python -m pytest --cov=inflammation.models tests/test_models.py +$ python3 -m pip install pytest-cov +$ python3 -m pytest --cov=inflammation.models tests/test_models.py ~~~ {: .language-bash} @@ -158,14 +157,14 @@ specifying the code to analyse for test coverage. ~~~ ============================= test session starts ============================== -platform darwin -- Python 3.9.6, pytest-6.2.5, py-1.11.0, pluggy-1.0.0 -rootdir: /Users/alex/python-intermediate-inflammation -plugins: anyio-3.3.4, cov-3.0.0 -collected 9 items +platform darwin -- Python 3.11.4, pytest-7.4.3, pluggy-1.3.0 +rootdir: /Users/alex/work/SSI/training/lessons/python-intermediate-inflammation +plugins: cov-4.1.0 +collected 9 items tests/test_models.py ......... [100%] ----------- coverage: platform darwin, python 3.9.6-final-0 ----------- +---------- coverage: platform darwin, python 3.11.4-final-0 ---------- Name Stmts Miss Cover -------------------------------------------- inflammation/models.py 9 1 89% @@ -182,7 +181,7 @@ But which statements are not being tested? The additional argument `--cov-report term-missing` can tell us: ~~~ -$ python -m pytest --cov=inflammation.models --cov-report term-missing tests/test_models.py +$ python3 -m pytest --cov=inflammation.models --cov-report term-missing tests/test_models.py ~~~ {: .language-bash} @@ -212,7 +211,7 @@ Again, we should also update our `requirements.txt` file with our latest package which now also includes `pytest-cov`, and commit it: ~~~ -$ pip3 freeze > requirements.txt +$ python3 -m pip freeze > requirements.txt $ cat requirements.txt ~~~ {: .language-bash} diff --git a/_episodes/23-continuous-integration-automated-testing.md b/_episodes/23-continuous-integration-automated-testing.md index fb4228727..c4cbd8573 100644 --- a/_episodes/23-continuous-integration-automated-testing.md +++ b/_episodes/23-continuous-integration-automated-testing.md @@ -175,7 +175,7 @@ This directory is used specifically for GitHub Actions, allowing us to specify any number of workflows that can be run under a variety of conditions, which is also written using YAML. So let's add a new YAML file called `main.yml` -(note it's extension is `.yml` without the `a`) +(note its extension is `.yml` without the `a`) within the new `.github/workflows` directory: ~~~ @@ -200,23 +200,23 @@ jobs: - name: Checkout repository uses: actions/checkout@v2 - - name: Set up Python 3.9 + - name: Set up Python 3.11 uses: actions/setup-python@v2 with: - python-version: "3.9" + python-version: "3.11" - name: Install Python dependencies run: | python3 -m pip install --upgrade pip - pip3 install -r requirements.txt + python3 -m pip install -r requirements.txt - name: Test with PyTest run: | - python -m pytest --cov=inflammation.models tests/test_models.py + python3 -m pytest --cov=inflammation.models tests/test_models.py ~~~ {: .language-yaml} -**Note:** *be sure to create this file as `main.yml` +***Note**: be sure to create this file as `main.yml` within the newly created `.github/workflows` directory, or it won't work!* @@ -240,8 +240,8 @@ Each of these steps are: - **Checkout repository for the job:** `uses` indicates that want to use a GitHub Action called `checkout` that does this -- **Set up Python 3.9:** - here we use the `setup-python` Action, indicating that we want Python version 3.9. +- **Set up Python version:** + here we use the `setup-python` Action, indicating that we want Python version 3.11. Note we specify the version within quotes, to ensure that this is interpreted as a complete string. Otherwise, if we wanted to test against for example Python 3.10, @@ -253,9 +253,9 @@ Each of these steps are: In order to locally install our `inflammation` package it's good practice to upgrade the version of pip that is present first, then we use pip to install our package dependencies. - Once installed, we can use `pip3 install -e .` as before to install our own package. + Once installed, we can use `python3 -m pip install -e .` as before to install our own package. We use `run` here to run theses commands in the CI shell environment -- **Test with PyTest:** lastly, we run `python -m pytest`, +- **Test with PyTest:** lastly, we run `python3 -m pytest`, with the same arguments we used manually before > ## What about other Actions? @@ -339,7 +339,7 @@ we can use a feature called **build matrices** which really shows the value of using CI to test at scale. Suppose the intended users of our software use either Ubuntu, Mac OS, or Windows, -and either have Python version 3.8, 3.9 or 3.10 installed, +and either have Python version 3.10 or 3.11 installed, and we want to support all of these. Assuming we have a suitable test suite, it would take a considerable amount of time to set up testing platforms @@ -364,7 +364,7 @@ So, our `.github/workflows/main.yml` should look like the following: strategy: matrix: os: [ubuntu-latest, macos-latest, windows-latest] - python-version: ["3.8", "3.9", "3.10"] + python-version: ["3.10", "3.11"] runs-on: {% raw %}${{ matrix.os }}{% endraw %} @@ -388,9 +388,9 @@ So, our `.github/workflows/main.yml` should look like the following: The `{% raw %}${{ }}{% endraw %}` are used as a means to reference configuration values from the matrix. -This way, every possible permutation of Python versions 3.8, 3.9, and 3.10 +This way, every possible permutation of Python versions 3.10 and 3.11 with the latest versions of Ubuntu, Mac OS and Windows operating systems -will be tested and we can expect 9 build jobs in total. +will be tested and we can expect 6 build jobs in total. Let's commit and push this change and see what happens: diff --git a/_episodes/24-diagnosing-issues-improving-robustness.md b/_episodes/24-diagnosing-issues-improving-robustness.md index 66446eda4..172021bb7 100644 --- a/_episodes/24-diagnosing-issues-improving-robustness.md +++ b/_episodes/24-diagnosing-issues-improving-robustness.md @@ -58,9 +58,9 @@ def patient_normalise(data): ~~~ {: .language-python} -**Note:** *there are intentional mistakes in the above code, +***Note:** there are intentional mistakes in the above code, which will be detected by further testing and code style checking below -so bear with us for the moment!* +so bear with us for the moment.* In the code above, we first go row by row and find the maximum inflammation value for each patient diff --git a/_episodes/32-software-design.md b/_episodes/32-software-design.md index 18dbe2ae7..292de8146 100644 --- a/_episodes/32-software-design.md +++ b/_episodes/32-software-design.md @@ -129,7 +129,7 @@ Let's recall the solution requirements we discussed in the previous episode: - *Functional Requirements*: - SR1.1.1 (from UR1.1): - add standard deviation to data model and include in graph visualisation view + add daily standard deviation to the data model and include in graph visualisation view - SR1.2.1 (from UR1.2): add a new view to generate a textual representation of statistics, which is invoked by an optional command line argument @@ -194,17 +194,17 @@ but also what you can do to make that code amenable to that type of testing. > Also make sure you push changes to your new feature branch remotely > to your software repository on GitHub. > -> **Note: do not add the tests for the new feature just yet - +> ***Note:** do not add the tests for the new feature just yet - > even though you would normally add the tests along with the new code, > we will do this in a later episode. -> Equally, do not merge your changes to the `develop` branch just yet.** +> Equally, do not merge your changes to the `develop` branch just yet.* > -> **Note 2: we have intentionally left this exercise without a solution +> ***Note 2:** we have intentionally left this exercise without a solution > to give you more freedom in implementing it how you see fit. > If you are struggling with adding a new view and command line parameter, -> you may find the standard deviation requirement easier. +> you may find adding the daily standard deviation requirement easier. > A later episode in this section will look at -> how to handle command line parameters in a scalable way.** +> how to handle command line parameters in a scalable way.* {: .challenge} ## Best Practices for 'Good' Software Design diff --git a/_episodes/34-functional-programming.md b/_episodes/34-functional-programming.md index 750a0e235..24bf78086 100644 --- a/_episodes/34-functional-programming.md +++ b/_episodes/34-functional-programming.md @@ -95,14 +95,14 @@ def factorial(n): ~~~ {: .language-python} -Note: You may have noticed that both functions in the above code examples have the same signature +***Note:** You may have noticed that both functions in the above code examples have the same signature (i.e. they take an integer number as input and return its factorial as output). You could easily swap these equivalent implementations without changing the way that the function is invoked. Remember, a single piece of software may well contain instances of multiple programming paradigms - including procedural, functional and object-oriented - it is up to you to decide which one to use and when to switch -based on the problem at hand and your personal coding style. +based on the problem at hand and your personal coding style.* Functional computations only rely on the values that are provided as inputs to a function and not on the state of the program that precedes the function call. @@ -338,10 +338,10 @@ print(list(result)) > > ~~~ > > {: .language-python} > > -> > Note: `map()` function returns a map iterator object +> > ***Note:** `map()` function returns a map iterator object > > which needs to be converted to a collection object > > (such as a list, dictionary, set, tuple) -> > using the corresponding "factory" function (in our case `list()`). +> > using the corresponding "factory" function (in our case `list()`).* > {: .solution} {: .challenge} diff --git a/_episodes/41-code-review.md b/_episodes/41-code-review.md index 0637666f4..b839ed051 100644 --- a/_episodes/41-code-review.md +++ b/_episodes/41-code-review.md @@ -323,7 +323,7 @@ compared to that of personal repositories. > for the feature that was implemented in your shared repository. > Implement tests against the appropriate specification in your local feature branch. > -> *Note: Try not to not fall into the trap of +> ***Note:** Try not to not fall into the trap of > writing the tests to test the existing code/implementation - > you should write the tests to make sure the code satisfies the requirements > regardless of the actual implementation. diff --git a/_episodes/43-software-release.md b/_episodes/43-software-release.md index d85275c47..68bb6154f 100644 --- a/_episodes/43-software-release.md +++ b/_episodes/43-software-release.md @@ -57,7 +57,7 @@ We can install Poetry much like any other Python distributable package, using `p ~~~ $ source venv/bin/activate -$ pip3 install poetry +$ python3 -m pip install poetry ~~~ {: .language-bash} @@ -123,7 +123,7 @@ Version [0.1.0]: 1.0.0 Description []: Analyse patient inflammation data Author [None, n to skip]: James Graham License []: MIT -Compatible Python versions [^3.8]: ^3.8 +Compatible Python versions [^3.11]: ^3.11 Would you like to define your main dependencies interactively? (yes/no) [yes] no Would you like to define your development dependencies interactively? (yes/no) [yes] no @@ -137,7 +137,7 @@ authors = ["James Graham "] license = "MIT" [tool.poetry.dependencies] -python = "^3.8" +python = "^3.11" [tool.poetry.dev-dependencies] @@ -248,7 +248,7 @@ you don't need to run this command yourself, you've already installed it using `poetry install` above. ~~~ -$ pip3 install dist/inflammation*.whl +$ python3 -m pip install dist/inflammation*.whl ~~~ {: .language-bash} diff --git a/_extras/common-issues.md b/_extras/common-issues.md index 82ebe7817..2aa1adaf5 100644 --- a/_extras/common-issues.md +++ b/_extras/common-issues.md @@ -13,10 +13,20 @@ Hanging issues with trying to run Python 3 in Git Bash on Windows The solution appears to be to use `winpty` - a Windows software package providing an interface similar to a Unix pty-master for communicating with Windows command line tools. -Inside the shell type `alias python='winpty python.exe'`. +Inside the shell type: + +~~~ +$ alias python="winpty python.exe" +~~~ +{: .language-bash} + This alias will be valid for the duration of the shell session. For a more permanent solution, from the shell do: -`echo "alias python='winpty python.exe'" >> ~/.bashrc` +~~~ +$ echo "alias python='winpty python.exe'" >> ~/.bashrc +~~~ +{: .language-bash} + (and from there on remember to invoke Python as `python` or whatever command you aliased it to). Read more details on the issue at @@ -163,7 +173,7 @@ In order to get `pip` to use the proxy, you need to add an additional parameter when installing packages with `pip`: ~~~ -$ pip3 install --proxy ` +$ python3 -m pip install --proxy ` ~~~ {: .language-bash} @@ -207,7 +217,7 @@ A workaround is to: - Close PyCharm - Downgrade the version of `pip` used by `venv`, e.g. in a command line terminal type: ~~~ - $ pip3 install pip==20.2.4 + $ python3 -m pip install pip==20.2.4 ~~~ {: .language-bash} - Restart PyCharm diff --git a/_extras/databases.md b/_extras/databases.md index b4bc67a65..829dcdaba 100644 --- a/_extras/databases.md +++ b/_extras/databases.md @@ -75,7 +75,7 @@ which contains an **Object Relational Mapping** (ORM) framework. Our first step is to install SQLAlchemy, then we can create our first **mapping**. ``` -$ pip3 install sqlalchemy +$ python3 -m pip install sqlalchemy ``` {: .language-bash} diff --git a/_extras/vscode.md b/_extras/vscode.md index 6796e7088..5165fdbdb 100644 --- a/_extras/vscode.md +++ b/_extras/vscode.md @@ -147,7 +147,7 @@ since then you will be able to run them from the terminal as well. For example, if you want `pylint` and `black` packages, execute the following from the terminal: ~~~bash -$ pip3 install pylint black +$ python3 -m pip install pylint black ~~~ They will now both be available to run as command line applications, diff --git a/fig/ci-ga-build-matrix.png b/fig/ci-ga-build-matrix.png index 88cc92fd8..c92ac0cdc 100644 Binary files a/fig/ci-ga-build-matrix.png and b/fig/ci-ga-build-matrix.png differ diff --git a/fig/ci-initial-ga-build-details.png b/fig/ci-initial-ga-build-details.png index fb86428a1..de7437d99 100644 Binary files a/fig/ci-initial-ga-build-details.png and b/fig/ci-initial-ga-build-details.png differ diff --git a/fig/ci-initial-ga-build-log.png b/fig/ci-initial-ga-build-log.png index 28bfc7a40..ef160505e 100644 Binary files a/fig/ci-initial-ga-build-log.png and b/fig/ci-initial-ga-build-log.png differ diff --git a/fig/ci-initial-ga-build.png b/fig/ci-initial-ga-build.png index 637abd966..0ed6c4324 100644 Binary files a/fig/ci-initial-ga-build.png and b/fig/ci-initial-ga-build.png differ diff --git a/fig/pycharm-configuring-interpreter.png b/fig/pycharm-configuring-interpreter.png index 14425ee0b..e36d96c27 100644 Binary files a/fig/pycharm-configuring-interpreter.png and b/fig/pycharm-configuring-interpreter.png differ diff --git a/fig/pycharm-installed-packages.png b/fig/pycharm-installed-packages.png index 28950f68b..2940de150 100644 Binary files a/fig/pycharm-installed-packages.png and b/fig/pycharm-installed-packages.png differ diff --git a/fig/pycharm-missing-python-interpreter.png b/fig/pycharm-missing-python-interpreter.png index 52a04ae50..17673de22 100644 Binary files a/fig/pycharm-missing-python-interpreter.png and b/fig/pycharm-missing-python-interpreter.png differ diff --git a/fig/pycharm-run-configuration-popup.png b/fig/pycharm-run-configuration-popup.png index 0f021b8d2..a51b7fccc 100644 Binary files a/fig/pycharm-run-configuration-popup.png and b/fig/pycharm-run-configuration-popup.png differ diff --git a/index.md b/index.md index cf7d21a0a..181982246 100644 --- a/index.md +++ b/index.md @@ -72,10 +72,22 @@ This course is for you if: and those of individual episodes - The software you write is fully documented and well architected +> ## Learning Objectives +> After going through this course, participants will be able to: +> - Set up and use a suitable development environment +together with popular source code management infrastructure to develop software collaboratively +> - Use a test framework to automate the verification of correct behaviour of code, +and employ parameterisation and continuous integration to scale and further automate code testing +> - Design robust, extensible software through the application of suitable programming paradigms +and design techniques +> - Understand the code review process and employ it to improve the quality of code +> - Prepare and release software for reuse by others +> - Manage software improvement from feedback through agile techniques +{: .objectives } + > ## Prerequisites -> To attend this course you should meet the following criteria. -> You can also test your prerequisite knowledge by taking -> [this short quiz](quiz/index.html). +> Before joining this training, participants should meet the following criteria. +> (You can use [this short quiz](quiz/index.html) to test your prerequisite knowledge.) > > #### Git > - **You are familiar with the concept of version control** @@ -98,20 +110,6 @@ This course is for you if: > - Optionally, you have experience redirecting inputs and outputs from a command {: .prereq} -> ## Learning Objectives for the Workshop -> - Set up and use a suitable development environment -> together with popular source code management infrastructure to develop software collaboratively -> - Use a test framework to automate the verification of correct behaviour of code, -> and employ parameterisation and continuous integration -> to scale and further automate your testing -> - Design robust, extensible software -> through the application of suitable programming paradigms and design techniques -> - Understand the code review process -> and employ it to improve the quality of code -> - Prepare and release your software for reuse by others -> - Manage software improvement from feedback through agile techniques -{: .objectives } - > ## Setup > Please make sure that you have all the necessary software and accounts setup ahead of the workshop > as described in the [Setup](./setup.html) section. diff --git a/setup.md b/setup.md index a10582ac8..35f76593e 100644 --- a/setup.md +++ b/setup.md @@ -201,22 +201,25 @@ your access token. {: .callout} ## Python Distribution -The material has been developed using the [standard Python distribution version 3.8](https://www.python.org/downloads/) -and is using `venv` for virtual environments and `pip` for package management. +The material has been tested using the standard Python distribution version 3.11. The course is using `venv` for virtual +environment management and `pip` for package management. The material has not been extensively tested with other Python distributions and package managers, but most sections are expected to work with some modifications. For example, package installation and virtual environments would need to be managed differently, but Python script invocations should remain the same regardless of the Python distribution used. -To download a Python distribution for your operating system, +To download the latest Python distribution for your operating system, please head to [Python.org](https://www.python.org/downloads/). If you are on Linux, it is likely that the system Python already installed will satisfy the requirements of this course. Check its version using the commands below. >## Recommended Python Version -> We recommend using at least Python version 3.8+ but any [supported version](https://devguide.python.org/versions/#versions) should work (i.e. version 3.7 onward. -> Specifically, we recommend upgrading from Python 2.7 wherever possible; continuing to use it will likely result in difficulty finding supported dependencies or syntax errors). +> We recommend using the latest Python version but any [supported version](https://devguide.python.org/versions/#versions) +> should work. +> Specifically, we recommend upgrading from Python 2.7 wherever possible; +> continuing to use it will likely result in difficulty finding supported dependencies or +> syntax errors. {: .callout} You can @@ -226,9 +229,13 @@ $ python3 --version # on Mac/Linux $ python --version # on Windows — Windows installation comes with a python.exe file rather than a python3.exe file ~~~ {: .language-bash} + +If you are using Windows and invoking `python` command causes your Git Bash terminal to hang with no error message or output, you may +need to create an alias for the python executable `python.exe`, as explained in the [troubleshooting section](../common-issues/index.html#python-hangs-in-git-bash). + If all is well with your installation, you should see something like: ~~~ -Python 3.8.2 +Python 3.11.4 ~~~ {: .output} @@ -240,9 +247,8 @@ type the following in your shell: {: .language-bash} This should enter you into a Python console and you should see something like: ~~~ -Python 3.8.2 (default, Jun 8 2021, 11:59:35) -[Clang 12.0.5 (clang-1205.0.22.11)] on darwin -Type "help", "copyright", "credits" or "license" for more information. +Python 3.11.4 (main, Jun 20 2023, 17:23:00) [Clang 14.0.3 (clang-1403.0.22.14.1)] on darwin +Type "help", "copyright", "credits" or "license" for more information. >>> ~~~ {: .language-bash}