Welcome to Thipster’s documentation!¶

THipster¶

THipster is a tool dedicated to simplifying the difficulty associated with writing Terraform files. It allows users to write infrastructure as code in a simplified format, using either YAML (with JINJA) or the dedicated Thipster DSL.

Written entirely in Python, it leverages the Python CDK for Terraform to create Terraform files and apply them to the chosen provider.

Technology Stack¶

Written in Python 3.11, thipster is designed as a python package, to be used either as a standalone tool, or as a module inside a running process like a CI/CD pipeline.

Project Status¶

THipster is currently in an active development state. If you want to know more, please check the CHANGELOG for more details.

Dependencies¶

In order to user THipster, you will need to have the following installed:

Python (3.11+)
pipenv v2021.5+
Terraform CLI (1.2+)
Node.js and npm v16+.

Installation¶

To use THipster, you can simply install the package with pip:

pip install thipster

If you want to install the google dependencies aswell use

pip install thipster[google]

The list of available versions can be found on PyPI.

Usage¶

You can use THipster in two ways:

By leveraging the THipster CLI
By directly using the THipster Python package in your own code

Main feature:

Generate Terraform files from a YAML+JINJA or THIPS file:

from thipster import Engine as ThipsterEngine
from thipster.auth import Google
from thipster.parser import ParserFactory
from thipster.repository import GithubRepo
from thipster.terraform import Terraform

# create new THipster engine
engine = ThipsterEngine(ParserFactory(), GithubRepo('THipster/models'), Google, Terraform())

# generate Terraform files and plan from a YAML+JINJA file
terraform_plan = engine.run('path/to/file/or/directory')
print(terraform_plan)

How to test the software¶

To run the tests, you can use the following command:

pip install -e .[test]
pytest tests

Known issues¶

All known issues, bugs, and feature requests are tracked in the Issue tracker.

Getting help¶

If you have questions, concerns, bug reports, etc, please file an issue in this repository’s Issue tracker.

Getting involved¶

To install the project for development, you can use the following command:

pip install -r requirements.txt && pip install -e .[dev,test,doc,google]
pre-commit install && pre-commit run --all-files

For more information on how to help out, please check the CONTRIBUTING file.

Open source licensing info¶

Credits and references¶

Projects that inspired you
- AWS Application Composer
Related projects
- Wing Programming Language

thipster¶

thipster package¶

Subpackages¶

thipster.auth package¶

Submodules¶

thipster.auth.google module¶

Module contents¶

thipster.engine package¶

Submodules¶

thipster.engine.engine module¶

Engine.py module.

class thipster.engine.engine.Engine(parser: ParserPort = None, repository: RepositoryPort = None, auth: AuthPort = None, terraform: TerraformPort = None)¶

Bases: object

THipster’s Engine.

The core of the application, it is used to call and link all interfaces together.

__init__(parser: ParserPort = None, repository: RepositoryPort = None, auth: AuthPort = None, terraform: TerraformPort = None)¶

THipster’s Engine.

The core of the application, it is used to call and link all interfaces together.

Parameters:

parser (ParserPort) – Instance of a Parser class
repository (RepositoryPort) – Instance of a Respository class
auth (AuthPort) – Instance of an Auth class
terraform (TerraformPort) – Instance of a Terraform class

apply_terraform(working_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/thipster/checkouts/latest/docs/source'), plan_file_path: str = 'thipster.tfplan') → tuple[int, str]¶

Apply Terraform.

Parameters:

working_dir (Path, optional) – The path of the working directory, by default Path.cwd()
plan_file_path (str, optional) – The path of the plan file, by default thipster.tfplan

Returns:

The terraform apply exit code and output

Return type:

tuple[int, str]

property auth¶: Get the authentification module.

generate_tf_files(file: ParsedFile, models: dict[str, ResourceModel]) → None¶

Generate Terraform files.

Parameters:

file (pf.ParsedFile) – The ParsedFile object containing the resources defined in the input file
models (dict[str, ResourceModel]) – The dictionary of models

get_models(file: ParsedFile) → dict[str, ResourceModel]¶

Get the models from the repository.

Parameters:: file (pf.ParsedFile) – The ParsedFile object containing the resources defined in the input file
Returns:: The dictionary of models
Return type:: dict[str, ResourceModel]

init_terraform(working_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/thipster/checkouts/latest/docs/source'), upgrade: bool = False) → tuple[int, str]¶

Initialize Terraform.

Parameters:

working_dir (Path, optional) – The path of the working directory, by default Path.cwd()
upgrade (bool, optional) – Whether to upgrade the Terraform providers, by default False

Returns:

The terraform init exit code and output

Return type:

tuple[int, str]

parse_files(path: str) → ParsedFile¶

Parse the input file or directory.

Parameters:: path (str) – The path of the files to be processed
Returns:: The ParsedFile object containing the resources defined in the input file
Return type:: pf.ParsedFile

property parser¶: Get the parser.

plan_terraform(working_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/thipster/checkouts/latest/docs/source'), plan_file_path: str = 'thipster.tfplan') → tuple[int, str]¶

Plan Terraform.

Parameters:

working_dir (Path, optional) – The path of the working directory, by default Path.cwd()
plan_file_path (str, optional) – The path of the plan file, by default thipster.tfplan

Returns:

The terraform plan exit code and output

Return type:

tuple[int, str]

property repository¶: Get the repository.

run(path: str) → str¶

Return json Terraform files from the input file name.

Calls the different run methods of the parser, repository, auth and terraform modules. Transforms the inputed filename into a Cloud architecture plan.

Parameters:: path (str) – The path of the files to be processed
Returns:: A string with the results of the Terraform plan
Return type:: str

property terraform¶: Get the Terraform module.

thipster.engine.exceptions module¶

Exceptions for the THipster engine.

exception thipster.engine.exceptions.BadPortError(got: type, expected: type, *args: object)¶

Bases: THipsterError

Exception raised when trying to set a port with an invalid class.

__init__(got: type, expected: type, *args: object) → None¶

Exception raised when trying to set a port with an invalid class.

Parameters:: var (str) – The variable name.

property message¶: Get the message of the exception.

exception thipster.engine.exceptions.THipsterError¶

Bases: Exception, ABC

Base class for all exceptions raised by THipster.

__str__() → str¶: Get the string representation of the exception.

abstract property message¶: Get the message of the exception.

thipster.engine.i_auth module¶

Authentification module interface.

class thipster.engine.i_auth.AuthPort¶

Bases: ABC

Authentification port.

abstract authenticate()¶

Abstract method used for authentication.

Raises:: NotImplementedError – If method is not implemented in inheriting classes

thipster.engine.i_parser module¶

Parser module interface.

class thipster.engine.i_parser.ParserPort¶

Bases: ABC

Parser port.

abstract classmethod run(path: str) → ParsedFile¶

Abstract run method.

Parameters:: path (str) – The path of the filesor directory to be processed
Returns:: Object containing a representation of an input file broken down into individual resources
Return type:: ParsedFile
Raises:: NotImplementedError – If method is not implemented in inheriting classes

thipster.engine.i_repository module¶

Repository module interface.

class thipster.engine.i_repository.RepositoryPort¶

Bases: ABC

Repository port.

abstract get(resource_names: list[str]) → dict[str, ResourceModel]¶

Abstract get method.

Parameters:: resourceNames (list[str]) – List of resource names to be retrieved from the repository
Returns:: Dictionary of ResourceModel objects, indexed by resource name
Return type:: dict[str, ResourceModel]

thipster.engine.i_terraform module¶

Terraform module interface.

class thipster.engine.i_terraform.TerraformPort¶

Bases: ABC

Terraform port.

abstract classmethod apply(working_dir: Path, plan_file_path: str | None = None) → tuple[int, str]¶

Apply generated terraform code.

Parameters:

working_dir (Path) – Path to the working directory
plan_file_path (str, optional) – Path to plan file, by default None

Returns:

The Terraform apply exit code and output

Return type:

tuple[int, str]

Raises:

NotImplementedError – If method is not implemented in inheriting classes

abstract classmethod generate(file: ParsedFile, models: dict[str, ResourceModel], _authenticator: AuthPort)¶

Generate Terraform code from parsed file and models.

Parameters:

file (pf.ParsedFile) – The ParsedFile object containing the resources defined in the input file
models (dict[str, rm.ResourceModel]) – The dictionary of models

Raises:

NotImplementedError – If method is not implemented in inheriting classes

abstract classmethod init(working_dir: Path, upgrade: bool)¶

Init Terraform for generated terraform code.

Parameters:

working_dir (Path) – Path to the working directory
upgrade (bool) – Whether to upgrade Terraform providers or not

Raises:

NotImplementedError – If method is not implemented in inheriting classes

abstract classmethod plan(working_dir: Path, plan_file_path: str) → tuple[int, str]¶

Get plan from generated terraform code.

Parameters:

working_dir (Path) – Path to the working directory
plan_file_path (str) – Path and name of the plan file

Returns:

Terraform plan exitcode and output

Return type:

tuple[int, str]

Raises:

NotImplementedError – If method is not implemented in inheriting classes

thipster.engine.parsed_file module¶

parsedFile.py Module.

class thipster.engine.parsed_file.ParsedAttribute(name: str, position: Position | None, value: ParsedValue)¶

Bases: object

Reprensents a Parsed Attribute Object.

__init__(name: str, position: Position | None, value: ParsedValue)¶

Represent a Parsed Attribute Object.

Parameters:

name (str) – name of the attribute
position (Position | None) – position of the attribute in its origin file
value (ParsedValue) – value of the attribute

property unmarshalled_value¶: Value of the parsed attribute.

property value¶: Value of the parsed attribute.

class thipster.engine.parsed_file.ParsedDict(value: list[ParsedAttribute])¶

Bases: ParsedValue

Represents a Parsed Dictionnary Object.

__init__(value: list[ParsedAttribute])¶

Represent a Parsed Dictionnary Object.

Parameters:: value (list[ParsedAttribute]) – value of the parsed dictionnary

property unmarshalled¶: Return the unmarshalled value.

class thipster.engine.parsed_file.ParsedFile¶

Bases: object

Represents a Parsed File.

Object containing a list of parsed resources making up a file.

__init__()¶: Represent a Parsed File.

class thipster.engine.parsed_file.ParsedList(value: list[ParsedValue])¶

Bases: ParsedValue

Represents a Parsed List Object.

__init__(value: list[ParsedValue])¶

Represent a Parsed List Object.

Parameters:: value (list[ParsedValue]) – value of the parsed list

__iter__()¶: Return an iterator object.

__next__()¶: Return the next value of the iterator.

property unmarshalled¶: Return the unmarshalled value.

class thipster.engine.parsed_file.ParsedLiteral(value: bool | int | float | str)¶

Bases: ParsedValue

Represents a Parsed Literal Object.

__init__(value: bool | int | float | str)¶

Represent a Parsed Literal Object.

Parameters:: value (Literal) – value of the parsed literal

property unmarshalled¶: Return the unmarshalled value.

class thipster.engine.parsed_file.ParsedOutput(value: str, position: Position | None)¶

Bases: object

Represents a Parsed output.

__init__(value: str, position: Position | None)¶

Represent a Parsed output.

Parameters:

name (str) – value to output
position (Position) – position of the output block in its origin file

class thipster.engine.parsed_file.ParsedResource(parsed_resource_type: str, name: str, position: Position | None, attributes: list[ParsedAttribute])¶

Bases: object

Represents a Parsed Resource.

__init__(parsed_resource_type: str, name: str, position: Position | None, attributes: list[ParsedAttribute])¶

Represent a Parsed Resource.

Parameters:

parsed_resource_type (str) –
name (str) – name of the resource
position (Position) – position of the resource in its origin file
attributes (list[ParsedAttribute]) – list of attributes of the resource

class thipster.engine.parsed_file.ParsedValue¶

Bases: ABC

Parsed Value Interface.

abstract property unmarshalled¶: Return the unmarshalled value of the object.

class thipster.engine.parsed_file.Position(filename: str, ln: int, col: int)¶

Bases: object

Represents the position of a token.

Indicates the initial position of a token, resource or character in the input files. It includes the file name, line and column numbers of the designated element.

__eq__(_Position__value: object) → bool¶

Check if 2 positions are equal.

Parameters:: __value (object) – Position to compare
Returns:: True if both positions are equal or False otherwise
Return type:: bool
Raises:: TypeError – If ‘__value’ is not a Position

__init__(filename: str, ln: int, col: int)¶

Represent the position of a token.

Indicates the initial position of a token, resource or character in the input files. It includes the file name, line and column numbers of the designated element.

Parameters:

fileName (str) – file name
ln (int) – line number
col (int) – column number

__str__() → str¶

Return a string of the position object.

Returns:: (File : {}, Ln {}, Col {})
Return type:: str

thipster.engine.resource_model module¶

ResourceModel.py module.

class thipster.engine.resource_model.ModelAttribute(cdk_name: str, default: ModelValue | None = None, optional: bool = True, is_list: bool = False)¶

Bases: object

Represents a Resource Model attribute.

__init__(cdk_name: str, default: ModelValue | None = None, optional: bool = True, is_list: bool = False)¶

Represent a Resource Model attribute.

Parameters:

name (str) – Attribute name
default (ModelValue, optional) – Default Attribute value if there is one, by default None
optional (bool, optional) – Is attribute optional ?, by default True
is_list (bool, optional) – Is attribute a list ?, by default False

property default¶: Default value of the attribute.

class thipster.engine.resource_model.ModelDict(value: dict[str, ModelAttribute] | None)¶

Bases: ModelValue

Represent a dictionary value for a Resource Model attribute.

__init__(value: dict[str, ModelAttribute] | None)¶

Represent a dictionary value for a Resource Model attribute.

Parameters:: value (dict[str, ModelAttribute] | None) – Dictionary value

class thipster.engine.resource_model.ModelList(value: list[ModelValue | None] | None)¶

Bases: ModelValue

Represent a List of values for a Resource Model attribute.

__init__(value: list[ModelValue | None] | None)¶

Represent a List of values for a Resource Model attribute.

Parameters:: value (list[ModelValue | None] | None) – List of values

__iter__()¶: Iterate over the list.

__next__()¶: Return the next value of the iterator.

class thipster.engine.resource_model.ModelLiteral(value)¶

Bases: ModelValue

Represent a literal value for a Resource Model attribute.

__init__(value)¶

Represent a literal value for a Resource Model attribute.

Parameters:: value (bool | int | float | str) – Literal value

class thipster.engine.resource_model.ModelValue¶

Bases: ABC

Model Attribute Value Interface.

value = None¶

class thipster.engine.resource_model.ResourceModel(resource_type: str, attributes: dict[str, ModelAttribute] | None, dependencies: dict[str, dict[str, object]] | None, internal_objects: dict[str, dict[str, object]] | None, name_key: str | None, cdk_provider: str, cdk_module: str, cdk_name: str)¶

Bases: object

Represents a Resource Model.

__init__(resource_type: str, attributes: dict[str, ModelAttribute] | None, dependencies: dict[str, dict[str, object]] | None, internal_objects: dict[str, dict[str, object]] | None, name_key: str | None, cdk_provider: str, cdk_module: str, cdk_name: str)¶

Represent a Resource Model.

Parameters:

resource_type (str) – Resource type
attributes (dict[str, ModelAttribute] | None) – Resource attributes
dependencies (dict[str, dict[str, object]] | None) – Resource dependencies
internal_objects (dict[str, dict[str, object]] | None) – Resource internal objects
name_key (str | None) – Key to declare the resource ‘name’ (if any) in the Terraform Python CDK
cdk_provider (str) – Terraform Python CDK provider
cdk_module (str) – Terraform Python CDK module
cdk_name (str) – Resource name in the Terraform Python CDK

Module contents¶

Central engine module for THipster.

This module contains the Engine class, which is the central class of the THipster package as well as the interfaces for the various components of the application.

thipster.parser package¶

Subpackages¶

thipster.parser.dsl_parser package¶

Submodules¶

thipster.parser.dsl_parser.ast module¶

THipster’s DSL AST (Abstract Syntax Tree) module.

class thipster.parser.dsl_parser.ast.AmountNode(position: Token, amount: Node, variable: VariableDefinitionNode | None, node: Node | None)¶

Bases: Node

Amount node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.ArithExprNode(terms: list[TermNode], operations)¶

Bases: Node

Arithmetic expression node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.BoolNode(token: Token)¶

Bases: Node

Boolean node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.CompExprNode(left_value: Node, operation, right_value: Node | None = None)¶

Bases: Node

Comparison expression node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.DictNode(values: list[ParameterNode])¶

Bases: ValueNode

Dictionary node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.FactorNode(factors: list[Node], operation)¶

Bases: Node

Factor node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.FileNode¶

Bases: Node

File node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.FloatNode(token: Token)¶

Bases: Node

Float node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.IfElseNode(condition: StringNode, if_case: Node, else_case: Node | None)¶

Bases: IfNode

If-else node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

class thipster.parser.dsl_parser.ast.IfNode(condition: StringNode, if_case: Node)¶

Bases: Node

If node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.IntNode(token: Token)¶

Bases: Node

Integer node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.ListNode(values: list[ValueNode])¶

Bases: ValueNode

List node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.LiteralNode(value: Node)¶

Bases: ValueNode

Literal node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.Node¶

Bases: ABC

Abstract base AST node.

abstract accept(visitor)¶: Accept visitor method.

property position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.OutputNode(position: Position, value: StringNode)¶

Bases: Node

Output node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.ParameterNode(name: StringNode, value: ValueNode)¶

Bases: Node

Parameter node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.ResourceNode(resource_type: StringNode, name: StringNode, parameters: DictNode | ListNode)¶

Bases: Node

Resource node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.StringExprNode(*values: Node | list[Node])¶

Bases: Node

String expression node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Token¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.StringNode(token: Token)¶

Bases: Node

String node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.TermNode(factors, operation)¶

Bases: Node

Term node.

accept(visitor)¶: Accept visitor method.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.ValueNode¶

Bases: Node, ABC

Abstract base value node.

value = None¶

class thipster.parser.dsl_parser.ast.VariableDefinitionNode(name: Token, value: Node)¶

Bases: Node

Variable definition node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property name¶: Return variable’s name.

property position: Position¶: Return node’s position in the file.

class thipster.parser.dsl_parser.ast.VariableNode(token: Token)¶

Bases: Node

Variable node.

__str__() → str¶: Return string representation of the node.

accept(visitor)¶: Accept visitor method.

property name¶: Return variable’s name.

property position: Position¶: Return node’s position in the file.

thipster.parser.dsl_parser.exceptions module¶

Exceptions for the DSL parser.

exception thipster.parser.dsl_parser.exceptions.DSLArithmeticError(position: Position, error_message: str, *args: object)¶

Bases: DSLParserBaseError

Exception raised when an arithmetic error is encountered.

__init__(position: Position, error_message: str, *args: object) → None¶

Exception raised when an arithmetic error is encountered.

Parameters:

position (Position) – The position where the error occured.
error_message (str) – The error message.

property message: str¶: Return the exception message.

exception thipster.parser.dsl_parser.exceptions.DSLConditionError(token: Token, *args: object)¶

Bases: DSLParserBaseError

Exception raised when a condition is not valid.

__init__(token: Token, *args: object) → None¶

Exception raised when a condition is not valid.

Parameters:: token (Token) – The token where the error occured.

property message: str¶: Return the exception message.

exception thipster.parser.dsl_parser.exceptions.DSLParserBaseError(*args: object)¶

Bases: THipsterError

Shared base exception for the DSL parser.

__init__(*args: object) → None¶: Shared base exception for the DSL parser.

exception thipster.parser.dsl_parser.exceptions.DSLParserNoEndingQuotesError(position: Position, *args: object)¶

Bases: DSLParserBaseError

Exception raised when no ending quotes are found.

__init__(position: Position, *args: object) → None¶

Exception raised when no ending quotes are found.

positionPosition: The position where the error occured.

property message: str¶: Return the exception message.

exception thipster.parser.dsl_parser.exceptions.DSLParserPathNotFoundError(file: str, *args: object)¶

Bases: DSLParserBaseError

Exception raised when a file or directory is not found.

__init__(file: str, *args: object) → None¶

Exception raised when a file or directory is not found.

Parameters:: file (str) – The file or directory that was not found.

property message: str¶: Return the exception message.

exception thipster.parser.dsl_parser.exceptions.DSLParserVariableAlreadyUsedError(var: str, *args: object)¶

Bases: DSLParserBaseError

Exception raised when a variable name is already used.

__init__(var: str, *args: object) → None¶

Exception raised when a variable name is already used.

Parameters:: var (str) – The variable name.

property message: str¶: Return the exception message.

exception thipster.parser.dsl_parser.exceptions.DSLParserVariableNotDeclaredError(var: str, *args: object)¶

Bases: DSLParserBaseError

Exception raised when a variable is not declared.

__init__(var: str, *args: object) → None¶

Exception raised when a variable is not declared.

Parameters:: var (str) – The variable name.

property message: str¶: Return the exception message.

exception thipster.parser.dsl_parser.exceptions.DSLSyntaxError(token: Token, expected: TOKENTYPES | list[TOKENTYPES], *args: object)¶

Bases: DSLParserBaseError

Exception raised when a syntax error is encountered.

__init__(token: Token, expected: TOKENTYPES | list[TOKENTYPES], *args: object) → None¶

Exception raised when a syntax error is encountered.

Parameters:

token (Token) – The token where the error occured.
expected (TT | list[TT]) – The expected token type(s).

property message: str¶: Return the exception message.

exception thipster.parser.dsl_parser.exceptions.DSLUnexpectedEOFError(*args: object)¶

Bases: DSLParserBaseError

Exception raised when an unexpected EOF is encountered.

__init__(*args: object) → None¶: Exception raised when an unexpected EOF is encountered.

property message: str¶: Return the exception message.

thipster.parser.dsl_parser.interpreter module¶

Interpreter for the DSL Parser.

class thipster.parser.dsl_parser.interpreter.Interpreter¶

Bases: object

Interpreter class for the DSL Parser.

Implements a visitor design pattern on the AST nodes

__init__() → None¶

Interpreter class for the DSL Parser.

Implements a visitor design pattern on the AST nodes

run(tree: FileNode) → ParsedFile¶

Run the interpreter on an Abstract Syntax Tree.

Parameters:: tree (FileNode) – The root node of the abstract syntax tree
Returns:: The parsed file stucture assiociated to the given AST
Return type:: ParsedFile

visit_amount(element: AmountNode) → list[object]¶

Visitor for an AmountNode.

Parameters:: element (AmountNode) – The visited node
Returns:: A list with the required number of object (resource, list item, …)
Return type:: list[object]

visit_arith_expr(element: ArithExprNode) → int | float¶

Visitor for an ArithExprNode.

Parameters:: element (ArithExprNode) – The visited node
Returns:: The arithmetic value of the node
Return type:: int | float

visit_bool(element: BoolNode) → bool¶

Visitor for a BoolNode.

Parameters:: element (BoolNode) – The visited node
Returns:: The value of the node
Return type:: bool

visit_comp_expr(element: CompExprNode) → bool¶

Visitor for a CompExprNode.

Parameters:: element (CompExprNode) – The visited node
Returns:: The boolean value of the node
Return type:: bool

visit_dict(element: DictNode) → ParsedDict¶

Visitor for a DictNode.

Parameters:: element (DictNode) – The visited node
Returns:: A ParsedDict object based on the node attributes
Return type:: ParsedDict

visit_factor(element: FactorNode) → int | float¶

Visitor for a Factor node.

Parameters:: element (FactorNode) – The visited node
Returns:: The arithmetic value of the node
Return type:: int | float

visit_file(element: FileNode)¶

Visitor for a FileNode.

Parameters:: element (FileNode) – The visited node
Returns:: A ParsedFile object based on the node’s resources
Return type:: ParsedFile

visit_float(element: FloatNode) → float¶

Visitor for a FloatNode.

Parameters:: element (FloatNode) – The visited node
Returns:: The value of the node
Return type:: float

visit_if(element: IfNode) → object | None¶

Visitor for an IfNode.

Parameters:: element (IfNode) – The visited node
Returns:: The value of the child node if the condition is true, else None
Return type:: object | None

visit_ifelse(element: IfElseNode)¶

Visitor for an IfElseNode.

Parameters:: element (IfElseNode) – The visited node
Returns:: The value of the “if” child node if the condition is true, else the value of the “else” child node
Return type:: object | None

visit_int(element: IntNode) → int¶

Visitor for an IntNode.

Parameters:: element (IntNode) – The visited node
Returns:: The value of the node
Return type:: int

visit_list(element: ListNode) → ParsedList¶

Visitor for a ListNode.

Parameters:: element (ListNode) – The visited node
Returns:: A ParsedLiteral object based on the node elements
Return type:: ParsedList

visit_literal(element: LiteralNode) → ParsedLiteral¶

Visitor for a LiteralNode.

Parameters:: element (LiteralNode) – The visited node
Returns:: A ParsedLiteral object based on the node value
Return type:: ParsedLiteral

visit_output(element: OutputNode) → list[ParsedOutput]¶

Visitor for an OutputNode.

Parameters:: element (OutputNode) – The visited node
Returns:: A ParsedOutput object based on the node’s attributes
Return type:: list[pf.ParsedOutput]

visit_parameter(element: ParameterNode) → ParsedAttribute¶

Visitor for a ParameterNode.

Parameters:: element (ParameterNode) – The visited node
Returns:: A ParsedAttribute object containing the name, position and value of the node
Return type:: ParsedAttribute

visit_resource(element: ResourceNode) → list[ParsedResource]¶

Visitor for a ResourceNode.

Parameters:: element (ResourceNode) – The visited node
Returns:: A ParsedResource object based on the node’s attributes
Return type:: list[pf.ParsedResource]

visit_string(element: StringNode) → str¶

Visitor for a BoolNode.

Parameters:: element (BoolNode) – The visited node
Returns:: The value of the node
Return type:: bool

visit_string_expr(element: StringExprNode) → str¶

Visitor for a StringExprNode.

Parameters:: element (StringExprNode) – The visited node
Returns:: The string value of the node
Return type:: str

visit_term(element: TermNode) → int | float¶

Visitor for a TermNode.

Parameters:: element (TermNode) – The visited node
Returns:: The arithmetic value of the node
Return type:: int | float

visit_variable(element: VariableNode) → object¶

Visitor for a VariableNode.

Parameters:: element (VariableNode) – The visited node
Returns:: The value of the declared variable
Return type:: object
Raises:: DSLParserVariableNotDeclared – Tried to use a varible that was not declared

visit_variable_definition(element: VariableDefinitionNode) → str¶

Visitor for a VariableDefinitionNode.

Parameters:: element (VariableDefinitionNode) – The visited node
Returns:: The name of the declared variable
Return type:: str
Raises:: DSLParserVariableAlreadyUsed – Tried to declare a varible that was already declared

thipster.parser.dsl_parser.lexer module¶

Lexer module for the DSL Parser.

class thipster.parser.dsl_parser.lexer.Lexer(files: dict[str, str])¶

Bases: object

Lexer for the DSL Parser.

__init__(files: dict[str, str])¶

Lexer for the DSL Parser.

Parameters:: files (dict[str, str]) – Dictionnary of files to tokenize, fileName : fileContent

lex(filename: str, file_content: str) → None¶

Tokenize a file contents.

Parameters:

filename (str) – Name of the file
file_content (str) – Content of the file

Raises:

DSLParserNoEndingQuotes – Syntax error : detected a starting quote but no ending one

run() → list[Token]¶

Launch the Lexer.

Returns:: List of Tokens representing the input files
Return type:: list[Token]

thipster.parser.dsl_parser.lexer_position module¶

Module to represent the state and position of the lexer.

class thipster.parser.dsl_parser.lexer_position.LexerPosition(filename: str = '')¶

Bases: object

Represents the state and position of the DSL lexer.

__init__(filename: str = '') → None¶

Represent the state and position of the DSL lexer.

Parameters:: filename (str) – Name of the current file

add_to_current_token(char) → None¶

Add a char to the current stored token.

Parameters:: char (_type_) – Char to add to the token

property currentCharPosition: Position¶: Get the current position of the lexer.

property currentTokenPosition: Position¶: Get the position of the current stored token.

increment_consecutive_whitespaces() → None¶: Add a consecutive whitespace to the lexer state.

new_line() → None¶: Get the position to the next line.

next_column(step: int = 1) → None¶

Get the position to a new column.

Parameters:: step (int) – Step to modify the current column, by default 1

reset_consecutive_whitespaces() → None¶: Reset consecutive whitespaces of the lexer state to 0.

reset_current_token(new_index: int | None = None) → None¶

Reset the current stored token and its index.

Parameters:: new_index (int, optional) – New index of the stored token, by default None

set_current_token_index(new_index: int | None = None) → None¶

Modify the stored token index.

Parameters:: new_index (int, optional) – New index of the stored token, by default None

thipster.parser.dsl_parser.parser module¶

Module that contains the THipster DSL Parser.

class thipster.parser.dsl_parser.parser.DSLParser¶

Bases: ParserPort

Parser for the THipster’s DSL.

classmethod run(path: str) → ParsedFile¶

Run the DSLParser.

Parameters:: path (str) – Path to run the parser into
Returns:: A ParsedFile object with the content of all the files in the input path
Return type:: ParsedFile

thipster.parser.dsl_parser.token module¶

Module containing the Token class and the TOKENTYPES enum.

class thipster.parser.dsl_parser.token.TOKENTYPES(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Contains all the possible token types.

AMOUNT = 'AMOUNT'¶

AND = 'AND'¶

BOOLEAN = 'BOOLEAN'¶

BRACKETS_END = 'BRACKETS_END'¶

BRACKETS_START = 'BRACKETS_START'¶

COLON = 'COLON'¶

COMMA = 'COMMA'¶

DIV = 'DIV'¶

EE = 'EE'¶

ELIF = 'ELIF'¶

ELSE = 'ELSE'¶

EOF = 'EOF'¶

EQ = 'EQ'¶

EXCLAMATION = 'EXCLAMATION'¶

FLOAT = 'FLOAT'¶

GT = 'GT'¶

GTE = 'GTE'¶

IF = 'IF'¶

INT = 'INT'¶

LT = 'LT'¶

LTE = 'LTE'¶

MINUS = 'MINUS'¶

MUL = 'MUL'¶

NE = 'NE'¶

NEWLINE = 'NEWLINE'¶

NOT = 'NOT'¶

OR = 'OR'¶

OUTPUT = 'OUTPUT'¶

PARENTHESES_END = 'PARENTHESES_END'¶

PARENTHESES_START = 'PARENTHESES_START'¶

PERCENT = 'PERCENT'¶

PLUS = 'PLUS'¶

POW = 'POW'¶

STRING = 'STRING'¶

TAB = 'TAB'¶

VAR = 'VAR'¶

WHITESPACE = 'WHITESPACE'¶

class thipster.parser.dsl_parser.token.Token(position: Position, token_type: TOKENTYPES, value: str | None = None)¶

Bases: object

Represents a Token of the THipster DSL.

__eq__(_Token__value: object) → bool¶: Check if two tokens are equal.

__init__(position: Position, token_type: TOKENTYPES, value: str | None = None)¶

Represent a Token.

Parameters:

position (Position) – Position of the token in its input file
tokenType (str) – Token type
value (str, optional) – Token value, by default None

__repr__() → str¶: Return the string representation of the token.

__str__() → str¶: Return the string value of the token.

thipster.parser.dsl_parser.token_parser module¶

THipster DSL token parser module.

class thipster.parser.dsl_parser.token_parser.TokenParser(tokens: list[Token])¶

Bases: object

Parse the tokens into an AST (Abstract Syntax Tree).

__init__(tokens: list[Token]) → None¶

Parse the tokens into an AST (Abstract Syntax Tree).

Parameters:: tokens (list[Token]) – The list of tokens to parse.

run() → FileNode¶: Run the parser.

Module contents¶

Submodules¶

thipster.parser.exceptions module¶

Exceptions for the THipster parser module.

exception thipster.parser.exceptions.NoFileFoundError(path: str, *args: object)¶

Bases: THipsterError

Exception raised when the parser cannot find any files to parse.

__init__(path: str, *args: object) → None¶

Exception raised when the parser cannot find any files to parse.

Parameters:: path (str) – The path where no files were found.

property message: str¶: Return the exception message.

exception thipster.parser.exceptions.ParserPathNotFoundError(path: str, *args: object)¶

Bases: THipsterError

Exception raised when the parser cannot find the path.

__init__(path: str, *args: object) → None¶

Exception raised when the parser cannot find the path.

Parameters:: path (str) – The path that was not found.

property message: str¶: Return the exception message.

thipster.parser.parser_factory module¶

ParserFactory module.

class thipster.parser.parser_factory.NoParser¶

Bases: ParserPort

Used when no parser is found for a file extension.

classmethod run(path) → ParsedFile¶: Run the Parser.

class thipster.parser.parser_factory.ParserFactory¶

Bases: ParserPort

Parser factory, used to run the right parser on the right file.

classmethod add_parser(parser: ParserPort, extensions: list[str])¶: Add a parser to the ParserFactory.

classmethod run(path: str) → ParsedFile¶

Run the ParserFactory.

Parameters:: path (str) – Path to run the parser into
Returns:: A ParsedFile object with the content of all the files in the input path
Return type:: ParsedFile

thipster.parser.yaml_parser module¶

YAML Parser module.

class thipster.parser.yaml_parser.YAMLParser¶

Bases: ParserPort

YAMLParser class, used to parse YAML files.

classmethod run(path: str) → ParsedFile¶

Run the YAMLParser.

Parameters:: path (str) – Path to run the parser into
Returns:: A ParsedFile object with the content of all the files in the input path
Return type:: ParsedFile

exception thipster.parser.yaml_parser.YAMLParserBaseError(*args: object)¶

Bases: THipsterError, ABC

Base error for YAMLParser.

__init__(*args: object) → None¶: Shared base exception for the YAML parser.

exception thipster.parser.yaml_parser.YAMLParserNoNameError(resource, *args: object)¶

Bases: YAMLParserBaseError

Error raised when a resource has no name.

__init__(resource, *args: object) → None¶

Error raised when a resource has no name.

Parameters:: resource – The resource that has no name.

property message: str¶: Return the error message.

Module contents¶

Parser module.

Contains the various parsers used by THipster to interpret the input files. Currently, two options are available: - The DSL parser, which interprets .thips files - The YAML JINJA parser, which interprets .yml/.yaml/.jinja files

thipster.repository package¶

Submodules¶

thipster.repository.exceptions module¶

Exceptions for the repository module.

exception thipster.repository.exceptions.ModelNotFoundError(model: str, *args)¶

Bases: THipsterError

Exception raised when a model is not found in the database.

__init__(model: str, *args) → None¶

Exception raised when a model is not found in the database.

Parameters:: model (str) – The json resource model that was not found.

property message¶: Return the exception message.

thipster.repository.github module¶

GithubRepo.py module.

class thipster.repository.github.GithubRepo(repo: str, branch: str = 'main')¶

Bases: JSONRepo

Represents a GitHub resources Repository.

JSON Models of resources and services offered by supported cloud providers are stored in a repository. This class is used to access those models if they are located in a GitHub repo.

__init__(repo: str, branch: str = 'main') → None¶

Represent a GitHub resources Repository.

JSON Models of resources and services offered by supported cloud providers are stored in a repository. This class is used to access those models if they are located in a GitHub repo.

Parameters:

repo (str) – Name of the repository, for example : ‘THipster/models’
branch (str, optional) – Name of the branch, by default ‘main’

get_json(name: str) → str | bytes | bytearray¶

Get the json file from the GitHub repository.

Parameters:: name (str) – Name of the desired resource
Returns:: Content of the JSON file defining the desired resource
Return type:: str | bytes | bytearray

thipster.repository.json module¶

JSONRepo.py module.

class thipster.repository.json.JSONRepo¶

Bases: RepositoryPort, ABC

Represents a JSON resources Repository.

JSON Models of resources and services offered by supported cloud providers are stored in a repository.

__init__() → None¶

Represent a JSON resources Repository.

JSON Models of resources and services offered by supported cloud providers are stored in a repository.

get(resource_names: list[str]) → dict[str, ResourceModel]¶

Get the corresponding resource Models from a list of names.

Parameters:: resourceNames (list[str]) – List of the desired resource models names
Returns:: Dictionnary of the corresponding resource models
Return type:: dict[str, rm.ResourceModel]

abstract get_json(name: str) → str | bytes | bytearray¶: Get the JSON file corresponding to the name given.

thipster.repository.local module¶

Local repository implementation.

class thipster.repository.local.LocalRepo(path: str)¶

Bases: JSONRepo

Represents a local resources Repository.

JSON Models of resources and services offered by supported cloud providers are stored in a repository. This class is used to access those models if they are stored locally.

__init__(path: str) → None¶

Represent a local resources Repository.

JSON Models of resources and services offered by supported cloud providers are stored in a repository. This class is used to access those models if they are stored locally.

get_json(name: str) → str | bytes | bytearray¶: Get the json file from the local repository.

Module contents¶

Repository module.

Contains the various options to store the JSON models used by THipster to generate the Python Terraform CDK constructs. Currently, two options are available: - A local repository, which stores the models in a local folder - A GitHub repository

thipster.terraform package¶

Submodules¶

thipster.terraform.cdk module¶

thipster.terraform.exceptions module¶

Module contents¶

Submodules¶

thipster.helpers module¶

Helper functions for thipster.

thipster.helpers.create_logger(class_name: str) → Logger¶: Create a logger for the given class.

thipster.helpers.execute_subprocess(command: list[str] | str, cwd: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/thipster/checkouts/latest/docs/source'), shell: bool = False) → tuple[int, str]¶

Execute a subprocess and return the exit code and output.

Parameters:

command (list[str] | str) – Command to execute
cwd (Path, optional) – Current working directory, defaults to Path.cwd()
shell (bool, optional) – Whether to use the shell, defaults to False

Returns:

Exit code and output

Return type:

tuple[int, str]

thipster.helpers.set_logging_config(log_level: str = 'INFO', filename: str | None = None, filemode: str = 'w') → None¶

Set logging configuration.

Parameters:

log_level (str) – Log level, defaults to INFO
filename (str, optional) – Log filename, defaults to None

Module contents¶

Thipster is a tool that enhances the compute capabilities of Terraform and simplifies its file writing through its dedicated language

Welcome to Thipster’s documentation!¶

THipster¶

Technology Stack¶

Project Status¶

Dependencies¶

Installation¶

Usage¶

How to test the software¶

Known issues¶

Getting help¶

Getting involved¶

Open source licensing info¶

Credits and references¶

thipster¶

thipster package¶

Subpackages¶

thipster.auth package¶

Submodules¶

thipster.auth.google module¶

Module contents¶

thipster.engine package¶

Submodules¶

thipster.engine.engine module¶

thipster.engine.exceptions module¶

thipster.engine.i_auth module¶

thipster.engine.i_parser module¶

thipster.engine.i_repository module¶

thipster.engine.i_terraform module¶

thipster.engine.parsed_file module¶

thipster.engine.resource_model module¶

Module contents¶

thipster.parser package¶

Subpackages¶

thipster.parser.dsl_parser package¶

Submodules¶

thipster.parser.dsl_parser.ast module¶

thipster.parser.dsl_parser.exceptions module¶

thipster.parser.dsl_parser.interpreter module¶

thipster.parser.dsl_parser.lexer module¶

thipster.parser.dsl_parser.lexer_position module¶

thipster.parser.dsl_parser.parser module¶

thipster.parser.dsl_parser.token module¶

thipster.parser.dsl_parser.token_parser module¶

Module contents¶

Submodules¶

thipster.parser.exceptions module¶

thipster.parser.parser_factory module¶

thipster.parser.yaml_parser module¶

Module contents¶

thipster.repository package¶

Submodules¶

thipster.repository.exceptions module¶

thipster.repository.github module¶

thipster.repository.json module¶

thipster.repository.local module¶

Module contents¶

thipster.terraform package¶

Submodules¶

thipster.terraform.cdk module¶

thipster.terraform.exceptions module¶

Module contents¶

Submodules¶

thipster.helpers module¶

Module contents¶

Indices and tables¶