Package
tidy
The core git-tidy
functions and classes that are utilized by
the :ref:cli
.
tidy.Commit
Bases: UserString
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.
Source code in tidy/core.py
is_parsed
property
True
if the commit has been parsed successfully.
If False
, only the sha
and msg
attributes
are available.
is_valid
property
True
if the commit was successfully validated against
the schema. If False
, some attributes in the schema may
be missing.
tidy.CommitRange
Bases: Commits
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).
Source code in tidy/core.py
tidy.Commits
Bases: Sequence
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
exclude(attr, value, match=False) -> Commits
Exclude commits by an attribute
Parameters:
Name | Type | Description | Default |
---|---|---|---|
attr |
str
|
The name of the attribute on the |
required |
value |
str | bool
|
The value to exclude by. |
required |
match |
bool, default=False
|
Treat |
False
|
Returns:
Type | Description |
---|---|
Commits
|
The excluded commits. |
Source code in tidy/core.py
filter
filter(attr, value, match=False) -> Commits
Filter commits by an attribute
Parameters:
Name | Type | Description | Default |
---|---|---|---|
attr |
str
|
The name of the attribute on the |
required |
value |
str | bool
|
The value to filter by. |
required |
match |
bool, default=False
|
Treat |
False
|
Returns:
Type | Description |
---|---|
Commits
|
The filtered commits. |
Source code in tidy/core.py
group
group(
attr,
ascending_keys=False,
descending_keys=False,
none_key_first=False,
none_key_last=False,
) -> dict[str, Commits]
Group commits by an attribute
Parameters:
Name | Type | Description | Default |
---|---|---|---|
attr |
str
|
The attribute to group by. |
required |
ascending_keys |
bool, default=False
|
Sort the keys in ascending order. |
False
|
descending_keys |
bool, default=False
|
Sort the keys in descending order. |
False
|
none_key_first |
bool, default=False
|
Make the "None" key be first. |
False
|
none_key_last |
bool, default=False
|
Make the "None" key be last. |
False
|
Returns:
Type | Description |
---|---|
dict[str, Commits]
|
A dictionary of |
Source code in tidy/core.py
tidy.Tag
Bases: UserString
A git tag.
date
property
date: datetime
Parse the date of the tag
Returns:
Name | Type | Description |
---|---|---|
datetime |
datetime
|
The tag parsed as a datetime object. |
from_sha
classmethod
from_sha(sha, tag_match=None) -> Tag
Create a Tag object from a sha or return None if there is no associated tag
Returns:
Type | Description |
---|---|
Tag
|
A constructed tag or |
Source code in tidy/core.py
tidy.commit
commit(no_verify=False, allow_empty=False, defaults=None) -> CompletedProcess
Performs a tidy git commit.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
no_verify |
bool, default=False
|
True if ignoring pre-commit hooks |
False
|
allow_empty |
bool, default=False
|
True if an empty commit should be allowed |
False
|
defaults |
dict, default=None
|
Defaults to be used when prompting for commit attributes. |
None
|
Returns:
Type | Description |
---|---|
CompletedProcess
|
The result from running git commit. Returns the git pre-commit hook results if |
CompletedProcess
|
failing during hook execution. |
Source code in tidy/core.py
tidy.lint
lint(range='', any=False) -> tuple[bool, CommitRange]
Lint commits against an upstream (branch, sha, etc).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
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. |
False
|
Raises:
Type | Description |
---|---|
`NoGithubPullRequestFoundError`
|
When using |
`MultipleGithubPullRequestsFoundError`
|
When using |
Returns:
Type | Description |
---|---|
tuple[bool, CommitRange]
|
A tuple of the lint result (True/False) and the associated CommitRange |
Source code in tidy/core.py
tidy.log
log(
range="",
style="default",
tag_match=None,
before=None,
after=None,
reverse=False,
output=None,
) -> str
Renders git logs using tidy rendering.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
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 |
'default'
|
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 |
None
|
before |
str, default=None
|
Only return commits before a specific
date. Passed directly to |
None
|
after |
str, default=None
|
Only return commits after a specific
date. Passed directly to |
None
|
reverse |
bool, default=False
|
Reverse ordering of results. Passed
directly to |
False
|
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. |
None
|
Raises:
Type | Description |
---|---|
`NoGithubPullRequestFoundError`
|
When using |
`MultipleGithubPullRequestsFoundError`
|
When using |
Returns:
Type | Description |
---|---|
str
|
The rendered tidy log. |
Source code in tidy/core.py
tidy.squash
squash(ref, no_verify=False, allow_empty=False) -> CompletedProcess
Squashes all commits since the common ancestor of ref.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
ref |
str
|
The git reference to squash against. Every commit after the common ancestor of this reference will be squashed. |
required |
no_verify |
bool, default=False
|
True if ignoring pre-commit hooks |
False
|
allow_empty |
bool, default=False
|
True if an empty commit should be allowed |
False
|
Raises:
Type | Description |
---|---|
`NoSquashableCommitsError`
|
When no commits can be squashed. |
CalledProcessError
|
If the first |
`NoGithubPullRequestFoundError`
|
When using |
`MultipleGithubPullRequestsFoundError`
|
When using |
Returns:
Type | Description |
---|---|
CompletedProcess
|
The commit result. The commit result contains either a failed pre-commit hook result or a |
CompletedProcess
|
successful/failed commit result. |
Source code in tidy/core.py
tidy.exceptions
tidy.exceptions.CommitParseError
Bases: Error
For representing errors when parsing commits
tidy.exceptions.Error
Bases: Exception
The base error for all tidy errors
tidy.exceptions.GithubConfigurationError
Bases: Error
When not correctly set up for Github access
tidy.exceptions.GithubPullRequestAPIError
Bases: Error
When an unexpected error happens with the Github pull request API
tidy.exceptions.MultipleGithubPullRequestsFoundError
Bases: Error
When multiple Github pull requests have been opened
tidy.exceptions.NoGithubPullRequestFoundError
Bases: Error
When no Github pull requests have been opened
tidy.exceptions.NoSquashableCommitsError
Bases: Error
When no commits can be squashed
tidy.exceptions.SchemaError
Bases: Error
When an issue is found in the user-supplied schema