hammurabi package¶
Subpackages¶
- hammurabi.notifications package
- hammurabi.preconditions package
- hammurabi.reporters package
- hammurabi.rules package
- Submodules
- hammurabi.rules.abstract module
- hammurabi.rules.attributes module
- hammurabi.rules.base module
- hammurabi.rules.common module
- hammurabi.rules.dictionaries module
- hammurabi.rules.directories module
- hammurabi.rules.files module
- hammurabi.rules.ini module
- hammurabi.rules.json module
- hammurabi.rules.mixins module
- hammurabi.rules.operations module
- hammurabi.rules.templates module
- hammurabi.rules.text module
- hammurabi.rules.yaml module
- Module contents
Submodules¶
hammurabi.config module¶
hammurabi.exceptions module¶
-
exception
hammurabi.exceptions.
AbortLawError
[source]¶ Bases:
Exception
Custom exception to make sure that own exception types are caught by the Law’s execution.
-
exception
hammurabi.exceptions.
NotificationSendError
[source]¶ Bases:
Exception
Custom exception to make sure that own exception types are caught when sending notifications.
-
exception
hammurabi.exceptions.
PreconditionFailedError
[source]¶ Bases:
Exception
Custom exception representing a failed precondition. In case a precondition failed, there is no need to raise an error and report the rule as a failure. The precondition is for checking that a rule should or shouldn’t run; not for breaking the execution.
hammurabi.law module¶
This module contains the definition of Law which is responsible for the execution of its registered Rules. Every Law can have multiple rules to execute.
In case a rule raises an exception the execution may abort and none of
the remaining rules will be executed neither pipes or children. An abort
can cause an inconsistent state or a dirty git branch. If rule_can_abort
config is set to True, the whole execution of the :class:hammurabi.pillar.Pillar
will be aborted and the original exception will be re-raised.
-
class
hammurabi.law.
Law
(name: str, description: str, rules: Iterable[hammurabi.rules.base.Rule], preconditions: Iterable[hammurabi.preconditions.base.Precondition] = ())[source]¶ Bases:
hammurabi.mixins.GitMixin
A Law is a collection of Rules which is responsible for the rule execution and git committing.
Example usage:
>>> from pathlib import Path >>> from hammurabi import Law, Pillar, FileExists >>> >>> example_law = Law( >>> name="Name of the law", >>> description="Well detailed description what this law does.", >>> rules=( >>> FileExists( >>> name="Create pyproject.toml", >>> path=Path("./pyproject.toml") >>> ), >>> ) >>> ) >>> >>> pillar = Pillar() >>> pillar.register(example_law)
-
property
can_proceed
¶ Evaluate if the execution can be continued. If preconditions are set, those will be evaluated by this method.
- Returns
Return with the result of evaluation
- Return type
bool
Warning
hammurabi.rules.base.Rule.can_proceed()
checks the result ofself.preconditions
, which means the preconditions are executed. Make sure that you are not doing any modifications within rules used as preconditions, otherwise take extra attention for those rules.
-
commit
() → None[source]¶ Commit the changes made by registered rules and add a meaningful commit message.
Example commit message:
Migrate to next generation project template * Create pyproject.toml * Add meta info from setup.py to pyproject.toml * Add existing dependencies * Remove requirements.txt * Remove setup.py
-
property
documentation
¶ Get the name and description of the Law object.
- Returns
Return the name and description of the law as its documentation
- Return type
str
-
enforce
() → None[source]¶ Execute all registered rule. If
rule_can_abort
config option is set toTrue
, all the rules will be aborted and an exception will be raised.When the whole execution chain is finished, the changes will be committed except the failed ones.
Note
Failed rules and their chain (excluding prerequisites) will be added to the pull request description.
- Raises
AbortLawError
-
property
failed_rules
¶ Return the rules which did modifications and failed.
- Returns
Return the failed rules
- Return type
Union[Tuple[()], Tuple[Rule]]
-
get_execution_order
() → List[Union[hammurabi.rules.base.Rule, hammurabi.preconditions.base.Precondition]][source]¶ Get the execution order of the registered rules. The order will contain the pipes and children as well.
This helper function is useful in debugging and information gathering.
- Returns
Return the execution order of the rules
- Return type
List[Rule]
-
property
hammurabi.main module¶
hammurabi.mixins module¶
Mixins module contains helpers for both laws and rules. Usually this file will contain Git commands related helpers. Also, this module contains the extensions for several online git based VCS.
-
class
hammurabi.mixins.
GitHubMixin
[source]¶ Bases:
hammurabi.mixins.GitMixin
,hammurabi.mixins.PullRequestHelperMixin
Extending
hammurabi.mixins.GitMixin
to be able to open pull requests on GitHub after changes are pushed to remote.-
create_pull_request
() → Optional[str][source]¶ Create a PR on GitHub after the changes are pushed to remote. The pull request details (repository, branch) are set by the project configuration. The mapping of the details and configs:
Detail
Configuration
repo
repository (owner/repository format)
base
git_base_name
branch
git_branch_name
- Returns
Return the open (and updated) or opened PR’s url
- Return type
Optional[str]
-
-
class
hammurabi.mixins.
GitMixin
[source]¶ Bases:
object
Simple mixin which contains all the common git commands which are needed to push a change to an online VCS like GitHub or GitLab. This mixin could be used by
hammurabi.law.Law`s, :class:`hammurabi.rules.base
or any rules which can make modifications during its execution.-
static
checkout_branch
() → None[source]¶ Perform a simple git checkout, to not pollute the default branch and use that branch for the pull request later. The branch name can be changed in the config by setting the
git_branch_name
config option.The following command is executed:
git checkout -b <branch name>
-
git_add
(param: pathlib.Path) → None[source]¶ Add file contents to the index.
- Parameters
param (Path) – Path to add to the index
The following command is executed:
git add <path>
-
git_commit
(message: str) → None[source]¶ Commit the changes on the checked out branch.
- Parameters
message (str) – Git commit message
The following command is executed:
git commit -m "<commit message>"
-
static
-
class
hammurabi.mixins.
PullRequestHelperMixin
[source]¶ Bases:
object
Give helper classes for pull request related operations
-
generate_pull_request_body
(pillar) → str[source]¶ Generate the body of the pull request based on the registered laws and rules. The pull request body is markdown formatted.
- Parameters
pillar (
hammurabi.pillar.Pillar
) – Pillar configuration- Returns
Returns the generated pull request description
- Return type
str
-