add docstring to python3 and python2 buildpacks

repo2docker/buildpacks/python/__init__.py

@@ -1,12 +1,13 @@
-"""
-Generates a variety of Dockerfiles based on an input matrix
-"""
+"""Generates Dockerfiles based on an input matrix based on Python."""
 import os
+
 from ..base import BaseImage
 
 
 class PythonBuildPack(BaseImage):
+    """Setup Python 3 for use with a repository."""
     def get_packages(self):
+        """Return list of Python3 packages to be installed."""
         return super().get_packages().union({
             'python3',
             'python3-venv',
@@ -14,6 +15,13 @@ class PythonBuildPack(BaseImage):
         })
 
     def get_env(self):
+        """
+        Return environment variables to be set.
+
+        We set `VENV_PATH` to the virtual environment location and
+        the `NB_PYTHON_PREFIX` to the location of the jupyter binary.
+
+        """
         return super().get_env() + [
             ("VENV_PATH", "${APP_BASE}/venv"),
             # Prefix to use for installing kernels and finding jupyter binary
@@ -21,12 +29,29 @@ class PythonBuildPack(BaseImage):
         ]
 
     def get_path(self):
+        """Return paths (including virtual environment path) to be added to
+        the PATH environment variable.
+        
+        """
         return super().get_path() + [
             "${VENV_PATH}/bin"
         ]
 
-
     def get_build_script_files(self):
+        """
+        Dict of files to be copied to the container image for use in building.
+
+        This is copied before the `build_scripts` & `assemble_scripts` are
+        run, so can be executed from either of them.
+
+        It's a dictionary where the key is the source file path in the host
+        system, and the value is the destination file path inside the
+        container image.
+
+        This currently adds a frozen set of Python 3 requirements to the dict
+        of files.
+
+        """
         files = {
             'python/requirements.frozen.txt': '/tmp/requirements.frozen.txt',
         }
@@ -34,6 +59,22 @@ class PythonBuildPack(BaseImage):
         return files
 
     def get_build_scripts(self):
+        """
+        Return series of build-steps common to all Python 3 repositories.
+
+        All scripts here should be independent of contents of the repository.
+
+        This sets up:
+
+        - a directory for the virtual environment and its ownership by the
+          notebook user
+        - a Python 3 interpreter for the virtual environement
+        - a Python 3 jupyter kernel including a base set of requirements
+        - support for Jupyter widgets
+        - support for JupyterLab
+        - support for nteract
+
+        """
         return super().get_build_scripts() + [
             (
                 "root",
@@ -60,6 +101,8 @@ class PythonBuildPack(BaseImage):
         ]
 
     def get_assemble_scripts(self):
+        """Return series of build-steps specific to this repository.
+        """
         # If we have a runtime.txt & that's set to python-2.7,
         # we will *not* install requirements.txt but will find &
         # install a requirements3.txt file if it exists.
@@ -85,12 +128,16 @@ class PythonBuildPack(BaseImage):
         return assemble_scripts
 
     def detect(self):
+        """Check if current repo should be built with the Python 3 Build pack.
+        """
         return (os.path.exists(self.binder_path('requirements.txt')) and
                 super().detect())
 
 
 class Python2BuildPack(PythonBuildPack):
+    """Setup Python 2 for use with a repository."""
     def get_packages(self):
+        """Return list of Python 2 packages to be installed."""
         return super().get_packages().union({
             'python',
             'python-dev',
@@ -98,16 +145,41 @@ class Python2BuildPack(PythonBuildPack):
         })
 
     def get_env(self):
+        """
+        Return environment variables to be set.
+
+        We set `VENV_PATH` to the virtual environment location containing
+        Python 2.
+        
+        """
         return super().get_env() + [
             ('VENV2_PATH', '${APP_BASE}/venv2')
         ]
 
     def get_path(self):
+        """Return paths (including virtual environment path) to be added to
+        the PATH environment variable.
+        
+        """
         return super().get_path() + [
             "${VENV2_PATH}/bin"
         ]
 
     def get_build_script_files(self):
+        """
+        Dict of files to be copied to the container image for use in building.
+
+        This is copied before the `build_scripts` & `assemble_scripts` are
+        run, so can be executed from either of them.
+
+        It's a dictionary where the key is the source file path in the host
+        system, and the value is the destination file path inside the
+        container image.
+
+        This currently adds a frozen set of Python 2 requirements to the dict
+        of files.
+        
+        """
         files = {
             'python/requirements2.frozen.txt': '/tmp/requirements2.frozen.txt',
         }
@@ -115,6 +187,19 @@ class Python2BuildPack(PythonBuildPack):
         return files
 
     def get_build_scripts(self):
+        """
+        Return series of build-steps common to all Python 2 repositories.
+
+        All scripts here should be independent of contents of the repository.
+
+        This sets up:
+
+        - a directory for the virtual environment and its ownership by the
+          notebook user
+        - a Python 2 interpreter for the virtual environement
+        - a Python 2 jupyter kernel
+
+        """
         return super().get_build_scripts() + [
             (
                 "root",
@@ -139,6 +224,8 @@ class Python2BuildPack(PythonBuildPack):
         ]
 
     def get_assemble_scripts(self):
+        """Return series of build-steps specific to this repository.
+        """
         return super().get_assemble_scripts() + [
             (
                 '${NB_USER}',
@@ -147,6 +234,8 @@ class Python2BuildPack(PythonBuildPack):
         ]
 
     def detect(self):
+        """Check if current repo should be built with the Python 2 Build pack.
+        """
         requirements_txt = self.binder_path('requirements.txt')
         runtime_txt = self.binder_path('runtime.txt')
         if os.path.exists(requirements_txt) and os.path.exists(runtime_txt):