From 16d58e95fc487f780ccf75427f523cc9c6462920 Mon Sep 17 00:00:00 2001 From: Jacob Donenfeld Date: Mon, 31 Oct 2022 10:31:43 -0700 Subject: [PATCH] chore: Add docstrings to functions --- .github/scripts/update_version.py | 10 ++++--- pre_commit_hooks/gitlab_ci_lint.py | 1 + pre_commit_hooks/gitlab_script_check.py | 2 +- pre_commit_hooks/shared/debug_mode.py | 1 + pre_commit_hooks/shared/importer.py | 35 ++++++++++--------------- tests/gitlab_script_test.py | 1 + 6 files changed, 24 insertions(+), 26 deletions(-) diff --git a/.github/scripts/update_version.py b/.github/scripts/update_version.py index fac90c1..9445bd3 100644 --- a/.github/scripts/update_version.py +++ b/.github/scripts/update_version.py @@ -1,22 +1,24 @@ """Update the version file.""" import os + def increment_version(version): - version = version.split('.') + version = version.split(".") version[2] = str(int(version[2]) + 1) - return '.'.join(version) + return ".".join(version) + def update_manifest(): """Update the manifest file.""" version = "0.0.0" - with open(f"{os.getcwd()}/pre_commit_hooks/VERSION", 'r') as version_file: + with open(f"{os.getcwd()}/pre_commit_hooks/VERSION") as version_file: version = version_file.read() version_file.close() next_version = increment_version(version) - with open(f"{os.getcwd()}/pre_commit_hooks/VERSION", 'w') as version_file: + with open(f"{os.getcwd()}/pre_commit_hooks/VERSION", "w") as version_file: version_file.write(next_version) version_file.close() diff --git a/pre_commit_hooks/gitlab_ci_lint.py b/pre_commit_hooks/gitlab_ci_lint.py index d1fa52d..e90c029 100644 --- a/pre_commit_hooks/gitlab_ci_lint.py +++ b/pre_commit_hooks/gitlab_ci_lint.py @@ -1,3 +1,4 @@ +"""Run gitlab's lint api on yaml files""" from __future__ import annotations import argparse diff --git a/pre_commit_hooks/gitlab_script_check.py b/pre_commit_hooks/gitlab_script_check.py index 8960dac..e798de0 100644 --- a/pre_commit_hooks/gitlab_script_check.py +++ b/pre_commit_hooks/gitlab_script_check.py @@ -1,3 +1,4 @@ +"""Run shellcheck on script elements""" from __future__ import annotations import argparse @@ -180,7 +181,6 @@ def validate_script(script_element, job_name: str, file_name: str) -> bool: for key, value in yaml_dict.items(): # key is the potential job name if isinstance(value, dict): - # TODO: compile to bash and run shellcheck valid_script_keys = ["before_script", "script", "after_script"] for valid_script_key in valid_script_keys: if valid_script_key in value: diff --git a/pre_commit_hooks/shared/debug_mode.py b/pre_commit_hooks/shared/debug_mode.py index 1ee9a78..2dcf444 100644 --- a/pre_commit_hooks/shared/debug_mode.py +++ b/pre_commit_hooks/shared/debug_mode.py @@ -1,3 +1,4 @@ +"""Enable debugging mode for tracing http requests""" from __future__ import annotations import logging import http.client as http_client diff --git a/pre_commit_hooks/shared/importer.py b/pre_commit_hooks/shared/importer.py index 45063e8..3140c6a 100644 --- a/pre_commit_hooks/shared/importer.py +++ b/pre_commit_hooks/shared/importer.py @@ -1,3 +1,4 @@ +"""Helper file to import gitlab yaml files""" from __future__ import annotations import os import sys @@ -21,6 +22,7 @@ class Dumper(yaml.SafeDumper): def recursive_lookup(lookup_key, dictionary): + """Walk the dictionary and find a nested key""" if lookup_key in dictionary: return dictionary[lookup_key] for v in dictionary.values(): @@ -33,12 +35,15 @@ def recursive_lookup(lookup_key, dictionary): @dataclass class Reference: + """Sets !reference instances in yaml files to this object when parsed""" + data: list def parse_out_references( previous_yaml: list, current_yaml: dict, current_dictionary: dict ): + """Replace reference objects in a provided dictionary with the code they reference""" queue = [lens] # Initialize a queue, this will be the path through the dict while len(queue) > 0: # Creating loop to visit each node m = queue.pop(0) # lens element @@ -99,6 +104,7 @@ def find_reference( current_yaml: dict, current_dictionary: dict, ): + """Find the code the !reference object refers to""" if str(reference.data) in current_dictionary: return current_dictionary[str(reference.data)], current_dictionary lookup = recursive_lookup(reference.data[0], current_yaml) @@ -119,6 +125,7 @@ def find_reference( def constructor_reference(loader, node) -> Reference: + """Extends the yaml constructor to parse !reference tags into a reference object""" return Reference(loader.construct_sequence(node)) @@ -126,6 +133,7 @@ def constructor_reference(loader, node) -> Reference: def check_if_importable(file_path_str: str) -> bool: + """Check if the file path exists and is of type yaml""" if "http" in file_path_str: return False if file_path_str[-5:] != ".yaml" and file_path_str[-4:] != ".yml": @@ -137,6 +145,7 @@ def check_if_importable(file_path_str: str) -> bool: def import_from_root_file(root_file: str) -> (list, bool): + """Entry point to import all yaml files starting with the root file.""" files_to_import = [] import_queue = [root_file] ci_yaml = [] @@ -175,6 +184,7 @@ def import_from_root_file(root_file: str) -> (list, bool): def import_from_yaml(yaml_data: dict) -> list: + """Grabs the references to other files via import tags in a yaml dict.""" to_import = [] if "include" in yaml_data: if isinstance(yaml_data["include"], list): @@ -190,27 +200,8 @@ def import_from_yaml(yaml_data: dict) -> list: return to_import -# -# def parseReferences(previousYAML, currentYAML): -# -# -# def findReference(YAMLList, currentYAML, job, element): -# for YAMLFile in YAMLList: -# for key, value in YAMLFile.items(): -# -# for -# -# def recursive_lookup(k, d): -# if k in d: return d[k] -# for v in d.values(): -# if isinstance(v, dict): -# a = recursive_lookup(k, v) -# if a is not None: return a -# return None -# - - def parse_import_element(existing_imports: list, element) -> list: + """Helper function to only parse valid import definitions""" if isinstance(element, str) and check_if_importable(element): existing_imports.append(element) elif isinstance(element, list): @@ -243,7 +234,8 @@ def parse_import_element(existing_imports: list, element) -> list: continue # Unsure whether to check this at compile time. if rule_type == "exists": - # If checking if a str exists and it does not, pass on the associated import + # If checking if a str exists and it does not, + # pass on the associated import if isinstance(condition, str) and not check_if_importable( condition ): @@ -268,6 +260,7 @@ def parse_import_element(existing_imports: list, element) -> list: def find_root_ci_file(root_file_name: str): + """Finds the root CI file by looking at the base git repo path.""" # If root file is not specified, look for default location # Get git root directory git_root = Repo(".", search_parent_directories=True).working_tree_dir diff --git a/tests/gitlab_script_test.py b/tests/gitlab_script_test.py index f5fc30a..0274348 100644 --- a/tests/gitlab_script_test.py +++ b/tests/gitlab_script_test.py @@ -10,6 +10,7 @@ @pytest.fixture(autouse=True) def run_around_tests(): + """Start each test from git repo root directory""" git_root = Repo(".", search_parent_directories=True).working_tree_dir # set working directory to base of git repo os.chdir(str(git_root))