ping-dataexport 0.1.0__py3-none-any.whl

ping_dataexport/export/runner.py

@@ -0,0 +1,50 @@
+"""ExportRunner — connect via the connector, pick the writer, run the engine.
+
+Format registry: to add a new output format, add one RowWriter class in writer/
+and one entry in WRITER_REGISTRY.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict
+
+from ..applogger import AppLogger
+from ..config import DBConfig
+from ..db.connector import create_connector
+from ..writer.base import RowWriter
+from ..writer.delimited import DelimitedRowWriter
+from ..writer.parquet import ParquetRowWriter
+from .engine import ExportEngine, ExportStats
+from .options import ExportOptions
+
+WRITER_REGISTRY: Dict[str, Callable[[ExportOptions, str], RowWriter]] = {
+    "csv": DelimitedRowWriter,
+    "txt": DelimitedRowWriter,
+    "parquet": ParquetRowWriter,
+}
+
+
+class ExportRunner:
+    def __init__(self, logger: AppLogger):
+        self.logger = logger
+
+    def run(self, options: ExportOptions, db: DBConfig) -> ExportStats:
+        connector = create_connector(db.type)
+        for key, value in db.safe_items():
+            self.logger.info("DATABASE", "PROPERTY", f"{key}={value}")
+        conn = connector.connect(db)
+        self.logger.info("DATABASE", "CONNECTED", db.name)
+        try:
+            engine = ExportEngine(options, connector, conn, self.logger, self._writer_factory)
+            return engine.run()
+        finally:
+            conn.close()
+            self.logger.info("DATABASE", "DISCONNECTED", db.name)
+
+    @staticmethod
+    def _writer_factory(options: ExportOptions, data_date: str) -> RowWriter:
+        try:
+            factory = WRITER_REGISTRY[options.format]
+        except KeyError:
+            raise ValueError(f"no writer for format {options.format!r}") from None
+        return factory(options, data_date)

ping_dataexport/export/util.py

@@ -0,0 +1,65 @@
+"""Filename building + text-cleanup helpers shared by writers and planners."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+
+#: chars illegal in filenames on Windows/POSIX -> '_' (groupby values become suffixes)
+_ILLEGAL_FILENAME_CHARS = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+
+#: invisible/control characters removed by --stripmetachar (string columns only):
+#: control chars, DEL, NBSP, zero-width space/joiners, BOM
+_META_CHARS = (
+    "".join(chr(c) for c in range(0x00, 0x09))
+    + "\x0b\x0c"
+    + "".join(chr(c) for c in range(0x0e, 0x20))
+    + "\x7f\xa0\u200b\u200c\u200d\ufeff"
+)
+_META_TABLE = {ord(c): None for c in _META_CHARS}
+
+
+def sanitize_suffix(value: str) -> str:
+    """Make a partition value safe as a filename suffix."""
+    return _ILLEGAL_FILENAME_CHARS.sub("_", value)
+
+
+def output_filename(
+    base_name: str, suffix: Optional[str], format_: str, gzip: bool
+) -> str:
+    """base[_suffix].ext[.gz] — gzip suffix applies to delimited formats only."""
+    ext = {"csv": ".csv", "txt": ".txt", "parquet": ".parquet"}[format_]
+    stem = base_name if suffix is None else f"{base_name}_{sanitize_suffix(suffix)}"
+    name = stem + ext
+    if gzip and format_ != "parquet":
+        name += ".gz"
+    return name
+
+
+def build_text_cleaner(stripnewline: Optional[str], stripmetachar: bool):
+    """Returns clean(text)->text applying the strip rules; identity when both off.
+
+    Applies to string-typed column values only, for BOTH delimited and Parquet output.
+    """
+
+    def clean(value: str) -> str:
+        if stripmetachar:
+            value = value.translate(_META_TABLE)
+        if stripnewline == "space":
+            value = value.replace("\r\n", " ").replace("\n", " ").replace("\r", " ")
+        elif stripnewline == "blank":
+            value = value.replace("\r\n", "").replace("\n", "").replace("\r", "")
+        elif stripnewline == "escape":
+            value = value.replace("\r\n", "\\n").replace("\n", "\\n").replace("\r", "\\r")
+        elif stripnewline == "doubleescape":
+            value = value.replace("\r\n", "\\\\n").replace("\n", "\\\\n").replace("\r", "\\\\r")
+        return value
+
+    if stripnewline is None and not stripmetachar:
+        return lambda value: value
+    return clean
+
+
+def part_path(directory: Path, base_name: str, suffix: str, format_: str, gzip: bool) -> Path:
+    return directory / output_filename(base_name, suffix, format_, gzip)

ping_dataexport/job/executor.py

@@ -0,0 +1,107 @@
+"""JobExecutor — resolve paths -> removeexisting -> DB config -> ExportOptions -> run.
+
+Assumes the spec has already passed JobValidator (both dispatch paths validate).
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Optional
+
+from ..config import DBConfig
+from ..export.options import ExportOptions
+from ..export.runner import ExportRunner
+from ..export.engine import ExportStats
+from .shared_context import SharedContext
+from .spec import JobSpec
+
+
+class JobExecutor:
+    def __init__(self, ctx: SharedContext):
+        self.ctx = ctx
+
+    def execute(self, spec: JobSpec) -> ExportStats:
+        logger = self.ctx.logger
+        logger.set_job_name(spec.name)
+        self._open_job_log(spec)
+        started = time.monotonic()
+        try:
+            logger.info("CONFIG", "JOB", f"source={spec.source} mode={spec.mode or 'single'}"
+                        + (" TEST" if spec.test else ""))
+            options = self._resolve(spec)
+            if options.output_dir is not None and spec.removeexisting and not spec.test:
+                removed = self.ctx.resolver.remove_existing(options.output_dir)
+                logger.info("PATH", "REMOVEEXISTING", f"{removed} entries removed "
+                            f"from {options.output_dir}")
+            db = DBConfig.from_reader(self.ctx.reader, spec.source)
+            stats = ExportRunner(logger).run(options, db)
+            elapsed = time.monotonic() - started
+            logger.info("RESULT", "COMPLETED", f"{elapsed:.1f} seconds")
+            return stats
+        except Exception as exc:
+            logger.error("RESULT", "FAILED", str(exc))
+            raise
+        finally:
+            logger.close_job_file()
+
+    # -- helpers ------------------------------------------------------------
+
+    def _open_job_log(self, spec: JobSpec) -> None:
+        """Log-file priority: CLI --logfile > config LogFile > default path > stdout-only."""
+        path: Optional[Path] = None
+        if spec.logfile:
+            path = self.ctx.resolver.resolve(spec.logfile)
+        elif self.ctx.main.log_file:
+            path = self.ctx.resolver.resolve(self.ctx.main.log_file)
+        else:
+            default = self.ctx.resolver.default_log_path(spec.name)
+            if default is not None:
+                path = default
+        if path is not None:
+            self.ctx.logger.open_job_file(path)
+
+    def _resolve(self, spec: JobSpec) -> ExportOptions:
+        resolver = self.ctx.resolver
+        main = self.ctx.main
+        output_path = None
+        output_dir = None
+        if spec.output is not None:
+            output_path = resolver.resolve(spec.output)
+            if spec.gzip and spec.format != "parquet" and output_path.suffix != ".gz":
+                output_path = output_path.with_name(output_path.name + ".gz")
+            if not spec.test:
+                resolver.ensure_parent_dir(output_path)
+            self.ctx.logger.info("PATH", "OUTPUT", str(output_path))
+        elif spec.outputdir is not None:
+            output_dir = resolver.resolve(spec.outputdir)
+            if not spec.test:
+                resolver.ensure_dir(output_dir)
+            self.ctx.logger.info("PATH", "OUTPUTDIR", str(output_dir))
+
+        return ExportOptions(
+            job_name=spec.name,
+            source=spec.source,
+            query=spec.query,
+            format=spec.format,
+            output_path=output_path,
+            output_dir=output_dir,
+            base_name=spec.basename,
+            gzip=spec.gzip,
+            quote=spec.quote,
+            sep=spec.sep,
+            stripnewline=spec.stripnewline,
+            stripmetachar=spec.stripmetachar,
+            fetch_size=spec.fetchsize or main.fetch_size,
+            preview_row=main.preview_row,
+            mode=spec.mode,
+            column=spec.column,
+            split_rows=spec.row,
+            dates=spec.dates,
+            datefrom=spec.datefrom,
+            dateto=spec.dateto,
+            monthsrelative=spec.monthsrelative,
+            row_id_column=main.row_id_column,
+            data_date_column=main.data_date_column,
+            test=spec.test,
+        )

ping_dataexport/job/shared_context.py

@@ -0,0 +1,22 @@
+"""SharedContext — config.ini [Main] defaults computed once, shared across jobs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Union
+
+from ..applogger import AppLogger
+from ..config import ConfigReader, MainConfig
+from ..paths import PathResolver
+
+
+class SharedContext:
+    def __init__(self, config_path: Union[str, Path], logger: AppLogger):
+        self.config_path = Path(config_path)
+        self.reader = ConfigReader(self.config_path)
+        self.main = MainConfig.from_reader(self.reader)
+        self.resolver = PathResolver(
+            export_folder=self.main.export_folder,
+            force_make_dir=self.main.force_make_dir,
+        )
+        self.logger = logger

ping_dataexport/job/spec.py

@@ -0,0 +1,251 @@
+"""JobSpec (frozen, validated) + JobSpecBuilder (CLI > job.ini > [Main] > defaults)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from datetime import date, datetime, timedelta
+from typing import Optional, Tuple
+
+from ..cli import CliArgs
+from ..config import ConfigReader, MainConfig
+from ..errors import JobValidationError
+
+DEFAULT_QUOTE = '"'
+DEFAULT_SEP = ","
+DEFAULT_SPLIT_ROWS = 100000
+
+_TRUEISH = {"yes", "true", "1", "y", "on"}
+_FALSEISH = {"no", "false", "0", "n", "off"}
+
+#: job.ini key per CliArgs/JobSpec field
+_JOB_KEYS = {
+    "name": "Name",
+    "source": "Source",
+    "query": "Query",
+    "output": "Output",
+    "outputdir": "OutputDir",
+    "basename": "BaseName",
+    "format": "Format",
+    "gzip": "Gzip",
+    "quote": "Quote",
+    "sep": "Sep",
+    "stripnewline": "StripNewLine",
+    "stripmetachar": "StripMetaChar",
+    "fetchsize": "FetchSize",
+    "mode": "Mode",
+    "column": "Column",
+    "row": "Row",
+    "datefrom": "DateFrom",
+    "dateto": "DateTo",
+    "daysrelative": "DaysRelative",
+    "monthsrelative": "MonthsRelative",
+    "removeexisting": "RemoveExisting",
+}
+
+
+@dataclass(frozen=True)
+class JobSpec:
+    """Immutable description of one job after layered resolution.
+
+    `format` is the resolved output format ('csv' | 'txt' | 'parquet') or None for
+    console preview. `dates` is the pre-built inclusive date list for the
+    date/relativedate modes.
+    """
+
+    name: str
+    source: Optional[str]
+    query: Optional[str]
+    output: Optional[str] = None
+    outputdir: Optional[str] = None
+    basename: Optional[str] = None
+    format: Optional[str] = None
+    gzip: bool = False
+    quote: str = DEFAULT_QUOTE
+    sep: str = DEFAULT_SEP
+    stripnewline: Optional[str] = None
+    stripmetachar: bool = False
+    fetchsize: Optional[int] = None  # None -> [Main] FetchSize at execution
+    mode: Optional[str] = None
+    column: Optional[str] = None
+    row: int = DEFAULT_SPLIT_ROWS
+    datefrom: Optional[date] = None
+    dateto: Optional[date] = None
+    daysrelative: Optional[int] = None
+    monthsrelative: Optional[int] = None
+    removeexisting: bool = False
+    test: bool = False
+    logfile: Optional[str] = None
+    dates: Tuple[date, ...] = ()
+
+    @property
+    def is_console(self) -> bool:
+        return self.output is None and self.outputdir is None
+
+
+def parse_strict_date(value: str, *, what: str) -> date:
+    """Strict yyyy-MM-dd — anything else is a validation error (exit 1)."""
+    try:
+        parsed = datetime.strptime(value.strip(), "%Y-%m-%d").date()
+    except ValueError:
+        raise JobValidationError(f"{what} must be yyyy-MM-dd, got {value!r}") from None
+    # strptime accepts e.g. '2026-1-2'; enforce the canonical zero-padded form
+    if parsed.isoformat() != value.strip():
+        raise JobValidationError(f"{what} must be yyyy-MM-dd, got {value!r}")
+    return parsed
+
+
+def _parse_boolish(value: str, *, what: str) -> bool:
+    v = value.strip().lower()
+    if v in _TRUEISH:
+        return True
+    if v in _FALSEISH:
+        return False
+    raise JobValidationError(f"{what} must be Yes/No or True/False, got {value!r}")
+
+
+def _parse_intish(value: str, *, what: str) -> int:
+    try:
+        return int(str(value).strip())
+    except ValueError:
+        raise JobValidationError(f"{what} must be an integer, got {value!r}") from None
+
+
+class JobSpecBuilder:
+    """Layered resolution: CLI args > job.ini section > config.ini [Main] > defaults."""
+
+    def __init__(
+        self,
+        cli: CliArgs,
+        main: MainConfig,
+        job_reader: Optional[ConfigReader] = None,
+        *,
+        today: Optional[date] = None,
+    ):
+        self.cli = cli
+        self.main = main
+        self.job_reader = job_reader
+        self.today = today or date.today()
+
+    def build(self, section: Optional[str] = None) -> JobSpec:
+        """Build the spec for one job section (or pure ad-hoc CLI when section is None)."""
+        if section is not None:
+            if self.job_reader is None:
+                raise JobValidationError(f"--job {section} given but no job file was loaded")
+            if not self.job_reader.has_section(section):
+                raise JobValidationError(
+                    f"job section [{section}] not found in {self.job_reader.path}"
+                )
+
+        def layered(field: str) -> Optional[str]:
+            cli_value = getattr(self.cli, field)
+            if cli_value is not None:
+                return str(cli_value) if not isinstance(cli_value, bool) else "Yes"
+            if section is not None:
+                job_value = self.job_reader.get(section, _JOB_KEYS[field])
+                if job_value is not None and job_value.strip() != "":
+                    return job_value.strip() if field != "query" else job_value
+            return None
+
+        mode = layered("mode")
+        if mode is not None:
+            mode = mode.lower()
+
+        name = (
+            layered("name")
+            or (section if section is not None else None)
+            or "JOB_" + datetime.now().strftime("%Y%m%d_%H%M%S")
+        )
+
+        gzip_v = layered("gzip")
+        stripmeta_v = layered("stripmetachar")
+        remove_v = layered("removeexisting")
+        fetch_v = layered("fetchsize")
+        row_v = layered("row")
+        days_v = layered("daysrelative")
+        months_v = layered("monthsrelative")
+        datefrom_v = layered("datefrom")
+        dateto_v = layered("dateto")
+
+        datefrom = parse_strict_date(datefrom_v, what="--datefrom") if datefrom_v else None
+        dateto = parse_strict_date(dateto_v, what="--dateto") if dateto_v else None
+        if mode == "monthbydate" and datefrom is None:
+            datefrom = self.today  # anchor defaults to today
+
+        output = layered("output")
+        outputdir = layered("outputdir")
+        basename = layered("basename")
+        fmt = layered("format")
+        if fmt is not None:
+            fmt = fmt.lower()
+            if fmt == "text":
+                fmt = "txt"
+
+        sep = layered("sep")
+        if sep is not None and sep == "\\t":
+            sep = "\t"
+
+        spec = JobSpec(
+            name=name,
+            source=layered("source"),
+            query=layered("query"),
+            output=output,
+            outputdir=outputdir,
+            basename=basename,
+            format=self._resolve_format(fmt, output, outputdir),
+            gzip=_parse_boolish(gzip_v, what="Gzip") if gzip_v is not None else False,
+            quote=layered("quote") if layered("quote") is not None else DEFAULT_QUOTE,
+            sep=sep if sep is not None else DEFAULT_SEP,
+            stripnewline=(layered("stripnewline") or None),
+            stripmetachar=(
+                _parse_boolish(stripmeta_v, what="StripMetaChar") if stripmeta_v else False
+            ),
+            fetchsize=_parse_intish(fetch_v, what="FetchSize") if fetch_v else None,
+            mode=mode,
+            column=layered("column"),
+            row=_parse_intish(row_v, what="Row") if row_v else DEFAULT_SPLIT_ROWS,
+            datefrom=datefrom,
+            dateto=dateto,
+            daysrelative=_parse_intish(days_v, what="DaysRelative") if days_v else None,
+            monthsrelative=_parse_intish(months_v, what="MonthsRelative") if months_v else None,
+            removeexisting=(
+                _parse_boolish(remove_v, what="RemoveExisting") if remove_v else False
+            ),
+            test=self.cli.test,
+            logfile=self.cli.logfile,
+        )
+        return self._with_dates(spec)
+
+    @staticmethod
+    def _resolve_format(
+        fmt: Optional[str], output: Optional[str], outputdir: Optional[str]
+    ) -> Optional[str]:
+        if fmt is not None:
+            return fmt
+        if output is not None:
+            lower = output.lower()
+            if lower.endswith(".gz"):
+                lower = lower[:-3]
+            for ext, resolved in ((".csv", "csv"), (".txt", "txt"), (".parquet", "parquet")):
+                if lower.endswith(ext):
+                    return resolved
+            return "csv"
+        if outputdir is not None:
+            return "csv"
+        return None  # console preview
+
+    def _with_dates(self, spec: JobSpec) -> JobSpec:
+        """Pre-build the inclusive date list for date/relativedate (Python, never SQL)."""
+        dates: Tuple[date, ...] = ()
+        if spec.mode == "date" and spec.datefrom and spec.dateto and spec.datefrom <= spec.dateto:
+            dates = tuple(
+                spec.datefrom + timedelta(days=i)
+                for i in range((spec.dateto - spec.datefrom).days + 1)
+            )
+        elif spec.mode == "relativedate" and spec.datefrom and spec.daysrelative is not None:
+            start = spec.datefrom - timedelta(days=spec.daysrelative)
+            dates = tuple(
+                start + timedelta(days=i) for i in range((spec.datefrom - start).days + 1)
+            )
+        if dates:
+            return replace(spec, dates=dates)
+        return spec

ping_dataexport/job/validator.py

@@ -0,0 +1,87 @@
+"""JobValidator — the full mode/argument rule table.
+
+One place for every mode/argument rule, enforced identically for the sequential
+path and every parallel job section. Raises JobValidationError; __main__ maps it
+to exit code 1.
+"""
+
+from __future__ import annotations
+
+from ..cli import MODES, STRIP_NEWLINE_MODES
+from ..errors import JobValidationError
+from .spec import JobSpec
+
+_MODES_NEEDING_COLUMN = {"groupby", "date", "relativedate", "watermark", "monthbydate"}
+
+
+class JobValidator:
+    @staticmethod
+    def validate(spec: JobSpec) -> None:
+        e = JobValidator._error
+
+        if not spec.source:
+            e(spec, "--source is required (or provide Source in the job section)")
+        if not spec.query:
+            e(spec, "--query is required (or provide Query in the job section)")
+
+        if spec.output and (spec.outputdir or spec.basename):
+            e(spec, "--output cannot be mixed with --outputdir/--basename")
+
+        if spec.mode:
+            if spec.mode not in MODES:
+                e(spec, f"unknown mode {spec.mode!r} (expected one of: {', '.join(MODES)})")
+            if not (spec.outputdir and spec.basename):
+                e(spec, f"--mode {spec.mode} requires both --outputdir and --basename")
+        elif spec.outputdir or spec.basename:
+            e(spec, "--outputdir/--basename require --mode")
+
+        if spec.mode in _MODES_NEEDING_COLUMN and not spec.column:
+            e(spec, f"--mode {spec.mode} requires --column")
+
+        if spec.mode == "date":
+            if not (spec.datefrom and spec.dateto):
+                e(spec, "--mode date requires --datefrom and --dateto")
+            if spec.datefrom > spec.dateto:
+                e(spec, f"--datefrom {spec.datefrom} is after --dateto {spec.dateto}")
+        if spec.mode == "relativedate":
+            if not spec.datefrom or spec.daysrelative is None:
+                e(spec, "--mode relativedate requires --datefrom and --daysrelative")
+            if spec.daysrelative < 0:
+                e(spec, "--daysrelative must be >= 0")
+        if spec.mode == "monthbydate":
+            if spec.monthsrelative is None:
+                e(spec, "--mode monthbydate requires --monthsrelative")
+            if spec.monthsrelative < 0:
+                e(spec, "--monthsrelative must be >= 0")
+        if spec.mode == "splitrow" and spec.row <= 0:
+            e(spec, "--row must be > 0")
+
+        if spec.removeexisting:
+            if not spec.mode:
+                e(spec, "--removeexisting requires --mode")
+            if spec.mode == "watermark":
+                e(spec, "--removeexisting is blocked with watermark (would destroy state)")
+
+        if spec.gzip and spec.format == "parquet":
+            e(spec, "--gzip cannot be used with parquet (built-in compression)")
+
+        if spec.stripnewline and spec.stripnewline not in STRIP_NEWLINE_MODES:
+            e(
+                spec,
+                f"unknown stripnewline {spec.stripnewline!r} "
+                f"(expected one of: {', '.join(STRIP_NEWLINE_MODES)})",
+            )
+
+        if spec.format in ("csv", "txt"):
+            effective_sep = "\t" if spec.format == "txt" else spec.sep
+            if spec.quote == effective_sep:
+                e(spec, "quote character must differ from the separator")
+            if len(spec.sep) != 1 or len(spec.quote) != 1:
+                e(spec, "separator and quote must each be a single character")
+
+        if spec.fetchsize is not None and spec.fetchsize <= 0:
+            e(spec, "--fetchsize must be > 0")
+
+    @staticmethod
+    def _error(spec: JobSpec, message: str) -> None:
+        raise JobValidationError(f"job {spec.name}: {message}")

ping_dataexport/paths.py

@@ -0,0 +1,71 @@
+"""PathResolver: ExportFolder defaulting, ForceMakeDir, guarded removeexisting."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Optional, Union
+
+from .errors import ExportError
+
+
+class PathResolver:
+    def __init__(self, export_folder: Optional[str] = None, force_make_dir: bool = True):
+        self.export_folder = export_folder
+        self.force_make_dir = force_make_dir
+
+    def resolve(self, path: Union[str, Path]) -> Path:
+        """Absolute path stays; relative path is joined under ExportFolder (or CWD)."""
+        p = Path(path).expanduser()
+        if not p.is_absolute():
+            base = Path(self.export_folder).expanduser() if self.export_folder else Path.cwd()
+            p = base / p
+        return p.resolve()
+
+    def ensure_dir(self, dir_path: Union[str, Path]) -> Path:
+        p = Path(dir_path)
+        if p.exists():
+            if not p.is_dir():
+                raise ExportError(f"not a directory: {p}")
+            return p
+        if not self.force_make_dir:
+            raise ExportError(f"directory does not exist (ForceMakeDir=No): {p}")
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    def ensure_parent_dir(self, file_path: Union[str, Path]) -> Path:
+        p = Path(file_path)
+        self.ensure_dir(p.parent)
+        return p
+
+    @staticmethod
+    def remove_existing(dir_path: Union[str, Path]) -> int:
+        """Delete the contents of a RESOLVED directory recursively; returns entries removed.
+
+        Safety guard: refuses a filesystem root or an unresolved relative path.
+        The directory itself is kept (recreated content lands in the same dir).
+        """
+        p = Path(dir_path)
+        if not p.is_absolute():
+            raise ExportError(f"removeexisting requires a resolved absolute path, got: {p}")
+        p = p.resolve()
+        if p == Path(p.anchor):
+            raise ExportError(f"refusing removeexisting on filesystem root: {p}")
+        if not p.exists():
+            return 0
+        if not p.is_dir():
+            raise ExportError(f"removeexisting target is not a directory: {p}")
+        removed = 0
+        for child in p.iterdir():
+            if child.is_dir() and not child.is_symlink():
+                shutil.rmtree(child)
+            else:
+                child.unlink()
+            removed += 1
+        return removed
+
+    def default_log_path(self, job_name: str) -> Optional[Path]:
+        """{ExportFolder}/logs/log_{jobname}.txt — None when no ExportFolder (stdout-only)."""
+        if not self.export_folder:
+            return None
+        return Path(self.export_folder).expanduser() / "logs" / f"log_{job_name}.txt"