Skip to main content

Contributors Forks Stargazers Issues MIT License LinkedIn


Logo

dodgem

Version bumper for Python project files.
Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Roadmap
  5. Contributing
  6. License
  7. Contact
  8. Acknowledgments

About The Project

dodgem usage

Sometimes you need to bump the version in your Python project files automatically. For example, you might:

  • Have a CI/CD pipeline, and want to automatically bump the patch version of your library on merge to your develop branch
  • Have a workflow (e.g. on Bitbucket Pipelines, GitHub actions etc.) that allows developers to automatically perform version bumps by including tags in their commit message (e.g. [major], [minor])
  • Just want to reduce the chances of human error when bumping version numbers manually

Dodgem is a command-line utility for doing all of the above, and a bit more, aiming to eventually cover as many Python project file formats as possible, but currently supporting:

  • setuptools (setup.py) with the version= named argument
  • pyproject.toml managed by the Poetry dependency manager

Named after (version) bumper cars which are also sometimes called dodgems in some dialects of English.

(back to top)

Built With

This project uses:

  • Click for its CLI
  • Poetry for dependency management
  • Blessings for colorized and formatted CLI output

(back to top)

Getting Started

Getting started is straightforward. Dodgem aims to automatically detect as much as possible.

Prerequisites

You'll need Python 3.7 or newer with pip to install Dodgem.

Installation

Install Dodgem using pip or your favourite Python dependency manager and you're done.

pip3 install dodgem

Test your installation with:

dodgem --help

You should see help documentation printed.

(back to top)

Usage

You can use dodgem --help for detailed information on using the utility:

Usage: dodgem [OPTIONS]

  Bump version numbers in a project file.

Options:
  --file TEXT              The file to parse (defaults to automatic
                           detection).
  --file-type TEXT         The file type to parse (defaults to automatic).
  --file-format TEXT       The file format to parse (defaults to automatic).
  --commit-message TEXT    The commit message to infer the version bump from.
  --no-auto-patch          If given, disables automatic patch version bump if
                           commit message provided.
  --major-tag TEXT         The commit message tag indicating a major version
                           bump.
  --minor-tag TEXT         The commit message tag indicating a minor version
                           bump.
  --patch-tag TEXT         The commit message tag indicating a patch version
                           bump.
  --prerelease-tag TEXT    The commit message tag indicating a prerelease
                           version bump.
  --ignore-tag-case        Ignores capitalization in commit message tags.
  --quiet                  Suppresses all extraneous output.
  --pep-440                Use PEP-440 for version strings.
  --bump-major             If given, performs a major version bump.
  --bump-minor             If given, performs a minor version bump.
  --bump-patch             If given, performs a patch version bump.
  --bump-prerelease        If given, performs a prerelease version bump.
  --bump-build             If given, performs a build version bump.
  --prerelease-token TEXT  The prerelease token to append.
  --build-token TEXT       The build token to append.
  --dry                    If given, does not write the version change to
                           disk.
  --help                   Show this message and exit.

Example: Bump Minor Version

Bump the minor version of your project like this:

dodgem --bump-minor

If you don't want to commit the change to disk, use --dry like so:

dodgem --bump-minor --dry

If the informational output given by the CLI is getting in the way of downstream processing, use --quiet:

dodgem --bump-minor --quiet

Example: From Commit Message

Dodgem can bump your project version based on a commit message. By default.

  • If the message contains [major] then a major version bump will be performed
  • If the message contains [minor] then a minor version bump will be performed
  • Otherwise, a patch version bump will be performed

For example, to use your last git commit message to bump your projects version.

dodgem --commit-message="$(git log -1)"

Example: Custom Tags

If the default [major] and [minor] tags don't suit you, and you'd perfer (major), (minor) and an explicit (patch) tag:

dodgem --commit-message="$(git log -1)" --major-tag='(major)' --minor-tag='(minor)' --patch-tag='(patch)' --no-auto-patch

(back to top)

Roadmap

  • Support setuptools (setup.py)
  • Support Poetry
  • Support prerelease/build versions (shoutout to @mitchelkoster for the feature idea)

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Any contributions are very welcome. Please fork the project and open a PR, or open an issue if you've found a bug and/or would like to suggest a feature.

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Saul Johnson - @lambdacasserole - saul.a.johnson@gmail.com

Project Link: https://github.com/lambdacasserole/dodgem

(back to top)

Acknowledgments

The following resources are awesome:

  • Best-README-Template was used for this readme
  • tomlkit was used for parsing TOML in a way that preserves comments, order, formatting etc.
  • semver was used for parsing and bumping semver numbers

Shoutout to @mitchelkoster for contributing a load of feature ideas, and rooting out a bunch of bugs and edge cases!

(back to top)

Metadata

Release files for dodgem 1.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dodgem 1.3.2
File Size Uploaded Provenance Actions
dodgem-1.3.2.tar.gz 8.7 kB Without provenance Details for dodgem-1.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dodgem 1.3.2
File Interpreter ABI Platform Actions
dodgem-1.3.2-py3-none-any.whl Python 3 none any Details for dodgem-1.3.2-py3-none-any.whl

Total release size: 18.4 kB

Release files / dodgem-1.3.2.tar.gz

Download URL dodgem-1.3.2.tar.gz
Size 8.7 kB
Tags Source
SHA-256 checksum
How to use checksums
1736076b1aaaaf4c21b4715a06650fead1a08d1ea5f11850d96861f95a560d04
BLAKE2b-256 checksum
How to use checksums
8fe67f6059973e3ccea3c56b086d11e482475b017af94f02227922ddc9dda7ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.1.1 CPython/3.12.10 Darwin/24.6.0

Release files / dodgem-1.3.2-py3-none-any.whl

Download URL dodgem-1.3.2-py3-none-any.whl
Size 9.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
20a86432a69f516283c08aa5fabe7c0c47cb9d96914ccdcf5c2a018882128a1d
BLAKE2b-256 checksum
How to use checksums
bdb88592671db3f448baf7b66162f844a9f4487830860868c9fca709b8a5133a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.1.1 CPython/3.12.10 Darwin/24.6.0

Security for dodgem 1.3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page