ping-dataexport 0.1.0__py3-none-any.whl

ping_dataexport/db/connector.py

@@ -0,0 +1,99 @@
+"""Connector interface + ColumnInfo + factory.
+
+Driver packages (pyodbc, oracledb) are imported lazily inside their connector
+modules, so the package imports cleanly with only the stdlib + pyarrow installed
+(the sqlite connector needs nothing extra).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Iterator, List, Optional, Sequence
+
+from ..config import DBConfig
+from ..errors import ConfigError
+
+# Canonical column kinds — feed the Parquet schema and watermark type detection.
+INT = "INT"
+BIGINT = "BIGINT"
+FLOAT = "FLOAT"
+DOUBLE = "DOUBLE"
+DECIMAL = "DECIMAL"
+BOOL = "BOOL"
+DATE = "DATE"
+TIME = "TIME"
+TIMESTAMP = "TIMESTAMP"
+STRING = "STRING"
+BINARY = "BINARY"
+
+
+@dataclass(frozen=True)
+class ColumnInfo:
+    name: str
+    kind: str = STRING
+    precision: Optional[int] = None  # DECIMAL only
+    scale: Optional[int] = None  # DECIMAL only
+
+
+class Connector(ABC):
+    """One instance per DB Type; stateless — connections are created per job."""
+
+    paramstyle: str = "qmark"
+
+    #: False when describe() infers types from sample values (sqlite) rather than
+    #: driver type codes — such kinds are best-effort, not authoritative.
+    authoritative_types: bool = True
+
+    @abstractmethod
+    def connect(self, db: DBConfig) -> Any:
+        """Open a DB-API connection (read-only usage; autocommit where applicable)."""
+
+    @abstractmethod
+    def describe(self, cursor: Any, sample_rows: Sequence[Sequence[Any]] = ()) -> List[ColumnInfo]:
+        """Column names + canonical kinds from cursor.description (+ type codes).
+
+        `sample_rows` is the already-fetched first batch — used only by drivers
+        whose description carries no type codes (sqlite).
+        """
+
+    def rewrite_params(self, sql: str) -> str:
+        """Planners emit qmark '?' placeholders; numeric-style drivers rewrite them."""
+        return sql
+
+    def adapt_params(self, params: Sequence[Any]) -> Sequence[Any]:
+        """Convert bind values to what the driver accepts (planners bind native types)."""
+        return params
+
+    def prepare_cursor(self, conn: Any, fetch_size: int) -> Any:
+        cursor = conn.cursor()
+        if hasattr(cursor, "arraysize"):
+            cursor.arraysize = fetch_size
+        return cursor
+
+    @staticmethod
+    def fetch_batches(cursor: Any, fetch_size: int) -> Iterator[List[Sequence[Any]]]:
+        """fetchmany loop — never fetchall()."""
+        while True:
+            rows = cursor.fetchmany(fetch_size)
+            if not rows:
+                return
+            yield rows
+
+
+def create_connector(db_type: str) -> Connector:
+    if db_type == "sqlite":
+        from .sqlite_connector import SqliteConnector
+
+        return SqliteConnector()
+    if db_type in ("mssql-odbc", "freetds", "oracle-odbc", "odbc"):
+        from .pyodbc_connector import PyodbcConnector
+
+        return PyodbcConnector(db_type)
+    if db_type == "oracle":
+        from .oracle_connector import OracleConnector
+
+        return OracleConnector()
+    if db_type == "sqlalchemy":
+        raise ConfigError("Type=sqlalchemy is a phase-2 connector (not implemented yet)")
+    raise ConfigError(f"unsupported DB Type: {db_type!r}")

ping_dataexport/db/oracle_connector.py

@@ -0,0 +1,86 @@
+"""Oracle native connector via oracledb (cx_Oracle's maintained successor).
+
+- paramstyle is numeric: planners emit qmark '?', rewrite_params converts to :1, :2, …
+- An output type handler keeps NUMBER columns as int/Decimal — never float — so
+  precision survives all the way to the writers.
+"""
+
+from __future__ import annotations
+
+import decimal
+from typing import Any, List, Sequence
+
+from ..config import DBConfig
+from ..errors import ConfigError, ExportError
+from .connector import ColumnInfo, Connector
+from .type_map import _MAX_INT64_PRECISION, from_oracledb_description
+
+
+def rewrite_qmark_to_numeric(sql: str) -> str:
+    """'?' -> ':1', ':2', … outside single-quoted literals (pure, testable)."""
+    out: List[str] = []
+    n = 0
+    in_string = False
+    for ch in sql:
+        if ch == "'":
+            in_string = not in_string
+            out.append(ch)
+        elif ch == "?" and not in_string:
+            n += 1
+            out.append(f":{n}")
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+class OracleConnector(Connector):
+    paramstyle = "numeric"
+
+    def rewrite_params(self, sql: str) -> str:
+        return rewrite_qmark_to_numeric(sql)
+
+    def connect(self, db: DBConfig) -> Any:
+        try:
+            import oracledb
+        except ImportError:
+            raise ExportError(
+                "Type=oracle requires the oracledb package (pip install oracledb)"
+            ) from None
+        if not db.host or not (db.service or db.sid):
+            raise ConfigError(f"[{db.section}] Type=oracle needs Host and Service (or SID)")
+        port = db.port or 1521
+        if db.service:
+            dsn = f"{db.host}:{port}/{db.service}"
+        else:
+            dsn = oracledb.makedsn(db.host, port, sid=db.sid)
+        try:
+            conn = oracledb.connect(user=db.username, password=db.password, dsn=dsn)
+        except oracledb.Error as exc:
+            raise ExportError(f"cannot connect to [{db.section}]: {exc}") from exc
+        conn.outputtypehandler = _number_fidelity_handler(oracledb)
+        return conn
+
+    def prepare_cursor(self, conn: Any, fetch_size: int) -> Any:
+        cursor = conn.cursor()
+        cursor.arraysize = fetch_size
+        return cursor
+
+    def describe(self, cursor: Any, sample_rows: Sequence[Sequence[Any]] = ()) -> List[ColumnInfo]:
+        if cursor.description is None:
+            return []
+        return [from_oracledb_description(d) for d in cursor.description]
+
+
+def _number_fidelity_handler(oracledb: Any):
+    """NUMBER(scale=0, p<=18) -> int; any other NUMBER -> Decimal (never float)."""
+
+    def handler(cursor: Any, metadata: Any):
+        if metadata.type_code is oracledb.DB_TYPE_NUMBER:
+            precision = metadata.precision or 0
+            scale = metadata.scale if metadata.scale is not None else 0
+            if scale == 0 and 0 < precision <= _MAX_INT64_PRECISION:
+                return cursor.var(int, arraysize=cursor.arraysize)
+            return cursor.var(decimal.Decimal, arraysize=cursor.arraysize)
+        return None
+
+    return handler

ping_dataexport/db/pyodbc_connector.py

@@ -0,0 +1,82 @@
+"""pyodbc connector — Types mssql-odbc / freetds / oracle-odbc / generic odbc.
+
+pyodbc itself is imported lazily in connect(), so this module (and the
+connection-string builder) works without the driver installed.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Sequence
+
+from ..config import DBConfig
+from ..errors import ConfigError, ExportError
+from .connector import ColumnInfo, Connector
+from .type_map import from_pyodbc_description
+
+_DEFAULT_MSSQL_DRIVER = "ODBC Driver 18 for SQL Server"
+_DEFAULT_FREETDS_DRIVER = "FreeTDS"
+_DEFAULT_MSSQL_PORT = 1433
+
+
+def build_connection_string(db: DBConfig, db_type: str) -> str:
+    """Build/complete the ODBC connection string from discrete keys (pure, testable)."""
+    if db.connection_string:
+        cs = db.connection_string
+    elif db.dsn:
+        cs = f"DSN={db.dsn}"
+    elif db_type == "mssql-odbc":
+        if not (db.host and db.database):
+            raise ConfigError(f"[{db.section}] mssql-odbc needs Host+Database (or ConnectionString)")
+        driver = db.driver or _DEFAULT_MSSQL_DRIVER
+        server = f"{db.host},{db.port}" if db.port else f"{db.host},{_DEFAULT_MSSQL_PORT}"
+        cs = f"Driver={{{driver}}};Server={server};Database={db.database}"
+    elif db_type == "freetds":
+        if not (db.host and db.database):
+            raise ConfigError(f"[{db.section}] freetds needs Host+Database (or ConnectionString/DSN)")
+        driver = db.driver or _DEFAULT_FREETDS_DRIVER
+        cs = f"Driver={{{driver}}};Server={db.host};Port={db.port or _DEFAULT_MSSQL_PORT};Database={db.database}"
+    elif db_type == "oracle-odbc":
+        if not db.driver or not db.host:
+            raise ConfigError(
+                f"[{db.section}] oracle-odbc needs Driver+Host (+Port/Service) or ConnectionString/DSN"
+            )
+        target = f"{db.host}:{db.port or 1521}/{db.service or db.sid or ''}".rstrip("/")
+        cs = f"Driver={{{db.driver}}};DBQ={target}"
+    else:
+        raise ConfigError(f"[{db.section}] Type=odbc requires ConnectionString or DSN")
+
+    upper = cs.upper()
+    if db.username and "UID=" not in upper:
+        cs += f";UID={db.username}"
+    if db.password and "PWD=" not in upper:
+        cs += f";PWD={db.password}"
+    return cs
+
+
+class PyodbcConnector(Connector):
+    paramstyle = "qmark"
+
+    def __init__(self, db_type: str):
+        self.db_type = db_type
+
+    def connect(self, db: DBConfig) -> Any:
+        try:
+            import pyodbc
+        except ImportError:
+            raise ExportError(
+                f"Type={self.db_type} requires the pyodbc package (pip install pyodbc)"
+            ) from None
+        cs = build_connection_string(db, self.db_type)
+        try:
+            conn = pyodbc.connect(cs, autocommit=True)  # export is read-only
+        except pyodbc.Error as exc:
+            raise ExportError(f"cannot connect to [{db.section}]: {exc}") from exc
+        encoding = db.encoding or "utf-8"
+        conn.setdecoding(pyodbc.SQL_CHAR, encoding=encoding)
+        conn.setdecoding(pyodbc.SQL_WCHAR, encoding="utf-16le" if not db.encoding else encoding)
+        return conn
+
+    def describe(self, cursor: Any, sample_rows: Sequence[Sequence[Any]] = ()) -> List[ColumnInfo]:
+        if cursor.description is None:
+            return []
+        return [from_pyodbc_description(d) for d in cursor.description]

ping_dataexport/db/sqlite_connector.py

@@ -0,0 +1,61 @@
+"""Native SQLite connector (stdlib sqlite3) — Type=sqlite.
+
+Zero-dependency; powers the integration test suite. Opens the database file
+read-only via URI mode so an export can never modify the source.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any, List, Sequence
+
+from ..config import DBConfig
+from ..errors import ConfigError, ExportError
+from .connector import ColumnInfo, Connector
+from .type_map import from_sqlite_sample
+
+
+class SqliteConnector(Connector):
+    paramstyle = "qmark"
+    authoritative_types = False  # kinds inferred from sample values
+
+    def connect(self, db: DBConfig) -> sqlite3.Connection:
+        if db.connection_string and db.connection_string.startswith("file:"):
+            uri = db.connection_string
+        else:
+            raw = db.database or db.connection_string
+            if not raw:
+                raise ConfigError(f"[{db.section}] Type=sqlite requires Database=<file path>")
+            path = Path(raw).expanduser()
+            if not path.is_file():
+                raise ExportError(f"sqlite database file not found: {path}")
+            uri = f"file:{path.resolve().as_posix()}?mode=ro"
+        try:
+            return sqlite3.connect(uri, uri=True)
+        except sqlite3.Error as exc:
+            raise ExportError(f"cannot open sqlite database {uri}: {exc}") from exc
+
+    def adapt_params(self, params: Sequence[Any]) -> Sequence[Any]:
+        """sqlite3 stores dates as TEXT and (3.12+) has no default date adapters:
+        bind date/datetime as ISO strings so comparisons match the stored form."""
+        import datetime
+
+        adapted = []
+        for p in params:
+            if isinstance(p, datetime.datetime):
+                adapted.append(p.isoformat(sep=" "))
+            elif isinstance(p, datetime.date):
+                adapted.append(p.isoformat())
+            else:
+                adapted.append(p)
+        return adapted
+
+    def describe(self, cursor: Any, sample_rows: Sequence[Sequence[Any]] = ()) -> List[ColumnInfo]:
+        if cursor.description is None:
+            return []
+        columns: List[ColumnInfo] = []
+        for idx, desc in enumerate(cursor.description):
+            values = [row[idx] for row in sample_rows]
+            columns.append(from_sqlite_sample(desc[0], values))
+        return columns

ping_dataexport/db/type_map.py

@@ -0,0 +1,118 @@
+"""Driver type codes -> canonical ColumnInfo kinds.
+
+Pure functions, no driver imports: pyodbc's type codes are plain Python types and
+oracledb's are matched by their DB_TYPE_* names, so everything here is unit-testable
+without any driver installed.
+"""
+
+from __future__ import annotations
+
+import datetime
+import decimal
+import re
+from typing import Any, Optional, Sequence
+
+from .connector import (
+    BIGINT,
+    BINARY,
+    BOOL,
+    DATE,
+    DECIMAL,
+    DOUBLE,
+    FLOAT,
+    STRING,
+    TIME,
+    TIMESTAMP,
+    ColumnInfo,
+)
+
+_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+_TIMESTAMP_RE = re.compile(r"^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(:\d{2}(\.\d+)?)?$")
+
+#: Oracle NUMBER with scale 0 up to this precision stays an integer (int64-safe).
+_MAX_INT64_PRECISION = 18
+
+
+def from_pyodbc_description(desc_row: Sequence[Any]) -> ColumnInfo:
+    """pyodbc description entry: (name, type_code, display, internal, precision, scale, nullok).
+
+    pyodbc type codes are the Python types the driver will produce.
+    """
+    name = desc_row[0]
+    code = desc_row[1]
+    precision = desc_row[4] if len(desc_row) > 4 else None
+    scale = desc_row[5] if len(desc_row) > 5 else None
+    if code is bool:
+        return ColumnInfo(name, BOOL)
+    if code is int:
+        return ColumnInfo(name, BIGINT)
+    if code is float:
+        return ColumnInfo(name, DOUBLE)
+    if code is decimal.Decimal:
+        return ColumnInfo(name, DECIMAL, precision=precision or 38, scale=scale or 0)
+    if code is datetime.date:
+        return ColumnInfo(name, DATE)
+    if code is datetime.time:
+        return ColumnInfo(name, TIME)
+    if code is datetime.datetime:
+        return ColumnInfo(name, TIMESTAMP)
+    if code in (bytes, bytearray, memoryview):
+        return ColumnInfo(name, BINARY)
+    return ColumnInfo(name, STRING)
+
+
+def from_oracledb_description(desc_row: Sequence[Any]) -> ColumnInfo:
+    """oracledb FetchInfo/tuple entry; type matched by DB_TYPE_* name (no import needed)."""
+    name = desc_row[0]
+    type_name = getattr(desc_row[1], "name", str(desc_row[1])).upper()
+    precision: Optional[int] = desc_row[4] if len(desc_row) > 4 else None
+    scale: Optional[int] = desc_row[5] if len(desc_row) > 5 else None
+
+    if "NUMBER" in type_name:
+        p = precision or 0
+        s = scale if scale is not None else 0
+        if p == 0 and s in (0, -127):
+            # Unconstrained NUMBER — p/s unknown, downcast to DOUBLE (documented).
+            return ColumnInfo(name, DOUBLE)
+        if s == 0 and p <= _MAX_INT64_PRECISION:
+            return ColumnInfo(name, BIGINT)
+        return ColumnInfo(name, DECIMAL, precision=p, scale=max(s, 0))
+    if "BINARY_DOUBLE" in type_name:
+        return ColumnInfo(name, DOUBLE)
+    if "BINARY_FLOAT" in type_name:
+        return ColumnInfo(name, FLOAT)
+    if "TIMESTAMP" in type_name or type_name.endswith("DB_TYPE_DATE"):
+        # Oracle DATE carries a time component -> TIMESTAMP
+        return ColumnInfo(name, TIMESTAMP)
+    if any(k in type_name for k in ("RAW", "BLOB")):
+        return ColumnInfo(name, BINARY)
+    if "BOOLEAN" in type_name:
+        return ColumnInfo(name, BOOL)
+    return ColumnInfo(name, STRING)
+
+
+def from_sqlite_sample(name: str, sample_values: Sequence[Any]) -> ColumnInfo:
+    """sqlite3 has no type codes: infer from the first non-NULL value of the first batch.
+
+    ISO-formatted strings are promoted to DATE/TIMESTAMP (the values themselves stay
+    strings from the driver; the writers convert). All-NULL columns fall back to STRING.
+    """
+    for value in sample_values:
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            return ColumnInfo(name, BOOL)
+        if isinstance(value, int):
+            return ColumnInfo(name, BIGINT)
+        if isinstance(value, float):
+            return ColumnInfo(name, DOUBLE)
+        if isinstance(value, (bytes, bytearray, memoryview)):
+            return ColumnInfo(name, BINARY)
+        if isinstance(value, str):
+            if _DATE_RE.match(value):
+                return ColumnInfo(name, DATE)
+            if _TIMESTAMP_RE.match(value):
+                return ColumnInfo(name, TIMESTAMP)
+            return ColumnInfo(name, STRING)
+        return ColumnInfo(name, STRING)
+    return ColumnInfo(name, STRING)

ping_dataexport/errors.py

@@ -0,0 +1,19 @@
+"""Exception hierarchy. Library code raises these; only __main__ maps them to exit codes."""
+
+from __future__ import annotations
+
+
+class PingExportError(Exception):
+    """Base for all errors raised by ping_dataexport."""
+
+
+class ConfigError(PingExportError):
+    """config.ini / job.ini is missing, unreadable, or has invalid values."""
+
+
+class JobValidationError(PingExportError):
+    """A job spec violates the argument/mode rules (the table in job/validator.py)."""
+
+
+class ExportError(PingExportError):
+    """A runtime export failure: connection, query, filesystem, writer."""

ping_dataexport/export/engine.py

@@ -0,0 +1,170 @@
+"""ExportEngine — THE export loop, shared by every mode and both dispatch paths.
+
+Responsibilities: run the planner, execute each partition, stream rows in
+fetchmany batches to the RowWriter, rotate files for splitrow, log progress every
+fetch_size rows and every partition's final count, handle --test / console
+preview, call the plan's on_success (watermark state) only after full success.
+"""
+
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, List, Optional, Sequence
+
+from ..applogger import AppLogger
+from ..db.connector import ColumnInfo, Connector
+from ..errors import ExportError
+from ..planner.base import Partition, for_options
+from ..writer.base import RowWriter
+from ..writer.delimited import render_value
+from .options import ExportOptions
+from .util import build_text_cleaner, output_filename
+
+WriterFactory = Callable[[ExportOptions, str], RowWriter]
+
+
+@dataclass
+class ExportStats:
+    partitions: int = 0
+    rows: int = 0
+    files: List[Path] = field(default_factory=list)
+
+
+class ExportEngine:
+    def __init__(
+        self,
+        options: ExportOptions,
+        connector: Connector,
+        conn: Any,
+        logger: AppLogger,
+        writer_factory: WriterFactory,
+    ):
+        self.options = options
+        self.connector = connector
+        self.conn = conn
+        self.logger = logger
+        self.writer_factory = writer_factory
+        self.data_date = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    def run(self) -> ExportStats:
+        plan = for_options(self.options).plan(self.options, self.conn, self.connector, self.logger)
+        stats = ExportStats()
+        for partition in plan.partitions:
+            rows, files = self._run_partition(partition)
+            stats.partitions += 1
+            stats.rows += rows
+            stats.files.extend(files)
+        if plan.on_success is not None and not self.options.test:
+            plan.on_success()
+        return stats
+
+    # -- one partition ------------------------------------------------------
+
+    def _run_partition(self, partition: Partition) -> "tuple[int, List[Path]]":
+        opts = self.options
+        if partition.where_display:
+            self.logger.info("EXPORT", "PARTITION", partition.where_display)
+        elif partition.label:
+            self.logger.info("EXPORT", "PARTITION", partition.label)
+
+        sql = self.connector.rewrite_params(partition.query)
+        params = self.connector.adapt_params(partition.params)
+        cursor = self.connector.prepare_cursor(self.conn, opts.fetch_size)
+        try:
+            try:
+                cursor.execute(sql, params) if params else cursor.execute(sql)
+            except Exception as exc:
+                raise ExportError(f"query failed: {exc}") from exc
+            first_batch = cursor.fetchmany(opts.fetch_size)
+            columns = self.connector.describe(cursor, first_batch)
+
+            if opts.test or opts.is_console:
+                rows = self._preview(first_batch, columns, cursor)
+                self.logger.info("TEST" if opts.test else "EXPORT", "PREVIEW",
+                                 f"{rows:,} row(s) shown")
+                return rows, []
+            return self._write_partition(partition, cursor, first_batch, columns)
+        finally:
+            cursor.close()
+
+    def _write_partition(
+        self,
+        partition: Partition,
+        cursor: Any,
+        first_batch: Sequence[Sequence[Any]],
+        columns: List[ColumnInfo],
+    ) -> "tuple[int, List[Path]]":
+        opts = self.options
+        split = opts.mode == "splitrow"
+        files: List[Path] = []
+        writer: Optional[RowWriter] = None
+        row_id = 0
+        rows_in_part = 0
+        part_no = 0
+
+        def open_writer() -> RowWriter:
+            nonlocal part_no, rows_in_part
+            part_no += 1
+            if split:
+                path = Path(opts.output_dir) / output_filename(
+                    opts.base_name, str(part_no), opts.format, opts.gzip
+                )
+            elif partition.filename is not None:
+                path = Path(opts.output_dir) / partition.filename
+            else:
+                path = Path(opts.output_path)
+            w = self.writer_factory(opts, self.data_date)
+            w.open(path, columns)
+            files.append(path)
+            self.logger.info("EXPORT", "FILE", str(path))
+            rows_in_part = 0
+            return w
+
+        try:
+            writer = open_writer()
+            batch: Sequence[Sequence[Any]] = first_batch
+            while batch:
+                for row in batch:
+                    if split and rows_in_part >= opts.split_rows:
+                        writer.close()
+                        writer = open_writer()
+                    row_id += 1
+                    rows_in_part += 1
+                    writer.write_row(row, row_id)
+                self.logger.info("EXPORT", "PROGRESS", f"{row_id:,} rows")
+                batch = cursor.fetchmany(opts.fetch_size)
+            writer.close()
+        except Exception:
+            if writer is not None:
+                writer.abort()
+            raise
+        self.logger.info("EXPORT", "PROGRESS", f"{row_id:,} rows (finished)")
+        return row_id, files
+
+    # -- preview (test mode + console output) --------------------------------
+
+    def _preview(
+        self,
+        first_batch: Sequence[Sequence[Any]],
+        columns: List[ColumnInfo],
+        cursor: Any,
+    ) -> int:
+        opts = self.options
+        limit = opts.preview_row
+        clean = build_text_cleaner(opts.stripnewline, opts.stripmetachar)
+        print(" | ".join(c.name for c in columns))
+        shown = 0
+        batch = first_batch
+        while batch and shown < limit:
+            for row in batch:
+                if shown >= limit:
+                    break
+                print(" | ".join(render_value(v, clean) for v in row))
+                shown += 1
+            if shown < limit:
+                batch = cursor.fetchmany(opts.fetch_size)
+            else:
+                break
+        return shown

ping_dataexport/export/options.py

@@ -0,0 +1,48 @@
+"""ExportOptions — the resolved, execution-ready options passed to engine/planners/writers.
+
+Built by JobExecutor from JobSpec + SharedContext ([Main] defaults filled in,
+paths resolved). Everything downstream reads only this object.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+@dataclass(frozen=True)
+class ExportOptions:
+    job_name: str
+    source: str
+    query: str
+    format: Optional[str]  # 'csv' | 'txt' | 'parquet' | None = console preview
+    output_path: Optional[Path] = None  # resolved single output file
+    output_dir: Optional[Path] = None  # resolved directory for mode exports
+    base_name: Optional[str] = None
+    gzip: bool = False
+    quote: str = '"'
+    sep: str = ","
+    stripnewline: Optional[str] = None
+    stripmetachar: bool = False
+    fetch_size: int = 10000
+    preview_row: int = 10
+    mode: Optional[str] = None
+    column: Optional[str] = None
+    split_rows: int = 100000
+    dates: Tuple[date, ...] = ()
+    datefrom: Optional[date] = None
+    dateto: Optional[date] = None
+    monthsrelative: Optional[int] = None
+    row_id_column: Optional[str] = None
+    data_date_column: Optional[str] = None
+    test: bool = False
+
+    @property
+    def is_console(self) -> bool:
+        return self.output_path is None and self.output_dir is None
+
+    @property
+    def is_delimited(self) -> bool:
+        return self.format in ("csv", "txt")