hammurabi package¶

Subpackages¶

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.helpers module¶

hammurabi.helpers.full_strip(value: str) → str[source]¶: Strip every line.

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 of self.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 to True, 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 passed_rules¶

Return the rules which did modifications and not failed.

Returns: Return the passed rules
Return type: Tuple[Rule, ..]

property skipped_rules¶

Return the rules which neither modified the code nor failed.

Returns: Return the skipped rules
Return type: Tuple[Rule, ..]

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.