tessl/pypi-commitizen

Python commitizen client tool for standardized commit conventions and automated version management

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Configuration

Name: tessl/pypi-commitizen
Author: tessl

Multi-format configuration system supporting TOML, JSON, and YAML formats with comprehensive settings for version management, changelog generation, and plugin configuration. Commitizen automatically discovers and loads configuration from various file formats in the project root.

Capabilities

Configuration Loading

Automatically discovers and loads configuration from multiple file formats with priority ordering.

def read_cfg(filepath: str | None = None) -> BaseConfig:
    """
    Read configuration from file or discover automatically.
    
    Searches for configuration in the following order when filepath is None:
    1. pyproject.toml [tool.commitizen]
    2. .cz.toml
    3. .cz.json  
    4. cz.json
    5. .cz.yaml
    6. cz.yaml
    7. cz.toml
    
    Parameters:
    - filepath: Optional path to specific configuration file
    
    Returns:
    BaseConfig instance with loaded settings
    """

Base Configuration

Abstract base class defining the configuration interface and common functionality.

class BaseConfig:
    """
    Base configuration class providing common configuration functionality.
    
    Handles settings management, validation, and environment variable substitution.
    """
    def __init__(self):
        """Initialize configuration with empty settings."""
    
    @property
    def settings(self) -> Settings:
        """Get configuration settings dictionary."""
    
    def set_key(self, key: str, value: Any) -> None:
        """
        Set configuration key-value pair.
        
        Parameters:
        - key: Configuration key
        - value: Configuration value
        """
    
    def add_path(self, path: Path | str) -> None:
        """
        Add configuration file path.
        
        Parameters:
        - path: Path to configuration file
        """
    
    @property
    def path(self) -> Path | None:
        """Get configuration file path."""

TOML Configuration

Configuration handler for TOML format files, including pyproject.toml integration.

class TomlConfig(BaseConfig):
    """
    TOML configuration file handler.
    
    Supports pyproject.toml [tool.commitizen] sections and standalone .cz.toml files.
    """
    def __init__(self, *, data: bytes | str, path: Path | str):
        """
        Initialize TOML configuration.
        
        Parameters:
        - data: TOML configuration data as bytes or string
        - path: Path to TOML configuration file
        """
    
    def init_empty_config_content(self) -> str:
        """
        Generate empty TOML configuration template.
        
        Returns:
        TOML configuration template string
        """
    
    def set_key(self, key: str, value: Any) -> None:
        """
        Set TOML configuration key-value pair.
        
        Parameters:
        - key: Configuration key
        - value: Configuration value
        """
    
    @property
    def is_empty_config(self) -> bool:
        """Check if TOML configuration is empty."""

JSON Configuration

Configuration handler for JSON format files.

class JsonConfig(BaseConfig):
    """
    JSON configuration file handler.
    
    Supports .cz.json and cz.json configuration files.
    """
    def __init__(self, *, data: bytes | str, path: Path | str):
        """
        Initialize JSON configuration.
        
        Parameters:
        - data: JSON configuration data as bytes or string
        - path: Path to JSON configuration file
        """
    
    def init_empty_config_content(self) -> str:
        """
        Generate empty JSON configuration template.
        
        Returns:
        JSON configuration template string
        """
    
    def set_key(self, key: str, value: Any) -> None:
        """
        Set JSON configuration key-value pair.
        
        Parameters:
        - key: Configuration key
        - value: Configuration value
        """
    
    @property
    def is_empty_config(self) -> bool:
        """Check if JSON configuration is empty."""

YAML Configuration

Configuration handler for YAML format files.

class YAMLConfig(BaseConfig):
    """
    YAML configuration file handler.
    
    Supports .cz.yaml and cz.yaml configuration files.
    """
    def __init__(self, *, data: bytes | str, path: Path | str):
        """
        Initialize YAML configuration.
        
        Parameters:
        - data: YAML configuration data as bytes or string
        - path: Path to YAML configuration file
        """
    
    def init_empty_config_content(self) -> str:
        """
        Generate empty YAML configuration template.
        
        Returns:
        YAML configuration template string
        """
    
    def set_key(self, key: str, value: Any) -> None:
        """
        Set YAML configuration key-value pair.
        
        Parameters:
        - key: Configuration key
        - value: Configuration value
        """
    
    @property
    def is_empty_config(self) -> bool:
        """Check if YAML configuration is empty."""

Configuration Settings

Core Settings

class Settings(TypedDict):
    """Core configuration settings for commitizen."""
    
    # Plugin and version settings
    name: str                           # Plugin name (e.g., "cz_conventional_commits")
    version: str                        # Current project version
    version_files: list[str]           # Files to update with new version
    version_scheme: str                # Version scheme (semver, pep440, etc.)
    version_provider: str | None       # Version provider (poetry, npm, etc.)
    version_type: str | None           # Version type override
    
    # Tag and commit settings  
    tag_format: str                    # Git tag format template
    bump_message: str                  # Commit message template for version bumps
    
    # Changelog settings
    changelog_file: str                # Changelog output file path
    changelog_format: str              # Changelog format (markdown, asciidoc, etc.)
    changelog_incremental: bool        # Generate incremental changelogs
    changelog_start_rev: str           # Starting revision for changelog
    changelog_merge_prerelease: bool   # Merge prerelease entries
    update_changelog_on_bump: bool     # Auto-update changelog during bump
    
    # Hook settings
    pre_bump_hooks: list[str] | None   # Commands to run before version bump
    post_bump_hooks: list[str] | None  # Commands to run after version bump
    
    # Behavior settings
    major_version_zero: bool           # Handle 0.x versions specially
    retry_after_failure: bool          # Retry operations after failure
    use_shortcuts: bool                # Enable command shortcuts
    allow_abort: bool                  # Allow abort commit messages
    allowed_prefixes: list[str]        # Additional allowed commit prefixes
    prerelease_offset: int             # Prerelease version offset
    always_signoff: bool               # Always add sign-off to commits
    
    # Template and customization
    template: str | None               # Changelog template file
    extras: dict[str, Any]             # Template extra variables
    style: list[tuple[str, str]]       # Output styling configuration
    customize: dict[str, Any]          # Plugin customization settings

Plugin-Specific Settings

class CzSettings(TypedDict):
    """Plugin-specific configuration settings."""
    
    # Message format settings
    message_template: str              # Commit message template
    example: str                       # Example commit message
    schema: str                        # Schema description
    schema_pattern: str                # Regex pattern for validation
    info: str                          # Plugin information text
    info_path: str | pathlib.Path      # Path to info file
    
    # Question configuration
    questions: list[dict[str, Any]]    # Interactive questions configuration
    
    # Version bump settings
    bump_pattern: str                  # Regex pattern for version increments
    bump_map: OrderedDict[str, str]    # Mapping of patterns to increment types
    bump_map_major_version_zero: OrderedDict[str, str]  # Special 0.x version mapping
    
    # Change type settings
    change_type_map: dict[str, str] | None  # Change type to display name mapping
    change_type_order: list[str]       # Order of change types in changelog
    
    # Parser settings
    commit_parser: str                 # Commit message parser pattern
    changelog_pattern: str             # Changelog entry pattern

Configuration Examples

Basic pyproject.toml Configuration

[tool.commitizen]
name = "cz_conventional_commits"
version = "1.0.0"
version_files = [
    "src/__version__.py",
    "pyproject.toml:version"
]
tag_format = "v$version"
update_changelog_on_bump = true

Advanced pyproject.toml Configuration

[tool.commitizen]
name = "cz_conventional_commits"
version = "2.1.0"
version_scheme = "semver"
version_provider = "poetry"
version_files = [
    "src/__version__.py",
    "pyproject.toml:version",
    "package.json:version"
]

# Git settings
tag_format = "v$version"
bump_message = "release $current_version → $new_version [skip-ci]"

# Changelog settings
changelog_file = "CHANGELOG.md"
changelog_format = "markdown"
changelog_incremental = true
changelog_start_rev = "v1.0.0"
changelog_merge_prerelease = true
update_changelog_on_bump = true

# Hook settings
pre_bump_hooks = [
    "scripts/run_tests.sh",
    "scripts/update_docs.sh"
]
post_bump_hooks = [
    "scripts/deploy.sh",
    "scripts/notify_team.sh"  
]

# Behavior settings
major_version_zero = false
retry_after_failure = true
use_shortcuts = true
allow_abort = false
always_signoff = false
prerelease_offset = 0

# Output styling
style = [
    ["question", "fg:blue bold"],
    ["answer", "fg:green"],
    ["error", "fg:red bold"]
]

Custom Plugin Configuration

[tool.commitizen]
name = "cz_customize"
version = "1.0.0"

[tool.commitizen.customize]
message_template = "{{change_type}}: {{message}}"
example = "feature: add new authentication system"
schema = "<type>: <description>"
schema_pattern = "(feat|fix|docs|style|refactor|test|chore):\\s.*"

bump_pattern = "^(feat|fix|BREAKING)"
bump_map = {
    "BREAKING" = "MAJOR",
    "feat" = "MINOR",
    "fix" = "PATCH"
}

change_type_order = ["BREAKING", "feat", "fix", "refactor", "docs"]
change_type_map = {
    "feat" = "Features", 
    "fix" = "Bug Fixes",
    "docs" = "Documentation"
}

[[tool.commitizen.customize.questions]]
type = "list"
name = "change_type"
message = "Select the type of change you are committing:"
choices = [
    {value = "feat", name = "feat: A new feature"},
    {value = "fix", name = "fix: A bug fix"},
    {value = "docs", name = "docs: Documentation changes"}
]

[[tool.commitizen.customize.questions]]
type = "input"
name = "message"
message = "Write a short description of the change:"

JSON Configuration Example

{
  "commitizen": {
    "name": "cz_conventional_commits",
    "version": "1.0.0",
    "version_files": [
      "package.json:version",
      "src/version.js"
    ],
    "tag_format": "v$version",
    "update_changelog_on_bump": true,
    "changelog_file": "CHANGELOG.md",
    "pre_bump_hooks": [
      "npm run test",
      "npm run build"
    ]
  }
}

YAML Configuration Example

commitizen:
  name: cz_conventional_commits
  version: 1.0.0
  version_files:
    - VERSION
    - setup.py:version  
  tag_format: "v$version"
  update_changelog_on_bump: true
  changelog_file: CHANGELOG.md
  pre_bump_hooks:
    - make test
    - make build
  post_bump_hooks:
    - make deploy

Programmatic Usage

from commitizen.config import BaseConfig, read_cfg
from pathlib import Path

# Load configuration from project
config = read_cfg()  # Auto-discovery
# or
config = read_cfg("pyproject.toml")  # Specific file

# Access settings
print(config.settings["name"])
print(config.settings["version"])

# Modify configuration
config.set_key("version", "2.0.0")
config.set_key("changelog_file", "HISTORY.md")

# Create configuration programmatically
custom_config = BaseConfig()
custom_config.set_key("name", "cz_conventional_commits")
custom_config.set_key("version", "1.0.0")
custom_config.set_key("version_files", ["setup.py:version"])
custom_config.set_key("tag_format", "v$version")

# Check configuration state
print(f"Configuration loaded from: {config.path}")

Install with Tessl CLI