Merge pull request #13 from brainelectronics/feature/render-version-f…

…ile-from-template

Render version file from template

.github/workflows/unittest.yaml

@@ -3,7 +3,7 @@
 
 name: Unittest Python Package
 
-on: push
+on: [push, pull_request]
 
 permissions:
   contents: read
@@ -24,23 +24,12 @@ jobs:
     - name: Create coverage report
       run: |
         coverage xml
-    - uses: actions/cache@v3
-      with:
-        path: ./reports/coverage/coverage.xml
-        key: coverage-xml-report
-
-  upload-coverage:
-    needs: test-and-coverage
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/cache@v3
-      with:
-        path: ./reports/coverage/coverage.xml
-        key: coverage-xml-report
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v3
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         files: ./reports/coverage/coverage.xml
         flags: unittests
+        fail_ci_if_error: true
+        # path_to_write_report: ./reports/coverage/codecov_report.txt
         verbose: true

.gitignore

@@ -1,3 +1,9 @@
+# created files based on README examples
+examples/*.c
+examples/*.h
+examples/*.py
+examples/version_info
+
 # custom, package specific ignores
 .DS_Store
 .DS_Store?

README.md

@@ -14,6 +14,21 @@ Update version info file with latest changelog version entry
 
 Create version info files based on the latest changelog entry.
 
+<!-- MarkdownTOC -->
+
+- [Installation](#installation)
+- [Usage](#usage)
+    - [Available default template files](#available-default-template-files)
+        - [C header file](#c-header-file)
+        - [Python package file](#python-package-file)
+- [Advanced](#advanced)
+    - [Custom regular expressions](#custom-regular-expressions)
+    - [Custom template file](#custom-template-file)
+- [Credits](#credits)
+
+<!-- /MarkdownTOC -->
+
+
 ## Installation
 
 ```bash
@@ -23,19 +38,76 @@ pip install changelog2version
 ## Usage
 
 This example shows you how to parse the [repo's changelog](changelog.md) and
-update the [package version file](src/changelog2version/version.py) with that
+update the [package version file][ref-package-version-file] with that
 version.
 
 ```bash
 changelog2version \
     --changelog_file changelog.md \
-    --version_file src/changelog2version/version.py \
+    --version_file examples/version.py \
+    --debug
+```
+
+### Available default template files
+
+By default a Python version file is generated. Check the table below and the
+example usage for further details and supported template files
+
+| Type   | Parameter | Description |
+| ------ | --------- | ----------- |
+| Python | `py`      | See [example package version][ref-package-version-file] |
+| C/CPP  | `c`       | Header file with available version info |
+
+#### C header file
+
+```bash
+changelog2version \
+    --changelog_file changelog.md \
+    --version_file examples/version_info.h \
+    --version_file_type c \
+    --debug
+```
+
+```
+//
+//  version_info.h
+//
+//  Created automatically by script
+//
+
+#ifndef version_info_h
+#define version_info_h
+
+#define MAJOR_VERSION   0     //< major software version
+#define MINOR_VERSION   4     //< minor software version
+#define PATCH_VERSION   0     //< patch software version
+
+#endif
+```
+
+#### Python package file
+
+```bash
+changelog2version \
+    --changelog_file changelog.md \
+    --version_file examples/version.py \
+    --version_file_type py \
     --debug
 ```
 
+```
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+
+__version_info__ = ("0", "4", "0")
+__version__ = '.'.join(__version_info__)
+
+```
+
 ## Advanced
 
 ### Custom regular expressions
+
 To extract a version line from a given changelog file with an alternative
 regex, the `version_line_regex` argument can be used as shown below. The
 expression is validated during the CLI argument parsing
@@ -52,13 +124,64 @@ Same applies for a custom semver line regex in order to extract the semantic
 version part from a full version line, use the `semver_line_regex` argument to
 adjust the regular expression to your needs.
 
+### Custom template file
+
+Beside the default supported [template files][ref-templates-folder] users can
+also provide custom template files.
+
+This is the list of currently available variables
+
+| Name                          | Description                                               |
+| ----------------------------- | --------------------------------------------------------- |
+| `major_version`               | Major version, incompatible API changes                   |
+| `minor_version`               | Minor version, add functionality (backwards-compatible)   |
+| `patch_version`               | Patch version, bug fixes (backwards-compatible)           |
+| `prerelease_data`             | pre-release data, if available                            |
+| `build_data`                  | Build metadata, if available                              |
+| `file_name`                   | User specified name of rendered file                      |
+| `file_name_without_suffix`    | User specified name of rendered file without suffix       |
+| `template_name`               | Name of rendered template file                            |
+| `template_name_without_suffix`| Name of rendered template file without suffix             |
+| Custom keyword                | Provided by the user via `--additional_template_data`     |
+
+```bash
+additional_data="{\"creation_datetime\": \"$(date +"%Y-%m-%dT%H:%M:%S")\", \"machine_name\": \"$(whoami)\"}"
+changelog2version \
+    --changelog_file changelog.md \
+    --version_file examples/version_info.c \
+    --template_file examples/version_info.c.template \
+    --additional_template_data "${additional_data}" \
+    --debug
+
+# or less fancy
+changelog2version \
+    --changelog_file changelog.md \
+    --version_file examples/version_info.c \
+    --template_file examples/version_info.c.template \
+    --additional_template_data '{"creation_datetime": "2022-08-05T21:11:12", "machine_name": "Death Star"}' \
+    --debug
+```
+
+Executing the created example file `examples/version_info.c` will print the
+following content (datetime and creator might be different)
+
+```
+Script version is (major.minor.patch): 0.4.0
+Prerelease data: None
+Prerelease data: None
+Creation datetime: 2022-08-05T21:11:12
+Created by Death Star
+```
+
 ## Credits
 
 Based on the [PyPa sample project][ref-pypa-sample]. Also a big thank you to
 the creators and maintainers of [SemVer.org][ref-semver] for their
 documentation and [regex example][ref-semver-regex-example]
 
 <!-- Links -->
+[ref-package-version-file]: src/changelog2version/version.py
+[ref-templates-folder]: src/changelog2version/templates
 [ref-pypa-sample]: https://github.com/pypa/sampleproject
 [ref-semver]: https://semver.org/
 [ref-semver-regex-example]: https://regex101.com/r/Ly7O1x/3/

changelog.md

@@ -17,6 +17,36 @@ r"^\#\# \[\d{1,}[.]\d{1,}[.]\d{1,}\] \- \d{4}\-\d{2}-\d{2}$"
 -->
 
 ## Released
+## [0.4.0] - 2022-08-07
+### Added
+- Property `semver_data` to access extracted VersionInfo from parsed semver
+  line in [`ExtractVersion class`](src/changelog2version/extract_version.py)
+- Header and python version template file
+- [`RenderVersionFile class`](src/changelog2version/render_version_file.py) to
+  render template files with provided content, resolve [#5][ref-issue-5]
+- [Examples folder](examples) with example C script to demonstrate template
+  rendering on other files than python
+- `--template_file` argument to specify a custom template file for rendering
+- `--additional_template_data` to add custom data for the template rendering
+- `c` is now a valid and supported file type of `--version_file_type`
+- Documentation extended for new CLI args with more detailed examples
+- `Jinja2` is a required package for this package
+
+### Changed
+- `parser_valid_file` function returns a resolved path
+- `--version_file_type` is no longer case sensitive
+- `--version_file` does no longer have to exist
+- Run [GitHub CI unittest workflow](.github/workflows/unittest.yml) also on
+  pull requests
+
+### Removed
+- Functions to update python version files from `update_version.py` script
+
+### Fixed
+- Only one job in [GitHub CI unittest workflow](.github/workflows/unittest.yml)
+- Let [GitHub CI unittest workflow](.github/workflows/unittest.yml) fail when
+  Codecov runs into errors during upload
+
 ## [0.3.0] - 2022-08-05
 ### Changed
 - Regex to extract the first version line from a changelog supports the full
@@ -88,13 +118,15 @@ r"^\#\# \[\d{1,}[.]\d{1,}[.]\d{1,}\] \- \d{4}\-\d{2}-\d{2}$"
 - Data folder after fork
 
 <!-- Links -->
-[Unreleased]: https://github.com/brainelectronics/changelog2version/compare/0.3.0...develop
+[Unreleased]: https://github.com/brainelectronics/changelog2version/compare/0.4.0...develop
 
+[0.4.0]: https://github.com/brainelectronics/changelog2version/tree/0.4.0
 [0.3.0]: https://github.com/brainelectronics/changelog2version/tree/0.3.0
 [0.2.0]: https://github.com/brainelectronics/changelog2version/tree/0.2.0
 [0.1.1]: https://github.com/brainelectronics/changelog2version/tree/0.1.1
 [0.1.0]: https://github.com/brainelectronics/changelog2version/tree/0.1.0
 
+[ref-issue-5]: https://github.com/brainelectronics/changelog2version/issues/5
 [ref-issue-8]: https://github.com/brainelectronics/changelog2version/issues/8
 [ref-issue-11]: https://github.com/brainelectronics/changelog2version/issues/11
 [ref-issue-4]: https://github.com/brainelectronics/changelog2version/issues/4

examples/version_info.c.template

@@ -0,0 +1,45 @@
+//
+//  {{ file_name }}
+//
+//  Rendered from {{ template_name }} by script on {{ creation_datetime }}
+//
+//  Created by {{ machine_name }}
+//
+
+#include <stdio.h>
+
+#define MAJOR_VERSION   {{ major_version }}
+#define MINOR_VERSION   {{ minor_version }}
+#define PATCH_VERSION   {{ patch_version }}
+
+void print_prerelease_data(void)
+{
+    printf("Prerelease data: {{ prerelease_data }}\n");
+}
+
+void print_build_data(void)
+{
+    printf("Prerelease data: {{ build_data }}\n");
+}
+
+void print_creation_datetime(void)
+{
+    printf("Creation datetime: {{ creation_datetime }}\n");
+}
+
+void print_creator(void)
+{
+    printf("Created by {{ machine_name }}\n");
+}
+
+int main(int argc, char const *argv[])
+{
+    printf("Script version is (major.minor.patch): %d.%d.%d\n", MAJOR_VERSION, MINOR_VERSION, PATCH_VERSION);
+
+    print_prerelease_data();
+    print_build_data();
+    print_creation_datetime();
+    print_creator();
+
+    return 0;
+}

requirements.txt

@@ -1,4 +1,6 @@
 # List external packages here
 # Avoid fixed versions
 # to parse changelog semver
-semver>=2.13.0,<3
+semver>=2.13.0,<3
+# to render template files
+jinja2>=3.1.0,<4

setup.py

@@ -135,7 +135,8 @@
     # For an analysis of "install_requires" vs pip's requirements files see:
     # https://packaging.python.org/discussions/install-requires-vs-requirements/
     install_requires=[
-        "semver>=2.13.0,<3"
+        "semver>=2.13.0,<3",
+        "jinja2>=3.1.0,<4"
     ],  # Optional
     # List additional groups of dependencies here (e.g. development
     # dependencies). Users will be able to install these using the "extras"
@@ -160,6 +161,9 @@
     # package_data={  # Optional
     #     "sample": ["package_data.dat"],
     # },
+    package_data={
+        "changelog2version": ["templates/*"]
+    },
     # Although 'package_data' is the preferred approach, in some case you may
     # need to place data files outside of your packages. See:
     # http://docs.python.org/distutils/setupscript.html#installing-additional-files