Tidy Package

tidy

The core git-tidy functions and classes that are utilized by the Tidy CLI.

class tidy.Commit(msg, schema, tag_match=None)[source]

Parses a commit message into structured components.

It is assumed the commit message is formatted as YAML by the appropriate “git log” command (see CommitRange). If data is able to be parsed, attributes of the commit can be accessed as attributes of this object. For example, a type attribute in the schema is accessible as Commit().type.

If the commit cannot be parsed as valid YAML for unexpected reasons, is_parsed is False and only a limited amount of attributes are available.

property is_parsed

True if the commit has been parsed successfully.

If False, only the sha and msg attributes are available.

property is_valid

True if the commit was successfully validated against the schema. If False, some attributes in the schema may be missing.

property msg

The raw git commit message

property tag

Returns a Tag that contains the commit

property validation_errors

Returns the schema formaldict.Errors that occurred during validation

class tidy.CommitRange(range='', tag_match=None, before=None, after=None, reverse=False)[source]

Represents a range of commits. The commit range can be filtered and grouped using all of the methods in Commits.

When doing git log, the user can provide a range (e.g. “origin/develop..”). Any range used in “git log” can be used as a range to the CommitRange object.

If the special :github/pr value is used as a range, the Github API is used to figure out the range based on a pull request opened from the current branch (if found).

class tidy.Commits(commits)[source]

A filterable and groupable collection of commits

When a list of Commit objects is organized in this sequence, the “group”, “filter”, and “exclude” chainable methods can be used for various access patterns. These access patterns are typically used when writing git tidy log templates.

exclude(attr, value, match=False)[source]

Exclude commits by an attribute

Parameters

  • attr (str) – The name of the attribute on the Commit object.

  • value (str|bool) – The value to exclude by.

  • match (bool, default=False) – Treat value as a regex pattern and match against it.

Returns

The excluded commits.

Return type

Commits

filter(attr, value, match=False)[source]

Filter commits by an attribute

Parameters

  • attr (str) – The name of the attribute on the Commit object.

  • value (str|bool) – The value to filter by.

  • match (bool, default=False) – Treat value as a regex pattern and match against it.

Returns

The filtered commits.

Return type

Commits

group(attr, ascending_keys=False, descending_keys=False, none_key_first=False, none_key_last=False)[source]

Group commits by an attribute

Parameters

  • attr (str) – The attribute to group by.

  • ascending_keys (bool, default=False) – Sort the keys in ascending order.

  • descending_keys (bool, default=False) – Sort the keys in descending order.

  • none_key_first (bool, default=False) – Make the “None” key be first.

  • none_key_last (bool, default=False) – Make the “None” key be last.

Returns

A dictionary of Commits keyed on groups.

Return type

collections.OrderedDict

class tidy.Tag(tag)[source]

A git tag.

property date

Parse the date of the tag

Returns

The tag parsed as a datetime object.

Return type

datetime

classmethod from_sha(sha, tag_match=None)[source]

Create a Tag object from a sha or return None if there is no associated tag

Returns

A constructed tag or None if no tags contain the commit.

Return type

Tag

tidy.commit(no_verify=False, allow_empty=False, defaults=None)[source]

Performs a tidy git commit.

Parameters

  • no_verify (bool, default=False) – True if ignoring pre-commit hooks

  • allow_empty (bool, default=False) – True if an empty commit should be allowed

  • defaults (dict, default=None) – Defaults to be used when prompting for commit attributes.

Returns

The result from running git commit. Returns the git pre-commit hook results if failing during hook execution.

Return type

subprocess.CompletedProcess

tidy.lint(range='', any=False)[source]

Lint commits against an upstream (branch, sha, etc).

Parameters

  • range (str, default='') – The git revision range against which linting happens. The special value of “:github/pr” can be used to lint against the remote branch of the pull request that is opened from the local branch. No range means linting will happen against all commits.

  • any (bool, default=False) – If True, linting will pass if at least one commit passes.

Raises
Returns

A tuple of the lint result (True/False) and the associated CommitRange

Return type

tuple(bool, CommitRange)

tidy.log(range='', style='default', tag_match=None, before=None, after=None, reverse=False, output=None)[source]

Renders git logs using tidy rendering.

Parameters

  • range (str, default='') – The git revision range over which logs are output. Using “:github/pr” as the range will use the base branch of an open github pull request as the range. No range will result in all commits being logged.

  • style (str, default="default") – The template to use when rendering. Defaults to “default”, which means .git-tidy/log.tpl will be used to render. When used, the .git-tidy/log_{{style}}.tpl file will be rendered.

  • tag_match (str, default=None) – A glob(7) pattern for matching tags when associating a tag with a commit in the log. Passed through to git describe --contains --matches when finding a tag.

  • before (str, default=None) – Only return commits before a specific date. Passed directly to git log --before.

  • after (str, default=None) – Only return commits after a specific date. Passed directly to git log --after.

  • reverse (bool, default=False) – Reverse ordering of results. Passed directly to git log --reverse.

  • output (str|file) – Path or file-like object to which the template is written. Using the special “:github/pr” output path will post the log as a comment on the pull request.

Raises
Returns

The rendered tidy log.

Return type

str

tidy.squash(ref, no_verify=False, allow_empty=False)[source]

Squashes all commits since the common ancestor of ref.

Parameters

  • ref (str) – The git reference to squash against. Every commit after the common ancestor of this reference will be squashed.

  • no_verify (bool, default=False) – True if ignoring pre-commit hooks

  • allow_empty (bool, default=False) – True if an empty commit should be allowed

Raises
Returns

The commit result. The commit result contains either a failed pre-commit hook result or a successful/failed commit result.

Return type

subprocess.CompletedProcess

tidy.exceptions

exception tidy.exceptions.CommitParseError[source]

For representing errors when parsing commits

exception tidy.exceptions.Error[source]

The base error for all tidy errors

exception tidy.exceptions.GithubConfigurationError[source]

When not correctly set up for Github access

exception tidy.exceptions.GithubPullRequestAPIError[source]

When an unexpected error happens with the Github pull request API

exception tidy.exceptions.MultipleGithubPullRequestsFoundError[source]

When multiple Github pull requests have been opened

exception tidy.exceptions.NoGithubPullRequestFoundError[source]

When no Github pull requests have been opened

exception tidy.exceptions.NoSquashableCommitsError[source]

When no commits can be squashed

exception tidy.exceptions.SchemaError[source]

When an issue is found in the user-supplied schema