Add parameters and volatility to Function

[enobayram]

Resolves #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]

honestly this looks really good! I left a couple of comments that I'd consider optional, so lmk if you plan to address them or not and i'll either await the update or merge as-is

[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]

Codecov Report

Attention: Patch coverage is 82.24852% with 30 lines in your changes missing coverage. Please review.

Project coverage is 89.43%. Comparing base (b7c0d8c) to head (3a148aa).

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #104      +/-   ##
==========================================
- Coverage   89.78%   89.43%   -0.36%     
==========================================
  Files          86       86              
  Lines        3867     4031     +164     
  Branches      783      836      +53     
==========================================
+ Hits         3472     3605     +133     
- Misses        322      343      +21     
- Partials       73       83      +10     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ 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.

[Dan-Knott]

There is an issue with the ordering of the arg_types. You can test this by changing the return type of one of the columns:

        Function(
            "generate_series_squared",
            """
            SELECT i::float, i*i
            FROM generate_series(1, _limit) as i;
            """,
            language="sql",
            parameters=[FunctionParam("_limit", "integer", default=1)],
            returns=FunctionReturn(table=["num float", "num_squared integer"]),
            volatility=FunctionVolatility.IMMUTABLE,
        ),

[DanCardin]

needed to order the aggregate by the ordinality, mb

[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.