detquantlib 5.7.1__tar.gz → 5.8.0__tar.gz

{detquantlib-5.7.1 → detquantlib-5.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detquantlib
-Version: 5.7.1
+Version: 5.8.0
 Summary: An internal library containing functions and classes that can be used across Quant models.
 License-File: LICENSE.txt
 Author: Dynamic Energy Trading
@@ -84,6 +84,12 @@ poetry run python docs.py
 
 Classes:
 
+- `AzureClient`:
+  - `from detquantlib.data import AzureClient`
+  - `from detquantlib.data.databases.azure_client import AzureClient`
+- `AzureConfig`:
+  - `from detquantlib.data import AzureConfig`
+  - `from detquantlib.data.databases.azure_client import AzureConfig`
 - `BatteryState`:
   - `from detquantlib.assets import BatteryState`
   - `from detquantlib.assets.battery import BatteryState`

{detquantlib-5.7.1 → detquantlib-5.8.0}/README.md

@@ -54,6 +54,12 @@ poetry run python docs.py
 
 Classes:
 
+- `AzureClient`:
+  - `from detquantlib.data import AzureClient`
+  - `from detquantlib.data.databases.azure_client import AzureClient`
+- `AzureConfig`:
+  - `from detquantlib.data import AzureConfig`
+  - `from detquantlib.data.databases.azure_client import AzureConfig`
 - `BatteryState`:
   - `from detquantlib.assets import BatteryState`
   - `from detquantlib.assets.battery import BatteryState`

{detquantlib-5.7.1 → detquantlib-5.8.0}/detquantlib/data/__init__.py

@@ -1,3 +1,4 @@
+from .databases.azure_client import AzureClient, AzureConfig
 from .databases.detdatabase import DetDatabase
 from .databases.helpers import *
 from .databases.snowflake_client import SnowflakeClient, SnowflakeConfig
@@ -6,6 +7,8 @@ from .sftp.sftp import Sftp
 from .tennet.tennet_client import TennetAPIError, TennetClient
 
 __all__ = [
+    "AzureClient",
+    "AzureConfig",
     "DetDatabase",
     "Entsoe",
     "Sftp",

detquantlib-5.8.0/detquantlib/data/databases/azure_client.py

@@ -0,0 +1,655 @@
+"""
+Client for working with an Azure SQL database from Python.
+
+This module provides a configuration dataclass and a client class that wrap ``pyodbc`` and
+``SQLAlchemy`` with a small, safe API for interacting with Azure SQL Database (or any SQL Server
+instance reachable through the Microsoft ODBC driver). Data is exchanged as pandas DataFrames.
+"""
+
+# Python built-in packages
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Any, Iterator, Optional, Sequence
+
+# Third-party packages
+import pandas as pd
+import pyodbc
+from sqlalchemy import Engine, create_engine, inspect, text
+from sqlalchemy.exc import SQLAlchemyError
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_DRIVER = "ODBC Driver 18 for SQL Server"
+_MAX_IDENTIFIER_LENGTH = 128
+_ODBC_VALUE_NEEDS_BRACES_RE = re.compile(r"[\s;{}=]")
+
+
+@dataclass
+class AzureConfig:
+    """
+    Connection settings for an Azure SQL database.
+
+    Exactly one authentication method is used, chosen in this order of precedence:
+    - ``authentication`` (i.e. Microsoft Entra ID, formerly Azure Active Directory)
+    - ``user`` and ``password`` (i.e. SQL authentication)
+
+    Attributes:
+        server: Server address, e.g. ``"myserver.database.windows.net"``. A protocol prefix and
+            port can be included, e.g. ``"tcp:myserver.database.windows.net,1433"``.
+        database: Name of the default database, used by operations that do not specify one. Can
+            be left unset if every operation passes a database explicitly.
+        user: Login name. For SQL authentication, the SQL login. With ``authentication``, its
+            meaning depends on the method, e.g. the user principal name for
+            ``"ActiveDirectoryPassword"`` or ``"ActiveDirectoryInteractive"``, the application
+            (client) ID for ``"ActiveDirectoryServicePrincipal"``, or the client ID of a
+            user-assigned identity for ``"ActiveDirectoryMsi"``.
+        password: Password for SQL authentication, or the secret for ``authentication`` methods
+            that need one (e.g. the client secret for ``"ActiveDirectoryServicePrincipal"``).
+        authentication: Microsoft Entra ID authentication method passed to the ODBC driver, e.g.
+            ``"ActiveDirectoryInteractive"`` for browser-based sign-in with MFA,
+            ``"ActiveDirectoryServicePrincipal"`` or ``"ActiveDirectoryMsi"``.
+        driver: Name of the installed ODBC driver.
+        extra: Additional ODBC connection string attributes, e.g.
+            ``{"TrustServerCertificate": "yes", "Connection Timeout": 60}``. They override the
+            attributes built from the other fields.
+    """
+
+    server: Optional[str] = None
+    database: Optional[str] = None
+    user: Optional[str] = None
+    password: Optional[str] = None
+    authentication: Optional[str] = None
+    driver: str = _DEFAULT_DRIVER
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_env(cls, prefix: str = "AZURE_SQL_") -> "AzureConfig":
+        """
+        Builds a config from environment variables.
+
+        Reads variables named ``<prefix><FIELD>``, e.g. ``AZURE_SQL_SERVER``,
+        ``AZURE_SQL_DATABASE``, ``AZURE_SQL_USER``, ``AZURE_SQL_PASSWORD``,
+        ``AZURE_SQL_AUTHENTICATION`` and ``AZURE_SQL_DRIVER``. Unset variables become ``None``,
+        except ``AZURE_SQL_DRIVER``, which falls back to ``"ODBC Driver 18 for SQL Server"``.
+
+        Args:
+            prefix: Prefix prepended to each variable name.
+
+        Returns:
+            An ``AzureConfig`` populated from the environment.
+        """
+        g = lambda name: os.getenv(f"{prefix}{name}")
+        return cls(
+            server=g("SERVER"),
+            database=g("DATABASE"),
+            user=g("USER"),
+            password=g("PASSWORD"),
+            authentication=g("AUTHENTICATION"),
+            driver=g("DRIVER") or _DEFAULT_DRIVER,
+        )
+
+
+class AzureClient:
+    """
+    Client for interacting with an Azure SQL database.
+
+    Wraps SQLAlchemy engines on top of ``pyodbc`` and exposes methods for running SQL and
+    exchanging data as pandas DataFrames. The class can be used as a context manager so the
+    connections are closed automatically.
+
+    Every operation targets ``config.database`` by default, or another database on the same server
+    if one is specified. Azure SQL Database does not support cross-database queries (or the
+    ``USE`` statement), so the client keeps one engine per database. Each engine is created
+    lazily on first use and pools its connections, so they are reused across operations.
+
+    Query parameters use SQLAlchemy's named placeholder style, e.g. ``:status``.
+
+    Attributes:
+        config: The connection settings used by this client.
+
+    Examples:
+        Example 1: Loading a table
+        >>> with AzureClient() as client:
+        ...     customers = client.load_table("dbo.Customers", columns=["Id", "Name"], limit=100)
+
+        Example 2: Standard query method
+        >>> with AzureClient() as client:
+        ...     df = client.query(
+        ...         "SELECT * FROM dbo.Orders WHERE Status = :status", {"status": "SHIPPED"}
+        ...     )
+
+        Example 3: Targeting another database on the same server
+        >>> with AzureClient() as client:
+        ...     df = client.query("SELECT * FROM dbo.Positions", database="Risk")
+        ...     p1 = client.load_table("dbo.Prices", database="Trading")
+        ...     p2 = client.load_table("Trading.dbo.Prices")  # DB.SCHEMA.TABLE format
+
+        Example 4: Batch query method to stream a large table in chunks
+        >>> with AzureClient(AzureConfig.from_env()) as client:
+        ...     for chunk in client.query_batches("SELECT * FROM dbo.BigTable"):
+        ...         process(chunk)
+
+        Example 5: Writing a DataFrame to a table, creating the table if needed
+        >>> with AzureClient() as client:
+        ...     client.write_table(df, "dbo.Orders", auto_create_table=True)
+
+        Example 6: Running a statement that does not return data
+        >>> with AzureClient() as client:
+        ...     client.execute("DELETE FROM dbo.Orders WHERE Status = :s", {"s": "CANCELLED"})
+    """
+
+    def __init__(self, config: Optional[AzureConfig] = None) -> None:
+        """
+        Initializes the client without opening a connection.
+
+        Args:
+            config: Connection settings. If ``None``, settings are read from environment variables
+                via ``AzureConfig.from_env()``.
+        """
+        self.config = config or AzureConfig.from_env()
+        self._engines: dict[str, Engine] = {}
+
+    # ---------------------------------------------------------------------------------------------
+    # Connection management
+    # ---------------------------------------------------------------------------------------------
+    def _resolve_database(self, database: Optional[str]) -> str:
+        """
+        Determines which database an operation targets.
+
+        Args:
+            database: Database requested by the operation, or ``None`` for the default database.
+
+        Returns:
+            ``database`` if given, otherwise ``config.database``.
+
+        Raises:
+            ValueError: If neither is set, or if the name is not a valid identifier.
+        """
+        database = database or self.config.database
+        if not database:
+            raise ValueError(
+                "No database specified: set 'database' in the config or pass it to the method."
+            )
+        return self._check_identifier(database)
+
+    def _connection_params(self, database: Optional[str] = None) -> dict[str, Any]:
+        """
+        Builds the attributes of the ODBC connection string.
+
+        Selects a single authentication method (Entra ID or SQL authentication, in that order),
+        applies ``extra`` last, and drops any attributes that are ``None``.
+
+        Args:
+            database: Database to connect to. If ``None``, ``config.database`` is used.
+
+        Returns:
+            A dict of ODBC connection string attributes.
+
+        Raises:
+            ValueError: If ``server`` is missing, if no database is specified, or if no
+                credentials are configured.
+        """
+        c = self.config
+        if not c.server:
+            raise ValueError("Azure SQL 'server' is required.")
+
+        params: dict[str, Any] = {
+            "DRIVER": c.driver,
+            "SERVER": c.server,
+            "DATABASE": self._resolve_database(database),
+            "Encrypt": "yes",
+        }
+
+        if c.authentication:
+            params["Authentication"] = c.authentication
+            params["UID"] = c.user
+            params["PWD"] = c.password
+        elif c.user and c.password:
+            params["UID"] = c.user
+            params["PWD"] = c.password
+        else:
+            raise ValueError("No credentials provided: set user and password, or authentication.")
+
+        params.update(c.extra)
+        return {k: v for k, v in params.items() if v is not None}
+
+    @staticmethod
+    def _to_connection_string(params: dict[str, Any]) -> str:
+        """
+        Formats attributes as an ODBC connection string.
+
+        Values containing whitespace or any of ``;{}=`` are wrapped in braces, with closing braces
+        doubled, so that they are passed to the driver verbatim.
+
+        Args:
+            params: ODBC connection string attributes.
+
+        Returns:
+            The connection string, e.g. ``"DRIVER={ODBC Driver 18 for SQL Server};SERVER=..."``.
+        """
+        parts = []
+        for key, value in params.items():
+            value = str(value)
+            if _ODBC_VALUE_NEEDS_BRACES_RE.search(value):
+                value = "{" + value.replace("}", "}}") + "}"
+            parts.append(f"{key}={value}")
+        return ";".join(parts)
+
+    def connect(self, database: Optional[str] = None) -> Engine:
+        """
+        Creates the engine for a database if it does not exist yet.
+
+        The connection settings are validated here, as in ``_connection_params()``. The engine
+        itself opens connections lazily, on the first operation that needs one.
+
+        Args:
+            database: Database to connect to. If ``None``, ``config.database`` is used.
+
+        Returns:
+            The SQLAlchemy engine for the database.
+        """
+        database = self._resolve_database(database)
+        if database not in self._engines:
+            conn_str = self._to_connection_string(self._connection_params(database))
+            logger.info("Connecting to Azure SQL database %s on %s", database, self.config.server)
+            self._engines[database] = create_engine(
+                "mssql+pyodbc://",
+                creator=lambda: pyodbc.connect(conn_str),
+                fast_executemany=True,
+            )
+        return self._engines[database]
+
+    def close(self) -> None:
+        """
+        Closes all pooled connections and discards the engines of all databases.
+
+        Safe to call multiple times, or when no connection was ever opened.
+        """
+        for database, engine in self._engines.items():
+            engine.dispose()
+            logger.info("Azure SQL connection to database %s closed", database)
+        self._engines = {}
+
+    def __enter__(self) -> "AzureClient":
+        """
+        Creates the engine of the default database, if any, when entering a ``with`` block.
+
+        Returns:
+            This client instance.
+        """
+        if self.config.database:
+            self.connect()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        """
+        Closes the connections when leaving a ``with`` block.
+
+        Exceptions raised inside the block are not suppressed.
+
+        Args:
+            exc_type: Type of the exception raised in the block, if any.
+            exc: The exception instance raised in the block, if any.
+            tb: The traceback of the exception, if any.
+        """
+        self.close()
+
+    # ---------------------------------------------------------------------------------------------
+    # Reading data
+    # ---------------------------------------------------------------------------------------------
+    def query(
+        self,
+        sql: str,
+        params: Optional[dict[str, Any]] = None,
+        database: Optional[str] = None,
+    ) -> pd.DataFrame:
+        """
+        Runs a SQL query and returns the full result as a DataFrame.
+
+        Always pass user-supplied values through ``params`` (``:name`` placeholders) rather than
+        formatting them into the SQL string, to avoid SQL injection. A literal colon followed by a
+        word, e.g. inside a string literal, must be escaped as ``\\:``.
+
+        Args:
+            sql: The SQL statement to execute.
+            params: Values bound to the named placeholders in ``sql``.
+            database: Database to run the query in. If ``None``, ``config.database`` is used.
+
+        Returns:
+            A DataFrame containing every row returned by the query. Decimal values are converted
+            to floats, as in ``pandas.read_sql``.
+
+        Raises:
+            SQLAlchemyError: If the query fails. The error is logged before being re-raised.
+        """
+        engine = self.connect(database)
+        try:
+            with engine.connect() as conn:
+                result = conn.execute(text(sql), params or {})
+                cols = list(result.keys())
+                df = pd.DataFrame.from_records(result.fetchall(), columns=cols, coerce_float=True)
+        except SQLAlchemyError as e:
+            logger.error("Query failed: %s", e)
+            raise
+        logger.info("Loaded %d rows", len(df))
+        return df
+
+    def query_batches(
+        self,
+        sql: str,
+        params: Optional[dict[str, Any]] = None,
+        batch_size: int = 10_000,
+        database: Optional[str] = None,
+    ) -> Iterator[pd.DataFrame]:
+        """
+        Streams a large result set as a sequence of DataFrames.
+
+        Useful for results too large to hold in memory at once. Rows are fetched from the server
+        one batch at a time, and a connection is held until the iteration finishes.
+
+        Args:
+            sql: The SQL statement to execute.
+            params: Values bound to the placeholders in ``sql``, as in ``query()``.
+            batch_size: Maximum number of rows per batch.
+            database: Database to run the query in. If ``None``, ``config.database`` is used.
+
+        Yields:
+            DataFrames, each holding one batch of rows.
+        """
+        engine = self.connect(database)
+        with engine.connect() as conn:
+            result = conn.execute(text(sql), params or {})
+            cols = list(result.keys())
+            while rows := result.fetchmany(batch_size):
+                yield pd.DataFrame.from_records(rows, columns=cols, coerce_float=True)
+
+    def load_table(
+        self,
+        table: str,
+        columns: Optional[Sequence[str]] = None,
+        where: Optional[str] = None,
+        params: Optional[dict[str, Any]] = None,
+        limit: Optional[int] = None,
+        database: Optional[str] = None,
+    ) -> pd.DataFrame:
+        """
+        Loads a table, optionally filtered, into a DataFrame.
+
+        Args:
+            table: Table name, optionally qualified, e.g. ``"SCHEMA.TABLE"`` or
+                ``"DB.SCHEMA.TABLE"``. A database part selects the database to read from. Parts
+                may be wrapped in square brackets, e.g. ``"[META].[Commodity]"``, and are
+                bracket-quoted in the query either way.
+            columns: Columns to select, as literal names, e.g. ``"DateTime(UTC)"``. Each name is
+                bracket-quoted in the query. If ``None``, all columns are selected.
+            where: Optional SQL condition, without the ``WHERE`` keyword. Use placeholders and pass
+                the values via ``params``; this string is inserted into the query as-is.
+            params: Values bound to the placeholders in ``where``.
+            limit: Maximum number of rows to return.
+            database: Database to read from. If ``None``, the database part of ``table`` is used,
+                or ``config.database`` if ``table`` has none.
+
+        Returns:
+            A DataFrame containing the selected rows.
+        """
+        database, parts = self._split_table_name(table, database)
+        table_sql = ".".join(self._quote_identifier(p) for p in parts)
+        cols_sql = ", ".join(self._quote_identifier(c) for c in columns) if columns else "*"
+        top_sql = f"TOP ({int(limit)}) " if limit is not None else ""
+        sql = f"SELECT {top_sql}{cols_sql} FROM {table_sql}"
+        if where:
+            sql += f" WHERE {where}"
+        return self.query(sql, params, database=database)
+
+    def list_tables(
+        self, schema: Optional[str] = None, database: Optional[str] = None
+    ) -> pd.DataFrame:
+        """
+        Lists the tables visible in a database.
+
+        Views are not included.
+
+        Args:
+            schema: Schema to inspect, e.g. ``"dbo"``. If ``None``, tables in all schemas are
+                listed.
+            database: Database to inspect. If ``None``, ``config.database`` is used.
+
+        Returns:
+            A DataFrame with one row per table, sorted by schema and table name, using the columns
+            of the ``INFORMATION_SCHEMA.TABLES`` view.
+
+        Raises:
+            ValueError: If ``schema`` is not a valid, unqualified schema name.
+        """
+        sql = "SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE = 'BASE TABLE'"
+        params = None
+        if schema:
+            parts = self._split_name(schema)
+            if len(parts) > 1:
+                raise ValueError(f"Invalid schema name: {schema!r}. Expected an unqualified name.")
+            sql += " AND TABLE_SCHEMA = :schema"
+            params = {"schema": parts[0]}
+        sql += " ORDER BY TABLE_SCHEMA, TABLE_NAME"
+        return self.query(sql, params, database=database)
+
+    # ---------------------------------------------------------------------------------------------
+    # Writing data
+    # ---------------------------------------------------------------------------------------------
+    def write_table(
+        self,
+        df: pd.DataFrame,
+        table: str,
+        overwrite: bool = False,
+        auto_create_table: bool = False,
+        chunk_size: Optional[int] = None,
+        database: Optional[str] = None,
+    ) -> int:
+        """
+        Writes a DataFrame to a table.
+
+        Data is inserted in bulk with pandas' ``to_sql`` using pyodbc's ``fast_executemany``, which
+        is much faster than row-by-row inserts. The whole write runs in a single transaction: if
+        any part fails, the table is left unchanged.
+
+        Args:
+            df: The data to write. The index is not written. Unless the table is created by this
+                call, column names must match the table's columns.
+            table: Table name, optionally qualified, e.g. ``"SCHEMA.TABLE"`` or
+                ``"DB.SCHEMA.TABLE"``. A database part selects the database to write to. Parts may
+                be wrapped in square brackets. If no schema is given, the user's default schema
+                (usually ``dbo``) is used.
+            overwrite: If ``True``, the existing rows are replaced by ``df``. If ``False``, ``df``
+                is appended. Combined with ``auto_create_table``, the table itself is recreated
+                with column types inferred from ``df``.
+            auto_create_table: If ``True``, the table is created if it does not exist, with column
+                types inferred from ``df``.
+            chunk_size: Number of rows per insert batch. If ``None``, all rows are sent at once.
+            database: Database to write to. If ``None``, the database part of ``table`` is used,
+                or ``config.database`` if ``table`` has none.
+
+        Returns:
+            The number of rows written. If ``df`` is empty, nothing is written, the table is left
+            unchanged and ``0`` is returned.
+
+        Raises:
+            ValueError: If the table does not exist and ``auto_create_table`` is ``False``. Also
+                raised for invalid table, column or database names, as in ``_split_table_name()``.
+            SQLAlchemyError: If the write fails. The error is logged before being re-raised.
+        """
+        database, parts = self._split_table_name(table, database)
+        for col in df.columns:
+            self._check_identifier(str(col))
+
+        if df.empty:
+            logger.warning("DataFrame is empty; nothing written to %s", table)
+            return 0
+
+        # Pad the qualifier on the left, so "T" -> (None, T) and "S.T" -> (S, T)
+        schema, table_name = ([None] + parts)[-2:]
+        table_sql = ".".join(self._quote_identifier(p) for p in parts)
+
+        engine = self.connect(database)
+        # pandas' to_sql always creates missing tables, so the table must be checked beforehand
+        if not auto_create_table and not inspect(engine).has_table(table_name, schema=schema):
+            raise ValueError(
+                f"Table {table} does not exist. Set auto_create_table=True to create it."
+            )
+        try:
+            with engine.begin() as conn:
+                if overwrite and not auto_create_table:
+                    conn.execute(text(f"DELETE FROM {table_sql}"))
+                df.to_sql(
+                    table_name,
+                    conn,
+                    schema=schema,
+                    if_exists="replace" if overwrite and auto_create_table else "append",
+                    index=False,
+                    chunksize=chunk_size,
+                )
+        except SQLAlchemyError as e:
+            logger.error("Write to %s failed: %s", table, e)
+            raise
+        logger.info("Wrote %d rows to %s", len(df), table)
+        return len(df)
+
+    def execute(
+        self,
+        sql: str,
+        params: Optional[dict[str, Any]] = None,
+        database: Optional[str] = None,
+    ) -> Optional[int]:
+        """
+        Runs a SQL statement that does not return data.
+
+        Intended for statements such as ``INSERT``, ``UPDATE``, ``DELETE``, ``MERGE`` or
+        ``CREATE TABLE``. Always pass user-supplied values through ``params``, as in ``query()``.
+        The statement runs in its own transaction, which is committed if it succeeds and rolled
+        back if it fails.
+
+        Args:
+            sql: The SQL statement to execute.
+            params: Values bound to the placeholders in ``sql``, as in ``query()``.
+            database: Database to run the statement in. If ``None``, ``config.database`` is used.
+
+        Returns:
+            The number of rows affected, as reported by the driver, or ``None`` if unavailable
+            (e.g. for DDL statements, or when ``SET NOCOUNT ON`` is in effect).
+
+        Raises:
+            SQLAlchemyError: If the statement fails. The error is logged before being re-raised.
+        """
+        engine = self.connect(database)
+        try:
+            with engine.begin() as conn:
+                rowcount = conn.execute(text(sql), params or {}).rowcount
+        except SQLAlchemyError as e:
+            logger.error("Statement failed: %s", e)
+            raise
+        if rowcount is not None and rowcount < 0:
+            rowcount = None
+        logger.info("Statement affected %s rows", rowcount)
+        return rowcount
+
+    # ---------------------------------------------------------------------------------------------
+    # Identifier handling
+    # ---------------------------------------------------------------------------------------------
+    @staticmethod
+    def _check_identifier(name: str) -> str:
+        """
+        Validates a SQL Server identifier, as a literal name without square brackets.
+
+        Any character is allowed, since identifiers are always bracket-quoted before being placed
+        in a query (see ``_quote_identifier()``). Only the length is checked.
+
+        Args:
+            name: The identifier to validate.
+
+        Returns:
+            The identifier, unchanged.
+
+        Raises:
+            ValueError: If ``name`` is empty or longer than 128 characters.
+        """
+        if not name or len(name) > _MAX_IDENTIFIER_LENGTH:
+            raise ValueError(f"Invalid Azure SQL identifier: {name!r}")
+        return name
+
+    @staticmethod
+    def _quote_identifier(name: str) -> str:
+        """
+        Bracket-quotes an identifier so it can be safely placed in a query.
+
+        Guards against SQL injection in table, schema and column names, which cannot be passed as
+        bind parameters. Closing brackets in the name are escaped by doubling them, as done by
+        SQL Server's ``QUOTENAME`` function. The name is validated with ``_check_identifier()``.
+
+        Args:
+            name: The identifier, as a literal name without square brackets.
+
+        Returns:
+            The quoted identifier, e.g. ``"[DateTime(UTC)]"``.
+        """
+        return "[" + AzureClient._check_identifier(name).replace("]", "]]") + "]"
+
+    @staticmethod
+    def _split_name(name: str) -> list[str]:
+        """
+        Splits a dot-separated name into its parts, e.g. ``"SCHEMA.TABLE"``.
+
+        Parts may be wrapped in square brackets, e.g. ``"[META].[Commodity]"``, in which case the
+        brackets are removed. Dots inside brackets are not supported. Each part is validated with
+        ``_check_identifier()``.
+
+        Args:
+            name: The name to split.
+
+        Returns:
+            The parts of the name, without square brackets.
+        """
+        parts = []
+        for part in name.split("."):
+            if len(part) >= 2 and part.startswith("[") and part.endswith("]"):
+                part = part[1:-1].replace("]]", "]")
+            parts.append(AzureClient._check_identifier(part))
+        return parts
+
+    @staticmethod
+    def _split_table_name(table: str, database: Optional[str]) -> tuple[Optional[str], list[str]]:
+        """
+        Splits a table name of the form ``[DB.][SCHEMA.]TABLE`` into a database and the rest.
+
+        Azure SQL Database does not accept database parts in queries, so the database part is
+        removed from the name and used to select the engine instead.
+
+        Args:
+            table: The table name, as in ``_split_name()``.
+            database: Database passed explicitly to the calling method, or ``None``.
+
+        Returns:
+            A tuple with the database to use (``None`` for ``config.database``) and the
+            remaining one or two parts of the table name.
+
+        Raises:
+            ValueError: If the name has more than three parts, or if its database part
+                conflicts with ``database``.
+        """
+        parts = AzureClient._split_name(table)
+        if len(parts) > 3:
+            raise ValueError(f"Invalid table name: {table!r}. Expected at most DB.SCHEMA.TABLE.")
+        if len(parts) == 3:
+            name_database, *parts = parts
+            if database is not None and database.casefold() != name_database.casefold():
+                raise ValueError(
+                    f"Table name {table!r} refers to database {name_database!r}, "
+                    f"which conflicts with database={database!r}."
+                )
+            database = name_database
+        return database, parts

{detquantlib-5.7.1 → detquantlib-5.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "detquantlib"
-version = "5.7.1"
+version = "5.8.0"
 description = "An internal library containing functions and classes that can be used across Quant models."
 authors = ["Dynamic Energy Trading"]
 readme = "README.md"