From dc69fc1ace8b580340de864f4a73979801fc0752 Mon Sep 17 00:00:00 2001 From: alisterburt Date: Sat, 5 Aug 2023 13:35:50 +0100 Subject: [PATCH 1/4] first draft --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 7f7508c..6fb0789 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,6 +45,7 @@ nav: - tutorial/github/github_pages.md - Guides: - guides/index.md + - Virtual Environments: guides/environments.md - pyproject.toml: guides/pyproject.md - Packaging: guides/packaging.md - Typing: guides/typing.md From 70ae49200278b2e105f64811db0cdf0b35314ed3 Mon Sep 17 00:00:00 2001 From: alisterburt Date: Sat, 5 Aug 2023 13:37:27 +0100 Subject: [PATCH 2/4] add missing environments.md file --- docs/guides/environments.md | 220 ++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 docs/guides/environments.md diff --git a/docs/guides/environments.md b/docs/guides/environments.md new file mode 100644 index 0000000..71496fe --- /dev/null +++ b/docs/guides/environments.md @@ -0,0 +1,220 @@ +# Virtual Environments + +There are a few ways to manage virtual environments for Python development. +The most popular are: + +- [venv](https://docs.python.org/3/library/venv.html) +- [conda](https://docs.conda.io/en/latest/) + +In this guide we are going to learn how to use virtual environments to manage Python installation(s). +Specifically, +[conda environments](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html#conda-environments) +managed with +[micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html). + +## Why virtual environments? + +Python is ubiquitous, it's probably used in lots of different places on your computer already. +Code written for specific versions of either the Python language or Python packages won't necessarily work with different versions. + +A virtual environment is a little box you can put Python and various packages into. +The box is isolated from the rest of your system such that what you do inside the box won't affect what's going on outside the box. + +## Why *micromamba*? + +`micromamba` is a pure C++ reimplementation of `conda`. This makes it extremely fast and portable. +One of the easiest ways to mess up a conda installation is to install a bunch of stuff into the base environment. +`micromamba` doesn't give you a base environment, so you can't mess it up. + +## Install *micromamba* + +### Run the installer +Install `micromamba`, the executable we will use to manage our virtual environments. + +=== "MacOS/Linux" + + Download and run the official micromamba installer. + +
+ ```console + $ "${SHELL}" <(curl -L micro.mamba.pm/install.sh) + ---> 100% + + // You will be asked whether you want to initialise your shell. + // Respond "Y". + + Init shell? [Y/n] Y + + // You will be asked where you want to install micromamba. + // Using the default is recommended. + + Prefix location? [~/micromamba] + + // You will need to restart your shell for changes to take effect. + + Please restart your shell to activate micromamba. + ``` + +
+ + Next, setup `micromamba` to download packages from + [*conda-forge*](https://conda-forge.org/) + a community driven package repository. + +
+ + ```console + $ micromamba config append channels conda-forge + $ micromamba config append channels nodefaults + $ micromamba config set channel_priority strict + ``` + +
+ +=== "Windows" + + todo: add windows guide + +### Set up an alias + +!!!tip "set up an alias for micromamba" + `micromamba` replaces `conda`. Set up an alias if you want to type `conda` at the prompt. + +=== "bash" + + ```bash title="~/.bashrc" + alias conda="micromamba" + ``` + +=== "zsh" + + ```zsh title="~/.zshrc" + alias conda="micromamba" + ``` + +=== "PowerShell" + + ```PowerShell title="$Home\Documents\PowerShell\Microsoft.PowerShell_profile.ps1" + Set-Alias conda mamba + ``` + +We will use `conda` at the prompt rather than `micromamba` for the rest of this guide. + +## Usage + +### Creating and activating environments + +Run the following to create and activate an environment called `my-env` with Python 3.10 + +
+ + ```console + $ conda create --name my-env python=3.10 + + // To work in the environment we first need to activate it. + + $ conda activate my-env + + // Your prompt will indicate your current environment. + + $ (my-env) ➜ + + // Let's check that we have the correct Python version. + + $ (my-env) ➜ python --version + Python 3.10.10 + + ``` + +
+ + + +### Installing packages + +You can install most packages into your environment with `conda` or `pip`. +Install what you can with `conda`. If a package is available on +[PyPI](https://pypi.org/) but not [conda-forge](https://conda-forge.org/) then use `pip`. + +=== "conda" + +
+ + ```console + $ (my-env) ➜ conda install numpy + ``` + +
+ + +=== "pip" + +
+ + ```console + $ (my-env) ➜ pip install numpy + ``` + +
+ +### Deactivating environments + +We can deactivate an environment with + +
+ + ```console + $ (my-env) ➜ conda deactivate + + // You are no longer in my-env. + + $ + ``` + +
+ +### Removing environments + +We can remove an environment with + +
+ + ```console + $ conda env remove --name my-env + + // Your environment no longer exists + + $ conda activate my-env + Cannot activate, prefix does not exist at: '/Users/pydev/micromamba/envs/ + ``` + +
+ +### Running from outside an environment + +You can run use software in a specific environment from outside the environment. + +
+ + ```console + $ conda run --name my-env + ``` + +
+ +This is useful for workflows which rely on software with incompatible dependencies. + +### Tips + +!!!tip "Get comfy! 🧸" + Getting comfortable with the creation, destruction, activation and deactivation of environments at will is liberating. + Practice now! + +!!!tip "One environment per project 🌍" + Working with one environment per project is a useful ideal. + A general purpose environment can be useful for quick scripts and analysis. + +## Closing + +That's it! Working in virtual environments empowers you to install things without +worrying about messing up your whole system. From 23d1f072c0e4b897824ff277713286d8821d41fa Mon Sep 17 00:00:00 2001 From: alisterburt Date: Sat, 5 Aug 2023 13:53:23 +0100 Subject: [PATCH 3/4] format --- docs/guides/environments.md | 110 ++++++++++++++++++++---------------- 1 file changed, 60 insertions(+), 50 deletions(-) diff --git a/docs/guides/environments.md b/docs/guides/environments.md index 71496fe..81f5a1f 100644 --- a/docs/guides/environments.md +++ b/docs/guides/environments.md @@ -6,7 +6,8 @@ The most popular are: - [venv](https://docs.python.org/3/library/venv.html) - [conda](https://docs.conda.io/en/latest/) -In this guide we are going to learn how to use virtual environments to manage Python installation(s). +In this guide we are going to learn how to use virtual environments to manage +Python installation(s). Specifically, [conda environments](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html#conda-environments) managed with @@ -14,22 +15,28 @@ managed with ## Why virtual environments? -Python is ubiquitous, it's probably used in lots of different places on your computer already. -Code written for specific versions of either the Python language or Python packages won't necessarily work with different versions. +Python is ubiquitous, it's probably used in lots of different places on your +computer already. +Code written for specific versions of either the Python language or Python +packages won't necessarily work with different versions. -A virtual environment is a little box you can put Python and various packages into. -The box is isolated from the rest of your system such that what you do inside the box won't affect what's going on outside the box. +A virtual environment is a little box you can put Python and various packages +into. The box is isolated from the rest of your system such that what you do +inside the box won't affect what's going on outside the box. ## Why *micromamba*? -`micromamba` is a pure C++ reimplementation of `conda`. This makes it extremely fast and portable. -One of the easiest ways to mess up a conda installation is to install a bunch of stuff into the base environment. -`micromamba` doesn't give you a base environment, so you can't mess it up. +`micromamba` is a pure C++ reimplementation of `conda`. This makes it extremely +fast and portable. One of the easiest ways to mess up a conda installation is +to install a bunch of stuff into the base environment. `micromamba` doesn't +give you a base environment, so you can't mess it up. ## Install *micromamba* ### Run the installer -Install `micromamba`, the executable we will use to manage our virtual environments. + +Install `micromamba`, the executable we will use to manage our virtual +environments. === "MacOS/Linux" @@ -39,19 +46,19 @@ Install `micromamba`, the executable we will use to manage our virtual environme ```console $ "${SHELL}" <(curl -L micro.mamba.pm/install.sh) ---> 100% - + // You will be asked whether you want to initialise your shell. // Respond "Y". - + Init shell? [Y/n] Y - + // You will be asked where you want to install micromamba. // Using the default is recommended. - + Prefix location? [~/micromamba] - + // You will need to restart your shell for changes to take effect. - + Please restart your shell to activate micromamba. ``` @@ -60,26 +67,27 @@ Install `micromamba`, the executable we will use to manage our virtual environme Next, setup `micromamba` to download packages from [*conda-forge*](https://conda-forge.org/) a community driven package repository. - +
- + ```console $ micromamba config append channels conda-forge $ micromamba config append channels nodefaults $ micromamba config set channel_priority strict ``` - +
=== "Windows" todo: add windows guide - -### Set up an alias + +###  Set up an alias !!!tip "set up an alias for micromamba" - `micromamba` replaces `conda`. Set up an alias if you want to type `conda` at the prompt. - + `micromamba` replaces `conda`. Set up an alias if you want to type `conda` + at the prompt. + === "bash" ```bash title="~/.bashrc" @@ -91,61 +99,61 @@ Install `micromamba`, the executable we will use to manage our virtual environme ```zsh title="~/.zshrc" alias conda="micromamba" ``` - + === "PowerShell" - + ```PowerShell title="$Home\Documents\PowerShell\Microsoft.PowerShell_profile.ps1" Set-Alias conda mamba ``` -We will use `conda` at the prompt rather than `micromamba` for the rest of this guide. +We will use `conda` at the prompt rather than `micromamba` for the rest of this +guide. ## Usage ### Creating and activating environments -Run the following to create and activate an environment called `my-env` with Python 3.10 +Run the following to create and activate an environment called `my-env` +with Python 3.10.
- + ```console $ conda create --name my-env python=3.10 - + // To work in the environment we first need to activate it. - + $ conda activate my-env - + // Your prompt will indicate your current environment. - - $ (my-env) ➜ - + + $ (my-env) ➜ + // Let's check that we have the correct Python version. - + $ (my-env) ➜ python --version Python 3.10.10 - + ```
- - ### Installing packages You can install most packages into your environment with `conda` or `pip`. -Install what you can with `conda`. If a package is available on -[PyPI](https://pypi.org/) but not [conda-forge](https://conda-forge.org/) then use `pip`. +Install what you can with `conda`. If a package is available on +[PyPI](https://pypi.org/) but not [conda-forge](https://conda-forge.org/) +then use `pip`. === "conda"
- + ```console $ (my-env) ➜ conda install numpy ```
- === "pip" @@ -165,9 +173,9 @@ We can deactivate an environment with ```console $ (my-env) ➜ conda deactivate - + // You are no longer in my-env. - + $ ``` @@ -192,7 +200,8 @@ We can remove an environment with ### Running from outside an environment -You can run use software in a specific environment from outside the environment. +You can run use software in a specific environment from outside the +environment.
@@ -202,19 +211,20 @@ You can run use software in a specific environment from outside the environment.
-This is useful for workflows which rely on software with incompatible dependencies. +This is useful for workflows which rely on software with incompatible +dependencies. ### Tips !!!tip "Get comfy! 🧸" - Getting comfortable with the creation, destruction, activation and deactivation of environments at will is liberating. - Practice now! - + Getting comfortable with the creation, destruction, activation and + deactivation of environments at will is liberating. Practice now! + !!!tip "One environment per project 🌍" Working with one environment per project is a useful ideal. A general purpose environment can be useful for quick scripts and analysis. ## Closing -That's it! Working in virtual environments empowers you to install things without -worrying about messing up your whole system. +That's it! Working in virtual environments empowers you to install things +without worrying about messing up your whole system. From 4179b5aaaa339077dfc2f1a95dae7628fafedc63 Mon Sep 17 00:00:00 2001 From: alisterburt Date: Sat, 5 Aug 2023 13:56:49 +0100 Subject: [PATCH 4/4] small fix --- docs/guides/environments.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/guides/environments.md b/docs/guides/environments.md index 81f5a1f..61461d6 100644 --- a/docs/guides/environments.md +++ b/docs/guides/environments.md @@ -174,7 +174,7 @@ We can deactivate an environment with ```console $ (my-env) ➜ conda deactivate - // You are no longer in my-env. + // You are no longer in 'my-env'. $ ``` @@ -193,7 +193,8 @@ We can remove an environment with // Your environment no longer exists $ conda activate my-env - Cannot activate, prefix does not exist at: '/Users/pydev/micromamba/envs/ + Cannot activate, prefix does not exist at: + '/Users/pydev/micromamba/envs/' ```