documentation and cleanup

Author: gojko

aws_lambda_builders/workflows/nodejs_npm/actions.py

@@ -11,18 +11,44 @@
 
 class NodejsNpmPackAction(BaseAction):
 
+    """
+    A Lambda Builder Action that packages a Node.js package using NPM to extract the source and remove test resources
+    """
+
     NAME = 'NpmPack'
     DESCRIPTION = "Packaging source using NPM"
     PURPOSE = Purpose.COPY_SOURCE
 
     def __init__(self, artifacts_dir, scratch_dir, manifest_path, osutils, subprocess_npm):
+        """
+        :type artifacts_dir: str
+        :param artifacts_dir: an existing (writable) directory where to store the output.
+            Note that the actual result will be in the 'package' subdirectory here.
+
+        :type scratch_dir: str
+        :param scratch_dir: an existing (writable) directory for temporary files
+
+        :type manifest_path: str
+        :param manifest_path: path to package.json of an NPM project with the source to pack
+
+        :type osutils: aws_lambda_builders.workflows.nodejs_npm.utils.OSUtils
+        :param osutils: An instance of OS Utilities for file manipulation
+
+        :type subprocess_npm: aws_lambda_builders.workflows.nodejs_npm.npm.SubprocessNpm
+        :param subprocess_npm: An instance of the NPM process wrapper
+        """
         self.artifacts_dir = artifacts_dir
         self.manifest_path = manifest_path
         self.scratch_dir = scratch_dir
         self.osutils = osutils
         self.subprocess_npm = subprocess_npm
 
     def execute(self):
+        """
+        Runs the action.
+
+        :raises lambda_builders.actions.ActionFailedError: when NPM packaging fails
+        """
         try:
             package_path = "file:{}".format(self.osutils.abspath(self.osutils.dirname(self.manifest_path)))
 
@@ -44,19 +70,36 @@ def execute(self):
 
 class NodejsNpmInstallAction(BaseAction):
 
+    """
+    A Lambda Builder Action that installs NPM project dependencies
+    """
+
     NAME = 'NpmInstall'
     DESCRIPTION = "Installing dependencies from NPM"
     PURPOSE = Purpose.RESOLVE_DEPENDENCIES
 
-    def __init__(self, artifacts_dir, manifest_path, osutils, subprocess_npm):
+    def __init__(self, artifacts_dir, subprocess_npm):
+        """
+        :type artifacts_dir: str
+        :param artifacts_dir: an existing (writable) directory with project source files.
+            Dependencies will be installed in this directory.
+
+        :type subprocess_npm: aws_lambda_builders.workflows.nodejs_npm.npm.SubprocessNpm
+        :param subprocess_npm: An instance of the NPM process wrapper
+        """
+
         self.artifacts_dir = artifacts_dir
-        self.manifest_path = manifest_path
-        self.osutils = osutils
         self.subprocess_npm = subprocess_npm
 
     def execute(self):
+        """
+        Runs the action.
+
+        :raises lambda_builders.actions.ActionFailedError: when NPM execution fails
+        """
+
         try:
-            LOG.debug("NODEJS installing in: %s from: %s", self.artifacts_dir, self.manifest_path)
+            LOG.debug("NODEJS installing in: %s", self.artifacts_dir)
 
             self.subprocess_npm.run(
                     ['install', '-q', '--no-audit', '--no-save', '--production'],

aws_lambda_builders/workflows/nodejs_npm/npm.py

@@ -8,6 +8,12 @@
 
 
 class NpmExecutionError(Exception):
+
+    """
+    Exception raised in case NPM execution fails.
+    It will pass on the standard error output from the NPM console.
+    """
+
     MESSAGE = "NPM Failed: {message}"
 
     def __init__(self, **kwargs):
@@ -16,7 +22,20 @@ def __init__(self, **kwargs):
 
 class SubprocessNpm(object):
 
+    """
+    Wrapper around the NPM command line utility, making it
+    easy to consume execution results.
+    """
+
     def __init__(self, osutils, npm_exe=None):
+        """
+        :type osutils: aws_lambda_builders.workflows.nodejs_npm.utils.OSUtils
+        :param osutils: An instance of OS Utilities for file manipulation
+
+        :type npm_exe: str
+        :param npm_exe: Path to the NPM binary. If not set,
+            the default executable path npm will be used
+        """
         self.osutils = osutils
 
         if npm_exe is None:
@@ -26,6 +45,25 @@ def __init__(self, osutils, npm_exe=None):
 
     def run(self, args, cwd=None):
 
+        """
+        Runs the action.
+
+        :type args: list
+        :param args: Command line arguments to pass to NPM
+
+        :type cwd: str
+        :param cwd: Directory where to execute the command (defaults to current dir)
+
+        :rtype: str
+        :return: text of the standard output from the command
+
+        :raises aws_lambda_builders.workflows.nodejs_npm.npm.NpmExecutionError:
+            when the command executes with a non-zero return code. The exception will
+            contain the text of the standard error output from the command.
+
+        :raises ValueError: if arguments are not provided, or not a list
+        """
+
         if not isinstance(args, list):
             raise ValueError('args must be a list')
 

aws_lambda_builders/workflows/nodejs_npm/utils.py

@@ -9,6 +9,11 @@
 
 class OSUtils(object):
 
+    """
+    Wrapper around file system functions, to make it easy to
+    unit test actions in memory
+    """
+
     def extract_tarfile(self, tarfile_path, unpack_dir):
         with tarfile.open(tarfile_path, 'r:*') as tar:
             tar.extractall(unpack_dir)

aws_lambda_builders/workflows/nodejs_npm/workflow.py

@@ -12,6 +12,10 @@
 
 class NodejsNpmWorkflow(BaseWorkflow):
 
+    """
+    A Lambda builder workflow that knows how to pack
+    NodeJS projects using NPM.
+    """
     NAME = "NodejsNpmBuilder"
 
     CAPABILITY = Capability(language="nodejs",
@@ -51,8 +55,6 @@ def __init__(self,
                                        subprocess_npm=subprocess_npm)
 
         npm_install = NodejsNpmInstallAction(artifacts_dir,
-                                             manifest_path,
-                                             osutils=osutils,
                                              subprocess_npm=subprocess_npm)
         self.actions = [
             npm_pack,

tests/unit/workflows/nodejs_npm/test_actions.py

@@ -53,14 +53,11 @@ def test_raises_action_failed_when_npm_fails(self, OSUtilMock, SubprocessNpmMock
 
 class TestNodejsNpmInstallAction(TestCase):
 
-    @patch("aws_lambda_builders.workflows.nodejs_npm.utils.OSUtils")
     @patch("aws_lambda_builders.workflows.nodejs_npm.npm.SubprocessNpm")
-    def test_tars_and_unpacks_npm_project(self, OSUtilMock, SubprocessNpmMock):
-        osutils = OSUtilMock.return_value
+    def test_tars_and_unpacks_npm_project(self, SubprocessNpmMock):
         subprocess_npm = SubprocessNpmMock.return_value
 
-        action = NodejsNpmInstallAction("artifacts", "manifest",
-                                        osutils=osutils,
+        action = NodejsNpmInstallAction("artifacts",
                                         subprocess_npm=subprocess_npm)
 
         action.execute()
@@ -69,18 +66,14 @@ def test_tars_and_unpacks_npm_project(self, OSUtilMock, SubprocessNpmMock):
 
         subprocess_npm.run.assert_called_with(expected_args, cwd='artifacts')
 
-    @patch("aws_lambda_builders.workflows.nodejs_npm.utils.OSUtils")
     @patch("aws_lambda_builders.workflows.nodejs_npm.npm.SubprocessNpm")
-    def test_raises_action_failed_when_npm_fails(self, OSUtilMock, SubprocessNpmMock):
-        osutils = OSUtilMock.return_value
+    def test_raises_action_failed_when_npm_fails(self, SubprocessNpmMock):
         subprocess_npm = SubprocessNpmMock.return_value
 
         builder_instance = SubprocessNpmMock.return_value
         builder_instance.run.side_effect = NpmExecutionError(message="boom!")
 
         action = NodejsNpmInstallAction("artifacts",
-                                        "manifest",
-                                        osutils=osutils,
                                         subprocess_npm=subprocess_npm)
 
         with self.assertRaises(ActionFailedError) as raised:

tests/unit/workflows/nodejs_npm/test_workflow.py

@@ -0,0 +1,28 @@
+
+from unittest import TestCase
+
+from aws_lambda_builders.workflows.nodejs_npm.workflow import NodejsNpmWorkflow
+
+from aws_lambda_builders.workflows.nodejs_npm.actions import NodejsNpmPackAction, NodejsNpmInstallAction
+
+from aws_lambda_builders.actions import CopySourceAction
+
+
+class TestNodejsNpmWorkflow(TestCase):
+
+    """
+    the workflow requires an external utility (npm) to run, so it is extensively tested in integration tests.
+    this is just a quick wiring test to provide fast feedback if things are badly broken
+    """
+
+    def test_workflow_sets_up_npm_actions(self):
+
+        workflow = NodejsNpmWorkflow("source", "artifacts", "scratch_dir", "manifest")
+
+        assert len(workflow.actions) == 3
+
+        assert isinstance(workflow.actions[0], NodejsNpmPackAction)
+
+        assert isinstance(workflow.actions[1], CopySourceAction)
+
+        assert isinstance(workflow.actions[2], NodejsNpmInstallAction)