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
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 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

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 running spell_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 or self.options.force_wrap is True.
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=[]

footers¶

List of footers.

Type:: iterable of string, default=[]

required_footers¶

List of required footers.

Type:: iterable of string, default=[]

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.

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.

Classes¶

ConventionalCommit¶

ConventionalCommitRunner¶

Config¶

pccc

Navigation

Related Topics