From 3aa407b3ffac74f70e94daee397d350fa8226d3f Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Fri, 16 Mar 2018 09:22:59 -0700 Subject: [PATCH] add docstring to python3 and python2 buildpacks --- repo2docker/buildpacks/python/__init__.py | 97 ++++++++++++++++++++++- 1 file changed, 93 insertions(+), 4 deletions(-) diff --git a/repo2docker/buildpacks/python/__init__.py b/repo2docker/buildpacks/python/__init__.py index 0c4076bd..ee3a64e2 100644 --- a/repo2docker/buildpacks/python/__init__.py +++ b/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):