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

footers

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, and number 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 an Config() 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
breaking-token :: ( BREAKING CHANGE | BREAKING-CHANGE )
footer-sep :: ( ': ' | ' #' )
breaking-value :: .*
breaking :: breaking-token footer-sep breaking-value
footer-token :: ( 'user defined footers' )
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? breaking? 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.

should_ignore()

Decide whether a commit message should be ignored.

Check if self.options.ignore_generated_commits is True and if the commit matches one of the regular expressions in self.options.generated_commits.

Returns

True if the commit matches a generated commit pattern and ignoring generated commits is allowed, False otherwise.

Return type

boolean

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

ValueError – Indicates the commit 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

ValueError – Indicates the commit message body 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

ValueError – Indicates the commit message header exceeds its configured length.

wrap()

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, rewrap=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; default is STDIN.

Type

string

config_file

Configuration file path; default is pyproject.toml.

Type

string

header_length

Maximum header length; default is 50.

Type

int

body_length

Maximum body line length; default is 72.

Type

int

repair

Repair commit, implying spell check and rewrap; default is False.

Type

boolean

rewrap

Rewrap body; default is False.

Type

boolean

spell_check

Spell check header and body; default is False.

Type

boolean

ignore_generated_commits

Ignore generated commits which match generated_commits regular expressions; default is False.

Type

boolean

generated_commits

List of generated commits, as Python regular expressions; default is []. For TOML files, it’s probably best to use the multiline single quote strings to reduce escaping problems.

Type

[string]

types

List of header types; default is ['feat', 'fix'].

Type

[string]

scopes

List of header scopes; default is [].

Type

[string]

footers

List of footers; default is [].

Type

[string]

required_footers

List of required footers; default is [].

Type

[string]

config_as_dict()

Convert a Config() object to a dict.

Convert a Config() object’s configuration parameters to a dict 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.

Handles any FileNotFound, JSONDecodeError, or TomlDecodeError exceptions that arise during loading of configuration file by ignoring the file.

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.