Add parameters and volatility to Function

[enobayram]

Resolves https://github.com/DanCardin/sqlalchemy-declarative-extensions/issues/103

This PR adds support for declaring Functions with parameters for both the MySQL and the PostgreSQL dialects. The PostgreSQL dialect of Functions now also support a new volatility option, which can be one of FunctionVolatility.{VOLATILE,STABLE,IMMUTABLE}.

The PR also adds test cases for a variety of Function definitions that cover the new features.

The PR also updates the ReadTheDocs documentation.

[DanCardin]

~ah, you'll also need to rebase onto main, where i fixed the CI problem.~

JK i just rebased the PR version, but just something to be aware of if/when you develop on top of this.

[enobayram]

@DanCardin Thank you very much for your comments! And also for resolving the issue with the CI. I've made sure that the tests pass locally, let's hope they pass in CI too!

[codecov[bot]]

Codecov Report

:x: Patch coverage is 82.24852% with 30 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 89.73%. Comparing base (262c94b) to head (4d82258). :warning: Report is 17 commits behind head on main.

Files with missing lines	Patch %	Lines
...arative_extensions/dialects/postgresql/function.py	82.22%	15 Missing and 9 partials :warning:
..._declarative_extensions/dialects/mysql/function.py	88.23%	1 Missing and 1 partial :warning:
...eclarative_extensions/dialects/postgresql/query.py	50.00%	1 Missing and 1 partial :warning:
...sqlalchemy_declarative_extensions/function/base.py	50.00%	2 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #104      +/-   ##
==========================================
- Coverage   90.09%   89.73%   -0.37%     
==========================================
  Files          86       86              
  Lines        3878     4042     +164     
  Branches      785      838      +53     
==========================================
+ Hits         3494     3627     +133     
- Misses        316      337      +21     
- Partials       68       78      +10     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[M4rt1nCh]

Hey guys. Happy to see this MR in the pipeline. For a current project, we are currently missing exactly that function to pass arguments to a function. Any plans on your side to fix the ci and release that?

Thanks a lot in advance

[DanCardin]

i think this is still fairly untested, particularly the different kinds of input types.

but i prototyped pulling the individual argument components into a FunctionParam construct, rather than attempting to implement a full fledged parser and it at least appears to pass the existing tests.

What this does is limit the complexity of any string parsing to a maximum complexity bound from the user input side beyond which the user is just forced to supply the argument in terms of the abstraction. But for retrieving a given definition from postgres itself, it should always be avoiding any fancy parsing.

What i'm less clear about is how input/output parameters work. Seems like RETURNS TABLE(foo int, bar int) is actually represented as more arguments of type t, and i managed to get that working.

but variadic/inout/out arguments are all things i haven't personally investigated the use of thus far, and have no idea whether those work.

[DanCardin]

Odds any interested parties want to test out the PR in its current state?

It does currently 'regress' relative to the original suggestion allowing returns='table(a int)', requiring a more strict returns=FunctionReturn(table=['a int']) or parameters=[..., FunctionParam.table('a', 'int')]. Not that it couldn't have a parser for that simple case, i just lost it in the refactors and it didn't seem critical path enough to add back.