Manipulate keep a changelog files

• Convert to dict
• Convert from dict
• Release a new version
• Add changelog retrieval REST API endpoint
  • Starlette
  • Flask-RestX

Convert changelog to dict

Convert changelog markdown file following keep a changelog format into python dict.

import keepachangelog

changes = keepachangelog.to_dict("path/to/CHANGELOG.md")

changes would look like:

changes = {
    "1.1.0": {
        "changed": [
            "Enhancement 1 (1.1.0)",
            "sub enhancement 1",
            "sub enhancement 2",
            "Enhancement 2 (1.1.0)",
        ],
        "metadata": {
            "release_date": "2018-05-31",
            "version": "1.1.0",
            "semantic_version": {
                "major": 1,
                "minor": 1,
                "patch": 0,
                "prerelease": None,
                "buildmetadata": None,
            },
            "url": "https://github.test_url/test_project/compare/v1.0.1...v1.1.0",
        },
    },
    "1.0.1": {
        "fixed": [
            "Bug fix 1 (1.0.1)",
            "sub bug 1",
            "sub bug 2",
            "Bug fix 2 (1.0.1)",
        ],
        "metadata": {
            "release_date": "2018-05-31",
            "version": "1.0.1",
            "semantic_version": {
                "major": 1,
                "minor": 0,
                "patch": 1,
                "prerelease": None,
                "buildmetadata": None,
            },
            "url": "https://github.test_url/test_project/compare/v1.0.0...v1.0.1",
        },
    },
    "1.0.0": {
        "deprecated": ["Known issue 1 (1.0.0)", "Known issue 2 (1.0.0)"],
        "metadata": {
            "release_date": "2017-04-10",
            "version": "1.0.0",
            "semantic_version": {
                "major": 1,
                "minor": 0,
                "patch": 0,
                "prerelease": None,
                "buildmetadata": None,
            },
            "url": "https://github.test_url/test_project/releases/tag/v1.0.0",
        },
    },
}

For a markdown file with the following content:

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
### Changed
- Release note 1.
- Release note 2.

### Added
- Enhancement 1
 - sub enhancement 1
 - sub enhancement 2
- Enhancement 2

### Fixed
- Bug fix 1
 - sub bug 1
 - sub bug 2
- Bug fix 2

### Security
- Known issue 1
- Known issue 2

### Deprecated
- Deprecated feature 1
- Future removal 2

### Removed
- Deprecated feature 2
- Future removal 1

## [1.1.0] - 2018-05-31
### Changed
- Enhancement 1 (1.1.0)
 - sub enhancement 1
 - sub enhancement 2
- Enhancement 2 (1.1.0)

## [1.0.1] - 2018-05-31
### Fixed
- Bug fix 1 (1.0.1)
 - sub bug 1
 - sub bug 2
- Bug fix 2 (1.0.1)

## [1.0.0] - 2017-04-10
### Deprecated
- Known issue 1 (1.0.0)
- Known issue 2 (1.0.0)

[Unreleased]: https://github.test_url/test_project/compare/v1.1.0...HEAD
[1.1.0]: https://github.test_url/test_project/compare/v1.0.1...v1.1.0
[1.0.1]: https://github.test_url/test_project/compare/v1.0.0...v1.0.1
[1.0.0]: https://github.test_url/test_project/releases/tag/v1.0.0

show_unreleased parameter can be specified in order to include Unreleased section information. Note that release_date metadata will be set to None in such as case.

Retrieving the raw content

If for some reason you would like to retrieve the raw content of a release you can use to_raw_dict instead.

import keepachangelog

changes = keepachangelog.to_raw_dict("path/to/CHANGELOG.md")

changes would look like:

changes = {
    "1.1.0": {
        "raw": """### Changed
- Enhancement 1 (1.1.0)
 - sub enhancement 1
 - sub enhancement 2
- Enhancement 2 (1.1.0)""",
        "metadata": {
            "release_date": "2018-05-31",
            "version": "1.1.0",
            "semantic_version": {
                "major": 1,
                "minor": 1,
                "patch": 0,
                "prerelease": None,
                "buildmetadata": None,
            },
            "url": "https://github.test_url/test_project/compare/v1.0.1...v1.1.0",
        },
    },
    "1.0.1": {
        "raw": """### Fixed
- Bug fix 1 (1.0.1)
 - sub bug 1
 - sub bug 2
- Bug fix 2 (1.0.1)""",
        "metadata": {
            "release_date": "2018-05-31",
            "version": "1.0.1",
            "semantic_version": {
                "major": 1,
                "minor": 0,
                "patch": 1,
                "prerelease": None,
                "buildmetadata": None,
            },
            "url": "https://github.test_url/test_project/compare/v1.0.0...v1.0.1",
        },
    },
    "1.0.0": {
        "raw": """### Deprecated
- Known issue 1 (1.0.0)
- Known issue 2 (1.0.0)""",
        "metadata": {
            "release_date": "2017-04-10",
            "version": "1.0.0",
            "semantic_version": {
                "major": 1,
                "minor": 0,
                "patch": 0,
                "prerelease": None,
                "buildmetadata": None,
            },
            "url": "https://github.test_url/test_project/releases/tag/v1.0.0",
        },
    },
}

Convert dict to changelog

Convert a python dict (resulting from keepachangelog.to_dict) to a changelog markdown content following keep a changelog format.

import keepachangelog

changes = keepachangelog.to_dict("path/to/CHANGELOG.md")
content = keepachangelog.from_dict(changes)

Release

You can create a new release by using keepachangelog.release function.

import keepachangelog

new_version = keepachangelog.release("path/to/CHANGELOG.md")

This will:

• If new_version parameter is not provided, guess the new version number and return it:
  • Removed or Changed sections will be considered as breaking changes, thus incrementing the major version.
  • If the only section is Fixed, only patch will be incremented.
  • Otherwise, minor will be incremented.
• Update changelog.
  • Unreleased section content will be moved into a new section.
  • [Unreleased] link will be updated.
  • New link will be created corresponding to the new section (based on the format of the Unreleased link).

Endpoint

Starlette

An helper function is available to create a starlette endpoint to retrieve changelog as JSON.

from starlette.applications import Starlette
from keepachangelog.starlette import add_changelog_endpoint


app = Starlette()
# /changelog endpoint will return the dict extracted from the changelog as JSON.
add_changelog_endpoint(app, "path/to/CHANGELOG.md")

Note: starlette module must be installed.

Flask-RestX

An helper function is available to create a Flask-RestX endpoint to retrieve changelog as JSON.

import flask
import flask_restx
from keepachangelog.flask_restx import add_changelog_endpoint


app = flask.Flask(__name__)
api = flask_restx.Api(app)
# /changelog endpoint will return the dict extracted from the changelog as JSON.
add_changelog_endpoint(api, "path/to/CHANGELOG.md")

Note: flask-restx module must be installed.

How to install

1. python 3.6+ must be installed
2. Use pip to install module:

python -m pip install keepachangelog