hammurabi package¶
Subpackages¶
Submodules¶
hammurabi.config module¶
hammurabi.exceptions module¶
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])[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)
-
commit
()[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
()[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.
- Raises
AbortLawError
-
get_execution_order
() → List[hammurabi.rules.base.Rule][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]
-
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
Extending
hammurabi.mixins.GitMixin
to be able to open pull requests on GitHub after changes are pushed to remote.-
create_pull_request
()[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
-
static
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
-
-
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
()[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>
-
static
git_add
(param: pathlib.Path)[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)[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
git_remove
(param: pathlib.Path)[source]¶ Remove files from the working tree and from the index.
- Parameters
param (Path) – Path to remove from the working tree and the index
The following command is executed:
git rm <path>
-
property
has_changes
¶ Check if the rule made any changes. The check will return True if the git branch is dirty after the rule execution or the Rule set the
made_changes
attribute directly. In usual cases, themade_changes
attribute will not be set directly by any rule.- Returns
True if the git branch is dirty or
made_changes
attribute is True- Return type
bool
-
static
hammurabi.pillar module¶
Pillar module is responsible for handling the whole execution chain including managing a lock file, executing the registered laws, pushing the changes to the VCS and creating a pull request. All the laws registered to the pillar will be executed not in the order of the registration.
-
class
hammurabi.pillar.
Pillar
[source]¶ Bases:
hammurabi.mixins.GitHubMixin
Pillar is responsible for the execution of the chain of laws and rules. During the execution process a lock file will be created at the beginning of the process and at the end, the lock file will be released.
All the registered laws and rules can be retrieved using the
laws
andrules
properties, or if necessary single laws and rules can be accessed using the resource’s name as a parameter forget_law
orget_rule
methods.-
create_lock_file
()[source]¶ Create a lock file. If the lock file presents, the execution for the same target will be prevented.
-
enforce
()[source]¶ Run all the registered laws and rules one by one. This method is responsible for creating and releasing the lock file, executing the registered laws, push changes to the git origin and open the pull request.
This method glues together the lower level components and makes sure that the execution of laws and rules can not be called more than once at the same time for a target.
-
get_law
(name: str) → hammurabi.law.Law[source]¶ Get a law by its name. In case of no Laws are registered or the law can not be found by its name, a
StopIteration
exception will be raised.- Parameters
name (str) – Name of the law which will be used for the lookup
- Raises
StopIteration
exception if Law not found- Returns
Return the searched law
- Return type
-
get_rule
(name: str) → hammurabi.rules.base.Rule[source]¶ Get a registered rule (and its pipe/children) by the rule’s name.
This helper function is useful in debugging and information gathering.
- Parameters
name (str) – Name of the rule which will be used for the lookup
- Raises
StopIteration
exception if Rule not found- Returns
Return the rule in case of a match for the name
- Return type
-
property
laws
¶ Return the registered laws not in order of the registration.
-
register
(law: hammurabi.law.Law)[source]¶ Register the given Law to the Pillar. The order of the registration does not matter. The laws should never depend on each other.
- Parameters
law (
hammurabi.law.Law
) – Initialized Law which should be registered
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)
Warning
The laws should never depend on each other, because the execution may not happen in the same order the laws were registered. Instead, organize the depending rules in one law to resolve any dependency conflicts.
-
property
rules
¶ Return all the registered laws’ rules.
-