Goal: extend the keyword arguments of the to_sql and to_df arguments to optionally take in a session argument, which is a PyDough session object.

• If this argument is omitted, the behavior of to_sql and to_df is unchanged.
• If this argument is provided, the metadata/configs/database used by to_sql and to_df will come from the session object instead of pydough.active_session or the other keyword arguments
• If this argument is provided and any of the other keyword arguments that conflict with it are provided (metadata, configs, database), an exception is raised.

Additionally, to streamline utilization of these parameters throughout the codebase, and trivialize the extension of them, they will now be parceled together within a session object throughout the lifetime of the to_sql or to_df execution. This means:

• If no keyword argument is used, pydough.active_session is communicated throughout the workflow.
• If the session keyword argument is used, its value is communicated throughout the workflow.
• If the other keyword arguments are used, a new session object is constructed using their values (and the ones from active session, where omitted) is communicated throughout the workflow.

Examples:

import pydough
from pydough.configs import PyDoughSession
pydough_code = pydough.from_string(...)

# Create metadata objects
meta1 = ...
meta2 = ...

# Create config objects
configs1 = ...
configs2 = ...

# Create database connection objects
db1 = ...
db2 = ...

# Create a custom session object
s1 = PyDoughSession()
s1.metadata = ...
s1.configs = ...
s1.metadata = ...

# Uses pydough.active_session
df1 = to_sql(pydough_code)

# Same as df1
df2 = to_sql(pydough_code, session=pydough.active_session)

# Uses session containing meta1/configs1/db1 (aka uses s1)
df3 = to_sql(pydough_code, session=s1)

# Uses session containing meta2/configs2, and uses the database from `pydough.active_session`
df4 = to_sql(pydough_code, metadata=meta2, configs=configs2)

# Uses session containing meta2/configs2/db2
df5 = to_sql(pydough_code, metadata=meta2, configs=configs2, database=db2)

These changes must be thoroughly documented in the usage API documentation, and a small amount of testing is required (both for good and bad cases). Note: the error builder is not encapsulated in this manner, since it is only invoked from pydough.active_session.

Regarding the encapsulation of sessions, an example would be the arguments to convert_ast_to_relational, which currently contain the configs & dialect, but will instead just pass in the session.