BumpCalver Library
Description | Simple Calendar Versioning Library |
Author(s) | Mike Ryan |
Repository | https://github.com/devsetgo/bumpcalver |
Copyright | Copyright © 2024 - 2025 Mike Ryan |
Table of Contents
Support Python Versions
CI/CD Pipeline:
SonarCloud:
BumpCalver CLI Documentation¶
Note¶
This project should be consider in beta as it could have bugs due to being only a few months old.
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
- Getting Started
- Command-Line Usage
- Options
- Error Handling
- 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:
pip install bumpcalver
Note: Replace the installation command with the actual method based on how the package is distributed.
Getting Started¶
-
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. -
Run the CLI: Use the
bumpcalver
command with appropriate options to bump your project's version.
Example:
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¶
[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 for more format codes.
Command-Line Usage¶
The CLI provides several options to customize the version bumping process.
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 withbeta-
.--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:
bumpcalver --build
Beta Versioning¶
To create a beta version:
bumpcalver --build --beta
Specifying Timezone¶
To use a specific timezone:
bumpcalver --build --timezone Europe/London
Creating a Git Tag with Auto-Commit¶
To bump the version, commit changes, and create a Git tag:
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.
Quick Start¶
Install¶
pip install bumpcalver
Usage¶
Initialize Configuration¶
Create a pyproject.toml
file in your project's root directory with the following content:
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"
This configuration tells BumpCalver how to format your version strings, which timezone to use, and which files to update.
Basic Version Bump¶
To bump the version using the current date and build count:
bumpcalver --build
This command will:
- Increment the build count for the current date.
- Update the
__version__
variable inversion.py
andsrc/module_name/__init__.py
. - Use the timezone specified in your configuration (
UTC
in this case).
Beta Versioning¶
To create a beta version:
bumpcalver --build --beta
This will prefix your version with beta-
, resulting in a version like beta-2023-10-05-001
.
Specify Timezone¶
To use a specific timezone (overriding the configuration):
bumpcalver --build --timezone Europe/London
Create a Git Tag with Auto-Commit¶
To bump the version, commit changes, and create a Git tag:
bumpcalver --build --git-tag --auto-commit
This command will:
- Update the version as before.
- Commit the changes to Git.
- Create a Git tag with the new version.
Additional Options¶
- Disable Git Tagging:
bumpcalver --build --no-git-tag
- Disable Auto-Commit:
bumpcalver --build --no-auto-commit
Create Custom Date Formats¶
The date_format
option in the configuration file 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
)
See Documentation¶
For more examples and advanced usage, please refer to the full documentation or visit the project's repository.
Note: Replace #
with the actual link to your documentation or repository.
Example version.py
File¶
Ensure that your version.py
file (or the file specified in your configuration) contains the version variable:
__version__ = "0.1.0"
After running bumpcalver --build
, it will be updated to:
__version__ = "2023-10-05-001"
Integrate with Your Project¶
You can import the version into your application as needed:
from version import __version__
print(f"Current version: {__version__}")
Summary¶
With BumpCalver, you can automate version management based on the calendar date and build counts, ensuring consistent and meaningful version numbers across your project.
Timezones¶
Here is a list of all timezones that can be utilized. You can search for a specific timezone by typing in the search bar.
Timezone | UTC Offset |
---|---|
Africa/Abidjan | UTC+00:00 |
Africa/Accra | UTC+00:00 |
Africa/Addis_Ababa | UTC+03:00 |
Africa/Algiers | UTC+01:00 |
Africa/Asmara | UTC+03:00 |
Africa/Asmera | UTC+03:00 |
Africa/Bamako | UTC+00:00 |
Africa/Bangui | UTC+01:00 |
Africa/Banjul | UTC+00:00 |
Africa/Bissau | UTC+00:00 |
Africa/Blantyre | UTC+02:00 |
Africa/Brazzaville | UTC+01:00 |
Africa/Bujumbura | UTC+02:00 |
Africa/Cairo | UTC+03:00 |
Africa/Casablanca | UTC+01:00 |
Africa/Ceuta | UTC+02:00 |
Africa/Conakry | UTC+00:00 |
Africa/Dakar | UTC+00:00 |
Africa/Dar_es_Salaam | UTC+03:00 |
Africa/Djibouti | UTC+03:00 |
Africa/Douala | UTC+01:00 |
Africa/El_Aaiun | UTC+01:00 |
Africa/Freetown | UTC+00:00 |
Africa/Gaborone | UTC+02:00 |
Africa/Harare | UTC+02:00 |
Africa/Johannesburg | UTC+02:00 |
Africa/Juba | UTC+02:00 |
Africa/Kampala | UTC+03:00 |
Africa/Khartoum | UTC+02:00 |
Africa/Kigali | UTC+02:00 |
Africa/Kinshasa | UTC+01:00 |
Africa/Lagos | UTC+01:00 |
Africa/Libreville | UTC+01:00 |
Africa/Lome | UTC+00:00 |
Africa/Luanda | UTC+01:00 |
Africa/Lubumbashi | UTC+02:00 |
Africa/Lusaka | UTC+02:00 |
Africa/Malabo | UTC+01:00 |
Africa/Maputo | UTC+02:00 |
Africa/Maseru | UTC+02:00 |
Africa/Mbabane | UTC+02:00 |
Africa/Mogadishu | UTC+03:00 |
Africa/Monrovia | UTC+00:00 |
Africa/Nairobi | UTC+03:00 |
Africa/Ndjamena | UTC+01:00 |
Africa/Niamey | UTC+01:00 |
Africa/Nouakchott | UTC+00:00 |
Africa/Ouagadougou | UTC+00:00 |
Africa/Porto-Novo | UTC+01:00 |
Africa/Sao_Tome | UTC+00:00 |
Africa/Timbuktu | UTC+00:00 |
Africa/Tripoli | UTC+02:00 |
Africa/Tunis | UTC+01:00 |
Africa/Windhoek | UTC+02:00 |
America/Adak | UTC-09:00 |
America/Anchorage | UTC-08:00 |
America/Anguilla | UTC-04:00 |
America/Antigua | UTC-04:00 |
America/Araguaina | UTC-03:00 |
America/Argentina/Buenos_Aires | UTC-03:00 |
America/Argentina/Catamarca | UTC-03:00 |
America/Argentina/ComodRivadavia | UTC-03:00 |
America/Argentina/Cordoba | UTC-03:00 |
America/Argentina/Jujuy | UTC-03:00 |
America/Argentina/La_Rioja | UTC-03:00 |
America/Argentina/Mendoza | UTC-03:00 |
America/Argentina/Rio_Gallegos | UTC-03:00 |
America/Argentina/Salta | UTC-03:00 |
America/Argentina/San_Juan | UTC-03:00 |
America/Argentina/San_Luis | UTC-03:00 |
America/Argentina/Tucuman | UTC-03:00 |
America/Argentina/Ushuaia | UTC-03:00 |
America/Aruba | UTC-04:00 |
America/Asuncion | UTC-04:00 |
America/Atikokan | UTC-05:00 |
America/Atka | UTC-09:00 |
America/Bahia | UTC-03:00 |
America/Bahia_Banderas | UTC-06:00 |
America/Barbados | UTC-04:00 |
America/Belem | UTC-03:00 |
America/Belize | UTC-06:00 |
America/Blanc-Sablon | UTC-04:00 |
America/Boa_Vista | UTC-04:00 |
America/Bogota | UTC-05:00 |
America/Boise | UTC-06:00 |
America/Buenos_Aires | UTC-03:00 |
America/Cambridge_Bay | UTC-06:00 |
America/Campo_Grande | UTC-04:00 |
America/Cancun | UTC-05:00 |
America/Caracas | UTC-04:00 |
America/Catamarca | UTC-03:00 |
America/Cayenne | UTC-03:00 |
America/Cayman | UTC-05:00 |
America/Chicago | UTC-05:00 |
America/Chihuahua | UTC-06:00 |
America/Ciudad_Juarez | UTC-06:00 |
America/Coral_Harbour | UTC-05:00 |
America/Cordoba | UTC-03:00 |
America/Costa_Rica | UTC-06:00 |
America/Creston | UTC-07:00 |
America/Cuiaba | UTC-04:00 |
America/Curacao | UTC-04:00 |
America/Danmarkshavn | UTC+00:00 |
America/Dawson | UTC-07:00 |
America/Dawson_Creek | UTC-07:00 |
America/Denver | UTC-06:00 |
America/Detroit | UTC-04:00 |
America/Dominica | UTC-04:00 |
America/Edmonton | UTC-06:00 |
America/Eirunepe | UTC-05:00 |
America/El_Salvador | UTC-06:00 |
America/Ensenada | UTC-07:00 |
America/Fort_Nelson | UTC-07:00 |
America/Fort_Wayne | UTC-04:00 |
America/Fortaleza | UTC-03:00 |
America/Glace_Bay | UTC-03:00 |
America/Godthab | UTC-01:00 |
America/Goose_Bay | UTC-03:00 |
America/Grand_Turk | UTC-04:00 |
America/Grenada | UTC-04:00 |
America/Guadeloupe | UTC-04:00 |
America/Guatemala | UTC-06:00 |
America/Guayaquil | UTC-05:00 |
America/Guyana | UTC-04:00 |
America/Halifax | UTC-03:00 |
America/Havana | UTC-04:00 |
America/Hermosillo | UTC-07:00 |
America/Indiana/Indianapolis | UTC-04:00 |
America/Indiana/Knox | UTC-05:00 |
America/Indiana/Marengo | UTC-04:00 |
America/Indiana/Petersburg | UTC-04:00 |
America/Indiana/Tell_City | UTC-05:00 |
America/Indiana/Vevay | UTC-04:00 |
America/Indiana/Vincennes | UTC-04:00 |
America/Indiana/Winamac | UTC-04:00 |
America/Indianapolis | UTC-04:00 |
America/Inuvik | UTC-06:00 |
America/Iqaluit | UTC-04:00 |
America/Jamaica | UTC-05:00 |
America/Jujuy | UTC-03:00 |
America/Juneau | UTC-08:00 |
America/Kentucky/Louisville | UTC-04:00 |
America/Kentucky/Monticello | UTC-04:00 |
America/Knox_IN | UTC-05:00 |
America/Kralendijk | UTC-04:00 |
America/La_Paz | UTC-04:00 |
America/Lima | UTC-05:00 |
America/Los_Angeles | UTC-07:00 |
America/Louisville | UTC-04:00 |
America/Lower_Princes | UTC-04:00 |
America/Maceio | UTC-03:00 |
America/Managua | UTC-06:00 |
America/Manaus | UTC-04:00 |
America/Marigot | UTC-04:00 |
America/Martinique | UTC-04:00 |
America/Matamoros | UTC-05:00 |
America/Mazatlan | UTC-07:00 |
America/Mendoza | UTC-03:00 |
America/Menominee | UTC-05:00 |
America/Merida | UTC-06:00 |
America/Metlakatla | UTC-08:00 |
America/Mexico_City | UTC-06:00 |
America/Miquelon | UTC-02:00 |
America/Moncton | UTC-03:00 |
America/Monterrey | UTC-06:00 |
America/Montevideo | UTC-03:00 |
America/Montreal | UTC-04:00 |
America/Montserrat | UTC-04:00 |
America/Nassau | UTC-04:00 |
America/New_York | UTC-04:00 |
America/Nipigon | UTC-04:00 |
America/Nome | UTC-08:00 |
America/Noronha | UTC-02:00 |
America/North_Dakota/Beulah | UTC-05:00 |
America/North_Dakota/Center | UTC-05:00 |
America/North_Dakota/New_Salem | UTC-05:00 |
America/Nuuk | UTC-01:00 |
America/Ojinaga | UTC-05:00 |
America/Panama | UTC-05:00 |
America/Pangnirtung | UTC-04:00 |
America/Paramaribo | UTC-03:00 |
America/Phoenix | UTC-07:00 |
America/Port-au-Prince | UTC-04:00 |
America/Port_of_Spain | UTC-04:00 |
America/Porto_Acre | UTC-05:00 |
America/Porto_Velho | UTC-04:00 |
America/Puerto_Rico | UTC-04:00 |
America/Punta_Arenas | UTC-03:00 |
America/Rainy_River | UTC-05:00 |
America/Rankin_Inlet | UTC-05:00 |
America/Recife | UTC-03:00 |
America/Regina | UTC-06:00 |
America/Resolute | UTC-05:00 |
America/Rio_Branco | UTC-05:00 |
America/Rosario | UTC-03:00 |
America/Santa_Isabel | UTC-07:00 |
America/Santarem | UTC-03:00 |
America/Santiago | UTC-03:00 |
America/Santo_Domingo | UTC-04:00 |
America/Sao_Paulo | UTC-03:00 |
America/Scoresbysund | UTC-01:00 |
America/Shiprock | UTC-06:00 |
America/Sitka | UTC-08:00 |
America/St_Barthelemy | UTC-04:00 |
America/St_Johns | UTC-02:30 |
America/St_Kitts | UTC-04:00 |
America/St_Lucia | UTC-04:00 |
America/St_Thomas | UTC-04:00 |
America/St_Vincent | UTC-04:00 |
America/Swift_Current | UTC-06:00 |
America/Tegucigalpa | UTC-06:00 |
America/Thule | UTC-03:00 |
America/Thunder_Bay | UTC-04:00 |
America/Tijuana | UTC-07:00 |
America/Toronto | UTC-04:00 |
America/Tortola | UTC-04:00 |
America/Vancouver | UTC-07:00 |
America/Virgin | UTC-04:00 |
America/Whitehorse | UTC-07:00 |
America/Winnipeg | UTC-05:00 |
America/Yakutat | UTC-08:00 |
America/Yellowknife | UTC-06:00 |
Antarctica/Casey | UTC+08:00 |
Antarctica/Davis | UTC+07:00 |
Antarctica/DumontDUrville | UTC+10:00 |
Antarctica/Macquarie | UTC+10:00 |
Antarctica/Mawson | UTC+05:00 |
Antarctica/McMurdo | UTC+13:00 |
Antarctica/Palmer | UTC-03:00 |
Antarctica/Rothera | UTC-03:00 |
Antarctica/South_Pole | UTC+13:00 |
Antarctica/Syowa | UTC+03:00 |
Antarctica/Troll | UTC+02:00 |
Antarctica/Vostok | UTC+05:00 |
Arctic/Longyearbyen | UTC+02:00 |
Asia/Aden | UTC+03:00 |
Asia/Almaty | UTC+05:00 |
Asia/Amman | UTC+03:00 |
Asia/Anadyr | UTC+12:00 |
Asia/Aqtau | UTC+05:00 |
Asia/Aqtobe | UTC+05:00 |
Asia/Ashgabat | UTC+05:00 |
Asia/Ashkhabad | UTC+05:00 |
Asia/Atyrau | UTC+05:00 |
Asia/Baghdad | UTC+03:00 |
Asia/Bahrain | UTC+03:00 |
Asia/Baku | UTC+04:00 |
Asia/Bangkok | UTC+07:00 |
Asia/Barnaul | UTC+07:00 |
Asia/Beirut | UTC+03:00 |
Asia/Bishkek | UTC+06:00 |
Asia/Brunei | UTC+08:00 |
Asia/Calcutta | UTC+05:30 |
Asia/Chita | UTC+09:00 |
Asia/Choibalsan | UTC+08:00 |
Asia/Chongqing | UTC+08:00 |
Asia/Chungking | UTC+08:00 |
Asia/Colombo | UTC+05:30 |
Asia/Dacca | UTC+06:00 |
Asia/Damascus | UTC+03:00 |
Asia/Dhaka | UTC+06:00 |
Asia/Dili | UTC+09:00 |
Asia/Dubai | UTC+04:00 |
Asia/Dushanbe | UTC+05:00 |
Asia/Famagusta | UTC+03:00 |
Asia/Gaza | UTC+03:00 |
Asia/Harbin | UTC+08:00 |
Asia/Hebron | UTC+03:00 |
Asia/Ho_Chi_Minh | UTC+07:00 |
Asia/Hong_Kong | UTC+08:00 |
Asia/Hovd | UTC+07:00 |
Asia/Irkutsk | UTC+08:00 |
Asia/Istanbul | UTC+03:00 |
Asia/Jakarta | UTC+07:00 |
Asia/Jayapura | UTC+09:00 |
Asia/Jerusalem | UTC+03:00 |
Asia/Kabul | UTC+04:30 |
Asia/Kamchatka | UTC+12:00 |
Asia/Karachi | UTC+05:00 |
Asia/Kashgar | UTC+06:00 |
Asia/Kathmandu | UTC+05:45 |
Asia/Katmandu | UTC+05:45 |
Asia/Khandyga | UTC+09:00 |
Asia/Kolkata | UTC+05:30 |
Asia/Krasnoyarsk | UTC+07:00 |
Asia/Kuala_Lumpur | UTC+08:00 |
Asia/Kuching | UTC+08:00 |
Asia/Kuwait | UTC+03:00 |
Asia/Macao | UTC+08:00 |
Asia/Macau | UTC+08:00 |
Asia/Magadan | UTC+11:00 |
Asia/Makassar | UTC+08:00 |
Asia/Manila | UTC+08:00 |
Asia/Muscat | UTC+04:00 |
Asia/Nicosia | UTC+03:00 |
Asia/Novokuznetsk | UTC+07:00 |
Asia/Novosibirsk | UTC+07:00 |
Asia/Omsk | UTC+06:00 |
Asia/Oral | UTC+05:00 |
Asia/Phnom_Penh | UTC+07:00 |
Asia/Pontianak | UTC+07:00 |
Asia/Pyongyang | UTC+09:00 |
Asia/Qatar | UTC+03:00 |
Asia/Qostanay | UTC+05:00 |
Asia/Qyzylorda | UTC+05:00 |
Asia/Rangoon | UTC+06:30 |
Asia/Riyadh | UTC+03:00 |
Asia/Saigon | UTC+07:00 |
Asia/Sakhalin | UTC+11:00 |
Asia/Samarkand | UTC+05:00 |
Asia/Seoul | UTC+09:00 |
Asia/Shanghai | UTC+08:00 |
Asia/Singapore | UTC+08:00 |
Asia/Srednekolymsk | UTC+11:00 |
Asia/Taipei | UTC+08:00 |
Asia/Tashkent | UTC+05:00 |
Asia/Tbilisi | UTC+04:00 |
Asia/Tehran | UTC+03:30 |
Asia/Tel_Aviv | UTC+03:00 |
Asia/Thimbu | UTC+06:00 |
Asia/Thimphu | UTC+06:00 |
Asia/Tokyo | UTC+09:00 |
Asia/Tomsk | UTC+07:00 |
Asia/Ujung_Pandang | UTC+08:00 |
Asia/Ulaanbaatar | UTC+08:00 |
Asia/Ulan_Bator | UTC+08:00 |
Asia/Urumqi | UTC+06:00 |
Asia/Ust-Nera | UTC+10:00 |
Asia/Vientiane | UTC+07:00 |
Asia/Vladivostok | UTC+10:00 |
Asia/Yakutsk | UTC+09:00 |
Asia/Yangon | UTC+06:30 |
Asia/Yekaterinburg | UTC+05:00 |
Asia/Yerevan | UTC+04:00 |
Atlantic/Azores | UTC+00:00 |
Atlantic/Bermuda | UTC-03:00 |
Atlantic/Canary | UTC+01:00 |
Atlantic/Cape_Verde | UTC-01:00 |
Atlantic/Faeroe | UTC+01:00 |
Atlantic/Faroe | UTC+01:00 |
Atlantic/Jan_Mayen | UTC+02:00 |
Atlantic/Madeira | UTC+01:00 |
Atlantic/Reykjavik | UTC+00:00 |
Atlantic/South_Georgia | UTC-02:00 |
Atlantic/St_Helena | UTC+00:00 |
Atlantic/Stanley | UTC-03:00 |
Australia/ACT | UTC+10:00 |
Australia/Adelaide | UTC+09:30 |
Australia/Brisbane | UTC+10:00 |
Australia/Broken_Hill | UTC+09:30 |
Australia/Canberra | UTC+10:00 |
Australia/Currie | UTC+10:00 |
Australia/Darwin | UTC+09:30 |
Australia/Eucla | UTC+08:45 |
Australia/Hobart | UTC+10:00 |
Australia/LHI | UTC+10:30 |
Australia/Lindeman | UTC+10:00 |
Australia/Lord_Howe | UTC+10:30 |
Australia/Melbourne | UTC+10:00 |
Australia/NSW | UTC+10:00 |
Australia/North | UTC+09:30 |
Australia/Perth | UTC+08:00 |
Australia/Queensland | UTC+10:00 |
Australia/South | UTC+09:30 |
Australia/Sydney | UTC+10:00 |
Australia/Tasmania | UTC+10:00 |
Australia/Victoria | UTC+10:00 |
Australia/West | UTC+08:00 |
Australia/Yancowinna | UTC+09:30 |
Brazil/Acre | UTC-05:00 |
Brazil/DeNoronha | UTC-02:00 |
Brazil/East | UTC-03:00 |
Brazil/West | UTC-04:00 |
CET | UTC+02:00 |
CST6CDT | UTC-05:00 |
Canada/Atlantic | UTC-03:00 |
Canada/Central | UTC-05:00 |
Canada/Eastern | UTC-04:00 |
Canada/Mountain | UTC-06:00 |
Canada/Newfoundland | UTC-02:30 |
Canada/Pacific | UTC-07:00 |
Canada/Saskatchewan | UTC-06:00 |
Canada/Yukon | UTC-07:00 |
Chile/Continental | UTC-03:00 |
Chile/EasterIsland | UTC-05:00 |
Cuba | UTC-04:00 |
EET | UTC+03:00 |
EST | UTC-05:00 |
EST5EDT | UTC-04:00 |
Egypt | UTC+03:00 |
Eire | UTC+01:00 |
Etc/GMT | UTC+00:00 |
Etc/GMT+0 | UTC+00:00 |
Etc/GMT+1 | UTC-01:00 |
Etc/GMT+10 | UTC-10:00 |
Etc/GMT+11 | UTC-11:00 |
Etc/GMT+12 | UTC-12:00 |
Etc/GMT+2 | UTC-02:00 |
Etc/GMT+3 | UTC-03:00 |
Etc/GMT+4 | UTC-04:00 |
Etc/GMT+5 | UTC-05:00 |
Etc/GMT+6 | UTC-06:00 |
Etc/GMT+7 | UTC-07:00 |
Etc/GMT+8 | UTC-08:00 |
Etc/GMT+9 | UTC-09:00 |
Etc/GMT-0 | UTC+00:00 |
Etc/GMT-1 | UTC+01:00 |
Etc/GMT-10 | UTC+10:00 |
Etc/GMT-11 | UTC+11:00 |
Etc/GMT-12 | UTC+12:00 |
Etc/GMT-13 | UTC+13:00 |
Etc/GMT-14 | UTC+14:00 |
Etc/GMT-2 | UTC+02:00 |
Etc/GMT-3 | UTC+03:00 |
Etc/GMT-4 | UTC+04:00 |
Etc/GMT-5 | UTC+05:00 |
Etc/GMT-6 | UTC+06:00 |
Etc/GMT-7 | UTC+07:00 |
Etc/GMT-8 | UTC+08:00 |
Etc/GMT-9 | UTC+09:00 |
Etc/GMT0 | UTC+00:00 |
Etc/Greenwich | UTC+00:00 |
Etc/UCT | UTC+00:00 |
Etc/UTC | UTC+00:00 |
Etc/Universal | UTC+00:00 |
Etc/Zulu | UTC+00:00 |
Europe/Amsterdam | UTC+02:00 |
Europe/Andorra | UTC+02:00 |
Europe/Astrakhan | UTC+04:00 |
Europe/Athens | UTC+03:00 |
Europe/Belfast | UTC+01:00 |
Europe/Belgrade | UTC+02:00 |
Europe/Berlin | UTC+02:00 |
Europe/Bratislava | UTC+02:00 |
Europe/Brussels | UTC+02:00 |
Europe/Bucharest | UTC+03:00 |
Europe/Budapest | UTC+02:00 |
Europe/Busingen | UTC+02:00 |
Europe/Chisinau | UTC+03:00 |
Europe/Copenhagen | UTC+02:00 |
Europe/Dublin | UTC+01:00 |
Europe/Gibraltar | UTC+02:00 |
Europe/Guernsey | UTC+01:00 |
Europe/Helsinki | UTC+03:00 |
Europe/Isle_of_Man | UTC+01:00 |
Europe/Istanbul | UTC+03:00 |
Europe/Jersey | UTC+01:00 |
Europe/Kaliningrad | UTC+02:00 |
Europe/Kiev | UTC+03:00 |
Europe/Kirov | UTC+03:00 |
Europe/Kyiv | UTC+03:00 |
Europe/Lisbon | UTC+01:00 |
Europe/Ljubljana | UTC+02:00 |
Europe/London | UTC+01:00 |
Europe/Luxembourg | UTC+02:00 |
Europe/Madrid | UTC+02:00 |
Europe/Malta | UTC+02:00 |
Europe/Mariehamn | UTC+03:00 |
Europe/Minsk | UTC+03:00 |
Europe/Monaco | UTC+02:00 |
Europe/Moscow | UTC+03:00 |
Europe/Nicosia | UTC+03:00 |
Europe/Oslo | UTC+02:00 |
Europe/Paris | UTC+02:00 |
Europe/Podgorica | UTC+02:00 |
Europe/Prague | UTC+02:00 |
Europe/Riga | UTC+03:00 |
Europe/Rome | UTC+02:00 |
Europe/Samara | UTC+04:00 |
Europe/San_Marino | UTC+02:00 |
Europe/Sarajevo | UTC+02:00 |
Europe/Saratov | UTC+04:00 |
Europe/Simferopol | UTC+03:00 |
Europe/Skopje | UTC+02:00 |
Europe/Sofia | UTC+03:00 |
Europe/Stockholm | UTC+02:00 |
Europe/Tallinn | UTC+03:00 |
Europe/Tirane | UTC+02:00 |
Europe/Tiraspol | UTC+03:00 |
Europe/Ulyanovsk | UTC+04:00 |
Europe/Uzhgorod | UTC+03:00 |
Europe/Vaduz | UTC+02:00 |
Europe/Vatican | UTC+02:00 |
Europe/Vienna | UTC+02:00 |
Europe/Vilnius | UTC+03:00 |
Europe/Volgograd | UTC+03:00 |
Europe/Warsaw | UTC+02:00 |
Europe/Zagreb | UTC+02:00 |
Europe/Zaporozhye | UTC+03:00 |
Europe/Zurich | UTC+02:00 |
Factory | UTC+00:00 |
GB | UTC+01:00 |
GB-Eire | UTC+01:00 |
GMT | UTC+00:00 |
GMT+0 | UTC+00:00 |
GMT-0 | UTC+00:00 |
GMT0 | UTC+00:00 |
Greenwich | UTC+00:00 |
HST | UTC-10:00 |
Hongkong | UTC+08:00 |
Iceland | UTC+00:00 |
Indian/Antananarivo | UTC+03:00 |
Indian/Chagos | UTC+06:00 |
Indian/Christmas | UTC+07:00 |
Indian/Cocos | UTC+06:30 |
Indian/Comoro | UTC+03:00 |
Indian/Kerguelen | UTC+05:00 |
Indian/Mahe | UTC+04:00 |
Indian/Maldives | UTC+05:00 |
Indian/Mauritius | UTC+04:00 |
Indian/Mayotte | UTC+03:00 |
Indian/Reunion | UTC+04:00 |
Iran | UTC+03:30 |
Israel | UTC+03:00 |
Jamaica | UTC-05:00 |
Japan | UTC+09:00 |
Kwajalein | UTC+12:00 |
Libya | UTC+02:00 |
MET | UTC+02:00 |
MST | UTC-07:00 |
MST7MDT | UTC-06:00 |
Mexico/BajaNorte | UTC-07:00 |
Mexico/BajaSur | UTC-07:00 |
Mexico/General | UTC-06:00 |
NZ | UTC+13:00 |
NZ-CHAT | UTC+13:45 |
Navajo | UTC-06:00 |
PRC | UTC+08:00 |
PST8PDT | UTC-07:00 |
Pacific/Apia | UTC+13:00 |
Pacific/Auckland | UTC+13:00 |
Pacific/Bougainville | UTC+11:00 |
Pacific/Chatham | UTC+13:45 |
Pacific/Chuuk | UTC+10:00 |
Pacific/Easter | UTC-05:00 |
Pacific/Efate | UTC+11:00 |
Pacific/Enderbury | UTC+13:00 |
Pacific/Fakaofo | UTC+13:00 |
Pacific/Fiji | UTC+12:00 |
Pacific/Funafuti | UTC+12:00 |
Pacific/Galapagos | UTC-06:00 |
Pacific/Gambier | UTC-09:00 |
Pacific/Guadalcanal | UTC+11:00 |
Pacific/Guam | UTC+10:00 |
Pacific/Honolulu | UTC-10:00 |
Pacific/Johnston | UTC-10:00 |
Pacific/Kanton | UTC+13:00 |
Pacific/Kiritimati | UTC+14:00 |
Pacific/Kosrae | UTC+11:00 |
Pacific/Kwajalein | UTC+12:00 |
Pacific/Majuro | UTC+12:00 |
Pacific/Marquesas | UTC-09:30 |
Pacific/Midway | UTC-11:00 |
Pacific/Nauru | UTC+12:00 |
Pacific/Niue | UTC-11:00 |
Pacific/Norfolk | UTC+11:00 |
Pacific/Noumea | UTC+11:00 |
Pacific/Pago_Pago | UTC-11:00 |
Pacific/Palau | UTC+09:00 |
Pacific/Pitcairn | UTC-08:00 |
Pacific/Pohnpei | UTC+11:00 |
Pacific/Ponape | UTC+11:00 |
Pacific/Port_Moresby | UTC+10:00 |
Pacific/Rarotonga | UTC-10:00 |
Pacific/Saipan | UTC+10:00 |
Pacific/Samoa | UTC-11:00 |
Pacific/Tahiti | UTC-10:00 |
Pacific/Tarawa | UTC+12:00 |
Pacific/Tongatapu | UTC+13:00 |
Pacific/Truk | UTC+10:00 |
Pacific/Wake | UTC+12:00 |
Pacific/Wallis | UTC+12:00 |
Pacific/Yap | UTC+10:00 |
Poland | UTC+02:00 |
Portugal | UTC+01:00 |
ROC | UTC+08:00 |
ROK | UTC+09:00 |
Singapore | UTC+08:00 |
Turkey | UTC+03:00 |
UCT | UTC+00:00 |
US/Alaska | UTC-08:00 |
US/Aleutian | UTC-09:00 |
US/Arizona | UTC-07:00 |
US/Central | UTC-05:00 |
US/East-Indiana | UTC-04:00 |
US/Eastern | UTC-04:00 |
US/Hawaii | UTC-10:00 |
US/Indiana-Starke | UTC-05:00 |
US/Michigan | UTC-04:00 |
US/Mountain | UTC-06:00 |
US/Pacific | UTC-07:00 |
US/Samoa | UTC-11:00 |
UTC | UTC+00:00 |
Universal | UTC+00:00 |
W-SU | UTC+03:00 |
WET | UTC+01:00 |
Zulu | UTC+00:00 |
localtime | UTC+00:00 |
Code Used for Generating the Table¶
Run this code in a Python environment to generate the table above.
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo, available_timezones
# Prepare a list to store time zone information
timezones = []
for tz_name in sorted(available_timezones()):
tz = ZoneInfo(tz_name)
now = datetime.now(tz)
offset = tz.utcoffset(now)
if offset is None:
offset_str = 'Unknown'
else:
total_seconds = offset.total_seconds()
sign = '+' if total_seconds >= 0 else '-'
total_seconds = abs(total_seconds)
hours, remainder = divmod(total_seconds, 3600)
minutes, _ = divmod(remainder, 60)
offset_str = f"UTC{sign}{int(hours):02d}:{int(minutes):02d}"
timezones.append((tz_name, offset_str))
# Generate Markdown table
print("| Timezone | UTC Offset |")
print("| --- | --- |")
for tz_name, offset_str in timezones:
print(f"| {tz_name} | {offset_str} |")
Examples
Library Configuration Examples¶
Pyproject.toml is the preferred method, but there is an example for the bumpcalver.toml configuration included also.
PyProject.TOML¶
Add to your pyproject.toml
[project]
name = "example PyProject.toml"
version = "2025.2.2"
requires-python = ">=3.10"
description = "A powerful CLI tool for effortless calendar-based version management"
keywords = [ "cli", "tool", "calendar", "version", "management", "configuration", "example",]
readme = "README.md"
[project.license]
file = "LICENSE"
[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"
BumpCalver.TOML Configuration¶
File needs to be in the root and named bumpcalver.toml
version_format = "{current_date}-{build_count:03}"
date_format = "%y.%m.%d"
timezone = "America/New_York"
git_tag = true
auto_commit = true
[[file]]
path = "pyproject.toml"
file_type = "toml"
variable = "project.version"
version_standard = "python"
[[file]]
path = "examples/makefile"
file_type = "makefile"
variable = "APP_VERSION"
version_standard = "default"
[[file]]
path = "examples/dockerfile"
file_type = "dockerfile"
variable = "arg.VERSION"
version_standard = "default"
[[file]]
path = "examples/dockerfile"
file_type = "dockerfile"
variable = "env.APP_VERSION"
version_standard = "default"
[[file]]
path = "examples/p.py"
file_type = "python"
variable = "__version__"
version_standard = "python"
Example file layouts¶
Below are examples of various file types and how they could be setup using BumpCalver. As the intent of the library is to allow flexible use across different languages and use cases.
MakeFile¶
# Variables
REPONAME = bumpcalver
APP_VERSION = 2025.02.02
PYTHON = python3
PIP = $(PYTHON) -m pip
PYTEST = $(PYTHON) -m pytest
EXAMPLE_PATH = examples
SERVICE_PATH = src
TESTS_PATH = tests
SQLITE_PATH = _sqlite_db
LOG_PATH = log
PORT = 5000
WORKER = 8
LOG_LEVEL = debug
REQUIREMENTS_PATH = requirements.txt
# DEV_REQUIREMENTS_PATH = requirements/dev.txt
.PHONY: autoflake black cleanup create-docs flake8 help install isort run-example run-example-dev speedtest test
autoflake: ## Remove unused imports and unused variables from Python code
autoflake --in-place --remove-all-unused-imports --ignore-init-module-imports --remove-unused-variables -r $(SERVICE_PATH)
autoflake --in-place --remove-all-unused-imports --ignore-init-module-imports --remove-unused-variables -r $(TESTS_PATH)
autoflake --in-place --remove-all-unused-imports --ignore-init-module-imports --remove-unused-variables -r $(EXAMPLE_PATH)
YAML¶
application:
description: This is an example application configuration file.
name: ExampleApp
configuration:
version: 2025.02.02
database:
host: localhost
password: password
port: 5432
username: user
features:
feature_a: true
feature_b: false
feature_c: true
XML¶
<configuration>
<version>2025.02.02</version>
<application>
<name>ExampleApp</name>
<description>This is an example application configuration file.</description>
</application>
<database>
<host>localhost</host>
<port>5432</port>
<username>user</username>
<password>password</password>
</database>
<features>
<feature_a>true</feature_a>
<feature_b>false</feature_b>
<feature_c>true</feature_c>
</features>
</configuration>
TOML¶
[configuration]
version = "2025.02.02"
[configuration.application]
name = "ExampleApp"
description = "This is an example application configuration file."
[configuration.database]
host = "localhost"
port = 5432
username = "user"
password = "password"
[configuration.features]
feature_a = true
feature_b = false
feature_c = true
JSON¶
{
"version": "2025.02.02",
"application": {
"name": "ExampleApp",
"description": "This is an example application configuration file."
},
"database": {
"host": "localhost",
"port": 5432,
"username": "user",
"password": "password"
},
"features": {
"feature_a": true,
"feature_b": false,
"feature_c": true
}
}
Dockerfile¶
# Use an official Python runtime as a parent image
FROM python:3.14-slim
# Set the working directory in the container
WORKDIR /app
# Copy the current directory contents into the container at /app
COPY . /app
# Install any needed packages specified in requirements.txt
RUN pip install --no-cache-dir -r requirements.txt
# Make port 80 available to the world outside this container
EXPOSE 80
# Define environment variable
ENV APP_VERSION=2025.02.02
ARG VERSION=2025.02.02
# Run app.py when the container launches
CMD ["python", "app.py"]
About
About¶
BumpCalver Library is a library to help manage "calendar version" (CalVer) strings. You can update the version string in TOML, YAML, XML, JSON, Makefile, Dockerfile, and Python files. It follows PEP440 for Python packages, but is not intended to only be for Python pacakges. It supports git tags like beta, release, release-candidate, and custom tags of your own choosing. It has support for Timezones and build counts. It is a simple library that can be used in any project that needs to manage versioning.
The library is written in Python and is available on PyPi. It is open source and available on GitHub. Feel free to use it in your projects and contribute to the library.
About Me¶
I am a software engineering manager with an eclectic background in various industries (finance, manufacturing, and metrology). I am passionate about software development and love to learn new things.
Contributing¶
Please feel to contribute to this project. Adding common functions is the intent and if you have one to add or improve an existing it is greatly appreciated.
Ways to Contribute!¶
- Add or improve a function
- Add or improve documentation
- Add or improve Tests
- Report or fix a bug
Changelog¶
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog
Latest Changes¶
Improved documentation and update of dependencies (v2025.4.12.1)¶
What's Changed¶
- Improving Documentation (#47) @devsetgo
- pip(deps): bump pytest from 8.3.4 to 8.3.5 (#42) @dependabot[bot]
- pip(deps): bump mkdocs-print-site-plugin from 2.6.0 to 2.7.2 (#44) @dependabot[bot]
- pip(deps): bump pylint from 3.3.4 to 3.3.6 (#43) @dependabot[bot]
- pip(deps): bump mkdocs-material from 9.6.6 to 9.6.11 (#45) @dependabot[bot]
- pip(deps): bump genbadge[all] from 1.1.1 to 1.1.2 (#46) @dependabot[bot]
- pip(deps): bump mkdocstrings[python,shell] from 0.27.0 to 0.28.2 (#37) @dependabot[bot]
- pip(deps): bump twine from 6.0.1 to 6.1.0 (#38) @dependabot[bot]
- pip(deps): bump pylint from 3.3.3 to 3.3.4 (#39) @dependabot[bot]
- pip(deps): bump mkdocs-material from 9.5.49 to 9.6.6 (#40) @dependabot[bot]
- pip(deps): bump ruff from 0.9.4 to 0.9.9 (#41) @dependabot[bot]
- run of tests (#36) @devsetgo
- pip(deps): bump black from 24.10.0 to 25.1.0 (#31) @dependabot[bot]
- pip(deps): bump ruff from 0.8.4 to 0.9.4 (#32) @dependabot[bot]
- pip(deps): bump tox from 4.23.2 to 4.24.1 (#33) @dependabot[bot]
- pip(deps): bump pre-commit from 4.0.1 to 4.1.0 (#34) @dependabot[bot]
- pip(deps): bump autopep8 from 2.3.1 to 2.3.2 (#35) @dependabot[bot]
- pip(deps): bump ruff from 0.8.2 to 0.8.4 (#26) @dependabot[bot]
- pip(deps): bump hatchling from 1.26.3 to 1.27.0 (#27) @dependabot[bot]
- pip(deps): bump mkdocs-material from 9.5.47 to 9.5.49 (#28) @dependabot[bot]
- pip(deps): bump pylint from 3.3.2 to 3.3.3 (#29) @dependabot[bot]
- pip(deps): bump click from 8.1.7 to 8.1.8 (#30) @dependabot[bot]
Published Date: 2025 April 12, 16:34
Fix of Python Version (2024.12.14.1)¶
What's Changed¶
- bump version (#25) @devsetgo
- working on trusted publishing (#24) @devsetgo
- Bump of Version 24.12.06-001 (#23) @devsetgo
- Enhancing Date Formatting Capability (#22) @devsetgo
- Adding BumpCalver.toml option (#16) @devsetgo
- pip(deps): bump ruff from 0.7.1 to 0.7.2 (#15) @dependabot
- pip(deps): bump mkdocs-material from 9.5.40 to 9.5.43 (#11) @dependabot
- pip(deps): bump ruff from 0.6.9 to 0.7.1 (#12) @dependabot
- pip(deps): bump tox from 4.21.2 to 4.23.2 (#13) @dependabot
- pip(deps): bump pytest-cov from 5.0.0 to 6.0.0 (#14) @dependabot
Published Date: 2024 December 14, 20:10
Enhancing Date Formatting Capabilities (24.12.06-001-x)¶
What's Changed¶
- working on trusted publishing (#24) @devsetgo
Published Date: 2024 December 14, 20:03
Enhancing Date Formatting Capabilites (24.12.06-001)¶
What's Changed¶
- Changing version to xx.xx.xx-build.
- Bump of Version 24.12.06-001 (#23) @devsetgo
- Enhancing Date Formatting Capability (#22) @devsetgo
Published Date: 2024 December 06, 23:11
BumpCalver.toml Option (2024-11-08)¶
What's Changed¶
- Adding BumpCalver.toml option (#16) @devsetgo
- pip(deps): bump ruff from 0.7.1 to 0.7.2 (#15) @dependabot
- pip(deps): bump mkdocs-material from 9.5.40 to 9.5.43 (#11) @dependabot
- pip(deps): bump ruff from 0.6.9 to 0.7.1 (#12) @dependabot
- pip(deps): bump tox from 4.21.2 to 4.23.2 (#13) @dependabot
- pip(deps): bump pytest-cov from 5.0.0 to 6.0.0 (#14) @dependabot
Published Date: 2024 November 08, 21:41
Fix of OS classifiers (2024.10.20.4)¶
What's Changed¶
- Fixing Classifier Gaps (#10) @devsetgo
Published Date: 2024 October 20, 16:14
Fix of classifiers (2024.10.20.3)¶
What's Changed¶
- Updating classifiers (#9) @devsetgo
Published Date: 2024 October 20, 16:00
Adding Python 3.9 Support (2024.10.20)¶
What's Changed¶
- Fix to support Python 3.9 and higher (#8) @devsetgo
- Release Ready (#7) @devsetgo
Published Date: 2024 October 20, 15:35
Initial Release (2024.10.18)¶
What's Changed¶
- Initial Work by @devsetgo in https://github.com/devsetgo/bumpcalver/pull/1
- Pre-Release Work by @devsetgo in https://github.com/devsetgo/bumpcalver/pull/4
Full Changelog: https://github.com/devsetgo/bumpcalver/commits/2024.10.18
Published Date: 2024 October 18, 18:42