Detail Package

detail

class detail.Commit(data, tag_match=None)[source]

A commit object, parsed from a dictionary of formatted commit data. Allows one to easily see the tag.

property tag

Returns a Tag that contains the commit

class detail.Note(data, *, path, schema, commit=None)[source]

A note object with an optional associated commit

property is_valid

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

property validation_errors

Returns the schema formaldict.Errors that occurred during validation

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

Represents a range of notes. The range can be filtered and grouped using all of the methods in Notes.

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 NoteRange 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 detail.Notes(notes)[source]

A filterable and groupable collection of notes

When a list of Note 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 log templates.

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

Exclude notes by an attribute

Parameters

  • attr (str) – The name of the attribute on the Note 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

Notes

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

Filter notes by an attribute

Parameters

  • attr (str) – The name of the attribute on the Note 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 notes.

Return type

Notes

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

Group notes 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 Notes keyed on groups.

Return type

collections.OrderedDict

class detail.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

detail.detail(path=None)[source]

Creates or updates a note

Parameters

path (str, default=None) – A path to an existing note. If provided, the note will be updated.

Returns

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

Return type

subprocess.CompletedProcess

detail.lint(range='')[source]

Lint notes against a range (branch, sha, etc).

Linting passes when either succeed:

  • No commits are in the range.

  • Commits are found, and all notes pass linting. At least one note must be in the commit range.

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.

Raises
Returns

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

Return type

tuple(bool, NoteRange)

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

Renders notes.

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 file nickname to use when rendering. Defaults to “default”, which means .detail/log.tpl will be used to render. When used, the .detail/log_{{style}}.tpl file will be rendered.

  • template (str, default=None) – A template string to use when rendering. Supercedes any style provided.

  • 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 log.

Return type

str

detail.exceptions

exception detail.exceptions.CommitParseError[source]

For representing errors when parsing commits

exception detail.exceptions.Error[source]

The base error for all detail errors

exception detail.exceptions.GithubConfigurationError[source]

When not correctly set up for Github access

exception detail.exceptions.GithubPullRequestAPIError[source]

When an unexpected error happens with the Github pull request API

exception detail.exceptions.MultipleGithubPullRequestsFoundError[source]

When multiple Github pull requests have been opened

exception detail.exceptions.NoGithubPullRequestFoundError[source]

When no Github pull requests have been opened

exception detail.exceptions.SchemaError[source]

When an issue is found in the user-supplied schema