CONTRIBUTING.md

Latest commit

History

History
188 lines (139 loc) · 15.1 KB

CONTRIBUTING.md

File metadata and controls

188 lines (139 loc) · 15.1 KB
Raw

Table of contents

Contributing Guidelines

Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

We encourage contributions from the community and we will work with contributors to merge their pull requests. Rarely, we may close pull requests that do not meet our guidelines specified in CONTRIBUTING.md, or will require unreasonable effort to meet our quality bar.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

Reporting Bugs/Feature Requests

We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements.

When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can.

Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

  1. You are working against the latest source on the develop branch.
  2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated.

timeline
title Code integration journey (CI)
Project setup <br> (make dev) : Code checkout
: Virtual environment
: Dependencies
: Git pre-commit hooks
: Local branch
: Local changes
: Local tests
Pre-commit checks <br> (git commit) : Merge conflict check
: Trailing whitespaces
: TOML checks
: Code linting (standards)
: Markdown linting
: CloudFormation linting
: GitHub Actions linting
: Terraform linting
: Secrets linting
Pre-Pull Request <br> (make pr) : Code linting
: Docs linting
: Static typing analysis
: Tests (unit|functional|perf|dependencies)
: Security baseline
: Complexity baseline
: +pre-commit checks
Pull Request <br> (CI checks) : Semantic PR title check
: Related issue check
: Acknowledgment check
: Code coverage diff
: Contribution size check
: Contribution category check
: Dependency vulnerability check
: GitHub Actions security check
: +pre-pull request checks
After merge <br> (CI checks) : End-to-end tests
: Longer SAST check
: Security posture check (scorecard)
: GitHub Actions security check
: Rebuild Changelog
: Deploy staging docs
: Update draft release
Loading

Dev setup

Gitpod Ready-to-Code

Firstly, fork the repository.

To setup your development environment, we recommend using our pre-configured Cloud environment: https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-python. Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly.

Alternatively, you can use make dev within your local virtual environment.

To send us a pull request, please follow these steps:

  1. Create a new branch to focus on the specific change you are contributing e.g. improv/logger-debug-sampling
  2. Run all tests, and code baseline checks: make pr
    • Git hooks will run linting and formatting while make pr run deep checks that also run in the CI process
  3. Commit to your fork using clear commit messages.
  4. Send us a pull request with a conventional semantic title, and answering any default questions in the pull request interface.
  5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional document on forking a repository and creating a pull request.

Local documentation

You might find useful to run both the documentation website and the API reference locally while contributing:

  • API reference: make docs-api-local
  • Docs website: make docs-local
    • If you prefer using Docker: make docs-local-docker

Conventions

General terminology and practices

CategoryConvention
DocstringWe use a slight variation of Numpy convention with markdown to help generate more readable API references.
Style guideWe use black as well as Ruff to enforce beyond good practices PEP8. We use type annotations and enforce static type checking at CI (mypy).
Core utilitiesCore utilities use a Class, always accept service as a constructor parameter, can work in isolation, and are also available in other languages implementation.
UtilitiesUtilities are not as strict as core and focus on solving a developer experience problem while following the project Tenets.
ExceptionsSpecific exceptions live within utilities themselves and use Error suffix e.g. MetricUnitError.
Git commitsWe follow conventional commits. We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly.
API documentationAPI reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise.
DocumentationWe treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features.

Testing definition

We group tests in different categories

TestWhen to writeNotesSpeed
Unit testsVerify the smallest possible unit works.Networking access is prohibited. Prefer Functional tests given our complexity.Lightning fast (nsec to ms)
Functional testsGuarantee functionality works as expected. It's a subset of integration test covering multiple units.No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs.Fast (ms to few seconds at worst)
Integration testsGain confidence that code works with one or more external dependencies.No need for a Lambda function. Use our code base against an external dependency e.g., fetch an existing SSM parameter.Moderate to slow (a few minutes)
End-to-end testsGain confidence that a Lambda function with our code operates as expected.It simulates how customers configure, deploy, and run their Lambda function - Event Source configuration, IAM permissions, etc.Slow (minutes)
Performance testsEnsure critical operations won't increase latency and costs to customers.CI arbitrary hardware can make it flaky. We'll resume writing perf test after our new Integ/End have significant coverage.Fast to moderate (a few seconds to a few minutes)

NOTE: Functional tests are mandatory. We have plans to create a guide on how to create these different tests. Maintainers will help indicate whether additional tests are necessary and provide assistance as required.

Finding contributions to work on

Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), looking at any 'help wanted' issues is a great place to start.

Code of Conduct

This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opensource-codeofconduct@amazon.com with any additional questions or comments.

Security issue notifications

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.

Troubleshooting

API reference documentation

When you are working on the codebase and you use the local API reference documentation to preview your changes, you might see the following message: Module aws_lambda_powertools not found.

This happens when:

  • You did not install the local dev environment yet
    • You can install dev deps with make dev command
  • The code in the repository is raising an exception while the pdoc is scanning the codebase
    • Unfortunately, this exception is not shown to you, but if you run, poetry run pdoc --pdf aws_lambda_powertools, the exception is shown and you can prevent the exception from being raised
    • Once resolved the documentation should load correctly again

Licensing

See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.

We may ask you to sign a Contributor License Agreement (CLA) for larger changes.

, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
CONTRIBUTING.md
Latest commit
History
History
188 lines (139 loc) · 15.1 KB
CONTRIBUTING.md
File metadata and controls
188 lines (139 loc) · 15.1 KB
Raw
Table of contents 
Contributing Guidelines
Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
We encourage contributions from the community and we will work with contributors to merge their pull requests.
Rarely, we may close pull requests that do not meet our guidelines specified in CONTRIBUTING.md, or will require unreasonable effort to meet our quality bar.
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
information to effectively respond to your bug report or contribution.
Reporting Bugs/Feature Requests
We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements.
When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can.
Contributing via Pull Requests
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
  1. You are working against the latest source on the develop branch.
  2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.
At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated.
timeline
title Code integration journey (CI)
Project setup <br> (make dev) : Code checkout
: Virtual environment
: Dependencies
: Git pre-commit hooks
: Local branch
: Local changes
: Local tests
Pre-commit checks <br> (git commit) : Merge conflict check
: Trailing whitespaces
: TOML checks
: Code linting (standards)
: Markdown linting
: CloudFormation linting
: GitHub Actions linting
: Terraform linting
: Secrets linting
Pre-Pull Request <br> (make pr) : Code linting
: Docs linting
: Static typing analysis
: Tests (unit|functional|perf|dependencies)
: Security baseline
: Complexity baseline
: +pre-commit checks
Pull Request <br> (CI checks) : Semantic PR title check
: Related issue check
: Acknowledgment check
: Code coverage diff
: Contribution size check
: Contribution category check
: Dependency vulnerability check
: GitHub Actions security check
: +pre-pull request checks
After merge <br> (CI checks) : End-to-end tests
: Longer SAST check
: Security posture check (scorecard)
: GitHub Actions security check
: Rebuild Changelog
: Deploy staging docs
: Update draft release

Loading
Dev setup
Gitpod Ready-to-Code
Firstly, fork the repository.
To setup your development environment, we recommend using our pre-configured Cloud environment: https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-python. Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly.
Alternatively, you can use make dev within your local virtual environment.
To send us a pull request, please follow these steps:
  1. Create a new branch to focus on the specific change you are contributing e.g. improv/logger-debug-sampling
  2. Run all tests, and code baseline checks: make pr
    • Git hooks will run linting and formatting while make pr run deep checks that also run in the CI process
  3. Commit to your fork using clear commit messages.
  4. Send us a pull request with a conventional semantic title, and answering any default questions in the pull request interface.
  5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
GitHub provides additional document on forking a repository and
creating a pull request.
Local documentation
You might find useful to run both the documentation website and the API reference locally while contributing:
  • API reference: make docs-api-local
  • Docs website: make docs-local
    • If you prefer using Docker: make docs-local-docker
Conventions
General terminology and practices
CategoryConvention
DocstringWe use a slight variation of Numpy convention with markdown to help generate more readable API references.
Style guideWe use black as well as Ruff to enforce beyond good practices PEP8. We use type annotations and enforce static type checking at CI (mypy).
Core utilitiesCore utilities use a Class, always accept service as a constructor parameter, can work in isolation, and are also available in other languages implementation.
UtilitiesUtilities are not as strict as core and focus on solving a developer experience problem while following the project Tenets.
ExceptionsSpecific exceptions live within utilities themselves and use Error suffix e.g. MetricUnitError.
Git commitsWe follow conventional commits. We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly.
API documentationAPI reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise.
DocumentationWe treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features.
Testing definition
We group tests in different categories
TestWhen to writeNotesSpeed
Unit testsVerify the smallest possible unit works.Networking access is prohibited. Prefer Functional tests given our complexity.Lightning fast (nsec to ms)
Functional testsGuarantee functionality works as expected. It's a subset of integration test covering multiple units.No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs.Fast (ms to few seconds at worst)
Integration testsGain confidence that code works with one or more external dependencies.No need for a Lambda function. Use our code base against an external dependency e.g., fetch an existing SSM parameter.Moderate to slow (a few minutes)
End-to-end testsGain confidence that a Lambda function with our code operates as expected.It simulates how customers configure, deploy, and run their Lambda function - Event Source configuration, IAM permissions, etc.Slow (minutes)
Performance testsEnsure critical operations won't increase latency and costs to customers.CI arbitrary hardware can make it flaky. We'll resume writing perf test after our new Integ/End have significant coverage.Fast to moderate (a few seconds to a few minutes)
NOTE: Functional tests are mandatory. We have plans to create a guide on how to create these different tests. Maintainers will help indicate whether additional tests are necessary and provide assistance as required.
Finding contributions to work on
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), looking at any 'help wanted' issues is a great place to start.
Code of Conduct
This project has adopted the Amazon Open Source Code of Conduct.
For more information see the Code of Conduct FAQ or contact
opensource-codeofconduct@amazon.com with any additional questions or comments.
Security issue notifications
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.
Troubleshooting
API reference documentation
When you are working on the codebase and you use the local API reference documentation to preview your changes, you might see the following message: Module aws_lambda_powertools not found.
This happens when:
  • You did not install the local dev environment yet

    • You can install dev deps with make dev command
  • The code in the repository is raising an exception while the pdoc is scanning the codebase

    • Unfortunately, this exception is not shown to you, but if you run, poetry run pdoc --pdf aws_lambda_powertools, the exception is shown and you can prevent the exception from being raised
    • Once resolved the documentation should load correctly again
Licensing
See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.
We may ask you to sign a Contributor License Agreement (CLA) for larger changes.

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
CONTRIBUTING.md
Latest commit
History
History
188 lines (139 loc) · 15.1 KB
CONTRIBUTING.md
File metadata and controls
188 lines (139 loc) · 15.1 KB
Raw
Table of contents 
Contributing Guidelines
Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
We encourage contributions from the community and we will work with contributors to merge their pull requests.
Rarely, we may close pull requests that do not meet our guidelines specified in CONTRIBUTING.md, or will require unreasonable effort to meet our quality bar.
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
information to effectively respond to your bug report or contribution.
Reporting Bugs/Feature Requests
We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements.
When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can.
Contributing via Pull Requests
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
  1. You are working against the latest source on the develop branch.
  2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.
At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated.
timeline
title Code integration journey (CI)
Project setup <br> (make dev) : Code checkout
: Virtual environment
: Dependencies
: Git pre-commit hooks
: Local branch
: Local changes
: Local tests
Pre-commit checks <br> (git commit) : Merge conflict check
: Trailing whitespaces
: TOML checks
: Code linting (standards)
: Markdown linting
: CloudFormation linting
: GitHub Actions linting
: Terraform linting
: Secrets linting
Pre-Pull Request <br> (make pr) : Code linting
: Docs linting
: Static typing analysis
: Tests (unit|functional|perf|dependencies)
: Security baseline
: Complexity baseline
: +pre-commit checks
Pull Request <br> (CI checks) : Semantic PR title check
: Related issue check
: Acknowledgment check
: Code coverage diff
: Contribution size check
: Contribution category check
: Dependency vulnerability check
: GitHub Actions security check
: +pre-pull request checks
After merge <br> (CI checks) : End-to-end tests
: Longer SAST check
: Security posture check (scorecard)
: GitHub Actions security check
: Rebuild Changelog
: Deploy staging docs
: Update draft release

Loading
Dev setup
Gitpod Ready-to-Code
Firstly, fork the repository.
To setup your development environment, we recommend using our pre-configured Cloud environment: https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-python. Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly.
Alternatively, you can use make dev within your local virtual environment.
To send us a pull request, please follow these steps:
  1. Create a new branch to focus on the specific change you are contributing e.g. improv/logger-debug-sampling
  2. Run all tests, and code baseline checks: make pr
    • Git hooks will run linting and formatting while make pr run deep checks that also run in the CI process
  3. Commit to your fork using clear commit messages.
  4. Send us a pull request with a conventional semantic title, and answering any default questions in the pull request interface.
  5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
GitHub provides additional document on forking a repository and
creating a pull request.
Local documentation
You might find useful to run both the documentation website and the API reference locally while contributing:
  • API reference: make docs-api-local
  • Docs website: make docs-local
    • If you prefer using Docker: make docs-local-docker
Conventions
General terminology and practices
CategoryConvention
DocstringWe use a slight variation of Numpy convention with markdown to help generate more readable API references.
Style guideWe use black as well as Ruff to enforce beyond good practices PEP8. We use type annotations and enforce static type checking at CI (mypy).
Core utilitiesCore utilities use a Class, always accept service as a constructor parameter, can work in isolation, and are also available in other languages implementation.
UtilitiesUtilities are not as strict as core and focus on solving a developer experience problem while following the project Tenets.
ExceptionsSpecific exceptions live within utilities themselves and use Error suffix e.g. MetricUnitError.
Git commitsWe follow conventional commits. We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly.
API documentationAPI reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise.
DocumentationWe treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features.
Testing definition
We group tests in different categories
TestWhen to writeNotesSpeed
Unit testsVerify the smallest possible unit works.Networking access is prohibited. Prefer Functional tests given our complexity.Lightning fast (nsec to ms)
Functional testsGuarantee functionality works as expected. It's a subset of integration test covering multiple units.No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs.Fast (ms to few seconds at worst)
Integration testsGain confidence that code works with one or more external dependencies.No need for a Lambda function. Use our code base against an external dependency e.g., fetch an existing SSM parameter.Moderate to slow (a few minutes)
End-to-end testsGain confidence that a Lambda function with our code operates as expected.It simulates how customers configure, deploy, and run their Lambda function - Event Source configuration, IAM permissions, etc.Slow (minutes)
Performance testsEnsure critical operations won't increase latency and costs to customers.CI arbitrary hardware can make it flaky. We'll resume writing perf test after our new Integ/End have significant coverage.Fast to moderate (a few seconds to a few minutes)
NOTE: Functional tests are mandatory. We have plans to create a guide on how to create these different tests. Maintainers will help indicate whether additional tests are necessary and provide assistance as required.
Finding contributions to work on
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), looking at any 'help wanted' issues is a great place to start.
Code of Conduct
This project has adopted the Amazon Open Source Code of Conduct.
For more information see the Code of Conduct FAQ or contact
opensource-codeofconduct@amazon.com with any additional questions or comments.
Security issue notifications
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.
Troubleshooting
API reference documentation
When you are working on the codebase and you use the local API reference documentation to preview your changes, you might see the following message: Module aws_lambda_powertools not found.
This happens when:
  • You did not install the local dev environment yet

    • You can install dev deps with make dev command
  • The code in the repository is raising an exception while the pdoc is scanning the codebase

    • Unfortunately, this exception is not shown to you, but if you run, poetry run pdoc --pdf aws_lambda_powertools, the exception is shown and you can prevent the exception from being raised
    • Once resolved the documentation should load correctly again
Licensing
See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.
We may ask you to sign a Contributor License Agreement (CLA) for larger changes.

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
CONTRIBUTING.md
Latest commit
History
History
188 lines (139 loc) · 15.1 KB
CONTRIBUTING.md
File metadata and controls
188 lines (139 loc) · 15.1 KB
Raw
Table of contents 
Contributing Guidelines
Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
We encourage contributions from the community and we will work with contributors to merge their pull requests.
Rarely, we may close pull requests that do not meet our guidelines specified in CONTRIBUTING.md, or will require unreasonable effort to meet our quality bar.
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
information to effectively respond to your bug report or contribution.
Reporting Bugs/Feature Requests
We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements.
When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can.
Contributing via Pull Requests
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
  1. You are working against the latest source on the develop branch.
  2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.
At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated.
timeline
title Code integration journey (CI)
Project setup <br> (make dev) : Code checkout
: Virtual environment
: Dependencies
: Git pre-commit hooks
: Local branch
: Local changes
: Local tests
Pre-commit checks <br> (git commit) : Merge conflict check
: Trailing whitespaces
: TOML checks
: Code linting (standards)
: Markdown linting
: CloudFormation linting
: GitHub Actions linting
: Terraform linting
: Secrets linting
Pre-Pull Request <br> (make pr) : Code linting
: Docs linting
: Static typing analysis
: Tests (unit|functional|perf|dependencies)
: Security baseline
: Complexity baseline
: +pre-commit checks
Pull Request <br> (CI checks) : Semantic PR title check
: Related issue check
: Acknowledgment check
: Code coverage diff
: Contribution size check
: Contribution category check
: Dependency vulnerability check
: GitHub Actions security check
: +pre-pull request checks
After merge <br> (CI checks) : End-to-end tests
: Longer SAST check
: Security posture check (scorecard)
: GitHub Actions security check
: Rebuild Changelog
: Deploy staging docs
: Update draft release

Loading
Dev setup
Gitpod Ready-to-Code
Firstly, fork the repository.
To setup your development environment, we recommend using our pre-configured Cloud environment: https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-python. Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly.
Alternatively, you can use make dev within your local virtual environment.
To send us a pull request, please follow these steps:
  1. Create a new branch to focus on the specific change you are contributing e.g. improv/logger-debug-sampling
  2. Run all tests, and code baseline checks: make pr
    • Git hooks will run linting and formatting while make pr run deep checks that also run in the CI process
  3. Commit to your fork using clear commit messages.
  4. Send us a pull request with a conventional semantic title, and answering any default questions in the pull request interface.
  5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
GitHub provides additional document on forking a repository and
creating a pull request.
Local documentation
You might find useful to run both the documentation website and the API reference locally while contributing:
  • API reference: make docs-api-local
  • Docs website: make docs-local
    • If you prefer using Docker: make docs-local-docker
Conventions
General terminology and practices
CategoryConvention
DocstringWe use a slight variation of Numpy convention with markdown to help generate more readable API references.
Style guideWe use black as well as Ruff to enforce beyond good practices PEP8. We use type annotations and enforce static type checking at CI (mypy).
Core utilitiesCore utilities use a Class, always accept service as a constructor parameter, can work in isolation, and are also available in other languages implementation.
UtilitiesUtilities are not as strict as core and focus on solving a developer experience problem while following the project Tenets.
ExceptionsSpecific exceptions live within utilities themselves and use Error suffix e.g. MetricUnitError.
Git commitsWe follow conventional commits. We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly.
API documentationAPI reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise.
DocumentationWe treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features.
Testing definition
We group tests in different categories
TestWhen to writeNotesSpeed
Unit testsVerify the smallest possible unit works.Networking access is prohibited. Prefer Functional tests given our complexity.Lightning fast (nsec to ms)
Functional testsGuarantee functionality works as expected. It's a subset of integration test covering multiple units.No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs.Fast (ms to few seconds at worst)
Integration testsGain confidence that code works with one or more external dependencies.No need for a Lambda function. Use our code base against an external dependency e.g., fetch an existing SSM parameter.Moderate to slow (a few minutes)
End-to-end testsGain confidence that a Lambda function with our code operates as expected.It simulates how customers configure, deploy, and run their Lambda function - Event Source configuration, IAM permissions, etc.Slow (minutes)
Performance testsEnsure critical operations won't increase latency and costs to customers.CI arbitrary hardware can make it flaky. We'll resume writing perf test after our new Integ/End have significant coverage.Fast to moderate (a few seconds to a few minutes)
NOTE: Functional tests are mandatory. We have plans to create a guide on how to create these different tests. Maintainers will help indicate whether additional tests are necessary and provide assistance as required.
Finding contributions to work on
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), looking at any 'help wanted' issues is a great place to start.
Code of Conduct
This project has adopted the Amazon Open Source Code of Conduct.
For more information see the Code of Conduct FAQ or contact
opensource-codeofconduct@amazon.com with any additional questions or comments.
Security issue notifications
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.
Troubleshooting
API reference documentation
When you are working on the codebase and you use the local API reference documentation to preview your changes, you might see the following message: Module aws_lambda_powertools not found.
This happens when:
  • You did not install the local dev environment yet

    • You can install dev deps with make dev command
  • The code in the repository is raising an exception while the pdoc is scanning the codebase

    • Unfortunately, this exception is not shown to you, but if you run, poetry run pdoc --pdf aws_lambda_powertools, the exception is shown and you can prevent the exception from being raised
    • Once resolved the documentation should load correctly again
Licensing
See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.
We may ask you to sign a Contributor License Agreement (CLA) for larger changes.

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
CONTRIBUTING.md
Latest commit
History
History
188 lines (139 loc) · 15.1 KB
CONTRIBUTING.md
File metadata and controls
188 lines (139 loc) · 15.1 KB
Raw
Table of contents 
Contributing Guidelines
Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
We encourage contributions from the community and we will work with contributors to merge their pull requests.
Rarely, we may close pull requests that do not meet our guidelines specified in CONTRIBUTING.md, or will require unreasonable effort to meet our quality bar.
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
information to effectively respond to your bug report or contribution.
Reporting Bugs/Feature Requests
We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements.
When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can.
Contributing via Pull Requests
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
  1. You are working against the latest source on the develop branch.
  2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.
At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated.
timeline
title Code integration journey (CI)
Project setup <br> (make dev) : Code checkout
: Virtual environment
: Dependencies
: Git pre-commit hooks
: Local branch
: Local changes
: Local tests
Pre-commit checks <br> (git commit) : Merge conflict check
: Trailing whitespaces
: TOML checks
: Code linting (standards)
: Markdown linting
: CloudFormation linting
: GitHub Actions linting
: Terraform linting
: Secrets linting
Pre-Pull Request <br> (make pr) : Code linting
: Docs linting
: Static typing analysis
: Tests (unit|functional|perf|dependencies)
: Security baseline
: Complexity baseline
: +pre-commit checks
Pull Request <br> (CI checks) : Semantic PR title check
: Related issue check
: Acknowledgment check
: Code coverage diff
: Contribution size check
: Contribution category check
: Dependency vulnerability check
: GitHub Actions security check
: +pre-pull request checks
After merge <br> (CI checks) : End-to-end tests
: Longer SAST check
: Security posture check (scorecard)
: GitHub Actions security check
: Rebuild Changelog
: Deploy staging docs
: Update draft release

Loading
Dev setup
Gitpod Ready-to-Code
Firstly, fork the repository.
To setup your development environment, we recommend using our pre-configured Cloud environment: https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-python. Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly.
Alternatively, you can use make dev within your local virtual environment.
To send us a pull request, please follow these steps:
  1. Create a new branch to focus on the specific change you are contributing e.g. improv/logger-debug-sampling
  2. Run all tests, and code baseline checks: make pr
    • Git hooks will run linting and formatting while make pr run deep checks that also run in the CI process
  3. Commit to your fork using clear commit messages.
  4. Send us a pull request with a conventional semantic title, and answering any default questions in the pull request interface.
  5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
GitHub provides additional document on forking a repository and
creating a pull request.
Local documentation
You might find useful to run both the documentation website and the API reference locally while contributing:
  • API reference: make docs-api-local
  • Docs website: make docs-local
    • If you prefer using Docker: make docs-local-docker
Conventions
General terminology and practices
CategoryConvention
DocstringWe use a slight variation of Numpy convention with markdown to help generate more readable API references.
Style guideWe use black as well as Ruff to enforce beyond good practices PEP8. We use type annotations and enforce static type checking at CI (mypy).
Core utilitiesCore utilities use a Class, always accept service as a constructor parameter, can work in isolation, and are also available in other languages implementation.
UtilitiesUtilities are not as strict as core and focus on solving a developer experience problem while following the project Tenets.
ExceptionsSpecific exceptions live within utilities themselves and use Error suffix e.g. MetricUnitError.
Git commitsWe follow conventional commits. We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly.
API documentationAPI reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise.
DocumentationWe treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features.
Testing definition
We group tests in different categories
TestWhen to writeNotesSpeed
Unit testsVerify the smallest possible unit works.Networking access is prohibited. Prefer Functional tests given our complexity.Lightning fast (nsec to ms)
Functional testsGuarantee functionality works as expected. It's a subset of integration test covering multiple units.No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs.Fast (ms to few seconds at worst)
Integration testsGain confidence that code works with one or more external dependencies.No need for a Lambda function. Use our code base against an external dependency e.g., fetch an existing SSM parameter.Moderate to slow (a few minutes)
End-to-end testsGain confidence that a Lambda function with our code operates as expected.It simulates how customers configure, deploy, and run their Lambda function - Event Source configuration, IAM permissions, etc.Slow (minutes)
Performance testsEnsure critical operations won't increase latency and costs to customers.CI arbitrary hardware can make it flaky. We'll resume writing perf test after our new Integ/End have significant coverage.Fast to moderate (a few seconds to a few minutes)
NOTE: Functional tests are mandatory. We have plans to create a guide on how to create these different tests. Maintainers will help indicate whether additional tests are necessary and provide assistance as required.
Finding contributions to work on
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), looking at any 'help wanted' issues is a great place to start.
Code of Conduct
This project has adopted the Amazon Open Source Code of Conduct.
For more information see the Code of Conduct FAQ or contact
opensource-codeofconduct@amazon.com with any additional questions or comments.
Security issue notifications
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.
Troubleshooting
API reference documentation
When you are working on the codebase and you use the local API reference documentation to preview your changes, you might see the following message: Module aws_lambda_powertools not found.
This happens when:
  • You did not install the local dev environment yet

    • You can install dev deps with make dev command
  • The code in the repository is raising an exception while the pdoc is scanning the codebase

    • Unfortunately, this exception is not shown to you, but if you run, poetry run pdoc --pdf aws_lambda_powertools, the exception is shown and you can prevent the exception from being raised
    • Once resolved the documentation should load correctly again
Licensing
See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.
We may ask you to sign a Contributor License Agreement (CLA) for larger changes.

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
CONTRIBUTING.md
Latest commit
History
History
188 lines (139 loc) · 15.1 KB
CONTRIBUTING.md
File metadata and controls
188 lines (139 loc) · 15.1 KB
Raw
Table of contents 
Contributing Guidelines
Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
We encourage contributions from the community and we will work with contributors to merge their pull requests.
Rarely, we may close pull requests that do not meet our guidelines specified in CONTRIBUTING.md, or will require unreasonable effort to meet our quality bar.
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
information to effectively respond to your bug report or contribution.
Reporting Bugs/Feature Requests
We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements.
When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can.
Contributing via Pull Requests
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
  1. You are working against the latest source on the develop branch.
  2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.
At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated.
timeline
title Code integration journey (CI)
Project setup <br> (make dev) : Code checkout
: Virtual environment
: Dependencies
: Git pre-commit hooks
: Local branch
: Local changes
: Local tests
Pre-commit checks <br> (git commit) : Merge conflict check
: Trailing whitespaces
: TOML checks
: Code linting (standards)
: Markdown linting
: CloudFormation linting
: GitHub Actions linting
: Terraform linting
: Secrets linting
Pre-Pull Request <br> (make pr) : Code linting
: Docs linting
: Static typing analysis
: Tests (unit|functional|perf|dependencies)
: Security baseline
: Complexity baseline
: +pre-commit checks
Pull Request <br> (CI checks) : Semantic PR title check
: Related issue check
: Acknowledgment check
: Code coverage diff
: Contribution size check
: Contribution category check
: Dependency vulnerability check
: GitHub Actions security check
: +pre-pull request checks
After merge <br> (CI checks) : End-to-end tests
: Longer SAST check
: Security posture check (scorecard)
: GitHub Actions security check
: Rebuild Changelog
: Deploy staging docs
: Update draft release

Loading
Dev setup
Gitpod Ready-to-Code
Firstly, fork the repository.
To setup your development environment, we recommend using our pre-configured Cloud environment: https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-python. Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly.
Alternatively, you can use make dev within your local virtual environment.
To send us a pull request, please follow these steps:
  1. Create a new branch to focus on the specific change you are contributing e.g. improv/logger-debug-sampling
  2. Run all tests, and code baseline checks: make pr
    • Git hooks will run linting and formatting while make pr run deep checks that also run in the CI process
  3. Commit to your fork using clear commit messages.
  4. Send us a pull request with a conventional semantic title, and answering any default questions in the pull request interface.
  5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
GitHub provides additional document on forking a repository and
creating a pull request.
Local documentation
You might find useful to run both the documentation website and the API reference locally while contributing:
  • API reference: make docs-api-local
  • Docs website: make docs-local
    • If you prefer using Docker: make docs-local-docker
Conventions
General terminology and practices
CategoryConvention
DocstringWe use a slight variation of Numpy convention with markdown to help generate more readable API references.
Style guideWe use black as well as Ruff to enforce beyond good practices PEP8. We use type annotations and enforce static type checking at CI (mypy).
Core utilitiesCore utilities use a Class, always accept service as a constructor parameter, can work in isolation, and are also available in other languages implementation.
UtilitiesUtilities are not as strict as core and focus on solving a developer experience problem while following the project Tenets.
ExceptionsSpecific exceptions live within utilities themselves and use Error suffix e.g. MetricUnitError.
Git commitsWe follow conventional commits. We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly.
API documentationAPI reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise.
DocumentationWe treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features.
Testing definition
We group tests in different categories
TestWhen to writeNotesSpeed
Unit testsVerify the smallest possible unit works.Networking access is prohibited. Prefer Functional tests given our complexity.Lightning fast (nsec to ms)
Functional testsGuarantee functionality works as expected. It's a subset of integration test covering multiple units.No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs.Fast (ms to few seconds at worst)
Integration testsGain confidence that code works with one or more external dependencies.No need for a Lambda function. Use our code base against an external dependency e.g., fetch an existing SSM parameter.Moderate to slow (a few minutes)
End-to-end testsGain confidence that a Lambda function with our code operates as expected.It simulates how customers configure, deploy, and run their Lambda function - Event Source configuration, IAM permissions, etc.Slow (minutes)
Performance testsEnsure critical operations won't increase latency and costs to customers.CI arbitrary hardware can make it flaky. We'll resume writing perf test after our new Integ/End have significant coverage.Fast to moderate (a few seconds to a few minutes)
NOTE: Functional tests are mandatory. We have plans to create a guide on how to create these different tests. Maintainers will help indicate whether additional tests are necessary and provide assistance as required.
Finding contributions to work on
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), looking at any 'help wanted' issues is a great place to start.
Code of Conduct
This project has adopted the Amazon Open Source Code of Conduct.
For more information see the Code of Conduct FAQ or contact
opensource-codeofconduct@amazon.com with any additional questions or comments.
Security issue notifications
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.
Troubleshooting
API reference documentation
When you are working on the codebase and you use the local API reference documentation to preview your changes, you might see the following message: Module aws_lambda_powertools not found.
This happens when:
  • You did not install the local dev environment yet

    • You can install dev deps with make dev command
  • The code in the repository is raising an exception while the pdoc is scanning the codebase

    • Unfortunately, this exception is not shown to you, but if you run, poetry run pdoc --pdf aws_lambda_powertools, the exception is shown and you can prevent the exception from being raised
    • Once resolved the documentation should load correctly again
Licensing
See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.
We may ask you to sign a Contributor License Agreement (CLA) for larger changes.

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
CONTRIBUTING.md
Latest commit
History
History
188 lines (139 loc) · 15.1 KB
CONTRIBUTING.md
File metadata and controls
188 lines (139 loc) · 15.1 KB
Raw
Table of contents 
Contributing Guidelines
Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
We encourage contributions from the community and we will work with contributors to merge their pull requests.
Rarely, we may close pull requests that do not meet our guidelines specified in CONTRIBUTING.md, or will require unreasonable effort to meet our quality bar.
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
information to effectively respond to your bug report or contribution.
Reporting Bugs/Feature Requests
We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements.
When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can.
Contributing via Pull Requests
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
  1. You are working against the latest source on the develop branch.
  2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.
At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated.
timeline
title Code integration journey (CI)
Project setup <br> (make dev) : Code checkout
: Virtual environment
: Dependencies
: Git pre-commit hooks
: Local branch
: Local changes
: Local tests
Pre-commit checks <br> (git commit) : Merge conflict check
: Trailing whitespaces
: TOML checks
: Code linting (standards)
: Markdown linting
: CloudFormation linting
: GitHub Actions linting
: Terraform linting
: Secrets linting
Pre-Pull Request <br> (make pr) : Code linting
: Docs linting
: Static typing analysis
: Tests (unit|functional|perf|dependencies)
: Security baseline
: Complexity baseline
: +pre-commit checks
Pull Request <br> (CI checks) : Semantic PR title check
: Related issue check
: Acknowledgment check
: Code coverage diff
: Contribution size check
: Contribution category check
: Dependency vulnerability check
: GitHub Actions security check
: +pre-pull request checks
After merge <br> (CI checks) : End-to-end tests
: Longer SAST check
: Security posture check (scorecard)
: GitHub Actions security check
: Rebuild Changelog
: Deploy staging docs
: Update draft release

Loading
Dev setup
Gitpod Ready-to-Code
Firstly, fork the repository.
To setup your development environment, we recommend using our pre-configured Cloud environment: https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-python. Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly.
Alternatively, you can use make dev within your local virtual environment.
To send us a pull request, please follow these steps:
  1. Create a new branch to focus on the specific change you are contributing e.g. improv/logger-debug-sampling
  2. Run all tests, and code baseline checks: make pr
    • Git hooks will run linting and formatting while make pr run deep checks that also run in the CI process
  3. Commit to your fork using clear commit messages.
  4. Send us a pull request with a conventional semantic title, and answering any default questions in the pull request interface.
  5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
GitHub provides additional document on forking a repository and
creating a pull request.
Local documentation
You might find useful to run both the documentation website and the API reference locally while contributing:
  • API reference: make docs-api-local
  • Docs website: make docs-local
    • If you prefer using Docker: make docs-local-docker
Conventions
General terminology and practices
CategoryConvention
DocstringWe use a slight variation of Numpy convention with markdown to help generate more readable API references.
Style guideWe use black as well as Ruff to enforce beyond good practices PEP8. We use type annotations and enforce static type checking at CI (mypy).
Core utilitiesCore utilities use a Class, always accept service as a constructor parameter, can work in isolation, and are also available in other languages implementation.
UtilitiesUtilities are not as strict as core and focus on solving a developer experience problem while following the project Tenets.
ExceptionsSpecific exceptions live within utilities themselves and use Error suffix e.g. MetricUnitError.
Git commitsWe follow conventional commits. We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly.
API documentationAPI reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise.
DocumentationWe treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features.
Testing definition
We group tests in different categories
TestWhen to writeNotesSpeed
Unit testsVerify the smallest possible unit works.Networking access is prohibited. Prefer Functional tests given our complexity.Lightning fast (nsec to ms)
Functional testsGuarantee functionality works as expected. It's a subset of integration test covering multiple units.No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs.Fast (ms to few seconds at worst)
Integration testsGain confidence that code works with one or more external dependencies.No need for a Lambda function. Use our code base against an external dependency e.g., fetch an existing SSM parameter.Moderate to slow (a few minutes)
End-to-end testsGain confidence that a Lambda function with our code operates as expected.It simulates how customers configure, deploy, and run their Lambda function - Event Source configuration, IAM permissions, etc.Slow (minutes)
Performance testsEnsure critical operations won't increase latency and costs to customers.CI arbitrary hardware can make it flaky. We'll resume writing perf test after our new Integ/End have significant coverage.Fast to moderate (a few seconds to a few minutes)
NOTE: Functional tests are mandatory. We have plans to create a guide on how to create these different tests. Maintainers will help indicate whether additional tests are necessary and provide assistance as required.
Finding contributions to work on
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), looking at any 'help wanted' issues is a great place to start.
Code of Conduct
This project has adopted the Amazon Open Source Code of Conduct.
For more information see the Code of Conduct FAQ or contact
opensource-codeofconduct@amazon.com with any additional questions or comments.
Security issue notifications
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.
Troubleshooting
API reference documentation
When you are working on the codebase and you use the local API reference documentation to preview your changes, you might see the following message: Module aws_lambda_powertools not found.
This happens when:
  • You did not install the local dev environment yet

    • You can install dev deps with make dev command
  • The code in the repository is raising an exception while the pdoc is scanning the codebase

    • Unfortunately, this exception is not shown to you, but if you run, poetry run pdoc --pdf aws_lambda_powertools, the exception is shown and you can prevent the exception from being raised
    • Once resolved the documentation should load correctly again
Licensing
See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.
We may ask you to sign a Contributor License Agreement (CLA) for larger changes.

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
CONTRIBUTING.md
Latest commit
History
History
188 lines (139 loc) · 15.1 KB
CONTRIBUTING.md
File metadata and controls
188 lines (139 loc) · 15.1 KB
Raw
Table of contents 
Contributing Guidelines
Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
We encourage contributions from the community and we will work with contributors to merge their pull requests.
Rarely, we may close pull requests that do not meet our guidelines specified in CONTRIBUTING.md, or will require unreasonable effort to meet our quality bar.
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
information to effectively respond to your bug report or contribution.
Reporting Bugs/Feature Requests
We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements.
When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can.
Contributing via Pull Requests
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
  1. You are working against the latest source on the develop branch.
  2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.
At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated.
timeline
title Code integration journey (CI)
Project setup <br> (make dev) : Code checkout
: Virtual environment
: Dependencies
: Git pre-commit hooks
: Local branch
: Local changes
: Local tests
Pre-commit checks <br> (git commit) : Merge conflict check
: Trailing whitespaces
: TOML checks
: Code linting (standards)
: Markdown linting
: CloudFormation linting
: GitHub Actions linting
: Terraform linting
: Secrets linting
Pre-Pull Request <br> (make pr) : Code linting
: Docs linting
: Static typing analysis
: Tests (unit|functional|perf|dependencies)
: Security baseline
: Complexity baseline
: +pre-commit checks
Pull Request <br> (CI checks) : Semantic PR title check
: Related issue check
: Acknowledgment check
: Code coverage diff
: Contribution size check
: Contribution category check
: Dependency vulnerability check
: GitHub Actions security check
: +pre-pull request checks
After merge <br> (CI checks) : End-to-end tests
: Longer SAST check
: Security posture check (scorecard)
: GitHub Actions security check
: Rebuild Changelog
: Deploy staging docs
: Update draft release

Loading
Dev setup
Gitpod Ready-to-Code
Firstly, fork the repository.
To setup your development environment, we recommend using our pre-configured Cloud environment: https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-python. Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly.
Alternatively, you can use make dev within your local virtual environment.
To send us a pull request, please follow these steps:
  1. Create a new branch to focus on the specific change you are contributing e.g. improv/logger-debug-sampling
  2. Run all tests, and code baseline checks: make pr
    • Git hooks will run linting and formatting while make pr run deep checks that also run in the CI process
  3. Commit to your fork using clear commit messages.
  4. Send us a pull request with a conventional semantic title, and answering any default questions in the pull request interface.
  5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
GitHub provides additional document on forking a repository and
creating a pull request.
Local documentation
You might find useful to run both the documentation website and the API reference locally while contributing:
  • API reference: make docs-api-local
  • Docs website: make docs-local
    • If you prefer using Docker: make docs-local-docker
Conventions
General terminology and practices
CategoryConvention
DocstringWe use a slight variation of Numpy convention with markdown to help generate more readable API references.
Style guideWe use black as well as Ruff to enforce beyond good practices PEP8. We use type annotations and enforce static type checking at CI (mypy).
Core utilitiesCore utilities use a Class, always accept service as a constructor parameter, can work in isolation, and are also available in other languages implementation.
UtilitiesUtilities are not as strict as core and focus on solving a developer experience problem while following the project Tenets.
ExceptionsSpecific exceptions live within utilities themselves and use Error suffix e.g. MetricUnitError.
Git commitsWe follow conventional commits. We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly.
API documentationAPI reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise.
DocumentationWe treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features.
Testing definition
We group tests in different categories
TestWhen to writeNotesSpeed
Unit testsVerify the smallest possible unit works.Networking access is prohibited. Prefer Functional tests given our complexity.Lightning fast (nsec to ms)
Functional testsGuarantee functionality works as expected. It's a subset of integration test covering multiple units.No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs.Fast (ms to few seconds at worst)
Integration testsGain confidence that code works with one or more external dependencies.No need for a Lambda function. Use our code base against an external dependency e.g., fetch an existing SSM parameter.Moderate to slow (a few minutes)
End-to-end testsGain confidence that a Lambda function with our code operates as expected.It simulates how customers configure, deploy, and run their Lambda function - Event Source configuration, IAM permissions, etc.Slow (minutes)
Performance testsEnsure critical operations won't increase latency and costs to customers.CI arbitrary hardware can make it flaky. We'll resume writing perf test after our new Integ/End have significant coverage.Fast to moderate (a few seconds to a few minutes)
NOTE: Functional tests are mandatory. We have plans to create a guide on how to create these different tests. Maintainers will help indicate whether additional tests are necessary and provide assistance as required.
Finding contributions to work on
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), looking at any 'help wanted' issues is a great place to start.
Code of Conduct
This project has adopted the Amazon Open Source Code of Conduct.
For more information see the Code of Conduct FAQ or contact
opensource-codeofconduct@amazon.com with any additional questions or comments.
Security issue notifications
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.
Troubleshooting
API reference documentation
When you are working on the codebase and you use the local API reference documentation to preview your changes, you might see the following message: Module aws_lambda_powertools not found.
This happens when:
  • You did not install the local dev environment yet

    • You can install dev deps with make dev command
  • The code in the repository is raising an exception while the pdoc is scanning the codebase

    • Unfortunately, this exception is not shown to you, but if you run, poetry run pdoc --pdf aws_lambda_powertools, the exception is shown and you can prevent the exception from being raised
    • Once resolved the documentation should load correctly again
Licensing
See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.
We may ask you to sign a Contributor License Agreement (CLA) for larger changes.