gitter-badger / cottonformation-project Goto Github PK

cottonformation is a Python tool providing best development experience and highest productivity. Powered by modern Type Hint, Advanced Auto Complete, Parameter Hint, Instant official AWS Document look up. Here's how it looks like in PyCharm (Supported by PyCharm out-of-the-box, but you can configure it by installing extension or plugin in VSCode, Sublime, Atom ...).

1. Type hint and property hint: tell you what property is available, what is the type, and auto complete the code for you. rp prefix stands for Required Property, p prefix stands for Optional Property, you can navigate property using UP and DOWN key. You can also view available property and type (Cmd + P), see how at View Parameter Info.

2. Return value hint: tell you what return value is available, and allow you instantly acccess it without need looking up the AWS Document. You don't need to remember ANY API. To be honest, looking up the exact Resource Attribute Name in https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html and then GetAtt(resource_object, attribute_name) is really UGLY!

3. Parameter hint: tell you all available parameter and its type (Cmd + P). It works on both Resource Type and complex Property Type.

4. Jump to resource doc: instantly open the AWS Doc about this AWS Resource in web browser. Click on the class, hit F1 and click on the link.

5. Jump to property doc method 1: instantly open the AWS Doc about this Resource Property in web browser. Click on the class, hit F1 (view doc string), find the property and click on the link.

6. Jump to property doc method 2: reference the resource property using resource_object.property_name syntax, click on the property, hit F1 (view doc string), and click on the link.

7. Jump to return value doc: reference the resource attribute using resource_object.attribute_name syntax, click on the property, hit F1 (view doc string), and click on the link.

That's NOT everything, cottonformation can do far more than this.

The Goal:

There are lots of Cloud infrastructure as code tools available AWS CloudFormation, Terraform, troposphere, aws cdk, pulumi. They all be good in different way. cottonformation is not trying to beat or replace any of them, but focus on being the best in it's special way.

1. Most productive for development.
2. Most user friendly, no memorization, no difficult learning curve.
3. Less code, light weight, easy to customize and extend.

The History:

The first generation Infrastructure as Code (IAC) might be AWS CloudFormation firstly released on 2011 and Terraform firstly released on 2014. The first generation IAC are mostly Domain specific language (DSL). They are not as powerful as general programming language like Java, C#, Python, Ruby, Go. Because of the nature DSL, it is hard to manipulate data, customize logic flow, poor code reusability, difficult to customize and extend.

The rule breaker troposphere was released on 2013. It is a Python project allow you to write CloudFormation template in Python using Objective Oriented programming model. But due to the initial code design, natively it is not able to support modern developer features like "Auto Complete" and "Type Hint". As a result, at least 50% of development time is used in lookup manual, read documentations. At mean time, AWS Cloudformation is evolving very fast supporting more AWS Resource. Since troposphere relies on maintainer adding implementation manually, it usually falls behind the latest feature.

I started to maintain a parallel library troposphere_mate to support "Auto Complete" and "Type Hint" and more advanced feature. However, it cannot evolve fast since it is based on troposphere and I have no control at all on it. I used to think of re-design a new project using latest programming model to replace troposphere in my Organization. But there are 162 AWS Service, 768 AWS Resource, 2,499 AWS Property and 43,200 lines of declaration code to work on. It is impossible to keep it up-to-date as an individual developer.

Fortunately, AWS published the AWS CloudFormation resource specification as a machine readable json file, and type hint and static check technology is already mature in Python community, I believe it is a good timing to re-invent a modernized CloudFormation tool.

Again, cottomformation don't want to be the improved AWS CDK or Pulumi. It want to do the best on the limited, but important feature as IAC tool.

AWS CDK:

Python is not first class member in AWS CDK. The nature of AWS CDK is a TypeScript Library, and AWS find a way to call TypeScript / JavaScript API from other programming language like Java / Ruby / Python / C# / Go. When you run AWS CDK in programming language other than TypeScript, the code is actually been converted to low level api, and been handled by the backend TypeScript code. This causes two issue:

1. Significant delay in editing. Since "Type hint" and "Code Complete" is based on static code analysis technique and Python import engine. But internally AWS CDK import the underlying compiled Python - TypeScript *.jsii code when you import a AWS Resource declaration class. This is why it's slow with a 2019, 16GB memory Macbook Pro.
2. Hard to customize and extend. Because the python code is underlying calling TypeScript API, there's no way you can inject your custom logic in the python code because it is not recognized by TypeScript API.
3. You have to configure the Node.JS environment the Node.JS version of AWS CDK. In python community, we expect a simple pip install something then import something. You need additional configuration steps when you run it in a remote or a CI environment.

Pulumi:

Pulumi is more like terraform. Unlike troposphere and AWS CDK, it doesn't convert script to CloudFormation, but using it's own executing engine to deploy resources. Although it is easy to learn and worth, but you need to learn lots of new concept and component.

cottonformation is released on PyPI, so all you need is:

$ pip install cottonformation

To upgrade to latest version:

$ pip install --upgrade cottonformation