commitizen 4.8.2__tar.gz → 4.8.4__tar.gz

commitizen-4.8.4/PKG-INFO

@@ -0,0 +1,392 @@
+Metadata-Version: 2.3
+Name: commitizen
+Version: 4.8.4
+Summary: Python commitizen client tool
+License: MIT License
+         
+         Copyright (c) 2017 Santiago
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Keywords: commitizen,conventional,commits,git
+Author: Santiago Fraire
+Author-email: santiwilly@gmail.com
+Maintainer: Wei Lee
+Maintainer-email: weilee.rx@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: argcomplete (>=1.12.1,<3.7)
+Requires-Dist: charset-normalizer (>=2.1.0,<4)
+Requires-Dist: colorama (>=0.4.1,<1.0)
+Requires-Dist: decli (>=0.6.0,<1.0)
+Requires-Dist: importlib-metadata (>=8.0.0,<8.7.0) ; python_version < "3.10"
+Requires-Dist: jinja2 (>=2.10.3)
+Requires-Dist: packaging (>=19)
+Requires-Dist: prompt_toolkit (!=3.0.52)
+Requires-Dist: pyyaml (>=3.08)
+Requires-Dist: questionary (>=2.0,<3.0)
+Requires-Dist: termcolor (>=1.1.0,<4.0.0)
+Requires-Dist: tomlkit (>=0.5.3,<1.0.0)
+Requires-Dist: typing-extensions (>=4.0.1,<5.0.0) ; python_version < "3.11"
+Project-URL: Changelog, https://github.com/commitizen-tools/commitizen/blob/master/CHANGELOG.md
+Project-URL: Documentation, https://commitizen-tools.github.io/commitizen/
+Project-URL: Homepage, https://github.com/commitizen-tools/commitizen
+Project-URL: Issues, https://github.com/commitizen-tools/commitizen/issues
+Project-URL: Repository, https://github.com/commitizen-tools/commitizen
+Description-Content-Type: text/markdown
+
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/commitizen-tools/commitizen/pythonpackage.yml?label=python%20package&logo=github&logoColor=white&style=flat-square)](https://github.com/commitizen-tools/commitizen/actions)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square)](https://conventionalcommits.org)
+[![PyPI Package latest release](https://img.shields.io/pypi/v/commitizen.svg?style=flat-square)](https://pypi.org/project/commitizen/)
+[![PyPI Package download count (per month)](https://img.shields.io/pypi/dm/commitizen?style=flat-square)](https://pypi.org/project/commitizen/)
+[![Supported versions](https://img.shields.io/pypi/pyversions/commitizen.svg?style=flat-square)](https://pypi.org/project/commitizen/)
+[![Conda Version](https://img.shields.io/conda/vn/conda-forge/commitizen?style=flat-square)](https://anaconda.org/conda-forge/commitizen)
+[![homebrew](https://img.shields.io/homebrew/v/commitizen?color=teal&style=flat-square)](https://formulae.brew.sh/formula/commitizen)
+[![Codecov](https://img.shields.io/codecov/c/github/commitizen-tools/commitizen.svg?style=flat-square)](https://codecov.io/gh/commitizen-tools/commitizen)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?style=flat-square&logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+
+![Using Commitizen cli](images/demo.gif)
+
+---
+
+[**Commitizen Documentation Site**](https://commitizen-tools.github.io/commitizen/)
+
+---
+
+## About
+
+Commitizen is a powerful release management tool that helps teams maintain consistent and meaningful commit messages while automating version management.
+
+### What Commitizen Does
+
+By enforcing standardized commit conventions (defaulting to [Conventional Commits][conventional_commits]), Commitizen helps teams:
+
+- Write clear, structured commit messages
+- Automatically manage version numbers using semantic versioning
+- Generate and maintain changelogs
+- Streamline the release process
+
+### Key Benefits
+
+With just a simple `cz bump` command, Commitizen handles:
+
+1. **Version Management**: Automatically bumps version numbers and updates version files based on your commit history
+2. **Changelog Generation**: Creates and updates changelogs following the [Keep a changelog][keepchangelog] format
+3. **Commit Standardization**: Enforces consistent commit message formats across your team
+
+This standardization makes your commit history more readable and meaningful, while the automation reduces manual work and potential errors in the release process.
+
+### Features
+
+- Interactive CLI for standardized commits with default [Conventional Commits][conventional_commits] support
+- Intelligent [version bumping](https://commitizen-tools.github.io/commitizen/commands/bump/) using [Semantic Versioning][semver]
+- Automatic [keep a changelog][keepchangelog] generation
+- Built-in commit validation with pre-commit hooks
+- [Customizable](https://commitizen-tools.github.io/commitizen/customization/) commit rules and templates
+- Multi-format version file support
+- Custom rules and plugins via pip
+
+## Getting Started
+
+### Requirements
+
+Before installing Commitizen, ensure you have:
+
+- [Python](https://www.python.org/downloads/) `3.9+`
+- [Git][gitscm] `1.8.5.2+`
+
+### Installation
+
+#### Global Installation (Recommended)
+
+The recommended way to install Commitizen is using [`pipx`](https://pipx.pypa.io/) or [`uv`](https://docs.astral.sh/uv/), which ensures a clean, isolated installation:
+
+**Using pipx:**
+```bash
+# Install Commitizen
+pipx install commitizen
+
+# Keep it updated
+pipx upgrade commitizen
+```
+
+**Using uv:**
+```bash
+# Install commitizen
+uv tool install commitizen
+
+# Keep it updated
+uv tool upgrade commitizen
+```
+
+**(For macOS users) Using Homebrew:**
+```bash
+brew install commitizen
+```
+
+#### Project-Specific Installation
+
+You can add Commitizen to your Python project using any of these package managers:
+
+**Using pip:**
+```bash
+pip install -U commitizen
+```
+
+**Using conda:**
+```bash
+conda install -c conda-forge commitizen
+```
+
+**Using Poetry:**
+```bash
+# For Poetry >= 1.2.0
+poetry add commitizen --group dev
+
+# For Poetry < 1.2.0
+poetry add commitizen --dev
+```
+
+**Using uv:**
+```bash
+uv add --dev commitizen
+```
+
+**Using pdm:**
+```bash
+pdm add -d commitizen
+```
+
+### Basic Commands
+
+#### Initialize Commitizen
+
+To get started, you'll need to set up your configuration. You have two options:
+
+1. Use the interactive setup:
+```sh
+cz init
+```
+
+2. Manually create a configuration file (`.cz.toml` or `cz.toml`):
+```toml
+[tool.commitizen]
+version = "0.1.0"
+update_changelog_on_bump = true
+```
+
+#### Create Commits
+
+Create standardized commits using:
+```sh
+cz commit
+# or use the shortcut
+cz c
+```
+
+To sign off your commits:
+```sh
+cz commit -- --signoff
+# or use the shortcut
+cz commit -- -s
+```
+
+For more commit options, run `cz commit --help`.
+
+#### Version Management
+
+The most common command you'll use is:
+```sh
+cz bump
+```
+
+This command:
+
+- Bumps your project's version
+- Creates a git tag
+- Updates the changelog (if `update_changelog_on_bump` is enabled)
+- Updates version files
+
+You can customize:
+
+- [Version files](https://commitizen-tools.github.io/commitizen/commands/bump/#version_files)
+- [Version scheme](https://commitizen-tools.github.io/commitizen/commands/bump/#version_scheme)
+- [Version provider](https://commitizen-tools.github.io/commitizen/config/#version-providers)
+
+For all available options, see the [bump command documentation](https://commitizen-tools.github.io/commitizen/commands/bump/).
+
+### Advanced Usage
+
+#### Get Project Version
+
+```sh
+# Get your project's version (instead of Commitizen's version)
+cz version -p
+# Preview changelog changes
+cz changelog --dry-run "$(cz version -p)"
+```
+
+This command is particularly useful for automation scripts and CI/CD pipelines.
+
+For example, you can use the output of the command `cz changelog --dry-run "$(cz version -p)"` to notify your team about a new release in Slack.
+
+#### Pre-commit Integration
+
+Commitizen can automatically validate your commit messages using pre-commit hooks.
+
+1. Add to your `.pre-commit-config.yaml`:
+```yaml
+---
+repos:
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: master  # Replace with latest tag
+    hooks:
+      - id: commitizen
+      - id: commitizen-branch
+        stages: [pre-push]
+```
+
+2. Install the hooks:
+```sh
+pre-commit install --hook-type commit-msg --hook-type pre-push
+```
+
+| Hook              | Recommended Stage |
+| ----------------- | ----------------- |
+| commitizen        | commit-msg        |
+| commitizen-branch | pre-push          |
+
+> **Note**: Replace `master` with the [latest tag](https://github.com/commitizen-tools/commitizen/tags) to avoid warnings. You can automatically update this with:
+> ```sh
+> pre-commit autoupdate
+> ```
+
+For more details about commit validation, see the [check command documentation](https://commitizen-tools.github.io/commitizen/commands/check/).
+
+## Help & Reference
+
+### Command Line Interface
+
+Commitizen provides a comprehensive CLI with various commands. Here's the complete reference:
+
+![cz --help](images/cli_help/cz___help.svg)
+
+### Quick Reference
+
+| Command | Description | Alias |
+|---------|-------------|-------|
+| `cz init` | Initialize Commitizen configuration | - |
+| `cz commit` | Create a new commit | `cz c` |
+| `cz bump` | Bump version and update changelog | - |
+| `cz changelog` | Generate changelog | `cz ch` |
+| `cz check` | Validate commit messages | - |
+| `cz version` | Show version information | - |
+
+### Additional Resources
+
+- [Conventional Commits Specification][conventional_commits]
+- [Exit Codes Reference](https://commitizen-tools.github.io/commitizen/exit_codes/)
+- [Configuration Guide](https://commitizen-tools.github.io/commitizen/config/)
+- [Command Documentation](https://commitizen-tools.github.io/commitizen/commands/init/)
+
+### Getting Help
+
+For each command, you can get detailed help by adding `--help`:
+
+```sh
+cz commit --help
+cz bump --help
+cz changelog --help
+```
+
+For more details, visit our [documentation site](https://commitizen-tools.github.io/commitizen/).
+
+## Setting up bash completion
+
+Commitizen supports command-line completion through [argcomplete](https://kislyuk.github.io/argcomplete/), which is automatically installed as a dependency. This feature provides intelligent auto-completion for all Commitizen commands and options.
+
+### Supported Shells
+
+- **Bash**: Full support
+- **Zsh**: Limited support
+- **Fish**: Limited support
+- **Tcsh**: Limited support
+
+### Installation Methods
+
+#### Global Installation (Recommended)
+
+If you installed Commitizen globally (e.g., using `pipx` or `brew`), you can enable global completion:
+
+```bash
+# Enable global completion for all Python applications
+sudo activate-global-python-argcomplete
+```
+
+#### User-Specific Installation
+
+For a user-specific installation that persists across sessions:
+
+```bash
+# Add to your shell's startup file (e.g., ~/.bashrc, ~/.zshrc)
+register-python-argcomplete cz >> ~/.bashrc
+```
+
+#### Temporary Installation
+
+For one-time activation in your current shell session:
+
+```bash
+# Activate completion for current session only
+eval "$(register-python-argcomplete cz)"
+```
+
+### Verification
+
+After installation, you can verify the completion is working by:
+
+1. Opening a new terminal session
+2. Typing `cz` followed by a space and pressing `TAB` twice
+3. You should see a list of available commands
+
+For more detailed information about argcomplete configuration and troubleshooting, visit the [argcomplete documentation](https://kislyuk.github.io/argcomplete/).
+
+## Sponsors
+
+These are our cool sponsors!
+
+<!-- sponsors --><!-- sponsors -->
+
+[conventional_commits]: https://www.conventionalcommits.org
+[semver]: https://semver.org/
+[keepchangelog]: https://keepachangelog.com/
+[gitscm]: https://git-scm.com/downloads
+

{commitizen-4.8.2 → commitizen-4.8.4}/commitizen/__init__.py

@@ -1,7 +1,7 @@
 import logging
 import logging.config
 
-from colorama import init  # type: ignore
+from colorama import init
 
 from commitizen.cz.base import BaseCommitizen
 

commitizen-4.8.4/commitizen/__version__.py

@@ -0,0 +1 @@
+__version__ = "4.8.4"

{commitizen-4.8.2 → commitizen-4.8.4}/commitizen/bump.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import os
 import re
 from collections import OrderedDict
+from collections.abc import Iterable
 from glob import iglob
 from logging import getLogger
 from string import Template
@@ -61,7 +62,7 @@ def find_increment(
 def update_version_in_files(
     current_version: str,
     new_version: str,
-    files: list[str],
+    files: Iterable[str],
     *,
     check_consistency: bool = False,
     encoding: str = ENCODING,
@@ -76,7 +77,7 @@ def update_version_in_files(
     """
     # TODO: separate check step and write step
     updated = []
-    for path, regex in files_and_regexs(files, current_version):
+    for path, regex in _files_and_regexes(files, current_version):
         current_version_found, version_file = _bump_with_regex(
             path,
             current_version,
@@ -99,21 +100,22 @@ def update_version_in_files(
     return updated
 
 
-def files_and_regexs(patterns: list[str], version: str) -> list[tuple[str, str]]:
+def _files_and_regexes(patterns: Iterable[str], version: str) -> list[tuple[str, str]]:
     """
     Resolve all distinct files with their regexp from a list of glob patterns with optional regexp
     """
-    out = []
+    out: set[tuple[str, str]] = set()
     for pattern in patterns:
         drive, tail = os.path.splitdrive(pattern)
         path, _, regex = tail.partition(":")
         filepath = drive + path
         if not regex:
-            regex = _version_to_regex(version)
+            regex = re.escape(version)
 
-        for path in iglob(filepath):
-            out.append((path, regex))
-    return sorted(list(set(out)))
+        for file in iglob(filepath):
+            out.add((file, regex))
+
+    return sorted(out)
 
 
 def _bump_with_regex(
@@ -128,18 +130,16 @@ def _bump_with_regex(
     pattern = re.compile(regex)
     with open(version_filepath, encoding=encoding) as f:
         for line in f:
-            if pattern.search(line):
-                bumped_line = line.replace(current_version, new_version)
-                if bumped_line != line:
-                    current_version_found = True
-                lines.append(bumped_line)
-            else:
+            if not pattern.search(line):
                 lines.append(line)
-    return current_version_found, "".join(lines)
+                continue
 
+            bumped_line = line.replace(current_version, new_version)
+            if bumped_line != line:
+                current_version_found = True
+            lines.append(bumped_line)
 
-def _version_to_regex(version: str) -> str:
-    return version.replace(".", r"\.").replace("+", r"\+")
+    return current_version_found, "".join(lines)
 
 
 def create_commit_message(

{commitizen-4.8.2 → commitizen-4.8.4}/commitizen/changelog.py

@@ -29,10 +29,10 @@ from __future__ import annotations
 
 import re
 from collections import OrderedDict, defaultdict
-from collections.abc import Iterable
+from collections.abc import Generator, Iterable, Mapping, Sequence
 from dataclasses import dataclass
 from datetime import date
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from jinja2 import (
     BaseLoader,
@@ -63,7 +63,7 @@ class Metadata:
     latest_version_position: int | None = None
     latest_version_tag: str | None = None
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if self.latest_version and not self.latest_version_tag:
             # Test syntactic sugar
             # latest version tag is optional if same as latest version
@@ -84,7 +84,7 @@ def generate_tree_from_commits(
     changelog_message_builder_hook: MessageBuilderHook | None = None,
     changelog_release_hook: ChangelogReleaseHook | None = None,
     rules: TagRules | None = None,
-) -> Iterable[dict]:
+) -> Generator[dict[str, Any], None, None]:
     pat = re.compile(changelog_pattern)
     map_pat = re.compile(commit_parser, re.MULTILINE)
     body_map_pat = re.compile(commit_parser, re.MULTILINE | re.DOTALL)
@@ -169,8 +169,8 @@ def process_commit_message(
     commit: GitCommit,
     changes: dict[str | None, list],
     change_type_map: dict[str, str] | None = None,
-):
-    message: dict = {
+) -> None:
+    message: dict[str, Any] = {
         "sha1": commit.rev,
         "parents": commit.parents,
         "author": commit.author,
@@ -187,24 +187,27 @@ def process_commit_message(
             changes[change_type].append(msg)
 
 
-def order_changelog_tree(tree: Iterable, change_type_order: list[str]) -> Iterable:
+def generate_ordered_changelog_tree(
+    tree: Iterable[Mapping[str, Any]], change_type_order: list[str]
+) -> Generator[dict[str, Any], None, None]:
     if len(set(change_type_order)) != len(change_type_order):
         raise InvalidConfigurationError(
-            f"Change types contain duplicates types ({change_type_order})"
+            f"Change types contain duplicated types ({change_type_order})"
         )
 
-    sorted_tree = []
     for entry in tree:
-        ordered_change_types = change_type_order + sorted(
-            set(entry["changes"].keys()) - set(change_type_order)
-        )
-        changes = [
-            (ct, entry["changes"][ct])
-            for ct in ordered_change_types
-            if ct in entry["changes"]
-        ]
-        sorted_tree.append({**entry, **{"changes": OrderedDict(changes)}})
-    return sorted_tree
+        yield {
+            **entry,
+            "changes": _calculate_sorted_changes(change_type_order, entry["changes"]),
+        }
+
+
+def _calculate_sorted_changes(
+    change_type_order: list[str], changes: Mapping[str, Any]
+) -> OrderedDict[str, Any]:
+    remaining_change_types = set(changes.keys()) - set(change_type_order)
+    sorted_change_types = change_type_order + sorted(remaining_change_types)
+    return OrderedDict((ct, changes[ct]) for ct in sorted_change_types if ct in changes)
 
 
 def get_changelog_template(loader: BaseLoader, template: str) -> Template:
@@ -222,7 +225,7 @@ def render_changelog(
     tree: Iterable,
     loader: BaseLoader,
     template: str,
-    **kwargs,
+    **kwargs: Any,
 ) -> str:
     jinja_template = get_changelog_template(loader, template)
     changelog: str = jinja_template.render(tree=tree, **kwargs)
@@ -279,7 +282,7 @@ def incremental_build(
 
 
 def get_smart_tag_range(
-    tags: list[GitTag], newest: str, oldest: str | None = None
+    tags: Sequence[GitTag], newest: str, oldest: str | None = None
 ) -> list[GitTag]:
     """Smart because it finds the N+1 tag.
 
@@ -305,10 +308,10 @@ def get_smart_tag_range(
 
 
 def get_oldest_and_newest_rev(
-    tags: list[GitTag],
+    tags: Sequence[GitTag],
     version: str,
     rules: TagRules,
-) -> tuple[str | None, str | None]:
+) -> tuple[str | None, str]:
     """Find the tags for the given version.
 
     `version` may come in different formats:

{commitizen-4.8.2 → commitizen-4.8.4}/commitizen/changelog_formats/__init__.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import sys
-from typing import ClassVar, Protocol
+from typing import Callable, ClassVar, Protocol
 
 if sys.version_info >= (3, 10):
     from importlib import metadata
@@ -25,7 +25,7 @@ class ChangelogFormat(Protocol):
 
     config: BaseConfig
 
-    def __init__(self, config: BaseConfig):
+    def __init__(self, config: BaseConfig) -> None:
         self.config = config
 
     @property
@@ -64,10 +64,9 @@ def get_changelog_format(
     :raises FormatUnknown: if a non-empty name is provided but cannot be found in the known formats
     """
     name: str | None = config.settings.get("changelog_format")
-    format: type[ChangelogFormat] | None = guess_changelog_format(filename)
-
-    if name and name in KNOWN_CHANGELOG_FORMATS:
-        format = KNOWN_CHANGELOG_FORMATS[name]
+    format = (
+        name and KNOWN_CHANGELOG_FORMATS.get(name) or _guess_changelog_format(filename)
+    )
 
     if not format:
         raise ChangelogFormatUnknown(f"Unknown changelog format '{name}'")
@@ -75,7 +74,7 @@ def get_changelog_format(
     return format(config)
 
 
-def guess_changelog_format(filename: str | None) -> type[ChangelogFormat] | None:
+def _guess_changelog_format(filename: str | None) -> type[ChangelogFormat] | None:
     """
     Try guessing the file format from the filename.
 
@@ -91,3 +90,9 @@ def guess_changelog_format(filename: str | None) -> type[ChangelogFormat] | None
             if filename.endswith(f".{alt_extension}"):
                 return format
     return None
+
+
+def __getattr__(name: str) -> Callable[[str], type[ChangelogFormat] | None]:
+    if name == "guess_changelog_format":
+        return _guess_changelog_format
+    raise AttributeError(f"module {__name__} has no attribute {name}")

{commitizen-4.8.2 → commitizen-4.8.4}/commitizen/changelog_formats/base.py

@@ -20,7 +20,7 @@ class BaseFormat(ChangelogFormat, metaclass=ABCMeta):
     extension: ClassVar[str] = ""
     alternative_extensions: ClassVar[set[str]] = set()
 
-    def __init__(self, config: BaseConfig):
+    def __init__(self, config: BaseConfig) -> None:
         # Constructor needs to be redefined because `Protocol` prevent instantiation by default
         # See: https://bugs.python.org/issue44807
         self.config = config