From 76a50d543e6d68391d49227cdd4410013c0ce038 Mon Sep 17 00:00:00 2001 From: IsaacVRey Date: Thu, 28 Mar 2024 12:09:25 -0600 Subject: [PATCH 1/3] Add and standarize docstrings on modules/zos_lineinfile.py --- plugins/modules/zos_lineinfile.py | 60 ++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 20 deletions(-) diff --git a/plugins/modules/zos_lineinfile.py b/plugins/modules/zos_lineinfile.py index a6576af12..630ac22ac 100644 --- a/plugins/modules/zos_lineinfile.py +++ b/plugins/modules/zos_lineinfile.py @@ -300,28 +300,28 @@ def present(src, line, regexp, ins_aft, ins_bef, encoding, first_match, backrefs Insert a line at BOF/EOF Arguments: - src: {str} -- The z/OS USS file or data set to modify. - line: {str} -- The line to insert/replace into the src. - regexp: {str} -- The regular expression to look for in every line of the src. + src {str} -- The z/OS USS file or data set to modify. + line {str} -- The line to insert/replace into the src. + regexp {str} -- The regular expression to look for in every line of the src. If regexp matches, ins_aft/ins_bef will be ignored. - ins_aft: {str} -- Insert the line after matching '*regex*' pattern or EOF. + ins_aft {str} -- Insert the line after matching '*regex*' pattern or EOF. choices: - EOF - '*regex*' - ins_bef: {str} -- Insert the line before matching '*regex*' pattern or BOF. + ins_bef {str} -- Insert the line before matching '*regex*' pattern or BOF. choices: - BOF - '*regex*' - encoding: {str} -- Encoding of the src. - first_match: {bool} -- Take the first matching regex pattern. - backrefs: {bool} -- Back reference - force: {bool} -- force for modify a member part of a task in execution + encoding {str} -- Encoding of the src. + first_match {bool} -- Take the first matching regex pattern. + backrefs {bool} -- Back reference + force {bool} -- force for modify a member part of a task in execution Returns: str -- Information in JSON format. keys: - cmd: {str} -- dsed shell command - found: {int} -- Number of matching regex pattern - changed: {bool} -- Indicates if the source was modified. + cmd {str} -- dsed shell command + found {int} -- Number of matching regex pattern + changed {bool} -- Indicates if the source was modified. """ return datasets.lineinfile( src, @@ -342,23 +342,31 @@ def absent(src, line, regexp, encoding, force): """Delete lines with matching regex pattern Arguments: - src: {str} -- The z/OS USS file or data set to modify. - line: {str} -- The line to be deleted in the src. If line matches, + src {str} -- The z/OS USS file or data set to modify. + line {str} -- The line to be deleted in the src. If line matches, regexp will be ignored. - regexp: {str} -- The regular expression to look for in every line of the src. - encoding: {str} -- Encoding of the src. - force: {bool} -- force for modify a member part of a task in execution + regexp {str} -- The regular expression to look for in every line of the src. + encoding {str} -- Encoding of the src. + force {bool} -- force for modify a member part of a task in execution Returns: str -- Information in JSON format. keys: - cmd: {str} -- dsed shell command - found: {int} -- Number of matching regex pattern - changed: {bool} -- Indicates if the source was modified. + cmd {str} -- dsed shell command + found {int} -- Number of matching regex pattern + changed {bool} -- Indicates if the source was modified. """ return datasets.lineinfile(src, line, regex=regexp, encoding=encoding, state=False, debug=True, force=force) def quotedString(string): + """Add escape if string was quoted + + Arguments: + string {str} -- Given string + + Returns: + str -- The string with the quote marks replaced + """ # add escape if string was quoted if not isinstance(string, str): return string @@ -366,6 +374,18 @@ def quotedString(string): def main(): + """Initialize the module + + Raises: + fail_json: Parameter verification failed. + fail_json: regexp is required with backrefs=true + fail_json: line is required with state=present + fail_json: One of line or regexp is required with state=absent + fail_json: Source does not exist + fail_json: Data set type is NOT supported + fail_json: Creating backup has failed + fail_json: dsed return content is NOT in json format + """ module_args = dict( src=dict( type='str', From 18944a88c53b91c48f321ffe96dda3f9126a1477 Mon Sep 17 00:00:00 2001 From: IsaacVRey Date: Fri, 29 Mar 2024 16:58:31 -0600 Subject: [PATCH 2/3] Create changelog fragment --- changelogs/fragments/1355-update-docstring-zos_lineinfile.yml | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 changelogs/fragments/1355-update-docstring-zos_lineinfile.yml diff --git a/changelogs/fragments/1355-update-docstring-zos_lineinfile.yml b/changelogs/fragments/1355-update-docstring-zos_lineinfile.yml new file mode 100644 index 000000000..26942e514 --- /dev/null +++ b/changelogs/fragments/1355-update-docstring-zos_lineinfile.yml @@ -0,0 +1,3 @@ +trivial: + - zos_lineinfile - Updated docstrings to google style for visual aid to developers. + (https://github.com/ansible-collections/ibm_zos_core/pull/1355). \ No newline at end of file From 215dd0051ee687c14ee00552ac855efeeb688d6b Mon Sep 17 00:00:00 2001 From: IsaacVRey Date: Tue, 2 Apr 2024 14:26:25 -0600 Subject: [PATCH 3/3] Modify google style to numpy --- .../1355-update-docstring-zos_lineinfile.yml | 2 +- plugins/modules/zos_lineinfile.py | 149 +++++++++++------- 2 files changed, 92 insertions(+), 59 deletions(-) diff --git a/changelogs/fragments/1355-update-docstring-zos_lineinfile.yml b/changelogs/fragments/1355-update-docstring-zos_lineinfile.yml index 26942e514..3840b2862 100644 --- a/changelogs/fragments/1355-update-docstring-zos_lineinfile.yml +++ b/changelogs/fragments/1355-update-docstring-zos_lineinfile.yml @@ -1,3 +1,3 @@ trivial: - - zos_lineinfile - Updated docstrings to google style for visual aid to developers. + - zos_lineinfile - Updated docstrings to numpy style for visual aid to developers. (https://github.com/ansible-collections/ibm_zos_core/pull/1355). \ No newline at end of file diff --git a/plugins/modules/zos_lineinfile.py b/plugins/modules/zos_lineinfile.py index 630ac22ac..43e85061b 100644 --- a/plugins/modules/zos_lineinfile.py +++ b/plugins/modules/zos_lineinfile.py @@ -295,33 +295,45 @@ def present(src, line, regexp, ins_aft, ins_bef, encoding, first_match, backrefs, force): - """Replace a line with the matching regex pattern - Insert a line before/after the matching pattern - Insert a line at BOF/EOF - - Arguments: - src {str} -- The z/OS USS file or data set to modify. - line {str} -- The line to insert/replace into the src. - regexp {str} -- The regular expression to look for in every line of the src. - If regexp matches, ins_aft/ins_bef will be ignored. - ins_aft {str} -- Insert the line after matching '*regex*' pattern or EOF. - choices: - - EOF - - '*regex*' - ins_bef {str} -- Insert the line before matching '*regex*' pattern or BOF. - choices: - - BOF - - '*regex*' - encoding {str} -- Encoding of the src. - first_match {bool} -- Take the first matching regex pattern. - backrefs {bool} -- Back reference - force {bool} -- force for modify a member part of a task in execution - - Returns: - str -- Information in JSON format. keys: - cmd {str} -- dsed shell command - found {int} -- Number of matching regex pattern - changed {bool} -- Indicates if the source was modified. + """Replace a line with the matching regex pattern. + Insert a line before/after the matching pattern. + Insert a line at BOF/EOF. + + Parameters + ---------- + src : str + The z/OS USS file or data set to modify. + line : str + The line to insert/replace into the src. + regexp : str + The regular expression to look for in every line of the src. + If regexp matches, ins_aft/ins_bef will be ignored. + ins_aft : str + Insert the line after matching '*regex*' pattern or EOF. + choices: + - EOF + - '*regex*' + ins_bef : str + Insert the line before matching '*regex*' pattern or BOF. + choices: + - BOF + - '*regex*' + encoding : str + Encoding of the src. + first_match : bool + Take the first matching regex pattern. + backrefs : bool + Back reference. + force : bool + force for modify a member part of a task in execution. + + Returns + ------- + str + Information in JSON format. keys: + cmd {str} -- dsed shell command + found {int} -- Number of matching regex pattern + changed {bool} -- Indicates if the source was modified. """ return datasets.lineinfile( src, @@ -339,33 +351,45 @@ def present(src, line, regexp, ins_aft, ins_bef, encoding, first_match, backrefs def absent(src, line, regexp, encoding, force): - """Delete lines with matching regex pattern - - Arguments: - src {str} -- The z/OS USS file or data set to modify. - line {str} -- The line to be deleted in the src. If line matches, - regexp will be ignored. - regexp {str} -- The regular expression to look for in every line of the src. - encoding {str} -- Encoding of the src. - force {bool} -- force for modify a member part of a task in execution - - Returns: - str -- Information in JSON format. keys: - cmd {str} -- dsed shell command - found {int} -- Number of matching regex pattern - changed {bool} -- Indicates if the source was modified. + """Delete lines with matching regex pattern. + + Parameters + ---------- + src : str + The z/OS USS file or data set to modify. + line : str + The line to be deleted in the src. If line matches, + regexp will be ignored. + regexp : str + The regular expression to look for in every line of the src. + encoding : str + Encoding of the src. + force : bool + Force for modify a member part of a task in execution. + + Returns + ------- + str + Information in JSON format. keys: + cmd {str} -- dsed shell command + found {int} -- Number of matching regex pattern + changed {bool} -- Indicates if the source was modified. """ return datasets.lineinfile(src, line, regex=regexp, encoding=encoding, state=False, debug=True, force=force) def quotedString(string): - """Add escape if string was quoted + """Add escape if string was quoted. - Arguments: - string {str} -- Given string + Parameters + ---------- + string : str + Given string. - Returns: - str -- The string with the quote marks replaced + Returns + ------- + str + The string with the quote marks replaced. """ # add escape if string was quoted if not isinstance(string, str): @@ -374,17 +398,26 @@ def quotedString(string): def main(): - """Initialize the module - - Raises: - fail_json: Parameter verification failed. - fail_json: regexp is required with backrefs=true - fail_json: line is required with state=present - fail_json: One of line or regexp is required with state=absent - fail_json: Source does not exist - fail_json: Data set type is NOT supported - fail_json: Creating backup has failed - fail_json: dsed return content is NOT in json format + """Initialize the module. + + Raises + ------ + fail_json + Parameter verification failed. + fail_json + regexp is required with backrefs=true. + fail_json + line is required with state=present. + fail_json + One of line or regexp is required with state=absent. + fail_json + Source does not exist. + fail_json + Data set type is NOT supported. + fail_json + Creating backup has failed. + fail_json + dsed return content is NOT in json format. """ module_args = dict( src=dict(