From 4b8da33ffd9a233e62d25eec851dc1b093f986de Mon Sep 17 00:00:00 2001 From: Thomas Steinbach Date: Mon, 19 Apr 2021 22:11:39 +0200 Subject: [PATCH 1/5] added full documentation of the rule module --- CHANGELOG.md | 1 + gcip/core/rule.py | 66 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6871ca0..a3a3141 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added * Added full API documentation of the `gcip.core.need` module. +* Added full API documentation of the `gcip.core.rule` module. ## [0.7.0] - 2021-04-19 diff --git a/gcip/core/rule.py b/gcip/core/rule.py index 55881f7..1a5ce14 100644 --- a/gcip/core/rule.py +++ b/gcip/core/rule.py @@ -1,3 +1,17 @@ +"""This module represents the Gitlab CI [rules](https://docs.gitlab.com/ee/ci/yaml/#rules) keyword. + +Use rules to include or exclude jobs in pipelines. + +``` +my_job.prepend_rules( + Rule( + if_statement='$CI_COMMIT_BRANCH == "master"', + when=WhenStatement.ON_FAILURE, + allow_failure: True, + ) + ) +``` +""" from __future__ import annotations from enum import Enum @@ -13,6 +27,8 @@ class WhenStatement(Enum): + """This enum holds diferent [when](https://docs.gitlab.com/ee/ci/yaml/#when) statements for `Rule`s.""" + ALWAYS = "always" DELAYED = "delayed" MANUAL = "manual" @@ -22,6 +38,19 @@ class WhenStatement(Enum): class Rule: + """This module represents the Gitlab CI [rules](https://docs.gitlab.com/ee/ci/yaml/#rules) keyword. + + [extended_summary] + + Args: + if_statement (Optional[str], optional): The [rules:if clause](https://docs.gitlab.com/ee/ci/yaml/#when) which decides when + a job to the pipeline. Defaults to None. + when (WhenStatement, optional): The [when](https://docs.gitlab.com/ee/ci/yaml/#when) attribute which decides when to run a job. + Defaults to WhenStatement.ON_SUCCESS. + allow_failure (bool, optional): The [allow_failure](https://docs.gitlab.com/ee/ci/yaml/#allow_failure) attribute which let a + job fail without impacting the rest of the CI suite. Defaults to False. + """ + def __init__( self, *args: Any, @@ -34,10 +63,47 @@ def __init__( self._allow_failure = allow_failure def never(self) -> Rule: + """ + This method returns a copy of this rule with the `when` attribute set to `WhenStatement.NEVER`. + + This method is intended to be used for predefined rules. For instance you have defined an + often used rule `on_master` whose if statement checks if the pipeline is executed on branch + `master`. Then you can either run a job, if on master... + + ``` + my_job.append_rules(on_master) + ``` + + ... or do not run a job if on master... + + ``` + my_job.append_rules(on_master.never()) + ``` + + Returns: + Rule: A new rule object with `when` set to `WhenStatement.NEVER`. + """ self._when = WhenStatement.NEVER return self + def copy(self) -> Rule: + """ + Returns an identical copy of that rule. + + Returns: + Rule: A new rule object with identical configuration. + """ + return Rule(self._if, self._when, self._allow_failure) + def render(self) -> Dict[str, Union[str, bool]]: + """Return a representation of this Rule object as dictionary with static values. + + The rendered representation is used by the gcip to dump it + in YAML format as part of the .gitlab-ci.yml pipeline. + + Returns: + Dict[str, Any]: A dictionary representing the rule object in Gitlab CI. + """ rendered_rule: Dict[str, Union[str, bool]] = {} if self._if: rendered_rule.update({"if": self._if}) From fed1196f7ac8296553f1058fc3566a9cd99ac310 Mon Sep 17 00:00:00 2001 From: Thomas Steinbach Date: Tue, 20 Apr 2021 10:25:22 +0200 Subject: [PATCH 2/5] Update gcip/core/rule.py --- gcip/core/rule.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gcip/core/rule.py b/gcip/core/rule.py index 1a5ce14..821a342 100644 --- a/gcip/core/rule.py +++ b/gcip/core/rule.py @@ -27,7 +27,7 @@ class WhenStatement(Enum): - """This enum holds diferent [when](https://docs.gitlab.com/ee/ci/yaml/#when) statements for `Rule`s.""" + """This enum holds different [when](https://docs.gitlab.com/ee/ci/yaml/#when) statements for `Rule`s.""" ALWAYS = "always" DELAYED = "delayed" From a19a2308cc253737bbaeb6044b29f6b99b4619c8 Mon Sep 17 00:00:00 2001 From: Thomas Steinbach Date: Tue, 20 Apr 2021 10:25:34 +0200 Subject: [PATCH 3/5] Update gcip/core/rule.py --- gcip/core/rule.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gcip/core/rule.py b/gcip/core/rule.py index 821a342..5688a51 100644 --- a/gcip/core/rule.py +++ b/gcip/core/rule.py @@ -40,7 +40,7 @@ class WhenStatement(Enum): class Rule: """This module represents the Gitlab CI [rules](https://docs.gitlab.com/ee/ci/yaml/#rules) keyword. - [extended_summary] + Use `rules` to include or exclude jobs in pipelines. Args: if_statement (Optional[str], optional): The [rules:if clause](https://docs.gitlab.com/ee/ci/yaml/#when) which decides when From 302e9cbf2ed4dd706367df9f1bf519e79987037b Mon Sep 17 00:00:00 2001 From: Thomas Steinbach Date: Mon, 19 Apr 2021 23:26:47 +0200 Subject: [PATCH 4/5] added documentation to the service module --- CHANGELOG.md | 1 + gcip/core/service.py | 23 ++++++++++++++++++++++- 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a3a3141..e8588f7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 * Added full API documentation of the `gcip.core.need` module. * Added full API documentation of the `gcip.core.rule` module. +* Added API documentation to the `gcip.core.service` module. ## [0.7.0] - 2021-04-19 diff --git a/gcip/core/service.py b/gcip/core/service.py index 9336777..5062b90 100644 --- a/gcip/core/service.py +++ b/gcip/core/service.py @@ -1,8 +1,29 @@ +"""**ALPHA** This module represents the Gitlab CI [Service](https://docs.gitlab.com/ee/ci/yaml/README.html#services) keyword. + +The services keyword defines a Docker image that runs during a job linked to the Docker image that the image keyword defines. +This allows you to access the service image during build time. + +Currently this module is an unfinished prototype. +""" + + class Service: - """This class represents the Gitlab CI [Service](https://docs.gitlab.com/ee/ci/yaml/README.html#services) keyword.""" + """**ALPHA** This class represents the Gitlab CI [Service](https://docs.gitlab.com/ee/ci/yaml/README.html#services) keyword. + + Currently there is nothing more implemented than providing a service name. In general the `service` functionality + currently isn't well implemented, as is is only available for `gcip.core.pipeline.Pipeline`s. + """ def __init__(self, name: str): self._name = name def render(self) -> str: + """Return a representation of this Service object as dictionary with static values. + + The rendered representation is used by the gcip to dump it + in YAML format as part of the .gitlab-ci.yml pipeline. + + Returns: + Dict[str, Any]: A dictionary representing the service object in Gitlab CI. + """ return self._name From ac7e2cabef284b96dee92036bda1bd8707ce8770 Mon Sep 17 00:00:00 2001 From: Thomas Steinbach Date: Tue, 20 Apr 2021 10:27:35 +0200 Subject: [PATCH 5/5] Update gcip/core/service.py --- gcip/core/service.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gcip/core/service.py b/gcip/core/service.py index 5062b90..b0fedca 100644 --- a/gcip/core/service.py +++ b/gcip/core/service.py @@ -11,7 +11,7 @@ class Service: """**ALPHA** This class represents the Gitlab CI [Service](https://docs.gitlab.com/ee/ci/yaml/README.html#services) keyword. Currently there is nothing more implemented than providing a service name. In general the `service` functionality - currently isn't well implemented, as is is only available for `gcip.core.pipeline.Pipeline`s. + currently isn't well implemented, as it is only available for `gcip.core.pipeline.Pipeline`s. """ def __init__(self, name: str):