Support .binder directory (#653)

Support .binder directory

Author: betatim

docs/source/design.md

@@ -7,7 +7,7 @@ The philosophy for the repo2docker buildpacks includes:
 - using common configuration files for familiar installation and packaging tools
 - allowing configuration files to be combined to compose more complex setups
 - specifying default locations for configuration files
-(the repository's root directory or .binder directory)
+(in the repository's root, `binder` or `.binder` directory)
 
 
 When designing `repo2docker` and adding to it in the future, the

docs/source/usage.rst

@@ -72,13 +72,14 @@ specify the ``branch-name`` or ``commit-hash``. For example::
 Where to put configuration files
 ================================
 
-``repo2docker`` will look for configuration files in either:
+``repo2docker`` will look for configuration files in:
 
 * A folder named ``binder/`` in the root of the repository.
+* A folder named ``.binder/`` in the root of the repository.
 * The root directory of the repository.
 
-If the folder ``binder/`` is located at the top level of the repository,
-only configuration files in the ``binder/`` folder will be considered.
+`repo2docker` searches for these folders in order (``binder/``, ``.binder/``,
+root). Only configuration files in the first identified folder are considered.
 
 Check the complete list of :ref:`configuration files <config-files>` supported
 by ``repo2docker`` to see how to configure the build process.

repo2docker/__main__.py

@@ -7,6 +7,7 @@
 from . import __version__
 from .utils import validate_and_generate_port_mapping, is_valid_docker_image_name
 
+
 def validate_image_name(image_name):
     """
     Validate image_name read by argparse

repo2docker/buildpacks/base.py

@@ -423,12 +423,26 @@ def get_start_script(self):
         """
         return None
 
+    @property
+    def binder_dir(self):
+        has_binder = os.path.isdir("binder")
+        has_dotbinder = os.path.isdir(".binder")
+
+        if has_binder and has_dotbinder:
+            raise RuntimeError(
+                "The repository contains both a 'binder' and a '.binder' "
+                "directory. However they are exclusive.")
+
+        if has_dotbinder:
+            return ".binder"
+        elif has_binder:
+            return "binder"
+        else:
+            return ""
+
     def binder_path(self, path):
         """Locate a file"""
-        if os.path.exists('binder'):
-            return os.path.join('binder', path)
-        else:
-            return path
+        return os.path.join(self.binder_dir, path)
 
     def detect(self):
         return True

repo2docker/buildpacks/nix/nix-shell-wrapper

@@ -10,29 +10,36 @@ trap _term SIGTERM
 
 # if there is a binder/ sub-directory it takes precedence
 # files outside it are ignored
-if [ -e ./binder ]; then
-  nixpath="./binder/default.nix";
-  if [ -f ./binder/start ]; then
-    chmod u+x ./binder/start
-    # Using `$@`` here which is what the internet recommends leads to
-    # errors when the command is something like `jupyter --ip=0.0.0.0 ...`
-    # as nix-shell picks that up as an argument to it instead of the command.
-    # There are several issues on the nix repos discussing this and adding support
-    # for -- to indicate "all arguments after this are for the command, not nix-shell"
-    # but it seems they have stalled/not yet produced an implementation.
-    # So let's use `$*` for now.
-    nix-shell $nixpath --command "./binder/start $*" &
-  else
-    nix-shell $nixpath --command "$*" &
+# find binder sub-directory (if present)
+binder_dir="./"
+for dir in "./binder" "./.binder" ; do
+  if [ -e $dir ]; then
+    binder_dir=$dir
+    break
   fi
+done
+
+# raise error if both binder and .binder are found
+if [[ -d "./binder" && -d "./.binder" ]]; then
+  echo "Error: Found both binder and .binder directories."
+  exit 1
+fi
+
+echo "binder_dir is: $binder_dir"
+
+nixpath="$binder_dir/default.nix";
+if [ -f $binder_dir/start ]; then
+  chmod u+x $binder_dir/start
+  # Using `$@`` here which is what the internet recommends leads to
+  # errors when the command is something like `jupyter --ip=0.0.0.0 ...`
+  # as nix-shell picks that up as an argument to it instead of the command.
+  # There are several issues on the nix repos discussing this and adding support
+  # for -- to indicate "all arguments after this are for the command, not nix-shell"
+  # but it seems they have stalled/not yet produced an implementation.
+  # So let's use `$*` for now.
+  nix-shell $nixpath --command "$binder_dir/start $*" &
 else
-  nixpath="./default.nix";
-  if [ -f ./start ]; then
-    chmod u+x ./start
-    nix-shell $nixpath --command "./start $*" &
-  else
-    nix-shell $nixpath --command "$*" &
-  fi
+  nix-shell $nixpath --command "$*" &
 fi
 
 PID=$!

repo2docker/buildpacks/python/__init__.py

@@ -67,7 +67,7 @@ def get_assemble_scripts(self):
             ))
 
         # setup.py exists *and* binder dir is not used
-        if not os.path.exists('binder') and os.path.exists(setup_py):
+        if not self.binder_dir and os.path.exists(setup_py):
             assemble_scripts.append((
                 '${NB_USER}',
                 '{} install --no-cache-dir .'.format(pip)
@@ -88,6 +88,6 @@ def detect(self):
                 return True
             else:
                 return False
-        if not os.path.exists('binder') and os.path.exists(setup_py):
+        if not self.binder_dir and os.path.exists(setup_py):
             return True
         return os.path.exists(requirements_txt)

repo2docker/buildpacks/r.py

@@ -84,7 +84,7 @@ def detect(self):
             return True
 
         description_R = 'DESCRIPTION'
-        if ((not os.path.exists('binder') and os.path.exists(description_R))
+        if ((not self.binder_dir and os.path.exists(description_R))
           or 'r' in self.stencila_contexts):
             if not self.checkpoint_date:
                 # no R snapshot date set through runtime.txt
@@ -300,7 +300,7 @@ def get_assemble_scripts(self):
             ]
 
         description_R = 'DESCRIPTION'
-        if not os.path.exists('binder') and os.path.exists(description_R):
+        if not self.binder_dir and os.path.exists(description_R):
             assemble_scripts += [
                 (
                     "${NB_USER}",

tests/unit/test_binder_dir.py

@@ -0,0 +1,31 @@
+import os
+
+import pytest
+
+from repo2docker import buildpacks
+
+
+@pytest.mark.parametrize("binder_dir", ['.binder', 'binder'])
+def test_binder_dir_property(tmpdir, binder_dir):
+    tmpdir.chdir()
+    os.mkdir(binder_dir)
+
+    bp = buildpacks.BuildPack()
+    assert binder_dir in bp.binder_dir
+    assert bp.binder_path('foo.yaml') == os.path.join(binder_dir, 'foo.yaml')
+
+
+def test_root_binder_dir(tmpdir):
+    tmpdir.chdir()
+    bp = buildpacks.BuildPack()
+    assert bp.binder_dir == ''
+
+
+def test_exclusive_binder_dir(tmpdir):
+    tmpdir.chdir()
+    os.mkdir('./binder')
+    os.mkdir('./.binder')
+
+    bp = buildpacks.BuildPack()
+    with pytest.raises(RuntimeError):
+        _ = bp.binder_dir