ds_provider_postgresql_py_lib.utils
===================================

.. py:module:: ds_provider_postgresql_py_lib.utils

.. autoapi-nested-parse::

   **File:** ``__init__.py``
   **Region:** ``ds_provider_postgresql_py_lib/utils``

   Utils Package

   This package exports shared helper functions used across provider modules.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/ds_provider_postgresql_py_lib/utils/dataset_identity/index
   /autoapi/ds_provider_postgresql_py_lib/utils/dataset_rows/index
   /autoapi/ds_provider_postgresql_py_lib/utils/dataset_types/index
   /autoapi/ds_provider_postgresql_py_lib/utils/sql/index


Functions
---------

.. autoapisummary::

   ds_provider_postgresql_py_lib.utils.validate_duplicate_identity_rows
   ds_provider_postgresql_py_lib.utils.validate_identity_columns
   ds_provider_postgresql_py_lib.utils.execute_returning_rows
   ds_provider_postgresql_py_lib.utils.output_from_rows
   ds_provider_postgresql_py_lib.utils.pandas_dtype_to_sqlalchemy
   ds_provider_postgresql_py_lib.utils.quote_identifier


Package Contents
----------------

.. py:function:: validate_duplicate_identity_rows(content: pandas.DataFrame, identity_columns: collections.abc.Sequence[str]) -> None

   Ensure input does not contain duplicate identity values.

   :param content: Input DataFrame.
   :param identity_columns: Identity columns used for matching.

   :returns: None

   :raises ValidationError: If duplicate identity rows are found.


.. py:function:: validate_identity_columns(table: sqlalchemy.Table, identity_columns: collections.abc.Sequence[str], content: pandas.DataFrame) -> None

   Ensure identity columns exist in both input and target table.

   :param table: Reflected SQLAlchemy table.
   :param identity_columns: Identity columns used for matching.
   :param content: Input DataFrame.

   :returns: None

   :raises ValidationError: If identity configuration is invalid.


.. py:function:: execute_returning_rows(conn: sqlalchemy.engine.Connection, stmt: sqlalchemy.sql.Executable) -> list[dict[str, Any]]

   Execute a statement with RETURNING and convert rows to dicts.

   :param conn: SQLAlchemy connection.
   :param stmt: SQL statement to execute.

   :returns: Returned rows as dictionaries.
   :rtype: list[dict[str, Any]]


.. py:function:: output_from_rows(table: sqlalchemy.Table, rows: list[dict[str, Any]]) -> pandas.DataFrame

   Build output DataFrame using a stable table-column order.

   :param table: Reflected SQLAlchemy table.
   :param rows: Row dictionaries to materialize.

   :returns: Output DataFrame aligned to table column order.
   :rtype: pd.DataFrame


.. py:function:: pandas_dtype_to_sqlalchemy(dtypes: pandas.Series) -> dict[str, Any]

   Convert pandas dtypes Series to a dict mapping column names to SQLAlchemy types.

   :param dtypes: Pandas dtype series keyed by column name.

   :returns: SQLAlchemy column types keyed by column name.
   :rtype: dict[str, Any]


.. py:function:: quote_identifier(identifier: str) -> str

   Safely quote SQL identifiers for dynamic DDL statements.

   :param identifier: Raw SQL identifier.

   :returns: Properly quoted SQL identifier.
   :rtype: str