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.

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

BodyLengthError – Indicates the commit body length did not validate. Will attempt to wrap the body and revalidate if self.options.rewrap 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_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()¶: 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.

Classes¶

ConventionalCommit¶

ConventionalCommitRunner¶

Config¶

pccc

Navigation

Related Topics