Python library for manipulating Cloud Native Application Bundles.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Gareth Rushgrove 9d8b707b8d
bump version
4 years ago
.github add tests in a GitHub Action 4 years ago
cnab destination is now required 4 years ago
examples/testing ignore examples from type checks 4 years ago
fixtures destination is now required 4 years ago
.dockerignore add tests in a GitHub Action 4 years ago
.gitignore ignore examples from type checks 4 years ago
Dockerfile exclude docker tests from github action 4 years ago
LICENSE added a README and LICENCE file 4 years ago added support for invocation image 4 years ago
poetry.lock move to using canonicaljson for bundle output 4 years ago
pyproject.toml bump version 4 years ago
pytest.ini ignore examples from type checks 4 years ago

Python CNAB Library

Work-in-progress library for working with CNAB in Python.

There are probably three main areas of interest for a CNAB client:

  1. Handling the bundle.json format (101)
  2. Building invocation images (102)
  3. Running actions against a CNAB (103)

Claims and Signing are optional but will be worked on once the above are stable.


The module is published on PyPi and can be installed from there.

pip install cnab

Parsing bundle.json

Nothing too fancy here, the Bundle class has a from_dict static method which builds a full Bundle object.

import json
from cnab import Bundle

with open("bundle.json") as f:
    data = json.load(f)

bundle = Bundle.from_dict(data)

This could for example be used for validation purposes, or for building user interfaces for bundle.json files.

Describing bundle.json in Python

You can also describe the bundle.json file in Python. This will correctly validate the structure based on the current specification and would allow for building a custom DSL or other user interface for generating bundle.json files.

from cnab import Bundle, InvocationImage

bundle = Bundle(


Running CNABs

The module supports running actions on a CNAB, using the docker driver.

from cnab import CNAB

# The first argument can be a path to a bundle.json file, a dictionary
# or a full `Bundle` object
app = CNAB("fixtures/helloworld/bundle.json")

# list available actions

# list available parameters

# run the install action

# run the install action specifying a parameters
print("install", parameters={"port": 9090}))

# Many applications will require credentials
app = CNAB("fixtures/hellohelm/bundle.json")

# list required credentials

# Here we pass the value for the required credential
# in this case by reading the existing configuration from disk
with open("/home/garethr/.kube/config") as f:
    print("status", credentials={"kubeconfig":}))

Note that error handling for this is very work-in-progress.

Working with invocation images

pycnab also has a class for working with invocation images.

from cnab import CNABDirectory

directory = CNABDirectory("fixtures/invocationimage")

# Check whether the directory is valid
# Raises `InvalidCNABDirectory` exception if invalid

# Returns the text of the associated README file if present

# Returns the text of the associated LICENSE file if present


Thanks to QuickType for bootstrapping the creation of the Python code for manipulating bundle.json based on the current JSON Schema.