Skip to main content

Automatically check for semver compliance based on type hints

Project description

Judgement as a Service.

Typejudge will automatically check for semver compliance based on type hints. If the type signature for a function changes, it will judge this to be an API change and recommend a major version bump.

This is largely inspired by Elm’s package manager, which also enforces semver.


Note: typejudge only works on python 3.5 and higher.

Install with pip:

$ pip install typejudge


$ typejudge --help
usage: typejudge [-h] [-o OUT] [-f FILE] MODULE [VERSION]

judge your types

positional arguments:
  MODULE                module to import and check
  VERSION               current version of the package

optional arguments:
  -h, --help            show this help message and exit
  -o OUT, --out OUT     save current type definitions to this file
  -f FILE, --file FILE  load type definitions from this file

Example usage

Suppose we’ve got a module that contains some type annotations on the publicly exported API,

def greeting(name: str) -> str:
    return 'Hello ' + name

Save the types somewhere:

$ typejudge -o testmodule.json testmodule

Make some small change to, add a new function:

def greeting2(name: str, name2: str) -> str:
    return 'Hello ' + name + ' and ' name2

Typejudge will recommend this is a minor release:

$ typejudge -f testmodule.json testmodule

The same, but with a known current version number:

$ typejudge -f testmodule.json testmodule 0.3.2

Make a change to existing type signatures:

from typing import List

def greeting(names: List[str]) -> str:
    return 'Hello ' + ' '.join(names)

Typejudge will now recommend this is a major release:

$ typejudge -f testmodule.json testmodule

With no changes to the API’s types, typejudge will recommend a patch release.

Example usage with bumpversion

Typejudge works quite well with bumpversion. Doing this is probably inadvisable, but you can entirely automate releases.

Assuming similar files as in the previous section, set up a config file for bumpversion, something like:

$ cat .bumpversion.cfg
current_version = 2.0.3
commit = True
tag = True


And a

$ cat
import setuptools

    description="Test stuff",

Then run something along these lines to cut a new release:

$ bumpversion $(typejudge -f testmodule.json testmodule)

You’ll also want to save the state of the API at this point, so you can compare it at the next release:

$ typejudge -o testmodule.json testmodule

Obviously use some discretion when releasing in this way. Just because the types of your API remain the same, it doesn’t necessarily mean that your code is backwards compatible. Typejudge suggests the smallest version increment you should make.

Project details

Download files

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

Source Distribution

typejudge-0.3.0.tar.gz (3.8 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page