# AWS Lambda Environment Variables Modeler (Python)
[](https://github.com/ran-isenberg/aws-lambda-env-modeler/blob/master/LICENSE)
[](https://codecov.io/gh/ran-isenberg/aws-lambda-env-modeler)
AWS-Lambda-Env-Modeler is a Python library designed to simplify the process of managing and validating environment variables in your AWS Lambda functions.
It leverages the power of [Pydantic](https://pydantic-docs.helpmanual.io/) models to define the expected structure and types of the environment variables.
This library is especially handy for serverless applications where managing configuration via environment variables is a common practice.
**[📜Documentation](https://ran-isenberg.github.io/aws-lambda-env-modeler/)** | **[Blogs website](https://www.ranthebuilder.cloud)**
> **Contact details | ran.isenberg@ranthebuilder.cloud**
## **The Problem**
Environment variables are often viewed as an essential utility. They serve as static AWS Lambda function configuration.
Their values are set during the Lambda deployment, and the only way to change them is to redeploy the Lambda function with updated values.
However, many engineers use them unsafely despite being such an integral and fundamental part of any AWS Lambda function deployment.
This usage may cause nasty bugs or even crashes in production.
This library allows you to correctly parse, validate, and use your environment variables in your Python AWS Lambda code.
Read more about it [here](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-environment-variables)
### **Features**
- Validates the environment variables against a Pydantic model: define both semantic and syntactic validation.
- Serializes the string environment variables into complex classes and types.
- Provides means to access the environment variables safely with a global getter function in every part of the function.
- Provides a decorator to initialize the environment variables before executing a function.
- Caches the parsed model for performance improvement for multiple 'get' calls.
## Installation
You can install it using pip:
```bash
pip install aws-lambda-env-modeler
```
## Getting started
Head over to the complete project documentation pages at GitHub pages at [https://ran-isenberg.github.io/aws-lambda-env-modeler](https://ran-isenberg.github.io/aws-lambda-env-modeler/)
## Usage
First, define a Pydantic model for your environment variables:
```python
from pydantic import BaseModel, HttpUrl
class MyEnvVariables(BaseModel):
DB_HOST: str
DB_PORT: int
DB_USER: str
DB_PASS: str
FLAG_X: bool
API_URL: HttpUrl
```
Before executing a function, you must use the `@init_environment_variables` decorator to validate and initialize the environment variables automatically.
The decorator guarantees that the function will run with the correct variable configuration.
Then, you can fetch the environment variables using the global getter function, 'get_environment_variables,' and use them just like a data class. At this point, they are parsed and validated.
```python
from aws_lambda_env_modeler import init_environment_variables
@init_environment_variables(MyEnvVariables)
def my_handler_entry_function(event, context):
# At this point, environment variables are already validated and initialized
pass
```
Then, you can fetch and validate the environment variables with your model:
```python
from aws_lambda_env_modeler import get_environment_variables
env_vars = get_environment_variables(MyEnvVariables)
print(env_vars.DB_HOST)
```
## Disabling Cache for Testing
By default, the modeler uses cache - the parsed model is cached for performance improvement for multiple 'get' calls.
In some cases, such as during testing, you may want to turn off the cache. You can do this by setting the `LAMBDA_ENV_MODELER_DISABLE_CACHE` environment variable to 'True.'
This is especially useful in tests where you want to run multiple tests concurrently, each with a different set of environment variables.
Here's an example of how you can use this in a pytest test:
```python
import json
from http import HTTPStatus
from typing import Any, Dict
from unittest.mock import patch
from pydantic import BaseModel
from typing_extensions import Literal
from aws_lambda_env_modeler import LAMBDA_ENV_MODELER_DISABLE_CACHE, get_environment_variables, init_environment_variables
class MyHandlerEnvVars(BaseModel):
LOG_LEVEL: Literal['DEBUG', 'INFO', 'ERROR', 'CRITICAL', 'WARNING', 'EXCEPTION']
@init_environment_variables(model=MyHandlerEnvVars)
def my_handler(event: Dict[str, Any], context) -> Dict[str, Any]:
env_vars = get_environment_variables(model=MyHandlerEnvVars) # noqa: F841
# can access directly env_vars.LOG_LEVEL as dataclass
return {
'statusCode': HTTPStatus.OK,
'headers': {'Content-Type': 'application/json'},
'body': json.dumps({'message': 'success'}),
}
@patch.dict('os.environ', {LAMBDA_ENV_MODELER_DISABLE_CACHE: 'true', 'LOG_LEVEL': 'DEBUG'})
def test_my_handler():
response = my_handler({}, None)
assert response['statusCode'] == HTTPStatus.OK
assert response['headers'] == {'Content-Type': 'application/json'}
assert json.loads(response['body']) == {'message': 'success'}
```
## Code Contributions
Code contributions are welcomed. Read this [guide.](https://github.com/ran-isenberg/aws-lambda-env-modeler/blob/main/CONTRIBUTING.md)
## Code of Conduct
Read our code of conduct [here.](https://github.com/ran-isenberg/aws-lambda-env-modeler/blob/main/CODE_OF_CONDUCT.md)
## Connect
* Email: [ran.isenberg@ranthebuilder.cloud](mailto:ran.isenberg@ranthebuilder.cloud)
* Blog Website [RanTheBuilder](https://www.ranthebuilder.cloud)
* LinkedIn: [ranisenberg](https://www.linkedin.com/in/ranisenberg/)
* Twitter: [RanBuilder](https://twitter.com/RanBuilder)
## License
This library is licensed under the MIT License. See the [LICENSE](https://github.com/ran-isenberg/aws-lambda-env-modeler/blob/main/LICENSE) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/ran-isenberg/aws-lambda-env-modeler",
"name": "aws-lambda-env-modeler",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.9.0",
"maintainer_email": null,
"keywords": "environment variables parser, aws lambda, serverless best practices, aws serverless, lambda environment variables",
"author": "Ran Isenberg",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/93/84/6c852fb2440a72e65e2bf798af3e80f7f86055dfacafb8ea57723e0ec7db/aws_lambda_env_modeler-2.0.0.tar.gz",
"platform": null,
"description": "\n# AWS Lambda Environment Variables Modeler (Python)\n\n[](https://github.com/ran-isenberg/aws-lambda-env-modeler/blob/master/LICENSE)\n\n\n\n[](https://codecov.io/gh/ran-isenberg/aws-lambda-env-modeler)\n\n\n\n\n\n\nAWS-Lambda-Env-Modeler is a Python library designed to simplify the process of managing and validating environment variables in your AWS Lambda functions.\n\nIt leverages the power of [Pydantic](https://pydantic-docs.helpmanual.io/) models to define the expected structure and types of the environment variables.\n\nThis library is especially handy for serverless applications where managing configuration via environment variables is a common practice.\n\n**[\ud83d\udcdcDocumentation](https://ran-isenberg.github.io/aws-lambda-env-modeler/)** | **[Blogs website](https://www.ranthebuilder.cloud)**\n> **Contact details | ran.isenberg@ranthebuilder.cloud**\n\n\n## **The Problem**\n\nEnvironment variables are often viewed as an essential utility. They serve as static AWS Lambda function configuration.\n\nTheir values are set during the Lambda deployment, and the only way to change them is to redeploy the Lambda function with updated values.\n\nHowever, many engineers use them unsafely despite being such an integral and fundamental part of any AWS Lambda function deployment.\n\nThis usage may cause nasty bugs or even crashes in production.\n\n\nThis library allows you to correctly parse, validate, and use your environment variables in your Python AWS Lambda code.\n\nRead more about it [here](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-environment-variables)\n\n### **Features**\n\n- Validates the environment variables against a Pydantic model: define both semantic and syntactic validation.\n- Serializes the string environment variables into complex classes and types.\n- Provides means to access the environment variables safely with a global getter function in every part of the function.\n- Provides a decorator to initialize the environment variables before executing a function.\n- Caches the parsed model for performance improvement for multiple 'get' calls.\n\n\n## Installation\n\nYou can install it using pip:\n\n```bash\npip install aws-lambda-env-modeler\n```\n\n## Getting started\nHead over to the complete project documentation pages at GitHub pages at [https://ran-isenberg.github.io/aws-lambda-env-modeler](https://ran-isenberg.github.io/aws-lambda-env-modeler/)\n\n\n## Usage\nFirst, define a Pydantic model for your environment variables:\n\n```python\nfrom pydantic import BaseModel, HttpUrl\n\nclass MyEnvVariables(BaseModel):\n DB_HOST: str\n DB_PORT: int\n DB_USER: str\n DB_PASS: str\n FLAG_X: bool\n API_URL: HttpUrl\n```\n\nBefore executing a function, you must use the `@init_environment_variables` decorator to validate and initialize the environment variables automatically.\n\nThe decorator guarantees that the function will run with the correct variable configuration.\n\nThen, you can fetch the environment variables using the global getter function, 'get_environment_variables,' and use them just like a data class. At this point, they are parsed and validated.\n\n```python\nfrom aws_lambda_env_modeler import init_environment_variables\n\n@init_environment_variables(MyEnvVariables)\ndef my_handler_entry_function(event, context):\n # At this point, environment variables are already validated and initialized\n pass\n```\n\nThen, you can fetch and validate the environment variables with your model:\n\n```python\nfrom aws_lambda_env_modeler import get_environment_variables\n\nenv_vars = get_environment_variables(MyEnvVariables)\nprint(env_vars.DB_HOST)\n```\n\n## Disabling Cache for Testing\n\nBy default, the modeler uses cache - the parsed model is cached for performance improvement for multiple 'get' calls.\n\nIn some cases, such as during testing, you may want to turn off the cache. You can do this by setting the `LAMBDA_ENV_MODELER_DISABLE_CACHE` environment variable to 'True.'\n\nThis is especially useful in tests where you want to run multiple tests concurrently, each with a different set of environment variables.\n\nHere's an example of how you can use this in a pytest test:\n\n```python\nimport json\nfrom http import HTTPStatus\nfrom typing import Any, Dict\nfrom unittest.mock import patch\n\nfrom pydantic import BaseModel\nfrom typing_extensions import Literal\n\nfrom aws_lambda_env_modeler import LAMBDA_ENV_MODELER_DISABLE_CACHE, get_environment_variables, init_environment_variables\n\n\nclass MyHandlerEnvVars(BaseModel):\n LOG_LEVEL: Literal['DEBUG', 'INFO', 'ERROR', 'CRITICAL', 'WARNING', 'EXCEPTION']\n\n\n@init_environment_variables(model=MyHandlerEnvVars)\ndef my_handler(event: Dict[str, Any], context) -> Dict[str, Any]:\n env_vars = get_environment_variables(model=MyHandlerEnvVars) # noqa: F841\n # can access directly env_vars.LOG_LEVEL as dataclass\n return {\n 'statusCode': HTTPStatus.OK,\n 'headers': {'Content-Type': 'application/json'},\n 'body': json.dumps({'message': 'success'}),\n }\n\n\n@patch.dict('os.environ', {LAMBDA_ENV_MODELER_DISABLE_CACHE: 'true', 'LOG_LEVEL': 'DEBUG'})\ndef test_my_handler():\n response = my_handler({}, None)\n assert response['statusCode'] == HTTPStatus.OK\n assert response['headers'] == {'Content-Type': 'application/json'}\n assert json.loads(response['body']) == {'message': 'success'}\n```\n\n## Code Contributions\nCode contributions are welcomed. Read this [guide.](https://github.com/ran-isenberg/aws-lambda-env-modeler/blob/main/CONTRIBUTING.md)\n\n## Code of Conduct\nRead our code of conduct [here.](https://github.com/ran-isenberg/aws-lambda-env-modeler/blob/main/CODE_OF_CONDUCT.md)\n\n## Connect\n* Email: [ran.isenberg@ranthebuilder.cloud](mailto:ran.isenberg@ranthebuilder.cloud)\n* Blog Website [RanTheBuilder](https://www.ranthebuilder.cloud)\n* LinkedIn: [ranisenberg](https://www.linkedin.com/in/ranisenberg/)\n* Twitter: [RanBuilder](https://twitter.com/RanBuilder)\n\n\n## License\nThis library is licensed under the MIT License. See the [LICENSE](https://github.com/ran-isenberg/aws-lambda-env-modeler/blob/main/LICENSE) file.\n\n",
"bugtrack_url": null,
"license": "MIT-0",
"summary": "AWS-Lambda-Env-Modeler is a Python library designed to simplify the process of managing and validating environment variables in your AWS Lambda functions.",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/ran-isenberg/aws-lambda-env-modeler",
"Issue tracker": "https://github.com/ran-isenberg/aws-lambda-env-modeler/issues",
"Releases": "https://github.com/ran-isenberg/aws-lambda-env-modeler/releases",
"Repository": "https://github.com/ran-isenberg/aws-lambda-env-modeler"
},
"split_keywords": [
"environment variables parser",
" aws lambda",
" serverless best practices",
" aws serverless",
" lambda environment variables"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "48b2dfd72b092b243ac4866adca071aa3784d1eae03d1b1ce131cb5ec4d5c389",
"md5": "ce6080a2ffcd3e2688400a17efdd2d0b",
"sha256": "b587b2ac1f7c3bfa5ac95537d9a8a5dc58bfeacd472b86136f5235d479613b40"
},
"downloads": -1,
"filename": "aws_lambda_env_modeler-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ce6080a2ffcd3e2688400a17efdd2d0b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.9.0",
"size": 7047,
"upload_time": "2024-11-14T17:42:30",
"upload_time_iso_8601": "2024-11-14T17:42:30.574825Z",
"url": "https://files.pythonhosted.org/packages/48/b2/dfd72b092b243ac4866adca071aa3784d1eae03d1b1ce131cb5ec4d5c389/aws_lambda_env_modeler-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "93846c852fb2440a72e65e2bf798af3e80f7f86055dfacafb8ea57723e0ec7db",
"md5": "93aa2fdeb6c6e1ad7ae66efb742fc45f",
"sha256": "46be66434b79753593c5882e99647ba8b87395867b8f4fcfcfb05bdb02bd6ce0"
},
"downloads": -1,
"filename": "aws_lambda_env_modeler-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "93aa2fdeb6c6e1ad7ae66efb742fc45f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.9.0",
"size": 6099,
"upload_time": "2024-11-14T17:42:32",
"upload_time_iso_8601": "2024-11-14T17:42:32.107508Z",
"url": "https://files.pythonhosted.org/packages/93/84/6c852fb2440a72e65e2bf798af3e80f7f86055dfacafb8ea57723e0ec7db/aws_lambda_env_modeler-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-14 17:42:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ran-isenberg",
"github_project": "aws-lambda-env-modeler",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "aws-lambda-env-modeler"
}
JSON
