Improve docs, examples, add Dockerfile (#6)

* add simple and advanced usage examples and readme

* add Dockerfile for debugging non-nixos installation

* fix readme

Readme.md

@@ -88,9 +88,9 @@ Using nixpkgs as a base brings the following benefits:
 2. Nix specific fixes:  
    Some python packages might need some additional modification to work with nix. Those are already done in nixpkgs and mach-nix will reuse them.
 
-The overlay is generated by the following strategy for each required python package:
+The overlay is generated by applying the following strategy to each required python package:
    - If the exact required python package version already exists in nixpkgs, its definition stays untouched but it might be used as build input for other packages.
-   - If one or more versions of the required python package can be found in nixpkgs but none of them has a matching version, the one with the closest version to our requirement is picked and its definition is modified via `overrideAttrs`. The following attributes are modified:
+   - If one or more versions of the required python package can be found in nixpkgs, but none of them matches the exact required version, the one with the closest version to our requirement is picked and its definition is modified via `overrideAttrs`. The following attributes are modified:
       - `src`: updated to the required version
       - `name`: modified to match the new version
       - `buildInputs`: missing python inputs are added
@@ -98,3 +98,24 @@ The overlay is generated by the following strategy for each required python pack
       - `doCheck`: set to false by default if not specified by user
       - `doInstallCheck`: set to false by default if not specified by user
    - If no version of the required package is found in nixpkgs, the package is built from scratch by using `buildPythonPackage`.
+
+## Advanced Usage (Nix Only)
+Mach-nix can be fine tuned with additional arguments by importing it via `builtins.fetchGit`. Examples can be found in [./example](./example/). There are 3 different methods which can be invoked:
+1. **mkPythonExpr** - returns a derivation containing a nix expression in $out/share/expr.nix which describes the python environment defined by your inputs
+1. **mkPython** - returns the python environment derivation. It basically just evaluates the expression coming from **mkPythonExpr**. 
+1. **mkPythonShell** - returns the python environment suitable for nix-shell.
+
+All 3 methods take the following set of inputs which are processed in [./mach_nix/nix/expression.nix](./mach_nix/nix/expression.nix):
+
+### Required Arguments:
+ - **requirements** (string): Text content of a typical `requirements.txt`.
+
+### Optional Arguments:
+ - **python_attr** (string): Select one of (python27, python35, python36, python37, python38). (default: python37)
+ - **prefer_nixpkgs** (bool): Prefer python package versions from nixpkgs instead of newer ones. Decreases build time. (default: true)
+ - **disable_checks** (bool): Disable tests wherever possible to decrease build time.
+ - **nixpkgs_commit** (string): commit hash of nixpkgs version to use python packages from
+ - **nixpkgs_tarball_sha256** (string): sha256 hash of the unpacked tarball for the selected nixpkgs version. (obtained via `nix-prefetch-url --unpack https://github.com/nixos/nixpkgs/tarball/<nixpkgs_commit>`)
+ - **pypi_deps_db_commit** (string): commit hash of a specific version of the dependency graph ([pypi-deps-db](https://github.com/DavHau/pypi-deps-db)).
+ - **pypi_deps_db_sha256** (string): sha256 hash obtained via `nix-prefetch-url --unpack https://github.com/DavHau/pypi-deps-db/tarball/<pypi_deps_db_commit>`
+

debug/Dockerfile

@@ -0,0 +1,17 @@
+# For testing installation on non-nixos platform
+# Must be copied to project root and built from there.
+
+FROM python:3.7
+
+RUN useradd -ms /bin/bash user
+RUN mkdir -m 0755 /nix && chown user /nix
+
+
+USER user
+WORKDIR /home/user
+RUN echo "requests" > r
+
+
+COPY . project
+RUN pip install ./project
+ENV PATH="/home/user/.local/bin:${PATH}"

example/advanced-usage.nix

@@ -0,0 +1,15 @@
+let
+  mach-nix = import (builtins.fetchGit {
+    url = "https://github.com/DavHau/mach-nix/";
+    ref = "1.0.0";
+  });
+in mach-nix.mkPython {
+  requirements = builtins.readFile ./requirements.txt;
+  python_attr = "python36";
+  prefer_nixpkgs = false;
+  disable_checks = true;
+  nixpkgs_commit = "60c4ddb97fd5a730b93d759754c495e1fe8a3544";
+  nixpkgs_tarball_sha256 = "1a1pvfz130c4cma5a21wjl7yrivc7ls1ksqqmac23srk64ipzakf";
+  pypi_deps_db_commit = "ee346b782cd217a4d1483a4749429065a520610b";
+  pypi_deps_db_sha256 = "08k7ybvar5d820ygsg87ks14l086x7y0ciamizdj0shw2xkn7cly";
+}

example/requirements.txt

@@ -0,0 +1,4 @@
+## EXAMPLE
+requests
+
+# ... put your requirements here

example/simple-usage-expression.nix

@@ -0,0 +1,8 @@
+let
+  mach-nix = import (builtins.fetchGit {
+    url = "https://github.com/DavHau/mach-nix/";
+    ref = "1.0.0";
+  });
+in mach-nix.mkPythonExpr {
+  requirements = builtins.readFile ./requirements.txt;
+}

example/simple-usage-shell.nix

@@ -0,0 +1,8 @@
+let
+  mach-nix = import (builtins.fetchGit {
+    url = "https://github.com/DavHau/mach-nix/";
+    ref = "1.0.0";
+  });
+in mach-nix.mkPythonShell {
+  requirements = builtins.readFile ./requirements.txt;
+}

example/simple-usage.nix

@@ -0,0 +1,8 @@
+let
+  mach-nix = import (builtins.fetchGit {
+    url = "https://github.com/DavHau/mach-nix/";
+    ref = "1.0.0";
+  });
+in mach-nix.mkPython {
+  requirements = builtins.readFile ./requirements.txt;
+}

mach_nix/nix/expression.nix

@@ -6,7 +6,7 @@
   nixpkgs_commit ? builtins.readFile ./NIXPKGS_COMMIT,  # nixpkgs version to use python packages from
   nixpkgs_tarball_sha256 ? builtins.readFile ./NIXPKGS_TARBALL_SHA256,  # nixpkgs version to use python packages from
   pypi_deps_db_commit ? builtins.readFile ./PYPI_DEPS_DB_COMMIT,  # python dependency DB version to use
-  # Hash obtained using `nix-prefetch-url --unpack https://github.com/DavHau/pypi-deps-db/tarball/<pypi_deps_db_commit>.tar.gz`
+  # Hash obtained using `nix-prefetch-url --unpack https://github.com/DavHau/pypi-deps-db/tarball/<pypi_deps_db_commit>`
   pypi_deps_db_sha256 ? builtins.readFile ./PYPI_DEPS_DB_TARBALL_SHA256  # python dependency DB version to use
 }:
 let