Skip to main content

Utilities for managing version, changelogs, and project releases.

Project description


PyPI version

John Keats

Keats is an Python build, installation, and workflow manager. Keats removes the need to update an embedded version string for your packages by automatically creating and maintaining a file and a corresponding changelog.json file. Updates to pyproject.toml are automatically handled. Version updates are easy as calling keats version. Keats also includes an interactive release script, which can be called using keats release, which will release your package to your favorite repository such as PyPI.


Every Python developer seems to have their own tricks and scripts for maintaining changelogs, package versions, and managing releases. Rather than reinventing the wheel everytime you develop a new pacakge, Keats provides a standard workflow for doing python package releases. No customization or Makefiles are required.


To install Keats to your project, run:

poetry run add --dev keats

Verify your installation by running

poetry run keats keats

To list documentation, run keats with no arguments

poetry run keats

To begin version managment by creating a in your main package, run

poetry run keats version up

From within your python project, you can access your version number and other package information using something like (usually in the of your main package).

from import __version__, __title__, __authors__ # and so on

To bump to the next version and update your change log (for more on change logs, see below)

poetry run keats bump

To bump to a specific version:

poetry run keats bump <optional version>

To bump without updating the change log:

poetry run keats version bump


Changelogs are important understanding project status and developer intentions. Keats encourages an up-to-date changelog by providing an standard interface for maintaining and updating change logs using the following files:

  • .keats/changelog.json - JSON formatted list of changes, with version number, dates, and optional change list.
  • .keats/ - markdown formatted changelog

The recommended way to use this is to run keats bump which will bump your package version and update your change log:

poetry run keats bump <optional version>

This will provide an interactive script to update your changelog with a description and a list of changes. Entries are appended to the .keats/changelog.json and saved. The file is then converted to a markdown file for readability or documentation purposes.

To just update your change log:

poetry run keats changelog add

If you want to just update the .keats/ from the json file, run:

poetry run keats changelog up

To clear your change logs:

poetry run keats changelog clear

Global installation

To install Keats globally, run:

pip install keats

You can then run all of the commands without the poetry run prefix, given that your current directory is a Python project with a pyproject.toml file.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for keats, version 0.2.28
Filename, size File type Python version Upload date Hashes
Filename, size keats-0.2.28-py3-none-any.whl (11.2 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size keats-0.2.28.tar.gz (10.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page