Python Semantic Release

https://python-semantic-release.readthedocs.io/en/latest/
Admin
Python Semantic Release is an automated versioning and release management tool that detects...
Tokens:145,248
Snippets:1,139
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Build Documentation Locally

Source: https://python-semantic-release.readthedocs.io/en/latest/contributing/contributing_guide.html

Install documentation dependencies and start a live-reloading documentation server.

```bash
pip install -e .[docs]
sphinx-autobuild --open-browser docs docs/_build/html
```

--------------------------------

### Install python-semantic-release

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/automatic-releases/cronjobs.html

Installs the package into the active environment.

```bash
pip install python-semantic-release
```

--------------------------------

### Install Dependencies for Build Status Checks

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/upgrading/08-upgrade.rst.txt

Commands to install curl and jq on Ubuntu systems.

```bash
sudo apt update && sudo apt upgrade
sudo apt install -y curl jq
```

--------------------------------

### Build Metadata Commands

Source: https://python-semantic-release.readthedocs.io/en/latest/api/commands.html

Examples of appending build metadata to a version.

```bash
$ semantic-release version --minor --print
1.3.0

$ semantic-release version --minor --print --build-metadata "run.12345"
1.3.0+run.12345
```

--------------------------------

### CLI Version Command Example

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/automatic-releases/github-actions.html

Example of the semantic-release version command with specific flags for patch bumping, disabling changelogs, and adding build metadata.

```bash
semantic-release version --patch --no-changelog --build-metadata abc123
```

--------------------------------

### Pattern-Based Version Replacement Examples

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration.rst.txt

Examples of various variable declaration formats supported by the pattern matching engine for version replacement.

```text
# Common variable declaration formats
version='1.2.3'
version = "1.2.3"
release = "v1.2.3"     # if tag_format is set

# YAML
version: 1.2.3

# JSON
"version": "1.2.3"

# NPM & GitHub Actions YAML
version@1.2.3
version@v1.2.3        # if tag_format is set

# Walrus Operator
version := "1.2.3"

# Excessive whitespace
version        =    '1.2.3'

# Mixed Quotes
"version" = '1.2.3'

# Custom Tag Format with tag_format set (monorepos)
__release__ = "module-v1.2.3"

# requirements.txt
my-package == 1.2.3

# C-Macro style (no operand only whitespace required)
#define VERSION "1.2.3"
```

--------------------------------

### Monorepo Directory Structure Example

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/monorepos.rst.txt

Illustrates a common monorepo file structure where each package has its own configuration.

```text
project/
├── .git/
├── .venv/
├── packages/
│   ├── pkg1/
│   │   ├── docs/
│   │   │   └── source/
│   │   │       ├── conf.py
│   │   │       └── index.rst
│   │   │
│   │   ├── src/
│   │   │   └── pkg1/
│   │   │       ├── __init__.py
│   │   │       ├── __main__.py
│   │   │       └── py.typed
│   │   │
│   │   ├── CHANGELOG.md
│   │   ├── README.md
│   │   └── pyproject.toml             <-- PSR Configuration for Package 1
│   │
│   └── pkg2/
│       ├── docs/
│       │   └── source/
│       │       ├── conf.py
│       │       └── index.rst
│       ├── src/
│       │   └── pkg2/
│       │       ├── __init__.py
│       │       ├── __main__.py
│       │       └── py.typed
│       │
│       ├── CHANGELOG.md
│       ├── README.md
│       └── pyproject.toml             <-- PSR Configuration for Package 2
│
├── .gitignore
└── README.md
```

--------------------------------

### Configure build_command with uv installation

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/uv_integration.rst.txt

Ensures uv is installed in the environment before running lock and build commands.

```toml
[project.optional-dependencies]
build = ["uv ~= 0.7.12"]

[tool.semantic_release]
build_command = """
    python -m pip install -e '.[build]'
    uv lock --upgrade-package "$PACKAGE_NAME"
    git add uv.lock
    uv build
"""
```

--------------------------------

### Install and Verify Python Semantic Release

Source: https://python-semantic-release.readthedocs.io/en/latest/index.html

Install the package via pip and verify the installation by accessing the CLI help menu.

```bash
python3 -m pip install python-semantic-release
semantic-release --help
```

--------------------------------

### Publish with a specific tag

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/automatic-releases/github-actions.html

Example of the command-line equivalent for specifying a release tag.

```bash
semantic-release publish --tag <tag>
```

--------------------------------

### Root Options Configuration

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/github-actions.rst.txt

Example of passing additional options to the main semantic-release command.

```yaml
- uses: python-semantic-release/python-semantic-release@v9
  with:
    root_options: "-vv --noop"
```

--------------------------------

### Install Development Dependencies

Source: https://python-semantic-release.readthedocs.io/en/latest/contributing/contributing_guide.html

Install the package in editable mode with development, mypy, and test dependencies.

```bash
pip install -e .[dev,mypy,test]
```

--------------------------------

### Define Project Directory Structure

Source: https://python-semantic-release.readthedocs.io/en/latest/concepts/changelog_templates.html

Example layout showing how to organize templates, hidden components, and static files within a project.

```text
example-project/
├── src/
│   └── example_project/
│       └── __init__.py
└── ch-templates/
    ├── CHANGELOG.md.j2
    ├── .components/
    │   └── authors.md.j2
    ├── .macros.j2
    ├── src/
    │   └── example_project/
    │       └── data/
    │           └── data.json.j2
    └── static/
        └── config.cfg
```

--------------------------------

### Create Virtual Environment

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/cronjobs.rst.txt

Use this command to create a virtual environment for installing python-semantic-release.

```bash
virtualenv semantic_release -p `which python3`
```

--------------------------------

### Install python-semantic-release

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/cronjobs.rst.txt

Install the python-semantic-release package using pip within your virtual environment.

```bash
pip install python-semantic-release
```

--------------------------------

### Example Rendered Release Notes

Source: https://python-semantic-release.readthedocs.io/en/latest/concepts/changelog_templates.html

The resulting markdown output generated from the template.

```markdown
## What's Changed

### Feature

* Added a new feature by John Doe in [`a1b2c3d`](https://github.com/example/repo/commit/a1b2c3d)
```

--------------------------------

### Experimenting with version printing

Source: https://python-semantic-release.readthedocs.io/en/latest/api/commands.html

Examples of using the --print flag in combination with other versioning options to preview results.

```bash
semantic-release version --print
semantic-release version --patch --print
semantic-release version --prerelease --print
```

--------------------------------

### Example Changelog Output from Squash Commit

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/commit_parsing.rst.txt

This markdown illustrates the expected changelog output generated from the example GitHub squash commit message. It shows how different commit types are categorized and presented.

```markdown
## Features

    - **config**: add new config option (#123)

    ## Documentation

    - **configuration**: defined new config option for the project (#123)

    ## Refactoring

    - **config**: change the implementation of config loading (#123)
```

--------------------------------

### Example Project Structure After Release

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

Illustrates the expected directory structure of a project after a release, highlighting the generated CHANGELOG.md and other project files. The template directory itself is not included in the output.

```text
example-project/
    ├── CHANGELOG.md
    ├── src/
    │   └── example_project/
    │       ├── data/
    │       │   └── data.json
    │       └── __init__.py
    └── static/
        └── config.cfg
```

--------------------------------

### Advanced workflow configuration files

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration-guides/uv_integration.html

Example configuration files for an advanced pipeline using uv and Python Semantic Release.

```text
# File: .tool-versions
uv 0.7.12
```

```text
# File: .python-version
3.11.11
```

```toml
# File: pyproject.toml
[project.optional-dependencies]
build = ["python-semantic-release ~= 10.0"]
test = ["pytest ~= 8.0"]

[tool.semantic_release]
build_command = """
  uv lock --upgrade-package "$PACKAGE_NAME"
  uv build
"""
```

--------------------------------

### Build Package Locally

Source: https://python-semantic-release.readthedocs.io/en/latest/contributing/contributing_guide.html

Install build dependencies and execute the package build process manually.

```bash
pip install -e .[build]
python -m build .
```

--------------------------------

### Set build metadata via CLI

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/automatic-releases/github-actions.html

Example of the equivalent command line usage for the build_metadata input.

```bash
semantic-release version --build-metadata <metadata>
```

--------------------------------

### Force Version Increment Examples

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/api/commands.rst.txt

Demonstrates how to force the next version to be a patch, minor, major, or prerelease, and prints the result. These options override the usual calculation.

```bash
semantic-release version --prerelease --print
# 0.2.1-rc.2
```

```bash
semantic-release version --patch --print
# 0.2.2
```

```bash
semantic-release version --minor --print
# 0.3.0
```

```bash
semantic-release version --major --print
# 1.0.0
```

```bash
semantic-release version --minor --as-prerelease --print
# 0.3.0-rc.1
```

```bash
semantic-release version --prerelease --as-prerelease --print
# 0.2.1-rc.2
```

--------------------------------

### GitHub Actions Release and Upload Steps

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/github-actions.rst.txt

Example steps for publishing release assets to GitHub and uploading distribution artifacts.

```yaml
- name: Publish | Upload to GitHub Release Assets
  uses: python-semantic-release/publish-action@COMMIT_HASH  # v10.6.1
  if: steps.release.outputs.released == 'true'
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    tag: ${{ steps.release.outputs.tag }}

- name: Upload | Distribution Artifacts
  uses: actions/upload-artifact@COMMIT_HASH  # v4.X.X
  with:
    name: distribution-artifacts
    path: dist
    if-no-files-found: error
```

--------------------------------

### Example Generated Markdown Changelog

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

The resulting Markdown changelog generated from the example template, showing formatted release versions and commit details with links.

```markdown
# CHANGELOG

## v1.1.0 (2022-01-01)

### Feature

* Added a new feature ([`a1b2c3d`](https://github.com/example/repo/commit/a1b2c3d))

## v1.0.0 (2021-12-31)

### Fix

* Resolved divide by zero error ([`e4f5g6h`](https://github.com/example/repo/commit/e4f5g6h))
```

--------------------------------

### Changelog insertion flag example

Source: https://python-semantic-release.readthedocs.io/en/latest/concepts/changelog_templates.html

Demonstrates the state of a changelog file before and after the insertion of new release information.

```markdown
# CHANGELOG

<!-- version list -->

## 1.0.0

- Initial Release

```

```markdown
# CHANGELOG

<!-- version list -->

## v1.1.0

### Feature

- feat: added a new feature

### Fix

- fix: resolved divide by zero error

## 1.0.0

- Initial Release

```

--------------------------------

### Custom Changelog Jinja2 Template Example

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

An example of a Jinja2 template for generating release notes. It iterates through commit types and commits, formatting them into a Markdown list. This template assumes a specific data structure provided by the semantic-release library.

```jinja
## What's Changed
{%    for type_, commits in release["elements"] | dictsort
%}{%-   if type_ != "unknown"
%}{{ 
              "### %s" | format(type_ | title)

    }}}{%      for commit in commits
%}{{ 
                "* %s by %s in [`%s`](%s)" | format(
                  commit.descriptions[0] | capitalize,
                  commit.commit.author.name,
                  commit.hexsha[:7],
                  commit.hexsha | commit_hash_url,
                )

    }}{%-     endfor
%}{%    endif
%}{%  endfor
%}
```

--------------------------------

### Monorepo Directory Structure Example

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/monorepos.rst.txt

Illustrates a typical monorepo project structure with separate package directories and a shared configuration for release templates.

```treeview
project/
├── .git/
├── config/
│   └── release-templates/
│       ├── CHANGELOG.md.j2
│       └── .release_notes.md.j2
├── packages/
│   ├── pkg1/
│   │   ├── CHANGELOG.md
│   │   └── pyproject.toml
│   │
│   └── pkg2/
│       ├── CHANGELOG.md
│       └── pyproject.toml
│
├── .gitignore
└── README.md
```

--------------------------------

### Configure PSR for Monorepo Packages

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration-guides/monorepos.html

Example pyproject.toml configurations for individual packages within a monorepo.

```toml
# FILE: pkg1/pyproject.toml
[project]
name = "pkg1"
version = "1.0.0"

[tool.semantic_release]
commit_parser = "conventional-monorepo"
commit_message = """\
chore(release): pkg1@{version}`

Automatically generated by python-semantic-release
"""
tag_format = "pkg1-v{version}"
version_toml = ["pyproject.toml:project.version"]

[tool.semantic_release.commit_parser_options]
path_filters = ["."]
scope_prefix = "pkg1-"
```

```toml
# FILE: pkg2/pyproject.toml
[project]
name = "pkg2"
version = "1.0.0"

[tool.semantic_release]
commit_parser = "conventional-monorepo"
commit_message = """\
chore(release): pkg2@{version}`

Automatically generated by python-semantic-release
"""
tag_format = "pkg2-v{version}"
version_toml = ["pyproject.toml:project.version"]

[tool.semantic_release.commit_parser_options]
path_filters = ["."]
scope_prefix = "pkg2-"
```

--------------------------------

### Default Configuration Options Setup

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/cli/config.html

Sets default parser options based on the selected commit parser, supporting both known and custom parsers.

```python
    @model_validator(mode="after")
    def set_default_opts(self) -> Self:
        # Set the default parser options for the given commit parser when no user input is given
        if not self.commit_parser_options and self.commit_parser:
            parser_opts_type = None
            # If the commit parser is a known one, pull the default options object from it
            if self.commit_parser in _known_commit_parsers:
                # TODO: BREAKING CHANGE v11
                # parser_opts_type = (
                #     _known_commit_parsers[self.commit_parser]
                #     .get_default_options()
                #     .__class__
                # )
                parser_opts_type = _known_commit_parsers[
                    self.commit_parser
                ].parser_options
            else:
                try:
                    # if its a custom parser, try to import it and pull the default options object type
                    custom_class = dynamic_import(self.commit_parser)
                    # TODO: BREAKING CHANGE v11
                    # parser_opts_type = custom_class.get_default_options().__class__
                    if hasattr(custom_class, "parser_options"):
                        parser_opts_type = custom_class.parser_options

                except ModuleNotFoundError as err:
                    raise ParserLoadError(
                        str.join(
                            "\n",
                            [
                                str(err),
                                "Unable to import your custom parser! Check your configuration!",
                            ],
                        )
                    ) from err

                except AttributeError as err:
                    raise ParserLoadError(
                        str.join(
                            "\n",
                            [
                                str(err),
                                "Unable to find your custom parser class inside the given module.",
                                "Check your configuration!",
                            ],
                        )
                    ) from err
```

--------------------------------

### Replace content of RELEASE file

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration.html

Example of replacing the entire content of a file using the configured tag_format.

```diff
diff a/RELEASE b/RELEASE

- v0.1.0
+ v0.2.0
```

--------------------------------

### Package 1 PSR Configuration

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/monorepos.rst.txt

Example `pyproject.toml` configuration for `pkg1` using the `conventional-monorepo` commit parser.

```toml
# FILE: pkg1/pyproject.toml
[project]
name = "pkg1"
version = "1.0.0"

[tool.semantic_release]
commit_parser = "conventional-monorepo"
commit_message = """
chore(release): pkg1@{"version"}`

Automatically generated by python-semantic-release
"""
tag_format = "pkg1-v{version}"
version_toml = ["pyproject.toml:project.version"]

[tool.semantic_release.commit_parser_options]
path_filters = ["."]
scope_prefix = "pkg1-"
```

--------------------------------

### Package 2 PSR Configuration

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/monorepos.rst.txt

Example `pyproject.toml` configuration for `pkg2` using the `conventional-monorepo` commit parser.

```toml
# FILE: pkg2/pyproject.toml
[project]
name = "pkg2"
version = "1.0.0"

[tool.semantic_release]
commit_parser = "conventional-monorepo"
commit_message = """
chore(release): pkg2@{"version"}`

Automatically generated by python-semantic-release
"""
tag_format = "pkg2-v{version}"
version_toml = ["pyproject.toml:project.version"]

[tool.semantic_release.commit_parser_options]
path_filters = ["."]
scope_prefix = "pkg2-"
```

--------------------------------

### Render Changelog Template

Source: https://python-semantic-release.readthedocs.io/en/latest/concepts/changelog_templates.html

A Jinja2 template example for generating a Markdown changelog using the PSR context.

```jinja2
# CHANGELOG

{%    for version, release in ctx.history.released.items()
%}{{
        "## %s (%s)" | format(version.as_tag(), release.tagged_date.strftime("%Y-%m-%d"))

}}{%    for type_, commits in release["elements"] if type_ != "unknown" | dictsort
%}{{
          "### %s" | format(type_ | title)

}}{%      for commit in commits
%}{{
            "* %s ([`%s`](%s))" | format(
              commit.descriptions[0] | capitalize,
              commit.hexsha[:7],
              commit.hexsha | commit_hash_url,
            )

}}{%      endfor
%}{%    endfor
%}{%  endfor
%}
```

--------------------------------

### Configure root_options for GitHub Action

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/automatic-releases/github-actions.html

Example of passing additional options to the semantic-release command using the root_options parameter.

```yaml
- uses: python-semantic-release/publish-action@v9
  with:
    root_options: "-vv --noop"
```

--------------------------------

### View git log with partial tags

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration.rst.txt

Example output showing how partial tags appear in the git log after a version release.

```bash
git log --decorate --oneline --graph --all
# * 4d4cb0a (tag: v1.2.3, tag: v1.2, tag: v1, origin/main, main) 1.2.3
# * 3a2b1c0 fix: some bug
# * 2b1c0a9 (tag: v1.2.2) 1.2.2
# ...
```

```bash
git log --decorate --oneline --graph --all
# * 4d4cb0a (tag: v1.2.3+20251109, tag: v1.2.3, tag: v1.2, tag: v1, origin/main, main) 1.2.3+20251109
# * 3a2b1c0 chore: add partial tags to PSR configuration
# * 2b1c0a9 (tag: v1.2.3+20251031) 1.2.3+20251031
# ...
```

--------------------------------

### Continuous Delivery Workflow Example

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/github-actions.rst.txt

A complete GitHub Actions workflow that performs version release and publishes to PyPI on pushes to the main branch.

```yaml
name: Continuous Delivery

on:
  push:
    branches:
      - main

# default: least privileged permissions across all jobs
permissions:
  contents: read

jobs:
  release:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-release-${{ github.ref_name }}
      cancel-in-progress: false

    permissions:
      contents: write

    steps:
      # Note: We checkout the repository at the branch that triggered the workflow.
      # Python Semantic Release will automatically convert shallow clones to full clones
      # if needed to ensure proper history evaluation. However, we forcefully reset the
      # branch to the workflow sha because it is possible that the branch was updated
      # while the workflow was running, which prevents accidentally releasing un-evaluated
      # changes.
      - name: Setup | Checkout Repository on Release Branch
        uses: actions/checkout@COMMIT_HASH  # v6
        with:
          ref: ${{ github.ref_name }}

      - name: Setup | Force release branch to be at workflow sha
        run: |
          git reset --hard ${{ github.sha }}

      - name: Action | Semantic Version Release
        id: release
        # Adjust tag with desired version if applicable.
        uses: python-semantic-release/python-semantic-release@COMMIT_HASH  # v10.6.1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          git_committer_name: "github-actions"
          git_committer_email: "actions@users.noreply.github.com"
```

--------------------------------

### Force version increment with prerelease

Source: https://python-semantic-release.readthedocs.io/en/latest/api/commands.html

Example of forcing a specific version increment while maintaining prerelease status.

```bash
semantic-release version --prerelease --print
```

--------------------------------

### Iterate Through Released Versions

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

Example showing how to access and iterate over released versions from the 'history' context object to include version-specific changes.

```jinja
{%    set unreleased_commits = ctx.history.unreleased | dictsort
%}{%  for release in context.history.released.values()
%}{%    include ".versioned_changes.md.j2"
#}{%  endfor
%}
```

--------------------------------

### Attach Build Metadata to Versions

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/multibranch_releases.rst.txt

Use the `semantic-release version` command with build metadata to include branch and date information in version tags. This example uses bash commands to get the current branch and date.

```bash
semantic-release version \
   --build-metadata "$(git branch --show-current).$(date +%Y%m%d)"
```

--------------------------------

### Initialize version translator and build environment

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/cli/config.html

Sets up the version translator and parses build command environment variables from the configuration.

```python
# version_translator
version_translator = VersionTranslator(
    tag_format=raw.tag_format,
    prerelease_token=branch_config.prerelease_token,
    add_partial_tags=raw.add_partial_tags,
)

build_cmd_env = {}

for i, env_var_def in enumerate(raw.build_command_env):
    # creative hack to handle, missing =, but also = that then can be unpacked
    # as the resulting parts array can be either 2 or 3 in length. it becomes 3
    # with our forced empty value at the end which can be dropped
    parts = [*env_var_def.split("=", 1), ""]
    # removes any odd spacing around =, and extracts name=value
    name, env_val = (part.strip() for part in parts[:2])

    if not name:
        # Skip when invalid format (ex. starting with = and no name)
        logging.warning(
            "Skipping invalid build_command_env[%s] definition",
            i,
        )
        continue
```

--------------------------------

### Handle Initial Release Masking

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

Example of using the 'mask_initial_release' context variable to conditionally include a specific template for the first release, providing a generic message instead of detailed changes.

```jinja
#}{%  if releases | length == 1 and ctx.mask_initial_release
%}{#    # On a first release, generate a generic message
#}{%    include ".components/first_release.md.j2"
%}{%  else
%}{#    # Not the first release
#}{%    include ".components/versioned_changes.md.j2"
%}{#  endif
%}
```

--------------------------------

### Travis CI Configuration for Semantic Release

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/travis.rst.txt

Add this to your `.travis.yml` file to run semantic release commands after a successful build. It configures Git, installs the package, and triggers versioning and publishing.

```yaml
after_success:
- git config --global user.name "semantic-release (via TravisCI)"
- git config --global user.email "semantic-release@travis"
- pip install python-semantic-release
- semantic-release version && semantic-release publish
```

--------------------------------

### Custom Changelog Template Directory Structure

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

This example illustrates the expected directory structure for custom changelog templates. Files with a .j2 extension are rendered, while others are copied directly. Hidden files/folders are excluded.

```text
example-project/
    ├── src/
    │   └── example_project/
    │       └── __init__.py
    └── ch-templates/
        ├── CHANGELOG.md.j2
        ├── .components/
        │   └── authors.md.j2
        ├── .macros.j2
        ├── src/
        │   └── example_project/
        │       └── data/
        │           └── data.json.j2
        └── static/
            └── config.cfg
```

--------------------------------

### Print Next Version with Prerelease

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/api/commands.rst.txt

Prints the next version that will be applied, including a prerelease, and then exits.

```bash
semantic-release version --prerelease --print
```

--------------------------------

### Execute release workflow

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/upgrading/08-upgrade.rst.txt

Recommended command sequence to replicate the previous monolithic publish flow.

```bash
semantic-release version
twine upload dist/*  # or whichever path your distributions are placed in
semantic-release publish
```

--------------------------------

### Initialize Configuration Object

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/cli/config.html

Instantiates the configuration class with project metadata, build commands, and changelog settings.

```python
            if not env_val and env_var_def[-1] != "=":
                # avoid the edge case that user wants to define a value as empty
                # and don't autoresolve it
                env_val = os.getenv(name, "")

            build_cmd_env[name] = env_val

        # TODO: better support for custom parsers that actually just extend defaults
        #
        # Here we just assume the desired changelog style matches the parser name
        # as we provide templates specific to each parser type. Unfortunately if the user has
        # provided a custom parser, it would be up to the user to provide custom templates
        # but we just assume the base template is conventional
        # changelog_style = (
        #     raw.commit_parser
        #     if raw.commit_parser in _known_commit_parsers
        #     else "conventional"
        # )

        self = cls(
            project_metadata=project_metadata,
            repo_dir=raw.repo_dir,
            commit_parser=commit_parser,
            version_translator=version_translator,
            major_on_zero=raw.major_on_zero,
            allow_zero_version=raw.allow_zero_version,
            build_command=raw.build_command,
            build_command_env=build_cmd_env,
            version_declarations=tuple(version_declarations),
            hvcs_client=hvcs_client,
            changelog_file=changelog_file,
            changelog_mode=raw.changelog.mode,
            changelog_mask_initial_release=raw.changelog.default_templates.mask_initial_release,
            changelog_insertion_flag=raw.changelog.insertion_flag,
            assets=raw.assets,
            commit_author=commit_author,
            commit_message=raw.commit_message,
            changelog_excluded_commit_patterns=changelog_excluded_commit_patterns,
            # TODO: change when we have other styles per parser
            # changelog_style=changelog_style,
            changelog_style="conventional",
            changelog_output_format=raw.changelog.default_templates.output_format,
            prerelease=branch_config.prerelease,
            ignore_token_for_push=raw.remote.ignore_token_for_push,
            template_dir=template_dir,
            template_environment=template_environment,
            dist_glob_patterns=raw.publish.dist_glob_patterns,
            upload_to_vcs_release=raw.publish.upload_to_vcs_release,
            global_cli_options=global_cli_options,
            masker=masker,
            no_git_verify=raw.no_git_verify,
        )
        # credential masker
        self.apply_log_masking(self.masker)

        return self
```

--------------------------------

### Example GitHub Squash Commit Message

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/commit_parsing.rst.txt

This is an example of a GitHub-formatted squash commit message with conventional commit style. It demonstrates how multiple commits can be embedded within a single squash commit.

```text
feat(config): add new config option (#123)

    * refactor(config): change the implementation of config loading

    * docs(configuration): defined new config option for the project
```

--------------------------------

### semantic_release.setup_hook(argv: list[str]) -> None

Source: https://python-semantic-release.readthedocs.io/en/latest/api/modules/semantic_release.html

A hook function designed to be used within setup.py to enable the 'python setup.py publish' command.

```APIDOC
## semantic_release.setup_hook(argv: list[str]) -> None

### Description
A hook to be used in setup.py to enable python setup.py publish.

### Parameters
- **argv** (list[str]) - Required - sys.argv
```

--------------------------------

### Execute versioning and publishing workflow

Source: https://python-semantic-release.readthedocs.io/en/latest/upgrading/08-upgrade.html

Run these commands sequentially to handle versioning, manual artifact upload, and release publishing.

```bash
semantic-release version
twine upload dist/*  # or whichever path your distributions are placed in
semantic-release publish
```

--------------------------------

### Get Default Options Method

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/commit_parser/conventional/parser_monorepo.html

Returns the default configuration options for the monorepo parser.

```python
    def get_default_options(self) -> ConventionalCommitMonorepoParserOptions:
        return ConventionalCommitMonorepoParserOptions()
```

--------------------------------

### Prerelease Token Command Equivalent

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/github-actions.rst.txt

Shows the command-line equivalent for the prerelease token configuration.

```shell
semantic-release version --prerelease-token <token>
```

--------------------------------

### Define setup_hook for setup.py

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release.html

A hook function to enable CLI commands like version, publish, and changelog within setup.py.

```python
[docs]
def setup_hook(argv: list[str]) -> None:
    """
    A hook to be used in setup.py to enable `python setup.py publish`.

    :param argv: sys.argv
    """
    if len(argv) > 1 and any(
        cmd in argv for cmd in ["version", "publish", "changelog"]
    ):
        from semantic_release.cli.commands.main import main

        main()
```

--------------------------------

### Get release ID by tag

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/hvcs/gitea.html

Retrieves the release ID for a specific tag from the Gitea API.

```python
    @logged_function(logger)
    @suppress_not_found
    def get_release_id_by_tag(self, tag: str) -> int | None:
        """
        Get a release by its tag name
        https://gitea.com/api/swagger#/repository/repoGetReleaseByTag
        :param tag: Tag to get release for

        :return: ID of found release
        """
        tag_endpoint = self.create_api_url(
            endpoint=f"/repos/{self.owner}/{self.repo_name}/releases/tags/{tag}",
        )
        response = self.session.get(tag_endpoint)

        # Raise an error if the request was not successful
        response.raise_for_status()

        try:
            data = response.json()
            return data["id"]
        except JSONDecodeError as err:
            raise UnexpectedResponse("Unreadable json response") from err
        except KeyError as err:
            raise UnexpectedResponse("JSON response is missing an id") from err
```

--------------------------------

### Get Default Options

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/commit_parser/emoji.html

Static method to retrieve the default configuration options for the emoji parser.

```python
@staticmethod
    def get_default_options() -> EmojiParserOptions:
        return EmojiParserOptions()
```

--------------------------------

### Preview Default Release Notes

Source: https://python-semantic-release.readthedocs.io/en/latest/concepts/changelog_templates.html

Use this command to print the default release notes to the console for review without performing an actual release.

```bash
# Create a current tag
git tag v1.0.0
semantic-release --noop changelog --post-to-release-tag v1.0.0
```

--------------------------------

### Get default parser options

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/commit_parser/conventional/parser.html

Returns the default configuration options for the conventional commit parser.

```python
def get_default_options(self) -> ConventionalCommitParserOptions:
        return ConventionalCommitParserOptions()
```

--------------------------------

### Replace content of VERSION file

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration.html

Example of replacing the entire content of a file containing only a version number.

```diff
diff a/VERSION b/VERSION

- 0.1.0
+ 0.2.0
```

--------------------------------

### Manual release workflow with uv

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/uv_integration.rst.txt

Updates the version, refreshes the lock file, and creates the release in separate steps.

```bash
# 1. PSR stamps version into files (nothing else)
# don't build the changelog (especially in update mode)
semantic-release -v version --skip-build --no-commit --no-tag --no-changelog

# 2. run UV lock as pyproject.toml is updated with the next version
uv lock --upgrade-package <your-package-name>

# 3. stage the lock file to ensure it is included in the PSR commit
git add uv.lock

# 4. run PSR fully to create release
semantic-release -v version
```

--------------------------------

### Update newTag in kustomization.yml

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration.html

Example of updating a tag variable in a YAML file using the configured tag_format.

```diff
diff a/kustomization.yml b/kustomization.yml

  images:
    - name: repo/image
-     newTag: v0.1.0
+     newTag: v0.2.0
```

--------------------------------

### Full Version Command

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/api/commands.rst.txt

Executes the version command performing all available actions.

```bash
semantic-release version
```

--------------------------------

### Generated Release Notes from Squashed Commits

Source: https://python-semantic-release.readthedocs.io/en/latest/concepts/commit_parsing.html

The resulting changelog structure after parsing the squashed commit example.

```markdown
## Features

- **config**: add new config option (#123)

## Documentation

- **configuration**: defined new config option for the project (#123)

## Refactoring

- **config**: change the implementation of config loading (#123)

```

--------------------------------

### Load configuration file

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/cli/util.html

Reads and parses a configuration file from the filesystem, attempting TOML parsing first, followed by JSON.

```python
def load_raw_config_file(config_file: Path | str) -> dict[Any, Any]:
    """
    Load raw configuration as a dict from the filename specified
    by config_filename, trying the following parsing methods:

    1. try to parse with tomli.load (guessing it's a TOML file)
    2. try to parse with json.load (guessing it's a JSON file)
    3. raise InvalidConfiguration if none of the above parsing
       methods work

    This function will also raise FileNotFoundError if it is raised
    while trying to read the specified configuration file
    """
    logger.info("Loading configuration from %s", config_file)
    raw_text = (Path() / config_file).resolve().read_text(encoding="utf-8-sig")
    try:
        logger.debug("Trying to parse configuration %s in TOML format", config_file)
        return parse_toml(raw_text)
    except InvalidConfiguration as e:
        logger.debug("Configuration %s is invalid TOML: %s", config_file, str(e))
        logger.debug("trying to parse %s as JSON", config_file)
        try:
            # could be a "parse_json" function but it's a one-liner here
            return json.loads(raw_text)["semantic_release"]
        except KeyError:
            # valid configuration, but no "semantic_release" or "tool.semantic_release"
            # top level key
            logger.debug(
                "configuration has no 'semantic_release' or 'tool.semantic_release' "
                "top-level key"
            )
            return {}
        except json.JSONDecodeError as jde:
            raise InvalidConfiguration(
                dedent(
                    f"""
                    None of the supported configuration parsers were able to parse
                    the configuration file {config_file}:
                    * TOML: {e!s}
                    * JSON: {jde!s}
                    """
                )
            ) from jde
```

--------------------------------

### Print next version commands

Source: https://python-semantic-release.readthedocs.io/en/latest/api/commands.html

Commands to display the next version to be applied, with options for tag prefixes and last released versions.

```bash
semantic-release version --print
```

```bash
semantic-release version --print-tag
```

```bash
semantic-release version --print-last-released
```

```bash
semantic-release version --print-last-released-tag
```

--------------------------------

### Print Next Version

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/api/commands.rst.txt

Use the `--print` option with the `version` command to display the next semantic version that will be applied to the project without making any changes.

```bash
semantic-release version --print
```

--------------------------------

### Get Release ID by Tag

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/hvcs/github.html

Retrieves the ID of a GitHub release associated with a specific tag name.

```python
    @logged_function(logger)
    @suppress_not_found
    def get_release_id_by_tag(self, tag: str) -> int | None:
        """
        Get a release by its tag name
        https://docs.github.com/rest/reference/repos#get-a-release-by-tag-name
        :param tag: Tag to get release for
        :return: ID of release, if found, else None
        """
        tag_endpoint = self.create_api_url(
            endpoint=f"/repos/{self.owner}/{self.repo_name}/releases/tags/{tag}",
        )
        response = self.session.get(tag_endpoint)

        # Raise an error if the request was not successful
        response.raise_for_status()

        try:
            data = response.json()
            return data["id"]
        except JSONDecodeError as err:
            raise UnexpectedResponse("Unreadable json response") from err
        except KeyError as err:
            raise UnexpectedResponse("JSON response is missing an id") from err
```

--------------------------------

### Retrieve version dynamically in __init__.py

Source: https://python-semantic-release.readthedocs.io/en/latest/concepts/getting_started.html

Use importlib.metadata to fetch the version from package metadata instead of hardcoding it in the repository.

```python
# my_package/__init__.py
from importlib.metadata import version as get_version

__version__ = get_version(__package__)
# Note: __package__ must match your 'project.name' as defined in pyproject.toml
```

--------------------------------

### Enable Prerelease Mode via Shell

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/github-actions.rst.txt

Shows the command equivalent for forcing a prerelease version.

```shell
semantic-release version --as-prerelease
```

--------------------------------

### Get asset upload URL

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/hvcs/gitea.html

Constructs the API endpoint URL for uploading assets to a specific release.

```python
    @logged_function(logger)
    def asset_upload_url(self, release_id: str) -> str:
        """
        Get the correct upload url for a release
        https://gitea.com/api/swagger#/repository/repoCreateReleaseAttachment
        :param release_id: ID of the release to upload to
        """
        return self.create_api_url(
            endpoint=f"/repos/{self.owner}/{self.repo_name}/releases/{release_id}/assets",
        )
```

--------------------------------

### Update version in docs/conf.py

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration.html

Example of updating a version variable in a Python configuration file using SemVer format.

```diff
diff a/docs/conf.py b/docs/conf.py

- version = "0.1.0"
+ version = "0.2.0"
```

--------------------------------

### Print Next Version with Tag Prefix

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/api/commands.rst.txt

To include the configured tag prefix when printing the next version, use the `--print-tag` option.

```bash
semantic-release version --print-tag
```

--------------------------------

### Configure pyproject.toml for uv

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/configuration-guides/uv_integration.rst.txt

Define build dependencies and the semantic release build command using uv.

```toml
# File: pyproject.toml
[project.optional-dependencies]
build = ["python-semantic-release ~= 10.0"]
test = ["pytest ~= 8.0"]

[tool.semantic_release]
build_command = """
  uv lock --upgrade-package "$PACKAGE_NAME"
  uv build
"""
```

--------------------------------

### Markdown Changelog Before Update

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

Example of a Markdown changelog file before a new release is added using the 'update' mode.

```markdown
# CHANGELOG

<!-- version list -->

## 1.0.0

- Initial Release
```

--------------------------------

### Get authenticated remote URL

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/hvcs/github.html

Constructs the remote repository URL, optionally injecting the GitHub token for authentication.

```python
def remote_url(self, use_token: bool = True) -> str:
        """Get the remote url including the token for authentication if requested"""
        if not (self.token and use_token):
            logger.info("requested to use token for push but no token set, ignoring...")
            return self._remote_url

        actor = os.getenv("GITHUB_ACTOR", None)
        return self.create_server_url(
            auth=f"{actor}:{self.token}" if actor else self.token,
            path=f"/{self.owner}/{self.repo_name}.git",
        )
```

--------------------------------

### Create Virtual Environment

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/automatic-releases/cronjobs.html

Initializes a new virtual environment using the system's Python 3 interpreter.

```bash
virtualenv semantic_release -p `which python3`
```

--------------------------------

### Get changelog context filters

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/hvcs/gitlab.html

Returns a tuple of callable filters used for generating URLs and formatting in the changelog.

```python
def get_changelog_context_filters(self) -> tuple[Callable[..., Any], ...]:
    return (
        self.create_server_url,
        self.create_repo_url,
        self.commit_hash_url,
        self.compare_url,
        self.issue_url,
        self.merge_request_url,
        self.pull_request_url,
        self.create_release_url,
        self.format_w_official_vcs_name,
    )
```

--------------------------------

### Create Server URLs with create_server_url Filter

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

Prepend the VCS server host and URL scheme to a given path using `create_server_url`. Optionally include authentication, query, or fragment strings.

```jinja
{{ "example/repo.git" | create_server_url }}
```

```jinja
{{ "example/repo" | create_server_url(None, "results=1", "section-header") }}
```

--------------------------------

### API URL Configuration

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/hvcs/bitbucket.html

Logic for determining the API endpoint based on whether the environment is Bitbucket Cloud or an on-premise installation.

```python
self._api_url = parse_url(
            Bitbucket.DEFAULT_API_URL_CLOUD
            if is_bitbucket_cloud
            else Url(
                # Strip any auth, query or fragment from the domain
                scheme=api_domain_parts.scheme,
                host=api_domain_parts.host,
                port=api_domain_parts.port,
                path=str(
                    PurePosixPath(
                        # pass any custom server prefix path but ensure we don't
                        # double up the api path in the case the user provided it
                        str.replace(
                            api_domain_parts.path or "",
                            self.DEFAULT_API_PATH_ONPREM,
                            "",
                        ).lstrip("/")
                        or "/",
                        # apply the on-prem api path
                        self.DEFAULT_API_PATH_ONPREM.lstrip("/"),
                    )
                ),
            ).url.rstrip("/")
        )
```

```python
def _derive_api_url_from_base_domain(self) -> Url:
        return parse_url(
            Url(
                # infer from Domain url and append the api path
                **{
                    **self.hvcs_domain._asdict(),
                    "host": self.hvcs_domain.host,
                    "path": str(
                        PurePosixPath(
                            str.lstrip(self.hvcs_domain.path or "", "/") or "/",
                            self.DEFAULT_API_PATH_ONPREM.lstrip("/"),
                        )
                    ),
                }
            ).url.rstrip("/")
        )
```

--------------------------------

### Publish command tag option

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/github-actions.rst.txt

Demonstrates the equivalent command-line usage for the tag input option.

```shell
semantic-release publish --tag <tag>
```

--------------------------------

### Update version_toml configuration format

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/upgrading/08-upgrade.rst.txt

Transition from a string to a list of strings for the version_toml configuration option.

```toml
# Python Semantic Release v7 configuration
[tool.semantic_release]
version_toml = "pyproject.toml:tool.poetry.version"

# Python Semantic Release v8 configuration
[tool.semantic_release]
version_toml = ["pyproject.toml:tool.poetry.version"]
```

--------------------------------

### Version Parsing and Initialization

Source: https://python-semantic-release.readthedocs.io/en/latest/_modules/semantic_release/version/version.html

Initializes a Version object from regex match groups and metadata.

```python
        build_metadata = match.group("buildmetadata") or ""
        logger.debug(
            "parsed build metadata %r from version string %s",
            build_metadata,
            version_str,
        )

        return Version(
            int(match.group("major")),
            int(match.group("minor")),
            int(match.group("patch")),
            prerelease_token=prerelease_token,
            prerelease_revision=(
                int(prerelease_revision) if prerelease_revision else None
            ),
            build_metadata=build_metadata,
            tag_format=tag_format,
        )
```

--------------------------------

### Generate Default Release Notes

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

Use this command to print the default release notes to the console. Ensure a tag exists for the release.

```console
# Create a current tag
git tag v1.0.0
semantic-release --noop changelog --post-to-release-tag v1.0.0
```

--------------------------------

### Configure Package-Prefixed Prereleases

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration-guides/monorepos.html

Use package-specific branch matching to prevent collisions during alpha releases.

```toml
# FILE: pkg1/pyproject.toml
[tool.semantic_release.branches.alpha-release]
match = "^pkg1/feat/.+"                       # <-- note pkg1 prefix
prerelease = true
prerelease_token = "alpha"
```

```toml
# FILE: pkg2/pyproject.toml
[tool.semantic_release.branches.alpha-release]
match = "^pkg2/feat/.+"                       # <-- note pkg2 prefix
prerelease = true
prerelease_token = "alpha"
```

--------------------------------

### Package Configuration for Monorepo

Source: https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration-guides/monorepos.html

Example pyproject.toml configuration for a package within the monorepo, including path filters for documentation and template directory settings.

```toml
# FILE: pkg1/pyproject.toml
[project]
name = "pkg1"
version = "1.0.0"

[tool.semantic_release]
commit_parser = "conventional-monorepo"
commit_message = """\
chore(release): Release `pkg1@{version}`

Automatically generated by python-semantic-release
"""
tag_format = "pkg1-v{version}"
version_toml = ["pyproject.toml:project.version"]

[tool.semantic_release.commit_parser_options]
path_filters = [
    ".",
    "../../../docs/source/pkg1/**",
]
scope_prefix = "pkg1-"

[tool.semantic_release.changelog]
template_dir = "../../../docs/templates"
mode = "update"
exclude_commit_patterns = [
    '''^chore(?:\([^)]*?\))?: .+''',
    '''^ci(?:\([^)]*?\))?: .+''',
    '''^refactor(?:\([^)]*?\))?: .+''',
    '''^style(?:\([^)]*?\))?: .+''',
    '''^test(?:\([^)]*?\))?: .+''',
    '''^Initial [Cc]ommit''',
]

[tool.semantic_release.changelog.default_templates]
# To enable update mode: this value must set here because the default is not the
# same as the default in the other package & must be the final destination filename
# for the changelog relative to this file
changelog_file = "../../../docs/source/pkg1/changelog.md"
```

--------------------------------

### Generated Changelog Markdown Output

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/concepts/changelog_templates.rst.txt

This is an example of the output generated by a changelog template. It shows how commits are formatted under different sections like 'Feature'.

```markdown
      ## What's Changed

      ### Feature

      * Added a new feature by John Doe in [`a1b2c3d`](https://github.com/example/repo/commit/a1b2c3d)
```

--------------------------------

### Set build metadata via GitHub Action input

Source: https://python-semantic-release.readthedocs.io/en/latest/_sources/configuration/automatic-releases/github-actions.rst.txt

Demonstrates the equivalent command-line usage for the build_metadata input parameter.

```shell
semantic-release version --build-metadata <metadata>
```
Tokens:
Raw