Classes¶
ConventionalCommit¶
- class pccc.ConventionalCommit¶
Class describing a conventional commit.
Data structure containg the raw commit message, cleaned commit message, parsed conventional commit tokens, and parser exceptions for further use.
- raw¶
An unprocessed commit message.
- Type:
string
- cleaned¶
A cleaned, unparsed commit message.
- Type:
string
- header¶
Header fields and values.
- Type:
dict
- header["type"]
Header type.
- Type:
string
- header["scope"]
Header scope.
- Type:
string
- header["description"]
Header description.
- Type:
string
- header["length"]
The length of the header.
- Type:
int
- body¶
Body fields and values.
- Type:
dict
- body["paragraphs"]
The paragraphs of the body.
- Type:
[string]
- body["longest"]
The length of the longest body line.
- Type:
int
- breaking¶
Breaking change fields and values.
- Type:
dict
- breaking["flag"]
The breaking change flag is present, or not.
- Type:
boolean
- breaking["token"]
A string representing the breaking change token; either “BREAKING CHANGE” or “BREAKING-CHANGE” (for footer compatibility).
- Type:
string
- breaking["separator"]
A string representing the breaking change separator; either “: ” or “ #” (supposedly).
- Type:
string
- breaking["value"]
The breaking change value (description).
- Type:
string
An array of footer dicts, which are identical to the breaking dicts, without a “flag” field.
- Type:
[dict]
- closes_issues¶
An array of dicts, containing the
owner
,repo
, andnumber
keys, if available.- Type:
iterable of dict
- exc¶
ParseException raised during parsing, or
None
.- Type:
object
ConventionalCommitRunner¶
- class pccc.ConventionalCommitRunner¶
ConventionalCommit()
subclass with methods for execution.A
ConventionalCommit()
with addtional methods for loading, cleaning, and parsing a raw commit message as well as anConfig()
attribute for loading and accessing configuration information.- options¶
A
Config()
object for handling configuration.- Type:
object
- clean()¶
Clean a commit before parsing.
Remove all comment lines (matching the regular expression
"^\\s*#.*$"
) from a commit message before parsing.
- get()¶
Read a commit from a file or
STDIN
.Loads a the commit message from the file specified in the configuration, defaulting to
STDIN
.
- parse()¶
Parse a conventional commit message.
Parse a conventional commit message according to the specification, including user defined types, scopes, and footers.
BNF for conventional commit (v1.0.0):
type :: ( feat | fix | 'user defined types' ) scope :: '(' ( 'user defined scopes' ) ')' header-breaking-flag :: ! header-sep :: ': ' header-desc :: .* header :: type scope? header-breaking-flag? header-sep header-desc footer-token :: ( 'user defined footers' | BREAKING CHANGE | BREAKING-CHANGE ) footer-sep :: ( ': ' | ' #' ) footer-value :: .* footer :: footer-token footer-sep footer-value line :: .* newline :: '\n' skip :: newline newline par :: ( line newline )+ body :: skip par+ commit-msg :: header body? footer*
BNF for Github commit comment issue closing syntax:
closes-token :: 'github-closes' closes-sep :: footer-sep owner :: [a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38} repo :: [a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38} number :: [0-9]+ closes-value :: ( ( close[ds] | fix(ed|es) | resolve[ds] ) owner/repo#number )
- post_process()¶
Process commit after parsing.
- set_body_longest()¶
Calculate the length of the longest body line.
- set_breaking_longest()¶
Calculate the length of the longest breaking change line.
- should_ignore()¶
Decide whether a commit message should be ignored.
Check if
self.options.ignore_generated_commits
isTrue
and if the commit matches one of the regular expressions inself.options.generated_commits
.- Returns:
True
if the commit matches a generated commit pattern and ignoring generated commits is allowed,False
otherwise.- Return type:
boolean
- spell_check(parts=['header', 'body', 'breaking'])¶
Spell check the
parts
of the commit.Spell check the specified parts of the commit. Upon finding an error, add spell check information to
self.errors
. The information includes a line beginning with “# ERROR: ” indicating the problem word, a line beginning with “# TRY: ” listing suggestions from enchant, and a line beginning with “# IGNORE: “, which if present in the commit will cause the spell check to ignore that word.Rerunning
pccc
on the output will ignore all lines except the above “IGNORE” lines. None of these lines will be present in the final commit message. Manually adding “IGNORE” lines prior to runningspell_check()
will prevent checking the word.- Parameters:
parts (iterable, default = ["header", "body", "breaking"]) – The parts of the commit to be spell checked.
- validate()¶
Validate a commit after parsing.
Validate a commit on header and body lengths. Currently, there is no need to validate other fields as the commit will not parse if these are invalid.
- Returns:
True, if the commit validates.
- Return type:
boolean
- Raises:
BodyLengthError – Indicates the commit body length did not validate. Will attempt to wrap the body and revalidate if
self.options.wrap
orself.options.force_wrap
isTrue
.HeaderLengthError – Indicates the commit header length did not validate.
- validate_body_length()¶
Check that maximum body length is correct.
Check that the maximum body line length is less than or equal to
self.options.body_length
.- Returns:
True, if the body length validates.
- Return type:
boolean
- Raises:
BodyLengthError – Indicates the commit message body has a line that exceeds its configured maximum length.
- validate_breaking_length()¶
Check that maximum breaking change length is correct.
Check that the maximum breaking change line length is less than or equal to
self.options.body_length
.- Returns:
True, if the breaking change length validates.
- Return type:
boolean
- Raises:
BodyLengthError – Indicates the commit message breaking change has a line that exceeds its configured maximum length.
- validate_header_length()¶
Check that header length is correct.
Check that header length is less than or equal to
self.options.header_length
.- Returns:
True, if the header length validates.
- Return type:
boolean
- Raises:
HeaderLengthError – Indicates the commit message header exceeds its configured length.
- wrap(part='body')¶
Wrap a commit body to a given length.
Config¶
- class pccc.Config(commit='', config_file='pyproject.toml', header_length=50, body_length=72, repair=False, wrap=False, force_wrap=False, spell_check=False, ignore_generated_commits=False, generated_commits=[], types=['feat', 'fix'], scopes=[], footers=[], required_footers=[])¶
Class for accessing and loading pccc configuration options.
Provides default values for all pccc configuration options and loading methods for reading
pyproject.toml
and CLI options.- commit¶
Commit message location.
- Type:
string, default=”STDIN”
- config_file¶
Configuration file path.
- Type:
string, default=”pyproject.toml”
- header_length¶
Maximum header length.
- Type:
int, default=50
- body_length¶
Maximum body line length.
- Type:
int, default=72
- repair¶
Repair commit, implying spell check and wrap.
- Type:
boolean, default=False
- wrap¶
Wrap body and breaking change, if necessary.
- Type:
boolean, default=False
- force_wrap¶
Force wrap body and breaking change, regardless of length.
- Type:
boolean, default=False
- spell_check¶
Spell check commit message.
- Type:
boolean, default=False
- ignore_generated_commits¶
Ignore generated commits which match
generated_commits
regular expressions.- Type:
boolean, default=False
- generated_commits¶
List of generated commits, as Python regular expressions. For TOML files, it’s probably best to use the multiline single quote strings to reduce escaping problems.
- Type:
iterable of string, default=[]
- types¶
List of header types.
- Type:
iterable of string, default=[“feat”, “fix”]
- scopes¶
List of header scopes.
- Type:
iterable of string, default=[]
List of footers.
- Type:
iterable of string, default=[]
List of required footers.
- Type:
iterable of string, default=[]
- config_as_dict()¶
Convert a
Config()
object to adict
.Convert a
Config()
object’s configuration parameters to adict
for using in dumping TOML and JSON data.- Returns:
A
dict
containing key-value pairs of the configuration parameters and their values.- Return type:
dict
- load(argv=None)¶
Load configuration options.
Load configuration options from defaults (class constructor), file (either default or specified on CLI), then CLI, with later values overriding previous values.
Unset values are explicitly
None
at each level.
- set_format(format)¶
Set the output format.
Set the output format of
Config().__str__()
to either"TOML"
or"JSON"
.
- update(*args, **kwargs)¶
Update a configuration.
Update the current configuration object from the provided dictionary, ignoring any keys that are not attributes and values that are
None
. The provided key/value pairs override the original values in self.- Parameters:
kwargs (dict) – Key/value pairs of configuration options.
- validate()¶
Validate a configuration.
Validate the current configuration object to ensure compliance with the conventional commit specification. Current checks include: ensure that ‘fix’ and ‘feat’ are present in the
types
list.- Returns:
True for a valid configuration, raises on invalid configuration.
- Return type:
boolean
- Raises:
ValueError – Indicates a configuration value is incorrect.