| Name | picofun JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | PicoFun AWS Lambda generator |
| upload_time | 2024-10-20 16:08:01 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | Copyright 2023 Dave Hall - https://proactiveops.io Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PicoFun
*There's little fun in writing boilerplate*
PicoFun is a tool for generating Python based clients for OpenAPI spec files. The client for each endpoint is packaged as an AWS Lambda function. A terraform module is also generated to deploy the clients to AWS. The generated functions are designed to be be invoked using Step Functions or the Lambda Invoke API.
**PicoFun only supports OpenAPI version 3 spec files.** Swagger files and versions of OpenAPI prior to 3 are not supported.
## Installation
PicoFun can be installed using `pip`, but it is recommended to use `pipx`. This is particularly useful in a CI/CD pipeline. Invoke PicoFun with `pipx` like this:
```bash
pipx run picofun [ARGS]
```
If you need to install `pipx`, please [refer to the documention](https://pypa.github.io/pipx/).
## Configuration
PicoFun is configured using a TOML file. The default configuration file is `picofun.toml` in the current working directory. An alternative location for the configuration file can be specified using the optional `--config` argument.
The configuration file has the following structure:
```toml
bundle="/path/containing/code/to/bundle/into/build" # default is none
iam_role_prefix="my-prefix-" # default is "pf-" for PicoFun
layers="arn:aws:lambda:us-east-1:012345678910:layer:example:1,arn:aws:lambda:us-east-1:012345678910:layer:another-example:123" # default is none
output_dir="/path/to/write/output-files" # default is current-working-directory/output
postprocessor="fully.qualified.reference.to.postprocessor" # default is none
preprocessor="fully.qualified.reference.to.preprocessor" # default is none
role_permissions_boundary="arn:aws:iam::012345678910:policy/..." # default is none
subnets="subnet-1234567890abcdef0,subnet-234567890abcdef01" # default is none and VPC networking is no enabled
tags=... # default is none
template_path="/path/to/templates" # default is current-working-directory/templates
```
## Usage
PicoFun is invoked using the `picofun` command. The minimum arguments required to invoke PicoFun are the project namespace and the OpenAPI spec file. The project namespace is used to generate the names of the generated functions and the terraform module. The OpenAPI spec file is used to generate the clients.
Here is a minimal example:
```bash
picofun example https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/api-with-examples.json
```
This will create a directory called `output` in the current working directory. The directory will contain the generated functions and the terraform module. The terraform module is in the root directory of `output/`. The generated functions are in the `lambdas` sub directory and the code for lambda layer is in the `layer` sub directory.
While the `config.toml` file is the preferred way to manage the configuration for the project, there are times when it is useful to override the configuration file. The following arguments can be used to override the configuration file:
```
--config-file # Full path to the alternate configuration file
--output-dir # Directory to output the generated files
--layers # Comma separated list of Lambda layer ARNs to include in the function configuration
--bundle # Path to code to bundle into a layer. If requirements.txt present pip install will be run.
```
Here is an example of overriding the configuration file:
```bash
picofun --config ~/picofun-example.toml example example.json
```
Commonly the layers argument is used to provide different layer ARNs based on the target environment, region and AWS account. Here is an example of overriding the layers argument:
```bash
picofun --layers "arn:aws:lambda:us-east-1:012345678912:layer:example:1,arn:aws:lambda:us-east-1:012345678912:layer:another-example:123" example example.yaml
```
## Bundle
PicoFun supports bundling code into a Lambda layer. The code to bundle is specified using the `bundle` entry in the configuration file or the `--bundle` argument on the command line. If a `requirements.txt` file is present in the bundle directory, `pip install` will be run by terraform before creating the layer.
The most common use case for using code bundles is to include pre and post processors.
## Preprocessing and Postprocessing Requests
Out of the box PicoFun generates Lambda functions that make unauthenicated calls to endpoints. Often this isn't what teams need. The preprocessing and postprocessing hooks allow engineers to customize the request payload and response. A common use case for this is to add authentication headers to requests.
An example implementation of these hooks can be found in the [`example/zendesk_common`](example/zendesk_common) directory. The example pulls values from SSM Parameter store and uses them for the domain name and authorization header.
## Template Overrides
The default templates bundled with PicoFun are usually adequate for most use cases. There are times where more customisation is needed. This could be to include custom logic in the Lambda function or additional resources in the terraform module.
If you need to override one PicoFun template, you need to copy both from the package. The templates are located in the `templates` directory in the PicoFun package.
You can add the path to the templates to the `config.toml` file using the `template_path` entry.
## Terraform
PicoFun generates a terraform module to deploy the generated functions to AWS. The module is located in the root of your configured output directory. It `output`s the Lambda function ARNs and IAM role ARN.
The module can be included in your terraform project like this:
```hcl
module "example_lambdas" {
source = "/path/to/picofun/output"
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "picofun",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Dave Hall <skwashd@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/18/7f/6dd9d965d87cab7cebbbef2864da5f583e8d35e9cbd84b0b6d23efaa154f/picofun-0.3.1.tar.gz",
"platform": null,
"description": "# PicoFun\n\n*There's little fun in writing boilerplate*\n\nPicoFun is a tool for generating Python based clients for OpenAPI spec files. The client for each endpoint is packaged as an AWS Lambda function. A terraform module is also generated to deploy the clients to AWS. The generated functions are designed to be be invoked using Step Functions or the Lambda Invoke API.\n\n**PicoFun only supports OpenAPI version 3 spec files.** Swagger files and versions of OpenAPI prior to 3 are not supported.\n\n## Installation\n\nPicoFun can be installed using `pip`, but it is recommended to use `pipx`. This is particularly useful in a CI/CD pipeline. Invoke PicoFun with `pipx` like this:\n\n```bash\npipx run picofun [ARGS]\n```\n\nIf you need to install `pipx`, please [refer to the documention](https://pypa.github.io/pipx/).\n\n## Configuration\n\nPicoFun is configured using a TOML file. The default configuration file is `picofun.toml` in the current working directory. An alternative location for the configuration file can be specified using the optional `--config` argument.\n\nThe configuration file has the following structure:\n\n```toml\nbundle=\"/path/containing/code/to/bundle/into/build\" # default is none\niam_role_prefix=\"my-prefix-\" # default is \"pf-\" for PicoFun\nlayers=\"arn:aws:lambda:us-east-1:012345678910:layer:example:1,arn:aws:lambda:us-east-1:012345678910:layer:another-example:123\" # default is none\noutput_dir=\"/path/to/write/output-files\" # default is current-working-directory/output\npostprocessor=\"fully.qualified.reference.to.postprocessor\" # default is none\npreprocessor=\"fully.qualified.reference.to.preprocessor\" # default is none\nrole_permissions_boundary=\"arn:aws:iam::012345678910:policy/...\" # default is none\nsubnets=\"subnet-1234567890abcdef0,subnet-234567890abcdef01\" # default is none and VPC networking is no enabled\ntags=... # default is none\ntemplate_path=\"/path/to/templates\" # default is current-working-directory/templates\n```\n\n## Usage\n\nPicoFun is invoked using the `picofun` command. The minimum arguments required to invoke PicoFun are the project namespace and the OpenAPI spec file. The project namespace is used to generate the names of the generated functions and the terraform module. The OpenAPI spec file is used to generate the clients.\n\nHere is a minimal example:\n\n```bash\n\npicofun example https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/api-with-examples.json\n\n```\n\nThis will create a directory called `output` in the current working directory. The directory will contain the generated functions and the terraform module. The terraform module is in the root directory of `output/`. The generated functions are in the `lambdas` sub directory and the code for lambda layer is in the `layer` sub directory.\n\nWhile the `config.toml` file is the preferred way to manage the configuration for the project, there are times when it is useful to override the configuration file. The following arguments can be used to override the configuration file:\n\n```\n --config-file # Full path to the alternate configuration file\n --output-dir # Directory to output the generated files\n --layers # Comma separated list of Lambda layer ARNs to include in the function configuration\n --bundle # Path to code to bundle into a layer. If requirements.txt present pip install will be run. \n```\n\nHere is an example of overriding the configuration file:\n\n```bash\n\npicofun --config ~/picofun-example.toml example example.json\n\n```\n\nCommonly the layers argument is used to provide different layer ARNs based on the target environment, region and AWS account. Here is an example of overriding the layers argument:\n\n```bash\n\npicofun --layers \"arn:aws:lambda:us-east-1:012345678912:layer:example:1,arn:aws:lambda:us-east-1:012345678912:layer:another-example:123\" example example.yaml\n\n```\n\n## Bundle\n\nPicoFun supports bundling code into a Lambda layer. The code to bundle is specified using the `bundle` entry in the configuration file or the `--bundle` argument on the command line. If a `requirements.txt` file is present in the bundle directory, `pip install` will be run by terraform before creating the layer.\n\nThe most common use case for using code bundles is to include pre and post processors.\n\n## Preprocessing and Postprocessing Requests\n\nOut of the box PicoFun generates Lambda functions that make unauthenicated calls to endpoints. Often this isn't what teams need. The preprocessing and postprocessing hooks allow engineers to customize the request payload and response. A common use case for this is to add authentication headers to requests.\n\nAn example implementation of these hooks can be found in the [`example/zendesk_common`](example/zendesk_common) directory. The example pulls values from SSM Parameter store and uses them for the domain name and authorization header.\n\n## Template Overrides\n\nThe default templates bundled with PicoFun are usually adequate for most use cases. There are times where more customisation is needed. This could be to include custom logic in the Lambda function or additional resources in the terraform module. \n\nIf you need to override one PicoFun template, you need to copy both from the package. The templates are located in the `templates` directory in the PicoFun package.\n\nYou can add the path to the templates to the `config.toml` file using the `template_path` entry.\n\n## Terraform\n\nPicoFun generates a terraform module to deploy the generated functions to AWS. The module is located in the root of your configured output directory. It `output`s the Lambda function ARNs and IAM role ARN.\n\nThe module can be included in your terraform project like this:\n\n```hcl\nmodule \"example_lambdas\" {\n source = \"/path/to/picofun/output\"\n}\n```\n",
"bugtrack_url": null,
"license": "Copyright 2023 Dave Hall - https://proactiveops.io Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \u201cSoftware\u201d), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \u201cAS IS\u201d, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "PicoFun AWS Lambda generator",
"version": "0.3.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3a686b75df2b0d69af9a2feb59b2ff7157774494d5a027c0af691774d289373d",
"md5": "af8a99bc700be90fc0b389b3697d1054",
"sha256": "02fdf32a2d748c202965e827577d005554e1916b93401fc1ffaae53cecd451a2"
},
"downloads": -1,
"filename": "picofun-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af8a99bc700be90fc0b389b3697d1054",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16365,
"upload_time": "2024-10-20T16:08:00",
"upload_time_iso_8601": "2024-10-20T16:08:00.093996Z",
"url": "https://files.pythonhosted.org/packages/3a/68/6b75df2b0d69af9a2feb59b2ff7157774494d5a027c0af691774d289373d/picofun-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "187f6dd9d965d87cab7cebbbef2864da5f583e8d35e9cbd84b0b6d23efaa154f",
"md5": "6fbd867050c5ec7e90682292a58f1e0a",
"sha256": "154b420bc36c01b0a4348fc7a712368884ab5a5bfee4a508cf5c705454913860"
},
"downloads": -1,
"filename": "picofun-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "6fbd867050c5ec7e90682292a58f1e0a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19759,
"upload_time": "2024-10-20T16:08:01",
"upload_time_iso_8601": "2024-10-20T16:08:01.675211Z",
"url": "https://files.pythonhosted.org/packages/18/7f/6dd9d965d87cab7cebbbef2864da5f583e8d35e9cbd84b0b6d23efaa154f/picofun-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-20 16:08:01",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "picofun"
}
