API

This documentation lists the full API reference of all public classes and functions.

CDK

class cally.cdk.CallyResource(tf_identifier=None, **kwargs)

This resource is for referencing the underlying CDK for Terraform resource, so that it can be later instantiated. This allows us to maniuplate variables on __init__, along with setting defaults. Top level resources must be wrapped in this class, and attributes with a class specification may be wrapped with this for the purposes of setting defaults. Otherwise as long as the object structure is valid for the resource, the CDK will do the RightThings :TM:, however they will not be type checked and an output may succeed, but fail to validate/plan/apply.

Parameters:

tf_identifier (str | None) – This is required for the top level resource class, and invalid for resource attributes. It is recommended to specify this as the first argument rather than as a keyword. This is expected to be a string, for consistency it should follow the Identifier requirements set out by Terraform, but the CDKTF will attempt to normalise it.

defaults: dict | MappingProxyType

A dictionary of the default values to set on instantion, if not passed through as kwargs. Wrapping in a MappingProxyType avoids the mutable warnings. For example MappingProxyType({'prefix': 'foo'})

provider: str

Provider name, this is so cally knows where to load the underlying cdktf resource from. For example random.

resource: str

Resource name, that cally will load the matching class name from, for example RandomPet, lives in random_pet.

class cally.cdk.CallyStack(service)

This forms the parent of your custom stacks. It has a number of convenience methods, and it is intended that you override __init__, call super, and construct your own stack from there.

Parameters:

service (CallyStackService)

add_output(tf_identifier, output)

Adds a terraform output to the resulting generated terraform.

Parameters:

  • tf_identifier (str)

  • output (str)

Return type:

None

add_resource(resource)

Adds a CallyResource to the stack, all resources must be added to the stack from them to be including in the resutling output

Parameters:

resource (CallyResource)

Return type:

None

add_resources(resources)

Adds a list of CallyResources to the stack

Parameters:

resources (List[CallyResource])

Return type:

None

Config

class cally.cli.config.config_types.CallyStackService(name, environment, stack_type, backend=<factory>, providers=<factory>, stack_vars=<factory>)

This dataclass is automatically passed to the CallyStack class during instantiation. Allowing access to any service property, though it is recommended to use the documented functions.

Parameters:

  • name (str)

  • environment (str)

  • stack_type (str)

  • backend (CallyBackend)

  • providers (dict)

  • stack_vars (dict)

get_stack_var(var, default=None)

Any stack var, configured on the service is available via this method, with the ability to provide a default.

Parameters:

  • var (str)

  • default (Any | None)

Return type:

Any

cally.cli.config.service.CallyServiceCommand()

This can be applied to the ‘cls’ kwarg of a click.command decorator. It will make all service options available to the decorated command. Best combined with the pass object decorator for convenient access to the CallyServiceConfig object.

Example usage:

@click.command(name='print', cls=CallyServiceCommand())
@click.pass_obj
def example(service: CallyServiceConfig):
    click.echo(service.config.name)

Testing

class cally.testing.CallyTestHarness(methodName='runTest')

Cally provides a Test Harness as good base for building robust unit testing for your IDP and IAC. It takes care of ensuring a clean environment, and discrete working directory for each unittest, along with providing some useful methods for getting testdata or default service objects.

static get_cally_config(service='test', environment='cally')

Returns a CallyServiceConfig object, with a service and environment pre-configured as ‘test’ and ‘cally’

Return type:

CallyServiceConfig

static get_cally_stack_config(service='test', environment='cally', stack_type='CallyStack')

Returns a CallyStackServiceConfig object, with a service and environment pre-configured as service=’test’, environment=’cally’, stack_type=’CallyStack’

Return type:

CallyStackServiceConfig

get_test_file(filename)

Loads a the specified file path as a Path object, from the testdata directory

Return type:

Path

load_json_file(filename)

Loads a json testdata file and returns it as a dictionary

Return type:

dict

load_test_file(filename)

Loads a testdata file and reads it in as text

Return type:

str

setUp()

Hook method for setting up the test fixture before exercising it.

tearDown()

Hook method for deconstructing the test fixture after testing it.

property testdata: Path

Attempts to find a directory called ‘testdata’ within your tests directory

class cally.testing.CallyTfTestHarness(methodName='runTest')

This is an extension of the Cally Test harness, specifically for testing Stacks.

synth_stack(stack)

When passed a CallyStack object, synths it and returns the dictionary payload generated by the cdktf. Can be used to unit test your stacks.

Parameters:

stack (CallyStack)

Return type:

dict