Improve Pipelines and Pipes docstrings 258 (#261)

* Improve Pipelines and Pipes docstrings

      * Update doctrsings when applicable
      * Update a screenshot in the the user interface chapter

Signed-off-by: hyounes4560 <hyounes4560@conestogac.on.ca>

* Fix the line length for validity #258

* Fix failing test #258

Co-authored-by: Thomas Druez <tdruez@nexb.com>

Author: hyounes4560

docs/images/user-interface-5.png

@@ -19,6 +19,7 @@
 #
 # ScanCode.io is a free software code scanning tool from nexB Inc. and others.
 # Visit https://github.com/nexB/scancode.io for support and download.
+
 import json
 
 from django.apps import apps

scanpipe/api/views.py

@@ -38,7 +38,7 @@
 
 class Pipeline:
     """
-    Base class for all Pipelines.
+    Base class for all pipelines.
     """
 
     def __init__(self, run):
@@ -56,7 +56,7 @@ def steps(cls):
     @classmethod
     def get_steps(cls):
         """
-        Raise a deprecation warning when the steps are defined as a tuple in place of
+        Raises a deprecation warning when the steps are defined as a tuple instead of
         a classmethod.
         """
         if callable(cls.steps):
@@ -71,14 +71,14 @@ def get_steps(cls):
     @classmethod
     def get_doc(cls):
         """
-        Return the docstring.
+        Returns a docstring.
         """
         return getdoc(cls)
 
     @classmethod
     def get_graph(cls):
         """
-        Return the graph of steps.
+        Returns a graph of steps.
         """
         return [
             {"name": step.__name__, "doc": getdoc(step)} for step in cls.get_steps()
@@ -87,7 +87,7 @@ def get_graph(cls):
     @classmethod
     def get_info(cls):
         """
-        Return a dict of combined data about this Pipeline.
+        Returns a dictctionary of combined data about the current pipeline.
         """
         return {
             "description": cls.get_doc(),
@@ -96,7 +96,7 @@ def get_info(cls):
 
     def log(self, message):
         """
-        Log the `message` to this module logger and to the Run instance.
+        Logs the given `message` to the current module logger and Run instance.
         """
         now_as_localtime = timezone.localtime(timezone.now())
         timestamp = now_as_localtime.strftime("%Y-%m-%d %H:%M:%S.%f")[:-4]
@@ -146,15 +146,15 @@ def save_errors(self, *exceptions):
 
 def is_pipeline(obj):
     """
-    Return True if the `obj` is a subclass of `Pipeline` except for the
+    Returns True if the `obj` is a subclass of `Pipeline` except for the
     `Pipeline` class itself.
     """
     return inspect.isclass(obj) and issubclass(obj, Pipeline) and obj is not Pipeline
 
 
 def profile(step):
     """
-    Profile a Pipeline step and save the results as HTML in the project output
+    Profiles a Pipeline step and save the results as HTML file in the project output
     directory.
 
     Usage:

scanpipe/pipelines/__init__.py

@@ -27,7 +27,7 @@
 
 class Docker(root_filesystems.RootFS):
     """
-    A pipeline to analyze a Docker image.
+    A pipeline to analyze Docker images.
     """
 
     @classmethod
@@ -49,52 +49,52 @@ def steps(cls):
 
     def extract_images(self):
         """
-        Extract the images from tarballs.
+        Extracts images from input tarballs.
         """
         self.images, errors = docker.extract_images_from_inputs(self.project)
         if errors:
             self.add_error("\n".join(errors))
 
     def extract_layers(self):
         """
-        Extract layers from images.
+        Extracts layers from input images.
         """
         errors = docker.extract_layers_from_images(self.project, self.images)
         if errors:
             self.add_error("\n".join(errors))
 
     def find_images_linux_distro(self):
         """
-        Find the linux distro of the images.
+        Finds the linux distro of input images.
         """
         for image in self.images:
             image.get_and_set_distro()
 
     def collect_images_information(self):
         """
-        Collect images information and store on project.
+        Collects and stores image information in a project.
         """
         images_data = [docker.get_image_data(image) for image in self.images]
         self.project.update_extra_data({"images": images_data})
 
     def collect_and_create_codebase_resources(self):
         """
-        Collect and create all image files as CodebaseResource.
+        Collects and labels all image files as CodebaseResources.
         """
         for image in self.images:
             docker.create_codebase_resources(self.project, image)
 
     def collect_and_create_system_packages(self):
         """
-        Collect installed system packages for each layer based on the distro.
+        Collects installed system packages for each layer based on the distro.
         """
         with self.save_errors(rootfs.DistroNotFound, rootfs.DistroNotSupported):
             for image in self.images:
                 docker.scan_image_for_system_packages(self.project, image)
 
     def tag_uninteresting_codebase_resources(self):
         """
-        Flag remaining files not from a system package.
+        Flags files that don't belong to any system package.
         """
         docker.tag_whiteout_codebase_resources(self.project)
         rootfs.tag_uninteresting_codebase_resources(self.project)

scanpipe/pipelines/docker.py

@@ -26,8 +26,8 @@
 
 class LoadInventory(Pipeline):
     """
-    A pipeline to load a files and packages inventory from a ScanCode JSON scan.
-    (assumed to contain file information and package scan data).
+    A pipeline to load an inventory of files and packages from a ScanCode JSON scan.
+    (Presumably containing file information and package scan data).
     """
 
     @classmethod
@@ -39,7 +39,7 @@ def steps(cls):
 
     def get_scan_json_input(self):
         """
-        Locate the JSON scan input from the project input/ directory.
+        Locates a JSON scan input from a project's input/ directory.
         """
         inputs = list(self.project.inputs(pattern="*.json"))
         if len(inputs) != 1:
@@ -48,7 +48,7 @@ def get_scan_json_input(self):
 
     def build_inventory_from_scan(self):
         """
-        Process the JSON scan to populate resources and packages.
+        Processes a given JSON scan input to populate codebase resources and packages.
         """
         project = self.project
         scanned_codebase = scancode.get_virtual_codebase(project, self.input_location)

scanpipe/pipelines/load_inventory.py

@@ -30,7 +30,7 @@
 
 class RootFS(Pipeline):
     """
-    A pipeline to analyze a Linux root filesystem aka. rootfs.
+    A pipeline to analyze a Linux root filesystem, aka rootfs.
     """
 
     @classmethod
@@ -52,7 +52,7 @@ def steps(cls):
 
     def extract_input_files_to_codebase_directory(self):
         """
-        Extract root filesystem input archives with extractcode.
+        Extracts root filesystem input archives with extractcode.
         """
         input_files = self.project.inputs("*")
         target_path = self.project.codebase_path
@@ -68,13 +68,13 @@ def extract_input_files_to_codebase_directory(self):
 
     def find_root_filesystems(self):
         """
-        Find the root filesystems in project codebase/.
+        Finds root filesystems in the project's codebase/.
         """
         self.root_filesystems = list(rootfs.RootFs.from_project_codebase(self.project))
 
     def collect_rootfs_information(self):
         """
-        Collect rootfs information and store on project.
+        Collects and stores rootfs information in the project.
         """
         rootfs_data = {}
         for rfs in self.root_filesystems:
@@ -85,14 +85,14 @@ def collect_rootfs_information(self):
 
     def collect_and_create_codebase_resources(self):
         """
-        Collect and create all image files as CodebaseResource.
+        Collects and labels all image files as CodebaseResource.
         """
         for rfs in self.root_filesystems:
             rootfs.create_codebase_resources(self.project, rfs)
 
     def collect_and_create_system_packages(self):
         """
-        Collect installed system packages for each rootfs based on the distro.
+        Collects installed system packages for each rootfs based on the distro.
         The collection of system packages is only available for known distros.
         """
         with self.save_errors(rootfs.DistroNotFound, rootfs.DistroNotSupported):
@@ -101,25 +101,25 @@ def collect_and_create_system_packages(self):
 
     def tag_uninteresting_codebase_resources(self):
         """
-        Flag remaining files not from a system package if they are not worth tracking.
+        Flags files—not worth tracking—that don’t belong to any system packages.
         """
         rootfs.tag_uninteresting_codebase_resources(self.project)
 
     def tag_empty_files(self):
         """
-        Flag empty files.
+        Flags empty files.
         """
         rootfs.tag_empty_codebase_resources(self.project)
 
     def scan_for_application_packages(self):
         """
-        Scan unknown resources for packages infos.
+        Scans unknown resources for packages information.
         """
         scancode.scan_for_application_packages(self.project)
 
     def match_not_analyzed_to_system_packages(self):
         """
-        Match not-yet-analyzed files to files already related to system packages.
+        Matches "not-yet-analyzed" files to files already belong to system packages.
         """
         rootfs.match_not_analyzed(
             self.project,
@@ -129,7 +129,7 @@ def match_not_analyzed_to_system_packages(self):
 
     def match_not_analyzed_to_application_packages(self):
         """
-        Match not-yet-analyzed files to files already related to application packages.
+        Matches "not-yet-analyzed" files to files already belong to application packages.
         """
         # TODO: do it one rootfs at a time e.g. for rfs in self.root_filesystems:
         rootfs.match_not_analyzed(
@@ -140,18 +140,18 @@ def match_not_analyzed_to_application_packages(self):
 
     def scan_for_files(self):
         """
-        Scan unknown resources for copyrights, licenses, emails, and urls.
+        Scans unknown resources for copyrights, licenses, emails, and urls.
         """
         scancode.scan_for_files(self.project)
 
     def analyze_scanned_files(self):
         """
-        Analyze single file scan results for completeness.
+        Analyzes single file scan results for completeness.
         """
         pipes.analyze_scanned_files(self.project)
 
     def tag_not_analyzed_codebase_resources(self):
         """
-        Check for leftover files for sanity. We should have none.
+        Checks for any leftover files for sanity; there should be none.
         """
         pipes.tag_not_analyzed_codebase_resources(self.project)

scanpipe/pipelines/root_filesystems.py

@@ -28,9 +28,9 @@
 
 class ScanCodebase(Pipeline):
     """
-    A pipeline to scan a codebase with ScanCode-toolkit.
+    A pipeline to scan a codebase resource with ScanCode-toolkit.
 
-    The input files are copied to the project codebase/ directory and extracted
+    Input files are copied to the project's codebase/ directory and are extracted
     in place before running the scan.
     Alternatively, the code can be manually copied to the project codebase/
     directory.
@@ -62,14 +62,14 @@ def steps(cls):
 
     def copy_inputs_to_codebase_directory(self):
         """
-        Copy input files to the project codebase/ directory.
+        Copies input files to the project's codebase/ directory.
         The code can also be copied there prior to running the Pipeline.
         """
         copy_inputs(self.project.inputs(), self.project.codebase_path)
 
     def run_extractcode(self):
         """
-        Extract with extractcode.
+        Extracts with extractcode.
         """
         with self.save_errors(scancode.ScancodeError):
             scancode.run_extractcode(
@@ -80,7 +80,7 @@ def run_extractcode(self):
 
     def run_scancode(self):
         """
-        Scan extracted codebase/ content.
+        Scans extracted codebase/ content.
         """
         self.scan_output = self.project.get_output_file_path("scancode", "json")
 
@@ -97,7 +97,7 @@ def run_scancode(self):
 
     def build_inventory_from_scan(self):
         """
-        Process the JSON scan results to populate resources and packages.
+        Processes the JSON scan results to determine resources and packages.
         """
         project = self.project
         scanned_codebase = scancode.get_virtual_codebase(project, str(self.scan_output))
@@ -106,6 +106,6 @@ def build_inventory_from_scan(self):
 
     def csv_output(self):
         """
-        Generate csv outputs.
+        Generates a .csv output.
         """
         output.to_csv(self.project)

scanpipe/pipelines/scan_codebase.py

@@ -33,7 +33,7 @@
 class ScanPackage(ScanCodebase):
     """
     A pipeline to scan a single package archive with ScanCode-toolkit.
-    The output is a summary of scan results as a JSON file.
+    The output is a summary of the scan results in JSON format.
     """
 
     @classmethod
@@ -58,7 +58,7 @@ def steps(cls):
 
     def get_package_archive_input(self):
         """
-        Locate the package archive in the project input/ directory.
+        Locates the input package archive in the project's input/ directory.
         """
         input_files = self.project.input_files
         inputs = list(self.project.inputs())
@@ -70,7 +70,7 @@ def get_package_archive_input(self):
 
     def collect_archive_information(self):
         """
-        Collect information about the input archive and store the data on project.
+        Collects and store information about the input archive in the project.
         """
         self.project.update_extra_data(
             {
@@ -82,7 +82,7 @@ def collect_archive_information(self):
 
     def extract_archive_to_codebase_directory(self):
         """
-        Extract package archive with extractcode.
+        Extracts package archive with extractcode.
         """
         extract_errors = scancode.extract(self.archive_path, self.project.codebase_path)
 
@@ -91,7 +91,7 @@ def extract_archive_to_codebase_directory(self):
 
     def make_summary_from_scan_results(self):
         """
-        Build a summary from the JSON scan results.
+        Builds a summary in JSON format from the generated scan results.
         """
         summary = scancode.make_results_summary(self.project, str(self.scan_output))
         output_file = self.project.get_output_file_path("summary", "json")