Merge pull request #21837 from Azulinho/python-docs_add_virtualenv_and_nixshell_example

python docs: add an example for a virtualenv and pip through nix-shell

doc/languages-frameworks/python.md

@@ -804,6 +804,55 @@ If you want to create a Python environment for development, then the recommended
 method is to use `nix-shell`, either with or without the `python.buildEnv`
 function.
 
+### How to consume python modules using pip in a virtualenv like I am used to on other Operating Systems ?
+
+This is an example of a `default.nix` for a `nix-shell`, which allows to consume a `virtualenv` environment,
+and install python modules through `pip` the traditional way.
+
+Create this `default.nix` file, together with a `requirements.txt` and simply execute `nix-shell`.
+
+```
+with import <nixpkgs> {};
+with pkgs.python27Packages;
+
+stdenv.mkDerivation { 
+  name = "impurePythonEnv";
+  buildInputs = [
+    # these packages are required for virtualenv and pip to work:
+    #
+    python27Full
+    python27Packages.virtualenv
+    python27Packages.pip
+    # the following packages are related to the dependencies of your python 
+    # project. 
+    # In this particular example the python modules listed in the 
+    # requirements.tx require the following packages to be installed locally 
+    # in order to compile any binary extensions they may require.
+    #
+    taglib
+    openssl
+    git
+    libxml2
+    libxslt
+    libzip
+    stdenv
+    zlib ];
+  src = null;
+  shellHook = ''
+  # set SOURCE_DATE_EPOCH so that we can use python wheels
+  SOURCE_DATE_EPOCH=$(date +%s)
+  virtualenv --no-setuptools venv 
+  export PATH=$PWD/venv/bin:$PATH
+  pip install -r requirements.txt
+  '';
+}
+```
+
+Note that the `pip install` is an imperative action. So every time `nix-shell`
+is executed it will attempt to download the python modules listed in 
+requirements.txt. However these will be cached locally within the `virtualenv`
+folder and not downloaded again.
+
 
 ## Contributing