Add parameters and volatility to Function

docs/source/functions.md

@@ -2,7 +2,11 @@
 
 ```python
 from sqlalchemy.orm import declarative_base
-from sqlalchemy_declarative_extensions import declarative_database, Function, Functions
+from sqlalchemy_declarative_extensions import declarative_database, Functions
+
+# Import dialect-specific Function for full feature support
+from sqlalchemy_declarative_extensions.dialects.postgresql import Function
+# from sqlalchemy_declarative_extensions.dialects.mysql import Function
 
 _Base = declarative_base()
 
@@ -22,22 +26,49 @@ class Base(_Base):
             """,
             language="plpgsql",
             returns="trigger",
+        ),
+        Function(
+            "gimme_rows",
+            '''
+            SELECT id, name
+            FROM dem_rowz
+            WHERE group_id = _group_id;
+            ''',
+            language="sql",
+            parameters=["_group_id int"],
+            returns="TABLE(id int, name text)",
+            volatility='stable', # PostgreSQL specific characteristic
         )
+
+        # Example MySQL function
+        # Function(
+        #    "gimme_concat",
+        #    "RETURN CONCAT(label, ': ', CAST(val AS CHAR));",
+        #    parameters=["val INT", "label VARCHAR(50)"],
+        #    returns="VARCHAR(100)",
+        #    deterministic=True, # MySQL specific
+        #    data_access='NO SQL', # MySQL specific
+        #    security='INVOKER', # MySQL specific
+        # ),
     )
 ```
 
 ```{note}
 Functions options are wildly different across dialects. As such, you should likely always use
-the diaelect-specific `Function` object.
+the dialect-specific `Function` object (e.g., `sqlalchemy_declarative_extensions.dialects.postgresql.Function`
+or `sqlalchemy_declarative_extensions.dialects.mysql.Function`) to access all available features.
+The base `Function` provides only the most common subset of options.
 ```
 
 ```{note}
-Function behavior (for eaxmple...arguments) is not fully implemented at current time,
-although it **should** be functional for the options it does support. Any ability to instantiate
-an object which produces a syntax error should be considered a bug. Additionally, feature requests
-for supporting more function options are welcome!
+Function comparison logic now supports parsing and comparing function parameters (including name and type)
+and various dialect-specific characteristics:
+
+*   **PostgreSQL:** `LANGUAGE`, `VOLATILITY`, `SECURITY`, `RETURNS TABLE(...)` syntax.
+*   **MySQL:** `DETERMINISTIC`, `DATA ACCESS`, `SECURITY`.
 
-In particular, the current function support is heavily oriented around support for defining triggers.
+The comparison logic handles normalization (e.g., mapping `integer` to `int4` in PostgreSQL) to ensure
+accurate idempotency checks during Alembic autogeneration.
 ```
 
 ```{eval-rst}
@@ -52,3 +83,8 @@ any dialect-specific options.
 .. autoapimodule:: sqlalchemy_declarative_extensions.dialects.postgresql.function
    :members: Function, Procedure
 ```
+
+```{eval-rst}
+.. autoapimodule:: sqlalchemy_declarative_extensions.dialects.mysql.function
+   :members: Function
+```

src/sqlalchemy_declarative_extensions/dialects/mysql/function.py

@@ -42,12 +42,17 @@
             language=f.language,
             schema=f.schema,
             returns=f.returns,
+            parameters=f.parameters,
         )
 
     def to_sql_create(self) -> list[str]:
         components = ["CREATE FUNCTION"]
 
-        components.append(self.qualified_name + "()")
+        parameter_str = ""
+        if self.parameters:
+            parameter_str = ", ".join(self.parameters)
+
+        components.append(f"{self.qualified_name}({parameter_str})")
         components.append(f"RETURNS {self.returns}")
 
         if self.deterministic:
@@ -85,9 +90,32 @@
 
     def normalize(self) -> Function:
         definition = textwrap.dedent(self.definition).strip()
+
+        # Remove optional trailing semicolon for comparison robustness
+        if definition.endswith(";"):
+            definition = definition[:-1]
+
         returns = self.returns.lower()
+        normalized_returns = type_map.get(returns, returns)
+
+        normalized_parameters = None
+        if self.parameters:
+            normalized_parameters = []
+            for param in self.parameters:
+                # Naive split, assumes 'name type' format
+                parts = param.split(maxsplit=1)
+                if len(parts) == 2:
+                    name, type_str = parts
+                    norm_type = type_map.get(type_str.lower(), type_str.lower())
+                    normalized_parameters.append(f"{name} {norm_type}")
+                else:
+                    normalized_parameters.append(param) # Keep as is if format unexpected
+
         return replace(
-            self, definition=definition, returns=type_map.get(returns, returns)
+            self,
+            definition=definition,
+            returns=normalized_returns,
+            parameters=normalized_parameters,
         )
 
 

src/sqlalchemy_declarative_extensions/dialects/mysql/query.py

@@ -91,10 +91,15 @@ def get_functions_mysql(connection: Connection) -> Sequence[BaseFunction]:
 
     functions = []
     for f in connection.execute(functions_query, {"schema": database}).fetchall():
+        parameters = None
+        if f.parameters: # Parameter string might be None if no parameters
+            parameters = [p.strip() for p in f.parameters.split(",")]
+
         functions.append(
             Function(
                 name=f.name,
                 definition=f.definition,
+                parameters=parameters,
                 security=(
                     FunctionSecurity.definer
                     if f.security == "DEFINER"

src/sqlalchemy_declarative_extensions/dialects/mysql/schema.py

@@ -1,4 +1,5 @@
 from sqlalchemy import bindparam, column, table
+from sqlalchemy.sql import func, text
 
 from sqlalchemy_declarative_extensions.sqlalchemy import select
 
@@ -81,6 +82,21 @@
     .where(routine_table.c.routine_type == "PROCEDURE")
 )
 
+# Need to query PARAMETERS separately to reconstruct the parameter list
+parameters_subquery = (
+    select(
+        column("SPECIFIC_NAME").label("routine_name"),
+        func.group_concat(
+            text("concat(PARAMETER_NAME, ' ', DTD_IDENTIFIER) ORDER BY ORDINAL_POSITION SEPARATOR ', '"),
+        ).label("parameters"),
+    )
+    .select_from(table("PARAMETERS", schema="INFORMATION_SCHEMA"))
+    .where(column("SPECIFIC_SCHEMA") == bindparam("schema"))
+    .where(column("ROUTINE_TYPE") == "FUNCTION")
+    .group_by(column("SPECIFIC_NAME"))
+    .alias("parameters_sq")
+)
+
 functions_query = (
     select(
         routine_table.c.routine_name.label("name"),
@@ -89,6 +105,13 @@
         routine_table.c.dtd_identifier.label("return_type"),
         routine_table.c.is_deterministic.label("deterministic"),
         routine_table.c.sql_data_access.label("data_access"),
+        parameters_subquery.c.parameters.label("parameters"),
+    )
+    .select_from( # Join routines with the parameter subquery
+        routine_table.outerjoin(
+            parameters_subquery,
+            routine_table.c.routine_name == parameters_subquery.c.routine_name,
+        )
     )
     .where(routine_table.c.routine_schema == bindparam("schema"))
     .where(routine_table.c.routine_type == "FUNCTION")

src/sqlalchemy_declarative_extensions/dialects/postgresql/__init__.py

@@ -1,6 +1,7 @@
 from sqlalchemy_declarative_extensions.dialects.postgresql.function import (
     Function,
     FunctionSecurity,
+    FunctionVolatility,
 )
 from sqlalchemy_declarative_extensions.dialects.postgresql.grant import (
     DefaultGrant,
@@ -43,6 +44,7 @@
     "Function",
     "FunctionGrants",
     "FunctionSecurity",
+    "FunctionVolatility",
     "Grant",
     "Grant",
     "GrantStatement",

src/sqlalchemy_declarative_extensions/dialects/postgresql/function.py

@@ -3,6 +3,7 @@
 import enum
 import textwrap
 from dataclasses import dataclass, replace
+from typing import List, Optional
 
 from sqlalchemy_declarative_extensions.function import base
 
@@ -13,6 +14,47 @@
     definer = "DEFINER"
 
 
+@enum.unique
+class FunctionVolatility(enum.Enum):
+    VOLATILE = "VOLATILE"
+    STABLE = "STABLE"
+    IMMUTABLE = "IMMUTABLE"
+
+    @classmethod
+    def from_provolatile(cls, provolatile: str) -> FunctionVolatility:
+        """Convert a `pg_proc.provolatile` value to a `FunctionVolatility` enum."""
+        if provolatile == "v":
+            return cls.VOLATILE
+        if provolatile == "s":
+            return cls.STABLE
+        if provolatile == "i":
+            return cls.IMMUTABLE
+        raise ValueError(f"Invalid volatility: {provolatile}")
+
+
+def normalize_arg(arg: str) -> str:
+    parts = arg.strip().split(maxsplit=1)
+    if len(parts) == 2:
+        name, type_str = parts
+        norm_type = type_map.get(type_str.lower(), type_str.lower())
+        # Handle array types
+        if norm_type.endswith("[]"):
+            base_type = norm_type[:-2]
+            norm_base_type = type_map.get(base_type, base_type)
+            norm_type = f"{norm_base_type}[]"
+
+        return f"{name} {norm_type}"
+    else:
+        # Handle case where it might just be the type (e.g., from DROP FUNCTION)
+        type_str = arg.strip()
+        norm_type = type_map.get(type_str.lower(), type_str.lower())
+        if norm_type.endswith("[]"):
+            base_type = norm_type[:-2]
+            norm_base_type = type_map.get(base_type, base_type)
+            norm_type = f"{norm_base_type}[]"
+        return norm_type
+
+
 @dataclass
 class Function(base.Function):
     """Describes a PostgreSQL function.
@@ -24,19 +66,32 @@
 
     security: FunctionSecurity = FunctionSecurity.invoker
 
+    #: Defines the parameters for the function, e.g. ["param1 int", "param2 varchar"]
+    parameters: Optional[List[str]] = None
+
+    #: Defines the volatility of the function.
+    volatility: FunctionVolatility = FunctionVolatility.VOLATILE
+
     def to_sql_create(self, replace=False) -> list[str]:
         components = ["CREATE"]
 
         if replace:
             components.append("OR REPLACE")
 
+        parameter_str = ""
+        if self.parameters:
+            parameter_str = ", ".join(self.parameters)
+
         components.append("FUNCTION")
-        components.append(self.qualified_name + "()")
+        components.append(f"{self.qualified_name}({parameter_str})")
         components.append(f"RETURNS {self.returns}")
 
         if self.security == FunctionSecurity.definer:
             components.append("SECURITY DEFINER")
 
+        if self.volatility != FunctionVolatility.VOLATILE:
+            components.append(self.volatility.value)
+
         components.append(f"LANGUAGE {self.language}")
         components.append(f"AS $${self.definition}$$")
 
@@ -45,6 +100,20 @@
     def to_sql_update(self) -> list[str]:
         return self.to_sql_create(replace=True)
 
+    def to_sql_drop(self) -> list[str]:
+        param_types = []
+        if self.parameters:
+            for param in self.parameters:
+                # Naive split, assumes 'name type' or just 'type' format
+                parts = param.split(maxsplit=1)
+                if len(parts) == 2:
+                    param_types.append(parts[1])
+                else:
+                    param_types.append(param) # Assume it's just the type if no space
+
+        param_str = ", ".join(param_types)
+        return [f"DROP FUNCTION {self.qualified_name}({param_str});"]
+
     def with_security(self, security: FunctionSecurity):
         return replace(self, security=security)
 
@@ -53,9 +122,35 @@
 
     def normalize(self) -> Function:
         definition = textwrap.dedent(self.definition)
-        returns = self.returns.lower()
+
+        # Handle RETURNS TABLE(...) normalization
+        returns_lower = self.returns.lower().strip()
+        if returns_lower.startswith("table("):
+            # Basic normalization: lowercase and remove extra spaces
+            # This might need refinement for complex TABLE definitions
+            inner_content = returns_lower[len("table("):-1].strip()
+            cols = [normalize_arg(c) for c in inner_content.split(',')]
+            normalized_returns = f"table({', '.join(cols)})"
+        else:
+            # Normalize base return type (including array types)
+            norm_type = type_map.get(returns_lower, returns_lower)
+            if norm_type.endswith("[]"):
+                base = norm_type[:-2]
+                norm_base = type_map.get(base, base)
+                normalized_returns = f"{norm_base}[]"
+            else:
+                normalized_returns = norm_type
+
+        # Normalize parameter types
+        normalized_parameters = None
+        if self.parameters:
+            normalized_parameters = [normalize_arg(p) for p in self.parameters]
+
         return replace(
-            self, definition=definition, returns=type_map.get(returns, returns)
+            self,
+            definition=definition,
+            returns=normalized_returns,
+            parameters=normalized_parameters, # Use normalized parameters
         )
 
 

src/sqlalchemy_declarative_extensions/dialects/postgresql/query.py

@@ -14,6 +14,7 @@
 from sqlalchemy_declarative_extensions.dialects.postgresql.function import (
     Function,
     FunctionSecurity,
+    FunctionVolatility,
 )
 from sqlalchemy_declarative_extensions.dialects.postgresql.procedure import (
     Procedure,
@@ -195,13 +196,18 @@ def get_procedures_postgresql(connection: Connection) -> Sequence[BaseProcedure]
 
 def get_functions_postgresql(connection: Connection) -> Sequence[BaseFunction]:
     functions = []
+
     for f in connection.execute(functions_query).fetchall():
         name = f.name
         definition = f.source
         language = f.language
         schema = f.schema if f.schema != "public" else None
 
         function = Function(
+            parameters=(
+                [p.strip() for p in f.parameters.split(",")] if f.parameters else None
+            ),
+            volatility=FunctionVolatility.from_provolatile(f.volatility),
             name=name,
             definition=definition,
             language=language,
@@ -211,7 +217,7 @@ def get_functions_postgresql(connection: Connection) -> Sequence[BaseFunction]:
                 if f.security_definer
                 else FunctionSecurity.invoker
             ),
-            returns=f.return_type,
+            returns=f.return_type_string or f.base_return_type,
         )
         functions.append(function)