<h2 align="center">Manipulate keep a changelog files</h2>
<p align="center">
<a href="https://pypi.org/project/keepachangelog/"><img alt="pypi version" src="https://img.shields.io/pypi/v/keepachangelog"></a>
<a href="https://travis-ci.com/Colin-b/keepachangelog"><img alt="Build status" src="https://api.travis-ci.com/Colin-b/keepachangelog.svg?branch=master"></a>
<a href="https://travis-ci.com/Colin-b/keepachangelog"><img alt="Coverage" src="https://img.shields.io/badge/coverage-100%25-brightgreen"></a>
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
<a href="https://travis-ci.com/Colin-b/keepachangelog"><img alt="Number of tests" src="https://img.shields.io/badge/tests-31 passed-blue"></a>
<a href="https://pypi.org/project/keepachangelog/"><img alt="Number of downloads" src="https://img.shields.io/pypi/dm/keepachangelog"></a>
</p>
* [Convert to dict](#convert-changelog-to-dict)
* [Release a new version](#release)
* [Add changelog retrieval REST API endpoint](#endpoint)
* [Starlette](#starlette)
* [Flask-RestX](#flask-restx)
## Convert changelog to dict
Convert changelog markdown file following [keep a changelog](https://keepachangelog.com/en/1.1.0/) format into python dict.
```python
import keepachangelog
changes = keepachangelog.to_dict("path/to/CHANGELOG.md")
```
`changes` would look like:
```python
changes = {
"1.1.0": {
"changed": [
"Enhancement 1 (1.1.0)",
"sub enhancement 1",
"sub enhancement 2",
"Enhancement 2 (1.1.0)",
],
"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)",
],
"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)"],
"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:
```markdown
# 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` 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.
```python
import keepachangelog
changes = keepachangelog.to_raw_dict("path/to/CHANGELOG.md")
```
`changes` would look like:
```python
changes = {
"1.1.0": {
"raw": """### Changed
- Enhancement 1 (1.1.0)
- sub enhancement 1
- sub enhancement 2
- Enhancement 2 (1.1.0)""",
"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)""",
"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)""",
"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",
},
}
```
## Release
You can create a new release by using `keepachangelog.release` function.
```python
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](https://www.starlette.io) endpoint to retrieve changelog as JSON.
```python
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](https://pypi.python.org/pypi/starlette) module must be installed.
### Flask-RestX
An helper function is available to create a [Flask-RestX](https://flask-restx.readthedocs.io/en/latest/) endpoint to retrieve changelog as JSON.
```python
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](https://pypi.python.org/pypi/flask-restx) module must be installed.
## How to install
1. [python 3.6+](https://www.python.org/downloads/) must be installed
2. Use pip to install module:
```sh
python -m pip install keepachangelog
```
Raw data
{
"_id": null,
"home_page": "https://colin-b.github.io/keepachangelog/",
"name": "keepachangelog",
"maintainer": "Colin Bounouar",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "colin.bounouar.dev@gmail.com",
"keywords": "changelog,CHANGELOG.md,markdown",
"author": "Colin Bounouar",
"author_email": "colin.bounouar.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/21/2a/9c23fc183c320d3e448fb2e02d8daf23f4fa1de67dfb7d172d7b1c891864/keepachangelog-1.0.0.tar.gz",
"platform": "Windows",
"description": "<h2 align=\"center\">Manipulate keep a changelog files</h2>\n\n<p align=\"center\">\n<a href=\"https://pypi.org/project/keepachangelog/\"><img alt=\"pypi version\" src=\"https://img.shields.io/pypi/v/keepachangelog\"></a>\n<a href=\"https://travis-ci.com/Colin-b/keepachangelog\"><img alt=\"Build status\" src=\"https://api.travis-ci.com/Colin-b/keepachangelog.svg?branch=master\"></a>\n<a href=\"https://travis-ci.com/Colin-b/keepachangelog\"><img alt=\"Coverage\" src=\"https://img.shields.io/badge/coverage-100%25-brightgreen\"></a>\n<a href=\"https://github.com/psf/black\"><img alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"></a>\n<a href=\"https://travis-ci.com/Colin-b/keepachangelog\"><img alt=\"Number of tests\" src=\"https://img.shields.io/badge/tests-31 passed-blue\"></a>\n<a href=\"https://pypi.org/project/keepachangelog/\"><img alt=\"Number of downloads\" src=\"https://img.shields.io/pypi/dm/keepachangelog\"></a>\n</p>\n\n* [Convert to dict](#convert-changelog-to-dict)\n* [Release a new version](#release)\n* [Add changelog retrieval REST API endpoint](#endpoint)\n * [Starlette](#starlette)\n * [Flask-RestX](#flask-restx)\n\n## Convert changelog to dict\n\nConvert changelog markdown file following [keep a changelog](https://keepachangelog.com/en/1.1.0/) format into python dict.\n\n```python\nimport keepachangelog\n\nchanges = keepachangelog.to_dict(\"path/to/CHANGELOG.md\")\n```\n\n`changes` would look like:\n\n```python\nchanges = {\n \"1.1.0\": {\n \"changed\": [\n \"Enhancement 1 (1.1.0)\",\n \"sub enhancement 1\",\n \"sub enhancement 2\",\n \"Enhancement 2 (1.1.0)\",\n ],\n \"release_date\": \"2018-05-31\",\n \"version\": \"1.1.0\",\n \"semantic_version\": {\n \"major\": 1,\n \"minor\": 1,\n \"patch\": 0,\n \"prerelease\": None,\n \"buildmetadata\": None,\n },\n \"url\": \"https://github.test_url/test_project/compare/v1.0.1...v1.1.0\",\n },\n \"1.0.1\": {\n \"fixed\": [\n \"Bug fix 1 (1.0.1)\",\n \"sub bug 1\",\n \"sub bug 2\",\n \"Bug fix 2 (1.0.1)\",\n ],\n \"release_date\": \"2018-05-31\",\n \"version\": \"1.0.1\",\n \"semantic_version\": {\n \"major\": 1,\n \"minor\": 0,\n \"patch\": 1,\n \"prerelease\": None,\n \"buildmetadata\": None,\n },\n \"url\": \"https://github.test_url/test_project/compare/v1.0.0...v1.0.1\",\n },\n \"1.0.0\": {\n \"deprecated\": [\"Known issue 1 (1.0.0)\", \"Known issue 2 (1.0.0)\"],\n \"release_date\": \"2017-04-10\",\n \"version\": \"1.0.0\",\n \"semantic_version\": {\n \"major\": 1,\n \"minor\": 0,\n \"patch\": 0,\n \"prerelease\": None,\n \"buildmetadata\": None,\n },\n \"url\": \"https://github.test_url/test_project/releases/tag/v1.0.0\",\n },\n}\n```\n\nFor a markdown file with the following content:\n\n```markdown\n# Changelog\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n### Changed\n- Release note 1.\n- Release note 2.\n\n### Added\n- Enhancement 1\n - sub enhancement 1\n - sub enhancement 2\n- Enhancement 2\n\n### Fixed\n- Bug fix 1\n - sub bug 1\n - sub bug 2\n- Bug fix 2\n\n### Security\n- Known issue 1\n- Known issue 2\n\n### Deprecated\n- Deprecated feature 1\n- Future removal 2\n\n### Removed\n- Deprecated feature 2\n- Future removal 1\n\n## [1.1.0] - 2018-05-31\n### Changed\n- Enhancement 1 (1.1.0)\n - sub enhancement 1\n - sub enhancement 2\n- Enhancement 2 (1.1.0)\n\n## [1.0.1] - 2018-05-31\n### Fixed\n- Bug fix 1 (1.0.1)\n - sub bug 1\n - sub bug 2\n- Bug fix 2 (1.0.1)\n\n## [1.0.0] - 2017-04-10\n### Deprecated\n- Known issue 1 (1.0.0)\n- Known issue 2 (1.0.0)\n\n[Unreleased]: https://github.test_url/test_project/compare/v1.1.0...HEAD\n[1.1.0]: https://github.test_url/test_project/compare/v1.0.1...v1.1.0\n[1.0.1]: https://github.test_url/test_project/compare/v1.0.0...v1.0.1\n[1.0.0]: https://github.test_url/test_project/releases/tag/v1.0.0\n```\n\n`show_unreleased` parameter can be specified in order to include `Unreleased` section information.\nNote that `release_date` will be set to None in such as case.\n\n### Retrieving the raw content\n\nIf for some reason you would like to retrieve the raw content of a release you can use `to_raw_dict` instead.\n\n```python\nimport keepachangelog\n\nchanges = keepachangelog.to_raw_dict(\"path/to/CHANGELOG.md\")\n```\n\n`changes` would look like:\n\n```python\nchanges = {\n \"1.1.0\": {\n \"raw\": \"\"\"### Changed\n- Enhancement 1 (1.1.0)\n - sub enhancement 1\n - sub enhancement 2\n- Enhancement 2 (1.1.0)\"\"\",\n \"release_date\": \"2018-05-31\",\n \"version\": \"1.1.0\",\n \"semantic_version\": {\n \"major\": 1,\n \"minor\": 1,\n \"patch\": 0,\n \"prerelease\": None,\n \"buildmetadata\": None,\n },\n \"url\": \"https://github.test_url/test_project/compare/v1.0.1...v1.1.0\",\n },\n \"1.0.1\": {\n \"raw\": \"\"\"### Fixed\n- Bug fix 1 (1.0.1)\n - sub bug 1\n - sub bug 2\n- Bug fix 2 (1.0.1)\"\"\",\n \"release_date\": \"2018-05-31\",\n \"version\": \"1.0.1\",\n \"semantic_version\": {\n \"major\": 1,\n \"minor\": 0,\n \"patch\": 1,\n \"prerelease\": None,\n \"buildmetadata\": None,\n },\n \"url\": \"https://github.test_url/test_project/compare/v1.0.0...v1.0.1\",\n },\n \"1.0.0\": {\n \"raw\": \"\"\"### Deprecated\n- Known issue 1 (1.0.0)\n- Known issue 2 (1.0.0)\"\"\",\n \"release_date\": \"2017-04-10\",\n \"version\": \"1.0.0\",\n \"semantic_version\": {\n \"major\": 1,\n \"minor\": 0,\n \"patch\": 0,\n \"prerelease\": None,\n \"buildmetadata\": None,\n },\n \"url\": \"https://github.test_url/test_project/releases/tag/v1.0.0\",\n },\n}\n```\n\n## Release\n\nYou can create a new release by using `keepachangelog.release` function.\n\n```python\nimport keepachangelog\n\nnew_version = keepachangelog.release(\"path/to/CHANGELOG.md\")\n```\n\nThis will:\n* If `new_version` parameter is not provided, guess the new version number and return it:\n * `Removed` or `Changed` sections will be considered as breaking changes, thus incrementing the major version.\n * If the only section is `Fixed`, only patch will be incremented.\n * Otherwise, minor will be incremented.\n* Update changelog.\n * Unreleased section content will be moved into a new section.\n * `[Unreleased]` link will be updated.\n * New link will be created corresponding to the new section (based on the format of the Unreleased link).\n\n## Endpoint\n\n### Starlette\n\nAn helper function is available to create a [starlette](https://www.starlette.io) endpoint to retrieve changelog as JSON.\n\n```python\nfrom starlette.applications import Starlette\nfrom keepachangelog.starlette import add_changelog_endpoint\n\n\napp = Starlette()\n# /changelog endpoint will return the dict extracted from the changelog as JSON.\nadd_changelog_endpoint(app, \"path/to/CHANGELOG.md\")\n```\n\nNote: [starlette](https://pypi.python.org/pypi/starlette) module must be installed.\n\n### Flask-RestX\n\nAn helper function is available to create a [Flask-RestX](https://flask-restx.readthedocs.io/en/latest/) endpoint to retrieve changelog as JSON.\n\n```python\nimport flask\nimport flask_restx\nfrom keepachangelog.flask_restx import add_changelog_endpoint\n\n\napp = flask.Flask(__name__)\napi = flask_restx.Api(app)\n# /changelog endpoint will return the dict extracted from the changelog as JSON.\nadd_changelog_endpoint(api, \"path/to/CHANGELOG.md\")\n```\n\nNote: [flask-restx](https://pypi.python.org/pypi/flask-restx) module must be installed.\n\n## How to install\n1. [python 3.6+](https://www.python.org/downloads/) must be installed\n2. Use pip to install module:\n```sh\npython -m pip install keepachangelog\n```\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Manipulate keep a changelog files.",
"version": "1.0.0",
"split_keywords": [
"changelog",
"changelog.md",
"markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "43a2766e4067238613b51ac6720dd167f2398e832122d6ef23327ebeac0d3364",
"md5": "81d60be51f8903a67ef2c97db8c2c5f0",
"sha256": "1b73548ce85518b73009ce71af79c617c663437268cb085071973440c0505158"
},
"downloads": -1,
"filename": "keepachangelog-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "81d60be51f8903a67ef2c97db8c2c5f0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 9400,
"upload_time": "2021-05-21T14:31:59",
"upload_time_iso_8601": "2021-05-21T14:31:59.614639Z",
"url": "https://files.pythonhosted.org/packages/43/a2/766e4067238613b51ac6720dd167f2398e832122d6ef23327ebeac0d3364/keepachangelog-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "212a9c23fc183c320d3e448fb2e02d8daf23f4fa1de67dfb7d172d7b1c891864",
"md5": "f14e246a70b9fd392157e96831de0741",
"sha256": "0d3331f6601aeccf73620319782f0e993b1147b1fcba0ee2a534e4eef4b252b4"
},
"downloads": -1,
"filename": "keepachangelog-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "f14e246a70b9fd392157e96831de0741",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 8303,
"upload_time": "2021-05-21T14:32:00",
"upload_time_iso_8601": "2021-05-21T14:32:00.862304Z",
"url": "https://files.pythonhosted.org/packages/21/2a/9c23fc183c320d3e448fb2e02d8daf23f4fa1de67dfb7d172d7b1c891864/keepachangelog-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-05-21 14:32:00",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "keepachangelog"
}
JSON