Refactor and Document check_env.check()

[bmos]

What is this change?

• Adjust a few nonstandard imports of check directly rather than via importing check_env.
• Add comprehensive documentation to check_env.check().
• Convert optional parameter to keyword-only.
• Rename field parameter to value.
• Improve tests for check_env.check
• Add deprecation handler to avoid optional and field breaking changes.

Considerations for discussion

• Despite being a core function used in many connectors, check_env.check() was minimally documented.
• Allowing users to provide boolean values for positional parameters is not recommended as their intention can be confusing.

How to test the changes (if needed)

• CI tests should be adequate

Breaking Changes

Breaking changes are changes to our public API which may require existing users to change their code. If there are no breaking changes, any existing parsons user should not need to do anything after updating their parsons version.

Does this PR introduce breaking changes?

• label: Breaking change — This PR introduces one or more breaking changes.
• label: Non-breaking change — This PR does not introduce one or more breaking changes.

[ghost]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
parsons/aws
lambda_distribute.py					205
parsons/braintree
braintree.py
parsons/notifications
slack.py					128
parsons/redash
redash.py
parsons/utilities
check_env.py					78-85, 88-95
Project Total

This report was generated by python-coverage-comment-action

[shaunagm]

What are these @overload decorators doing?

[bmos]

Overload is a type hinting feature.
It tells static type checkers that if you provide a certain type as an input you get a certain type as an output.

[shaunagm]

Gotcha. Why are there three of them? It feels more verbose than is ideal (but maybe if we can use a comment to signal to the reader that these are type hints with no impact on the code itself, the verbosity is less of an issue)

[bmos]

That's just how the syntax works, unfortunately.
That's why overload is only used situationally. I think it's worth it here since check is used in a ton of connectors so having accurate typing is extra useful.

[bmos]

Happy to chat through how this works sometime, I just keep being busy on Thursdays 😅
It's a very helpful feature.

[shaunagm]

You've got some other PRs I could review too so yeah let's schedule a call.

[shaunagm]

Where is the opt parameter coming from? I get that it's being listed as deprecated, but I'm not seeing where it's used at all.

[bmos]

optional (the former 3rd positional argument) is now a keyword-only argument. So I added "opt" as the 3rd positional argument with the deprecation warning. That way it's not a breaking change if people try to provide the optional parameter as a positional argument.

[shaunagm]

Gotcha. What's your reasoning on moving it from a 3rd positional argument to a keyword-only argument?

[bmos]

https://docs.astral.sh/ruff/rules/boolean-type-hint-positional-argument/