configuration

Configuration management for generate_changelog.

CLASS	DESCRIPTION
Configuration	Configuration options for generate-changelog.

FUNCTION	DESCRIPTION
get_config	Return the current configuration.
get_default_config	Create a new Configuration object with default values.
set_config	Set a configuration key to a value.
write_default_config	Write a default configuration file to the specified path.

ATTRIBUTE	DESCRIPTION
DEFAULT_CONFIG_FILE_NAME	Base default configuration file name
DEFAULT_CONFIG_FILE_NAMES	Valid permutations of the default configuration file name.
IntOrCallable	The type should be either an int or a callable that returns an int. TYPE: TypeAlias
RELEASE_TYPE_ORDER	The sort order of the release types.
StrOrCallable	The type should be either a string or a callable that returns a string. TYPE: TypeAlias

Attributes

DEFAULT_CONFIG_FILE_NAME module-attribute

DEFAULT_CONFIG_FILE_NAME = '.changelog-config'

Base default configuration file name

DEFAULT_CONFIG_FILE_NAMES module-attribute

DEFAULT_CONFIG_FILE_NAMES = [
    f"{DEFAULT_CONFIG_FILE_NAME}.yaml",
    f"{DEFAULT_CONFIG_FILE_NAME}.yml",
    DEFAULT_CONFIG_FILE_NAME,
]

Valid permutations of the default configuration file name.

IntOrCallable module-attribute

IntOrCallable: TypeAlias = Union[int, Callable[[], int]]

The type should be either an int or a callable that returns an int.

RELEASE_TYPE_ORDER module-attribute

RELEASE_TYPE_ORDER = (
    None,
    "no-release",
    "alpha",
    "beta",
    "dev",
    "pre-release",
    "release-candidate",
    "patch",
    "minor",
    "major",
)

The sort order of the release types.

StrOrCallable module-attribute

StrOrCallable: TypeAlias = Union[str, Callable[[], str]]

The type should be either a string or a callable that returns a string.

Classes

Configuration dataclass

Configuration(
    variables: dict = dict(),
    starting_tag_pipeline: Optional[list] = list(),
    unreleased_label: str = "Unreleased",
    summary_pipeline: list = list(),
    body_pipeline: list = list(),
    output_pipeline: list = list(),
    template_dirs: list = list(),
    group_by: list = list(),
    verbosity: int = 0,
    report_path: Optional[Path] = None,
    tag_pattern: str = "^[0-9]+\\.[0-9]+(?:\\.[0-9]+)?$",
    include_merges: bool = False,
    ignore_patterns: list = list(),
    commit_classifiers: list = list(),
    valid_author_tokens: list = list(),
    release_hint_rules: list = list(),
)

Configuration options for generate-changelog.

METHOD	DESCRIPTION
rendered_variables	Render each variable value using the previous variables as the context.
update_from_file	Updates this configuration instance in place from a YAML file.

ATTRIBUTE	DESCRIPTION
body_pipeline	Process the commit’s body for use in the changelog. TYPE: list
commit_classifiers	Set the commit’s category metadata to the first classifier that returns True. TYPE: list
group_by	Group the commits within a version by these commit attributes. TYPE: list
ignore_patterns	Ignore commits whose summary line matches any of these regular expression patterns. TYPE: list
include_merges	Tells git-log whether to include merge commits in the log. TYPE: bool
output_pipeline	Process and store the full or partial changelog. TYPE: list
release_hint_rules	Rules applied to commits to determine the type of release to suggest. TYPE: list
report_path	Path to write a report of the changelog to. TYPE: Optional[Path]
starting_tag_pipeline	Pipeline to find the most recent tag for incremental changelog generation. TYPE: Optional[list]
summary_pipeline	Process the commit’s first line for use in the changelog. TYPE: list
tag_pattern	Only tags matching this regular expression are used for the changelog. TYPE: str
template_dirs	Full or relative paths to look for output generation templates. TYPE: list
unreleased_label	Used as the version title of the changes since the last valid tag. TYPE: str
valid_author_tokens	Tokens in git commit trailers that indicate authorship. TYPE: list
variables	User variables for reference in other parts of the configuration. TYPE: dict
verbosity	Level of verbose logging output. TYPE: int

Attributes

body_pipeline class-attribute instance-attribute

body_pipeline: list = field(default_factory=list)

Process the commit’s body for use in the changelog.

commit_classifiers class-attribute instance-attribute

commit_classifiers: list = field(default_factory=list)

Set the commit’s category metadata to the first classifier that returns True.

group_by class-attribute instance-attribute

group_by: list = field(default_factory=list)

Group the commits within a version by these commit attributes.

ignore_patterns class-attribute instance-attribute

ignore_patterns: list = field(default_factory=list)

Ignore commits whose summary line matches any of these regular expression patterns.

include_merges class-attribute instance-attribute

include_merges: bool = False

Tells git-log whether to include merge commits in the log.

output_pipeline class-attribute instance-attribute

output_pipeline: list = field(default_factory=list)

Process and store the full or partial changelog.

release_hint_rules class-attribute instance-attribute

release_hint_rules: list = field(default_factory=list)

Rules applied to commits to determine the type of release to suggest.

report_path class-attribute instance-attribute

report_path: Optional[Path] = None

Path to write a report of the changelog to.

starting_tag_pipeline class-attribute instance-attribute

starting_tag_pipeline: Optional[list] = field(default_factory=list)

Pipeline to find the most recent tag for incremental changelog generation. Leave empty to always start at first commit.

summary_pipeline class-attribute instance-attribute

summary_pipeline: list = field(default_factory=list)

Process the commit’s first line for use in the changelog.

tag_pattern class-attribute instance-attribute

tag_pattern: str = '^[0-9]+\\.[0-9]+(?:\\.[0-9]+)?$'

Only tags matching this regular expression are used for the changelog.

template_dirs class-attribute instance-attribute

template_dirs: list = field(default_factory=list)

Full or relative paths to look for output generation templates.

unreleased_label class-attribute instance-attribute

unreleased_label: str = 'Unreleased'

Used as the version title of the changes since the last valid tag.

valid_author_tokens class-attribute instance-attribute

valid_author_tokens: list = field(default_factory=list)

Tokens in git commit trailers that indicate authorship.

variables class-attribute instance-attribute

variables: dict = field(default_factory=dict)

User variables for reference in other parts of the configuration.

verbosity class-attribute instance-attribute

verbosity: int = 0

Level of verbose logging output.

Functions

rendered_variables

rendered_variables() -> dict

Render each variable value using the previous variables as the context.

update_from_file

update_from_file(filename: Path) -> None

Updates this configuration instance in place from a YAML file.

PARAMETER	DESCRIPTION
filename	Path to the YAML file TYPE: Path

RAISES	DESCRIPTION
UsageError	if the path does not exist or is a directory

Functions

get_config

get_config() -> Configuration

Return the current configuration.

If the configuration has never been initialized, it is instantiated with the defaults.

RETURNS	DESCRIPTION
Configuration	The global configuration object.

get_default_config

get_default_config() -> Configuration

Create a new Configuration object with default values.

RETURNS	DESCRIPTION
Configuration	A new Configuration object

set_config

set_config(key: str, value: Any) -> Configuration

Set a configuration key to a value.

write_default_config

write_default_config(filename: Path) -> None

Write a default configuration file to the specified path.

PARAMETER	DESCRIPTION
filename	Path to write to TYPE: Path