| Name | bumpcalver JSON |
| Version |
2024.12.14.1
JSON |
| download |
| home_page | None |
| Summary | A CLI tool for calendar-based version bumping |
| upload_time | 2024-12-15 01:10:46 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License Copyright (c) 2024 Mike Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
calendar versioning
calver
cli
library
python
versioning
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
autoflake
autopep8
black
build
click
flake8
genbadge
hatchling
httpx
mkdocs-material
mkdocs-print-site-plugin
mkdocstrings
packaging
pre-commit
pylint
pytest
pytest-cov
pytest-html
pytest-mock
pytest-runner
pytest-xdist
PyYAML
ruff
toml
tox
twine
wheel
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://pypi.python.org/pypi/bumpcalver/)
[](https://pepy.tech/project/bumpcalver)
[](https://pepy.tech/project/bumpcalver)
[](https://pepy.tech/project/bumpcalver)
Support Python Versions
[](https://github.com/astral-sh/ruff)
[](./reports/coverage/index.html)
[](./reports/coverage/index.html)
CI/CD Pipeline:
[](https://github.com/devsetgo/bumpcalver/actions/workflows/testing.yml)
[](https://github.com/devsetgo/bumpcalver/actions/workflows/testing.yml)
SonarCloud:
[](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)
[](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)
[](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)
[](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)
[](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)
# BumpCalver CLI Documentation
## Note
This project should be consider in beta and is not yet ready for production use.
## Overview
The **BumpCalver CLI** is a command-line interface for calendar-based version bumping. It automates the process of updating version strings in your project's files based on the current date and build count. Additionally, it can create Git tags and commit changes automatically. The CLI is highly configurable via a `pyproject.toml` file and supports various customization options to fit your project's needs.
---
## Table of Contents
- Documentation Site: [BumpCalver CLI](https://devsetgo.github.io/bumpcalver/)
- [Installation](#installation)
- [Getting Started](#getting-started)
- [Configuration](#configuration)
- [Example Configuration](#example-configuration)
- [Command-Line Usage](#command-line-usage)
- [Options](#options)
- [Examples](#examples)
- [Error Handling](#error-handling)
- [Support](#support)
---
## Installation
To install the BumpCalver CLI, you can add it to your project's dependencies. If it's packaged as a Python module, you might install it via:
```bash
pip install bumpcalver
```
*Note: Replace the installation command with the actual method based on how the package is distributed.*
---
## Getting Started
1. **Configure Your Project**: Create or update the `pyproject.toml` file in your project's root directory to include the `[tool.bumpcalver]` section with your desired settings.
2. **Run the CLI**: Use the `bumpcalver` command with appropriate options to bump your project's version.
Example:
```bash
bumpcalver --build --git-tag --auto-commit
```
---
## Configuration
The BumpCalver CLI relies on a `pyproject.toml` configuration file located at the root of your project. This file specifies how versioning should be handled, which files to update, and other settings.
As an alternative, you can use configuration file named `bumpcalver.toml`. The CLI will look for this file if `pyproject.toml` is not found.
### Configuration Options
- `version_format` (string): Format string for the version. Should include `{current_date}` and `{build_count}` placeholders.
- `date_format` (string): Format string for the date. Supports various combinations of year, month, day, quarter, and week.
- `timezone` (string): Timezone for date calculations (e.g., `UTC`, `America/New_York`).
- `file` (list of tables): Specifies which files to update and how to find the version string.
- `path` (string): Path to the file to be updated.
- `file_type` (string): Type of the file (e.g., `python`, `toml`, `yaml`, `json`, `xml`, `dockerfile`, `makefile`).
- `variable` (string, optional): The variable name that holds the version string in the file.
- `pattern` (string, optional): A regex pattern to find the version string.
- `version_standard` (string, optional): The versioning standard to follow (e.g., `python` for PEP 440).
- `git_tag` (boolean): Whether to create a Git tag with the new version.
- `auto_commit` (boolean): Whether to automatically commit changes when creating a Git tag.
### Example Configuration
```toml
[tool.bumpcalver]
version_format = "{current_date}-{build_count:03}"
date_format = "%y.%m.%d"
timezone = "America/New_York"
git_tag = true
auto_commit = true
[[tool.bumpcalver.file]]
path = "pyproject.toml"
file_type = "toml"
variable = "project.version"
version_standard = "python"
[[tool.bumpcalver.file]]
path = "examples/makefile"
file_type = "makefile"
variable = "APP_VERSION"
version_standard = "default"
[[tool.bumpcalver.file]]
path = "examples/dockerfile"
file_type = "dockerfile"
variable = "arg.VERSION"
version_standard = "default"
[[tool.bumpcalver.file]]
path = "examples/dockerfile"
file_type = "dockerfile"
variable = "env.APP_VERSION"
version_standard = "default"
[[tool.bumpcalver.file]]
path = "examples/p.py"
file_type = "python"
variable = "__version__"
version_standard = "python"
```
### Date Format Examples
The `date_format` option allows you to customize the date format used in version strings. Here are some examples of how to format dates:
- `%Y.%m.%d` - Full year, month, and day (e.g., `2024.12.25`)
- `%y.%m.%d` - Year without century, month, and day (e.g., `24.12.25`)
- `%y.Q%q` - Year and quarter (e.g., `24.Q1`)
- `%y.%m` - Year and month (e.g., `24.12`)
- `%y.%j` - Year and day of the year (e.g., `24.001` for January 1st, 2024)
- `%Y.%j` - Full year and day of the year (e.g., `2024.001` for January 1st, 2024)
- `%Y.%m` - Full year and month (e.g., `2024.12`)
- `%Y.Q%q` - Full year and quarter (e.g., `2024.Q1`)
Refer to the [Python datetime documentation](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes) for more format codes.
---
## Command-Line Usage
The CLI provides several options to customize the version bumping process.
```bash
Usage: bumpcalver [OPTIONS]
Options:
--beta Use beta versioning.
--build Use build count versioning.
--timezone TEXT Timezone for date calculations (default: value
from config or America/New_York).
--git-tag / --no-git-tag Create a Git tag with the new version.
--auto-commit / --no-auto-commit
Automatically commit changes when creating a Git
tag.
--help Show this message and exit.
```
### Options
- `--beta`: Prefixes the version with `beta-`.
- `--build`: Increments the build count based on the current date.
- `--timezone`: Overrides the timezone specified in the configuration.
- `--git-tag` / `--no-git-tag`: Forces Git tagging on or off, overriding the configuration.
- `--auto-commit` / `--no-auto-commit`: Forces auto-commit on or off, overriding the configuration.
---
## Examples
### Basic Version Bump
To bump the version using the current date and build count:
```bash
bumpcalver --build
```
### Beta Versioning
To create a beta version:
```bash
bumpcalver --build --beta
```
### Specifying Timezone
To use a specific timezone:
```bash
bumpcalver --build --timezone Europe/London
```
### Creating a Git Tag with Auto-Commit
To bump the version, commit changes, and create a Git tag:
```bash
bumpcalver --build --git-tag --auto-commit
```
---
## Error Handling
- **Unknown Timezone**: If an invalid timezone is specified, the default timezone (`America/New_York`) is used, and a warning is printed.
- **File Not Found**: If a specified file is not found during version update, an error message is printed.
- **Invalid Build Count**: If the existing build count in a file is invalid, it resets to `1`, and a warning is printed.
- **Git Errors**: Errors during Git operations are caught, and an error message is displayed.
- **Malformed Configuration**: If the `pyproject.toml` file is malformed, an error is printed, and the program exits.
---
## Support
For issues or questions, please open an issue on the project's repository.
---
Raw data
{
"_id": null,
"home_page": null,
"name": "bumpcalver",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "calendar versioning, calver, cli, library, python, versioning",
"author": null,
"author_email": "Mike Ryan <mikeryan56@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a2/f8/34ae568e1e2f5d89af48dab5091c879449a0281ccba7e109dbdda494602b/bumpcalver-2024.12.14.1.tar.gz",
"platform": null,
"description": "[](https://pypi.python.org/pypi/bumpcalver/)\n[](https://pepy.tech/project/bumpcalver)\n[](https://pepy.tech/project/bumpcalver)\n[](https://pepy.tech/project/bumpcalver)\n\nSupport Python Versions\n\n\n[](https://github.com/astral-sh/ruff)\n[](./reports/coverage/index.html)\n[](./reports/coverage/index.html)\n\nCI/CD Pipeline:\n\n[](https://github.com/devsetgo/bumpcalver/actions/workflows/testing.yml)\n[](https://github.com/devsetgo/bumpcalver/actions/workflows/testing.yml)\n\nSonarCloud:\n\n[](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)\n[](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)\n[](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)\n[](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)\n[](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)\n\n# BumpCalver CLI Documentation\n\n## Note\nThis project should be consider in beta and is not yet ready for production use.\n\n## Overview\n\nThe **BumpCalver CLI** is a command-line interface for calendar-based version bumping. It automates the process of updating version strings in your project's files based on the current date and build count. Additionally, it can create Git tags and commit changes automatically. The CLI is highly configurable via a `pyproject.toml` file and supports various customization options to fit your project's needs.\n\n---\n\n## Table of Contents\n- Documentation Site: [BumpCalver CLI](https://devsetgo.github.io/bumpcalver/)\n\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n- [Configuration](#configuration)\n - [Example Configuration](#example-configuration)\n- [Command-Line Usage](#command-line-usage)\n - [Options](#options)\n- [Examples](#examples)\n- [Error Handling](#error-handling)\n- [Support](#support)\n\n---\n\n## Installation\n\nTo install the BumpCalver CLI, you can add it to your project's dependencies. If it's packaged as a Python module, you might install it via:\n\n```bash\npip install bumpcalver\n```\n\n*Note: Replace the installation command with the actual method based on how the package is distributed.*\n\n---\n\n## Getting Started\n\n1. **Configure Your Project**: Create or update the `pyproject.toml` file in your project's root directory to include the `[tool.bumpcalver]` section with your desired settings.\n\n2. **Run the CLI**: Use the `bumpcalver` command with appropriate options to bump your project's version.\n\nExample:\n\n```bash\nbumpcalver --build --git-tag --auto-commit\n```\n\n---\n\n## Configuration\n\nThe BumpCalver CLI relies on a `pyproject.toml` configuration file located at the root of your project. This file specifies how versioning should be handled, which files to update, and other settings.\n\nAs an alternative, you can use configuration file named `bumpcalver.toml`. The CLI will look for this file if `pyproject.toml` is not found.\n\n### Configuration Options\n\n- `version_format` (string): Format string for the version. Should include `{current_date}` and `{build_count}` placeholders.\n- `date_format` (string): Format string for the date. Supports various combinations of year, month, day, quarter, and week.\n- `timezone` (string): Timezone for date calculations (e.g., `UTC`, `America/New_York`).\n- `file` (list of tables): Specifies which files to update and how to find the version string.\n - `path` (string): Path to the file to be updated.\n - `file_type` (string): Type of the file (e.g., `python`, `toml`, `yaml`, `json`, `xml`, `dockerfile`, `makefile`).\n - `variable` (string, optional): The variable name that holds the version string in the file.\n - `pattern` (string, optional): A regex pattern to find the version string.\n - `version_standard` (string, optional): The versioning standard to follow (e.g., `python` for PEP 440).\n- `git_tag` (boolean): Whether to create a Git tag with the new version.\n- `auto_commit` (boolean): Whether to automatically commit changes when creating a Git tag.\n\n### Example Configuration\n\n```toml\n[tool.bumpcalver]\nversion_format = \"{current_date}-{build_count:03}\"\ndate_format = \"%y.%m.%d\"\ntimezone = \"America/New_York\"\ngit_tag = true\nauto_commit = true\n\n[[tool.bumpcalver.file]]\npath = \"pyproject.toml\"\nfile_type = \"toml\"\nvariable = \"project.version\"\nversion_standard = \"python\"\n\n[[tool.bumpcalver.file]]\npath = \"examples/makefile\"\nfile_type = \"makefile\"\nvariable = \"APP_VERSION\"\nversion_standard = \"default\"\n\n[[tool.bumpcalver.file]]\npath = \"examples/dockerfile\"\nfile_type = \"dockerfile\"\nvariable = \"arg.VERSION\"\nversion_standard = \"default\"\n\n[[tool.bumpcalver.file]]\npath = \"examples/dockerfile\"\nfile_type = \"dockerfile\"\nvariable = \"env.APP_VERSION\"\nversion_standard = \"default\"\n\n[[tool.bumpcalver.file]]\npath = \"examples/p.py\"\nfile_type = \"python\"\nvariable = \"__version__\"\nversion_standard = \"python\"\n```\n\n### Date Format Examples\n\nThe `date_format` option allows you to customize the date format used in version strings. Here are some examples of how to format dates:\n\n- `%Y.%m.%d` - Full year, month, and day (e.g., `2024.12.25`)\n- `%y.%m.%d` - Year without century, month, and day (e.g., `24.12.25`)\n- `%y.Q%q` - Year and quarter (e.g., `24.Q1`)\n- `%y.%m` - Year and month (e.g., `24.12`)\n- `%y.%j` - Year and day of the year (e.g., `24.001` for January 1st, 2024)\n- `%Y.%j` - Full year and day of the year (e.g., `2024.001` for January 1st, 2024)\n- `%Y.%m` - Full year and month (e.g., `2024.12`)\n- `%Y.Q%q` - Full year and quarter (e.g., `2024.Q1`)\n\nRefer to the [Python datetime documentation](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes) for more format codes.\n\n---\n\n## Command-Line Usage\n\nThe CLI provides several options to customize the version bumping process.\n\n```bash\nUsage: bumpcalver [OPTIONS]\n\nOptions:\n --beta Use beta versioning.\n --build Use build count versioning.\n --timezone TEXT Timezone for date calculations (default: value\n from config or America/New_York).\n --git-tag / --no-git-tag Create a Git tag with the new version.\n --auto-commit / --no-auto-commit\n Automatically commit changes when creating a Git\n tag.\n --help Show this message and exit.\n```\n\n### Options\n\n- `--beta`: Prefixes the version with `beta-`.\n- `--build`: Increments the build count based on the current date.\n- `--timezone`: Overrides the timezone specified in the configuration.\n- `--git-tag` / `--no-git-tag`: Forces Git tagging on or off, overriding the configuration.\n- `--auto-commit` / `--no-auto-commit`: Forces auto-commit on or off, overriding the configuration.\n\n---\n\n## Examples\n\n### Basic Version Bump\n\nTo bump the version using the current date and build count:\n\n```bash\nbumpcalver --build\n```\n\n### Beta Versioning\n\nTo create a beta version:\n\n```bash\nbumpcalver --build --beta\n```\n\n### Specifying Timezone\n\nTo use a specific timezone:\n\n```bash\nbumpcalver --build --timezone Europe/London\n```\n\n### Creating a Git Tag with Auto-Commit\n\nTo bump the version, commit changes, and create a Git tag:\n\n```bash\nbumpcalver --build --git-tag --auto-commit\n```\n\n---\n\n## Error Handling\n\n- **Unknown Timezone**: If an invalid timezone is specified, the default timezone (`America/New_York`) is used, and a warning is printed.\n- **File Not Found**: If a specified file is not found during version update, an error message is printed.\n- **Invalid Build Count**: If the existing build count in a file is invalid, it resets to `1`, and a warning is printed.\n- **Git Errors**: Errors during Git operations are caught, and an error message is displayed.\n- **Malformed Configuration**: If the `pyproject.toml` file is malformed, an error is printed, and the program exits.\n\n---\n\n## Support\n\nFor issues or questions, please open an issue on the project's repository.\n\n---\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Mike Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "A CLI tool for calendar-based version bumping",
"version": "2024.12.14.1",
"project_urls": {
"Documentation": "https://devsetgo.github.io/bumpcalver/",
"Homepage": "https://github.com/devsetgo/bumpcalver",
"Repository": "https://github.com/devsetgo/bumpcalver"
},
"split_keywords": [
"calendar versioning",
" calver",
" cli",
" library",
" python",
" versioning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3ed59f53970895e96cb0ab4d75596be64185c020fd93f7b14556722f6c36f6ad",
"md5": "aefbda2ec87f8948c604f4a92d8816c3",
"sha256": "2000c9f15d025c483c8a5ad5cb4fac2b0b0afc4ea57a6fa77f615ae5c9d5aec0"
},
"downloads": -1,
"filename": "bumpcalver-2024.12.14.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aefbda2ec87f8948c604f4a92d8816c3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 16141,
"upload_time": "2024-12-15T01:10:42",
"upload_time_iso_8601": "2024-12-15T01:10:42.833180Z",
"url": "https://files.pythonhosted.org/packages/3e/d5/9f53970895e96cb0ab4d75596be64185c020fd93f7b14556722f6c36f6ad/bumpcalver-2024.12.14.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a2f834ae568e1e2f5d89af48dab5091c879449a0281ccba7e109dbdda494602b",
"md5": "d2bd2f4b0bff61124f4e608015211685",
"sha256": "89d4e1a96fd02ad0b1ae291e948779258b77817165659ad439ca7cf248a6f1b9"
},
"downloads": -1,
"filename": "bumpcalver-2024.12.14.1.tar.gz",
"has_sig": false,
"md5_digest": "d2bd2f4b0bff61124f4e608015211685",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 67386,
"upload_time": "2024-12-15T01:10:46",
"upload_time_iso_8601": "2024-12-15T01:10:46.607888Z",
"url": "https://files.pythonhosted.org/packages/a2/f8/34ae568e1e2f5d89af48dab5091c879449a0281ccba7e109dbdda494602b/bumpcalver-2024.12.14.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-15 01:10:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "devsetgo",
"github_project": "bumpcalver",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "autoflake",
"specs": [
[
"==",
"2.3.1"
]
]
},
{
"name": "autopep8",
"specs": [
[
"==",
"2.3.1"
]
]
},
{
"name": "black",
"specs": [
[
"==",
"24.10.0"
]
]
},
{
"name": "build",
"specs": [
[
"==",
"1.2.2.post1"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.7"
]
]
},
{
"name": "flake8",
"specs": [
[
"==",
"7.1.1"
]
]
},
{
"name": "genbadge",
"specs": [
[
"==",
"1.1.1"
]
]
},
{
"name": "hatchling",
"specs": [
[
"==",
"1.26.3"
]
]
},
{
"name": "httpx",
"specs": [
[
"==",
"0.28.1"
]
]
},
{
"name": "mkdocs-material",
"specs": [
[
"==",
"9.5.47"
]
]
},
{
"name": "mkdocs-print-site-plugin",
"specs": [
[
"==",
"2.6.0"
]
]
},
{
"name": "mkdocstrings",
"specs": [
[
"==",
"0.27.0"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.2"
]
]
},
{
"name": "pre-commit",
"specs": [
[
"==",
"4.0.1"
]
]
},
{
"name": "pylint",
"specs": [
[
"==",
"3.3.2"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.3.4"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"6.0.0"
]
]
},
{
"name": "pytest-html",
"specs": [
[
"==",
"4.1.1"
]
]
},
{
"name": "pytest-mock",
"specs": [
[
"==",
"3.14.0"
]
]
},
{
"name": "pytest-runner",
"specs": [
[
"==",
"6.0.1"
]
]
},
{
"name": "pytest-xdist",
"specs": [
[
"==",
"3.6.1"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "ruff",
"specs": [
[
"==",
"0.8.2"
]
]
},
{
"name": "toml",
"specs": [
[
"==",
"0.10.2"
]
]
},
{
"name": "tox",
"specs": [
[
"==",
"4.23.2"
]
]
},
{
"name": "twine",
"specs": [
[
"==",
"6.0.1"
]
]
},
{
"name": "wheel",
"specs": [
[
"==",
"0.45.1"
]
]
}
],
"lcname": "bumpcalver"
}
