finley's suggested modifications to virtual envs short course

Author: FinleyGibson

short_courses/virtual_environments.ipynb

@@ -26,15 +26,12 @@
     "## Why Use Virtual Environments?\n",
     "\n",
     "1. **Dependency Management**  \n",
-    "   Different projects might require different versions of the same library. A virtual environment allows each project to maintain its own set of dependencies.\n",
+    "   Different projects might require different versions of python or different versions of a particular library in order to work. A virtual environment allows each project to maintain its own set of dependencies, completely separate from other projects.\n",
     "\n",
     "2. **Reproducibility**  \n",
     "   Sharing code is easier when collaborators can recreate the exact environment you used, avoiding the “it works on my machine” problem.\n",
     "\n",
-    "3. **Conflict Avoidance**  \n",
-    "   If one project needs `libraryX==1.2.0` and another needs `libraryX==2.0.0`, separate virtual environments prevent these requirements from clashing.\n",
-    "\n",
-    "4. **System Integrity**  \n",
+    "3. **System Integrity**  \n",
     "   Installing or updating packages system-wide can break other applications. Virtual environments confine these changes to the environment, leaving system Python untouched.\n",
     "\n",
     "## Using venv across different operating systems \n",
@@ -64,62 +61,47 @@
     ":align: center\n",
     "```\n",
     "\n",
+    "Commands can then be typed directly into the terminal and executed by pressing Return. \n",
+    "\n",
     "#### Verifying Python Installation\n",
     "\n",
     "You can verify that Python is installed correctly by running: \n",
     "\n",
     "```bash\n",
-    "python\n",
+    "python --version\n",
     "```\n",
+    "This should produce a output stating the installed python version, for example:\n",
     "\n",
     "```bash\n",
-    "python3\n",
-    "```\n",
-    "\n",
-    "depending on the version of python that you have installed, Python 2 or 3. When running the relevant above command it will take you to an interactive Python session, where you can define variables and print them such as with the following commands:\n",
-    "\n",
-    "```python\n",
-    "x = 3 \n",
+    "Python 3.12.4\n",
     "```\n",
     "\n",
-    "```python\n",
-    "print(x)\n",
-    "```\n",
+    "Minor differences in the python version (beyond the first `.`) will not matter for the most part. However, unless you have a specific reason to use Python 2, the version should start with a 3. If it does not or if Python is not found on your system then you can install it via the [official website](https://www.python.org/downloads/).\n",
     "\n",
-    "If when running these commands you produce the following output: \n",
+    "Typically Python is invoked by calling python followed by the path to a python script file, containing some code: \n",
     "\n",
-    "```python\n",
-    "3\n",
+    "```bash\n",
+    "python example_script.py\n",
     "```\n",
+    "Calling Python from command line with no other arguments will open the [interpreter](https://docs.python.org/3/tutorial/interpreter.html) (indicated by the `>>>` prompt), where python commands can be executed in an interactive manner. This is rarely used as the code written is cleared when the interpreter is exited, which can be done by executing the `exit()` command: \n",
     "\n",
-    "then you have confirmed that you have a working version of Python installed. \n",
-    "\n",
-    "You can exit the interactive session with the following command: \n",
-    "\n",
-    "```python\n",
-    "exit\n",
+    "```bash\n",
+    ">>> exit()\n",
     "```\n",
     "\n",
-    "If you don't have Python installed currently, then you are able to install it via the [official website](https://www.python.org/downloads/).\n",
-    "\n",
     "#### Checking what is currently installed\n",
-    "\n",
-    "You can check which packages are currently installed with either of the following commands, again depending on if you have Python 2 or 3 installed. \n",
-    "\n",
+    "Python comes with some default packages installed already, and installation of packages is typically managed through PIP (a recursive acronym for \"pip install package\"). We can see what is currently installed system-wide using:\n",
     "```bash\n",
     "pip list \n",
     "```\n",
-    "\n",
-    "```bash\n",
-    "pip3 list\n",
-    "```\n",
+    "we _could_ install more packages system-wide using pip, but it is better to do so in a virtual environment.\n",
     "\n",
     "#### Creating an environment \n",
     "\n",
     "An environment can be created with the following command: \n",
     "\n",
     "```bash\n",
-    "python3 -m venv virtual_environment_1\n",
+    "python -m venv virtual_environment_1\n",
     "```\n",
     "\n",
     "On macOS this can then be activated with:\n",
@@ -142,40 +124,33 @@
     "deactivate\n",
     "```\n",
     "\n",
-    "which will remove the environment hint from the command line, highlighting that you are no longer in any environment. \n",
+    "which will remove the environment hint from the command line, highlighting that you are no longer in any virtual environment. \n",
     "\n",
-    "You would now be able to create a second virtual environment, called `virtual_environment_2` with the following commands: \n",
+    "You would now be able to create a and activate a second virtual environment, called `virtual_environment_2` with the following commands: \n",
     "\n",
     "```bash\n",
-    "python3 -m venv virtual_environment_2\n",
+    "python -m venv virtual_environment_2\n",
     "source virtual_environment_2/bin/activate\n",
     "```\n",
     "\n",
     "and easily switch between the two of them by first using `deactivate` and then `source <environment_name>/bin/activate`\n",
     "\n",
     "#### Installing a package\n",
     "\n",
-    "When we go to install a package it can be a good idea to check which packages are already installed which can be done with either of the following command depending on your python version: \n",
+    "Whith a virtual environment active, when we go to install a package it can be a good idea to check which packages are already installed.  This can be done with the following command: \n",
     "\n",
     "```bash\n",
     "pip list \n",
     "```\n",
-    "or\n",
-    "```bash\n",
-    "pip3 list\n",
-    "```\n",
-    "\n",
-    "This should give you a list of different python packages that are current installed. If you wanted to install [Pandas](https://pandas.pydata.org/), a very widespread Python Data Analysis Library then you could run the following command:\n",
+    "This should give you a list of different python packages that are current installed. If you wanted to install a new package, [Pandas](https://pandas.pydata.org/) for example (a very widespread Python Data Analysis Library), then you could run the following command:\n",
     "\n",
     "```bash\n",
-    "pip3 install pandas\n",
-    "```\n",
-    "or \n",
-    "```bash\n",
     "pip install pandas\n",
     "```\n",
     "\n",
-    "Now when you check which packages are install using `pip list` you should see that pandas is installed and can be used within this environment in your python scripts with the use of `import pandas` in this case. If you were to now run `deactivate` and `pip list` again you would see that the pandas packages is not listed. This is the key goal of virtual environments, allowing you to easily swap between environments where different combinations, and even version of packages are installed. For example it might be the case that on one of your projects you need to use Package X, but that only works with Package Y Version 1. However, there is a new release of Package Y Version 2 that has some novel features that you are interested in using for another project. Virtual environments allow you to install these package combinations once in different environments and then quickly switch between them using the process described above without having to perform the time-intensive install and uninstall process each time you switch between working on the projects. \n",
+    "Now when you check which packages are install using `pip list` you should see that pandas is installed and can be imported into code written with this environment active using `import pandas` (feel free to try this in the interactive shell). If you were to now run `deactivate` and `pip list` again you would see that the pandas packages is not listed. \n",
+    "\n",
+    "This is the key goal of virtual environments: allowing you to easily swap between different configurations of packages and their respective versions without uninstalling and reinstalling everything. For example it might be the case that on one of your projects you need to use `pandas 2.2.2`, but that this is incompatible with some other package used in a different project, which only works with `pandas 1.8.0`. Using virtual environments allows each project to install the working version of pandas without replacing the version installed in the other project. \n",
     "\n",
     "### Windows \n",
     "\n",
@@ -222,46 +197,33 @@
     "\n",
     "In your Command Prompt or PowerShell, run \n",
     "\n",
-    "\n",
-    "```shell\n",
-    "python\n",
-    "```\n",
-    "\n",
-    "Sometimes on Windows, Python might also be accessed with:\n",
-    "```shell\n",
-    "py\n",
-    "```\n",
-    "and depending on the version of python installed, it might be accessed via \n",
     "```shell\n",
-    "python3\n",
+    "python --version\n",
     "```\n",
-    "Once you have determined under which name your Python installation is under you can continue to make use of that name for the rest of the steps. \n",
-    "\n",
-    "You can then verify that your Python installation is working properly by running: \n",
-    "\n",
-    "```python\n",
-    "x = 3 \n",
-    "print(x)\n",
+    "This should produce a output stating the installed python version, for example:\n",
+    "```bash\n",
+    "Python 3.12.4\n",
     "```\n",
     "\n",
-    "If the output produced is `3`, then you have installed Python correctly.\n",
+    "Minor differences in the python version (beyond the first `.`) will not matter for the most part. However, unless you have a specific reason to use Python 2, the version should start with a 3. If it does not or if Python is not found on your system then you can install it via the [official website](https://www.python.org/downloads/).\n",
     "\n",
-    "You are able to exit the interactive session by typing: \n",
+    "Typically Python is invoked by calling python followed by the path to a python script file, containing some code: \n",
     "\n",
-    "```python\n",
-    "exit()\n",
+    "```bash\n",
+    "python example_script.py\n",
     "```\n",
     "\n",
-    "#### Checking Which Packages Are Currently Installed \n",
-    "\n",
-    "You can check which packages are currently installed by running: \n",
+    "Calling Python from command line with no other arguments will open the [interpreter](https://docs.python.org/3/tutorial/interpreter.html) (indicated by the `>>>` prompt), where python commands can be executed in an interactive manner. This is rarely used as the code written is cleared when the interpreter is exited, which can be done by executing the `exit()` command: \n",
     "\n",
-    "```shell\n",
-    "pip list\n",
+    "```bash\n",
+    ">>> exit()\n",
     "```\n",
-    "\n",
-    "If you have multiple Python versions installed, you may need `pip3 list` or `py -m pip list`, depending on the particulars of your Python installation.\n",
-    "\n",
+    "#### Checking what is currently installed\n",
+    "Python comes with some default packages installed already, and installation of packages is typically managed through PIP (a recursive acronym for \"pip install package\"). We can see what is currently installed system-wide using:\n",
+    "```bash\n",
+    "pip list \n",
+    "```\n",
+    "we _could_ install more packages system-wide using pip, but it is better to do so in a virtual environment.\n",
     "\n",
     "#### Creating a Virtual Environment \n",
     "\n",
@@ -279,7 +241,6 @@
     ".\\virtual_environment_1\\Scripts\\activate\n",
     "```\n",
     "\n",
-    "\n",
     "NOTE: Note: In PowerShell, you might need to prepend `.\\` to the command.\n",
     "Example: `.\\virtual_environment_1\\Scripts\\activate.`\n",
     "\n",
@@ -300,7 +261,7 @@
     "\n",
     "#### Creating Multiple Environments \n",
     "\n",
-    "You can create a second virtual environment, `virtual_environment_2`, as follows: \n",
+    "You can create and activate a second virtual environment, `virtual_environment_2`, as follows: \n",
     "\n",
     "```shell\n",
     "python -m venv virtual_environment_2\n",
@@ -315,7 +276,7 @@
     "```\n",
     "#### Installing a Package \n",
     "\n",
-    "Once you are inside an activated environment, you can install packages with `pip` (or `pip3` if that is what your system uses in a similar manner as before with `python`, `py` and `python3`). For example, to install [Pandas](https://pandas.pydata.org/):\n",
+    "Once you are inside an activated environment, you can install packages with `pip` (or `pip3` if that is what your system uses in a similar manner as before with `python3`). For example, to install [Pandas](https://pandas.pydata.org/):\n",
     "\n",
     "```shell\n",
     "pip install pandas\n",
@@ -327,13 +288,14 @@
     "```\n",
     "you should see pandas listed among your installed packages. This means you can use `import pandas` with Python scripts in this environment. If you leave the environment by typing `deactivate` and then check `pip list` again (outside the environment), you will not see pandas listed.\n",
     "\n",
-    "This behavior is the main advantage of virtual environments: they let you maintain different sets (and versions) of Python libraries for different projects, all on the same machine, without interference. For instance, you might need Package X that only works with Package Y version 1 for one project, while another project needs the newer Package Y version 2. With virtual environments, you can install each combination of packages only once and quickly switch between them.\n",
+    "This is the key goal of virtual environments: allowing you to easily swap between different configurations of packages and their respective versions without uninstalling and reinstalling everything. For example it might be the case that on one of your projects you need to use `pandas 2.2.2`, but that this is incompatible with some other package used in a different project, which only works with `pandas 1.8.0`. Using virtual environments allows each project to install the working version of pandas without replacing the version installed in the other project. \n",
     "\n",
     "## Python Environment and Dependency Management Tools \n",
     "\n",
     "There are a number of different options available for environmental and dependency management tools. Below are some of the most widely used tools for this task within Python. The following sections act as a set of signposts to the more comprehensive guides to their use on their official websites. \n",
     "\n",
     "### venv\n",
+    "(covered above)\n",
     "\n",
     "[venv Tutorial](https://docs.python.org/3/tutorial/venv.html)\n",
     "\n",
@@ -463,6 +425,7 @@
     "```\n",
     "\n",
     "### Poetry\n",
+    "Poetry bundles multiple tools for building and organising projects and managing dependencies. It makes use of venv to manage dependencies through a user-friendly interface, and also incorporates a build system to make your own projects easily installable (for example with pip). This is agreat way to standardise your workflow and make your work easy to reproduce! \n",
     "\n",
     "[Poetry Tutorial](https://python-poetry.org/docs/)\n",
     "\n",
@@ -471,14 +434,6 @@
     "```\n",
     "\n"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "301c5b93-8c6e-4b23-ac74-92e2c9f9a2a8",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {