ping-dataexport 0.2.1__tar.gz → 0.3.0__tar.gz

{ping_dataexport-0.2.1/src/ping_dataexport.egg-info → ping_dataexport-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: ping-dataexport
-Version: 0.2.1
-Summary: Universal database data export to CSV/TXT/Parquet — streaming, typed, no pandas
+Version: 0.3.0
+Summary: PING's Data Export Tool - To Parquet/CSV/TEXT as Accelerator for Data & AI Project
 Author: vorapol
 License-Expression: Apache-2.0
 Keywords: export,database,csv,parquet,etl,data-platform,airflow
@@ -46,7 +46,7 @@ Dynamic: license-file
   `decimal128(p,s)`, คอลัมน์ int ที่มี NULL ยังคงเป็น int, วันที่ยังคงเป็นวันที่
   และไม่ใช้ pandas เด็ดขาด
 - **ฐานข้อมูลที่รองรับ** — SQLite (Library มาตรฐาน ไม่ต้องติดตั้งอะไรเพิ่ม),
-  SQL Server (MS ODBC / FreeTDS), Oracle (โหมด thin แบบเ Native หรือ ODBC)
+  SQL Server (MS ODBC / FreeTDS), Oracle (โหมด thin แบบ Native หรือ ODBC)
   และแหล่งข้อมูล ODBC ใดก็ได้
 - **ใช้งานได้สองทาง** — ผ่าน CLI `ping-dataexport` หรือผ่าน Library API (`ping_dataexport.api`)
   ที่ออกแบบมาสำหรับ Airflow
@@ -151,7 +151,7 @@ PasswordBase64=c2VjcmV0    ; base64("secret")
 file defaults to `./config.ini` (`-cf` to point elsewhere).
 
 ```bash
-# preview to the console (no -o/-od): prints the first rows
+# preview to the console (no -o/-dir): prints the first rows
 ping-dataexport -s SQLITE01 -q "SELECT * FROM sales"
 
 # single file — format inferred from the extension (.csv/.txt/.parquet)
@@ -169,11 +169,11 @@ All options:
 | `-s` | `--source` | DB config section name (e.g. `DB01`) |
 | `-q` | `--query` | SQL query |
 | `-o` | `--output` | single output file (format from extension, or `-f`) |
-| `-od` | `--outputdir` | output directory (required for `-m` modes) |
-| `-bn` | `--basename` | base filename for mode exports |
+| `-dir` | `--outputdir` | output directory (required for `-m` modes); `-od` still works as a legacy alias |
+| `-pf` | `--prefix` | output filename prefix for mode exports; `-bn`/`--basename` still work as legacy aliases |
 | `-f` | `--format` | `csv`, `txt`, `parquet` |
 | `-gz` | `--gzip` | gzip the output (CSV/TXT only) |
-| `-sp` | `--sep` | field separator (default `,`; `\t` maps to tab) |
+| `-sep` | `--sep` | field separator (default `,`; `\t` maps to tab) |
 | `-quo` | `--quote` | quote character (default `"`) |
 | `-stnl` | `--stripnewline` | newline handling in text columns: `space` \| `blank` \| `escape` \| `doubleescape` |
 | `-stmc` | `--stripmetachar` | strip invisible/control characters from text columns |
@@ -188,21 +188,37 @@ All options:
 | `-rm` | `--removeexisting` | `Yes`: clear the output directory before exporting |
 | `-j` | `--job` | run one job.ini section — see section 5 |
 | `-jf` | `--jobfile` | job file path (default `./job.ini`) |
-| `-pl` | `--parallel` | run ALL job sections in parallel with N workers (default: CPU count) |
+| `-p` | `--parallel` | run ALL job sections in parallel with N workers (default: CPU count); `-pl` still works as a legacy alias |
 | `-n` | `--name` | job name shown in logs and the default log filename |
 | `-cf` | `--configfile` | config file path (default `./config.ini`) |
 | `-lf` | `--logfile` | log file path |
 | `-t` | `--test` | test mode: validate + preview, no files |
 
+### Which options must go together
+
+| If you use… | You must also have… | Notes |
+|-------------|--------------------|-------|
+| (anything) | `-s` + `-q` | the two basics — always required, unless `-j` supplies them from a job file |
+| `-o` | nothing else | single file; **cannot** be combined with `-dir`/`-pf` |
+| `-m` (any mode) | `-dir` + `-pf` | every mode writes multiple files, so it needs a directory + filename prefix |
+| `-dir` or `-pf` | `-m` | they only make sense for mode exports |
+| `-m groupby` / `watermark` | `-col` | the column to group / track |
+| `-m date` | `-col` + `-df` + `-dt` | the date column and an explicit range |
+| `-m relativedate` | `-col` + `-dr` | `-df` optional (defaults to today) |
+| `-m monthbydate` | `-col` + `-mr` | `-df` optional (defaults to today) |
+| `-m splitrow` | `-row` | no `-col` needed |
+| `-gz` | CSV/TXT output | rejected with parquet (it compresses itself) |
+| no `-o` and no `-dir` | — | console preview only (first `PreviewRow` rows, nothing written) |
+
 ## 4. Export modes (partitioned outputs)
 
-Modes split one query into multiple files. All need `-od` (output directory)
-+ `-bn` (base filename); partition values are always bound SQL parameters.
+Modes split one query into multiple files. All need `-dir` (output directory)
++ `-pf` (filename prefix); partition values are always bound SQL parameters.
 
 **`groupby` — one file per distinct value of a column:**
 
 ```bash
-ping-dataexport -s DB01 -q "SELECT * FROM sales" -m groupby -col region -od by_region -bn sales
+ping-dataexport -s DB01 -q "SELECT * FROM sales" -m groupby -col region -dir by_region -pf sales
 ```
 ```
 by_region/
@@ -217,7 +233,7 @@ by_region/
 
 ```bash
 ping-dataexport -s DB01 -q "SELECT * FROM sales" -m date -col txn_date \
-    -df 2026-01-01 -dt 2026-01-05 -od daily -bn sales
+    -df 2026-01-01 -dt 2026-01-05 -dir daily -pf sales
 ```
 ```
 daily/
@@ -233,7 +249,7 @@ daily/
 
 ```bash
 ping-dataexport -s DB01 -q "SELECT * FROM sales" -m relativedate -col txn_date \
-    -df 2026-01-10 -dr 3 -od rel -bn sales
+    -df 2026-01-10 -dr 3 -dir rel -pf sales
 ```
 ```
 rel/
@@ -248,7 +264,7 @@ at the anchor date; omit `-df` to anchor on today):**
 
 ```bash
 ping-dataexport -s DB01 -q "SELECT * FROM sales" -m monthbydate -col txn_date \
-    -df 2026-03-15 -mr 3 -od monthly -bn sales
+    -df 2026-03-15 -mr 3 -dir monthly -pf sales
 ```
 ```
 monthly/
@@ -261,7 +277,7 @@ monthly/
 **`splitrow` — rotate to a new file every N rows:**
 
 ```bash
-ping-dataexport -s DB01 -q "SELECT * FROM sales ORDER BY id" -m splitrow -row 100000 -od split -bn part
+ping-dataexport -s DB01 -q "SELECT * FROM sales ORDER BY id" -m splitrow -row 100000 -dir split -pf part
 ```
 ```
 split/
@@ -273,7 +289,7 @@ split/
 **`watermark` — incremental: only rows newer than the last run:**
 
 ```bash
-ping-dataexport -s DB01 -q "SELECT * FROM sales" -m watermark -col txn_date -od incr -bn sales
+ping-dataexport -s DB01 -q "SELECT * FROM sales" -m watermark -col txn_date -dir incr -pf sales
 ```
 ```
 incr/
@@ -299,7 +315,7 @@ file — see *Output and logs* below):
 
 Put recurring exports in a job file so you never retype long commands. Each
 `[Section]` is **one job**: run one with `-j SectionName`, or all of them at
-once with `-pl`. Every key is simply a CLI option written as a config key:
+once with `-p`. Every key is simply a CLI option written as a config key:
 
 ```ini
 [DailySales]
@@ -322,8 +338,8 @@ Output=out/full_dump.parquet
 
 ```bash
 ping-dataexport -j DailySales                 # one section (job.ini by default, -jf elsewhere)
-ping-dataexport -j DailySales -od other_dir   # CLI options override the section
-ping-dataexport -pl 4                         # ALL sections in parallel, 4 workers
+ping-dataexport -j DailySales -dir other_dir   # CLI options override the section
+ping-dataexport -p 4                          # ALL sections in parallel, 4 workers
 ```
 
 Every job.ini key and the CLI option it mirrors (keys are case-insensitive):
@@ -333,11 +349,11 @@ Every job.ini key and the CLI option it mirrors (keys are case-insensitive):
 | `Source` | `-s` / `--source` | which config.ini DB section to export from |
 | `Query` | `-q` / `--query` | the SQL to run; indent continuation lines for multi-line queries |
 | `Output` | `-o` / `--output` | single output file path |
-| `OutputDir` | `-od` / `--outputdir` | output directory (needed when `Mode=` is set) |
-| `BaseName` | `-bn` / `--basename` | base filename for mode exports |
+| `OutputDir` | `-dir` / `--outputdir` | output directory (needed when `Mode=` is set) |
+| `BaseName` | `-pf` / `--prefix` | output filename prefix for mode exports |
 | `Format` | `-f` / `--format` | `csv` / `txt` / `parquet` (else inferred from `Output` extension) |
 | `Gzip` | `-gz` / `--gzip` | `Yes`/`No` — gzip the output (CSV/TXT only) |
-| `Sep` | `-sp` / `--sep` | field separator (default `,`; `\t` = tab) |
+| `Sep` | `-sep` / `--sep` | field separator (default `,`; `\t` = tab) |
 | `Quote` | `-quo` / `--quote` | quote character (default `"`) |
 | `StripNewLine` | `-stnl` / `--stripnewline` | `space` \| `blank` \| `escape` \| `doubleescape` |
 | `StripMetaChar` | `-stmc` / `--stripmetachar` | `Yes`/`No` — strip invisible/control characters |
@@ -385,7 +401,7 @@ only, no metadata lookups.
 - Every run logs structured lines to stdout and to a log file:
   `-lf path` > `LogFile=` in config.ini > default
   `{ExportFolder}/logs/log_{jobname}.txt`.
-- CLI exit codes: `0` success, `1` failure (in `-pl` parallel mode: `1` if any
+- CLI exit codes: `0` success, `1` failure (in `-p` parallel mode: `1` if any
   job failed).
 
 ## ODBC prerequisites (ODBC sources only)

{ping_dataexport-0.2.1 → ping_dataexport-0.3.0}/README.md

@@ -17,7 +17,7 @@
   `decimal128(p,s)`, คอลัมน์ int ที่มี NULL ยังคงเป็น int, วันที่ยังคงเป็นวันที่
   และไม่ใช้ pandas เด็ดขาด
 - **ฐานข้อมูลที่รองรับ** — SQLite (Library มาตรฐาน ไม่ต้องติดตั้งอะไรเพิ่ม),
-  SQL Server (MS ODBC / FreeTDS), Oracle (โหมด thin แบบเ Native หรือ ODBC)
+  SQL Server (MS ODBC / FreeTDS), Oracle (โหมด thin แบบ Native หรือ ODBC)
   และแหล่งข้อมูล ODBC ใดก็ได้
 - **ใช้งานได้สองทาง** — ผ่าน CLI `ping-dataexport` หรือผ่าน Library API (`ping_dataexport.api`)
   ที่ออกแบบมาสำหรับ Airflow
@@ -122,7 +122,7 @@ PasswordBase64=c2VjcmV0    ; base64("secret")
 file defaults to `./config.ini` (`-cf` to point elsewhere).
 
 ```bash
-# preview to the console (no -o/-od): prints the first rows
+# preview to the console (no -o/-dir): prints the first rows
 ping-dataexport -s SQLITE01 -q "SELECT * FROM sales"
 
 # single file — format inferred from the extension (.csv/.txt/.parquet)
@@ -140,11 +140,11 @@ All options:
 | `-s` | `--source` | DB config section name (e.g. `DB01`) |
 | `-q` | `--query` | SQL query |
 | `-o` | `--output` | single output file (format from extension, or `-f`) |
-| `-od` | `--outputdir` | output directory (required for `-m` modes) |
-| `-bn` | `--basename` | base filename for mode exports |
+| `-dir` | `--outputdir` | output directory (required for `-m` modes); `-od` still works as a legacy alias |
+| `-pf` | `--prefix` | output filename prefix for mode exports; `-bn`/`--basename` still work as legacy aliases |
 | `-f` | `--format` | `csv`, `txt`, `parquet` |
 | `-gz` | `--gzip` | gzip the output (CSV/TXT only) |
-| `-sp` | `--sep` | field separator (default `,`; `\t` maps to tab) |
+| `-sep` | `--sep` | field separator (default `,`; `\t` maps to tab) |
 | `-quo` | `--quote` | quote character (default `"`) |
 | `-stnl` | `--stripnewline` | newline handling in text columns: `space` \| `blank` \| `escape` \| `doubleescape` |
 | `-stmc` | `--stripmetachar` | strip invisible/control characters from text columns |
@@ -159,21 +159,37 @@ All options:
 | `-rm` | `--removeexisting` | `Yes`: clear the output directory before exporting |
 | `-j` | `--job` | run one job.ini section — see section 5 |
 | `-jf` | `--jobfile` | job file path (default `./job.ini`) |
-| `-pl` | `--parallel` | run ALL job sections in parallel with N workers (default: CPU count) |
+| `-p` | `--parallel` | run ALL job sections in parallel with N workers (default: CPU count); `-pl` still works as a legacy alias |
 | `-n` | `--name` | job name shown in logs and the default log filename |
 | `-cf` | `--configfile` | config file path (default `./config.ini`) |
 | `-lf` | `--logfile` | log file path |
 | `-t` | `--test` | test mode: validate + preview, no files |
 
+### Which options must go together
+
+| If you use… | You must also have… | Notes |
+|-------------|--------------------|-------|
+| (anything) | `-s` + `-q` | the two basics — always required, unless `-j` supplies them from a job file |
+| `-o` | nothing else | single file; **cannot** be combined with `-dir`/`-pf` |
+| `-m` (any mode) | `-dir` + `-pf` | every mode writes multiple files, so it needs a directory + filename prefix |
+| `-dir` or `-pf` | `-m` | they only make sense for mode exports |
+| `-m groupby` / `watermark` | `-col` | the column to group / track |
+| `-m date` | `-col` + `-df` + `-dt` | the date column and an explicit range |
+| `-m relativedate` | `-col` + `-dr` | `-df` optional (defaults to today) |
+| `-m monthbydate` | `-col` + `-mr` | `-df` optional (defaults to today) |
+| `-m splitrow` | `-row` | no `-col` needed |
+| `-gz` | CSV/TXT output | rejected with parquet (it compresses itself) |
+| no `-o` and no `-dir` | — | console preview only (first `PreviewRow` rows, nothing written) |
+
 ## 4. Export modes (partitioned outputs)
 
-Modes split one query into multiple files. All need `-od` (output directory)
-+ `-bn` (base filename); partition values are always bound SQL parameters.
+Modes split one query into multiple files. All need `-dir` (output directory)
++ `-pf` (filename prefix); partition values are always bound SQL parameters.
 
 **`groupby` — one file per distinct value of a column:**
 
 ```bash
-ping-dataexport -s DB01 -q "SELECT * FROM sales" -m groupby -col region -od by_region -bn sales
+ping-dataexport -s DB01 -q "SELECT * FROM sales" -m groupby -col region -dir by_region -pf sales
 ```
 ```
 by_region/
@@ -188,7 +204,7 @@ by_region/
 
 ```bash
 ping-dataexport -s DB01 -q "SELECT * FROM sales" -m date -col txn_date \
-    -df 2026-01-01 -dt 2026-01-05 -od daily -bn sales
+    -df 2026-01-01 -dt 2026-01-05 -dir daily -pf sales
 ```
 ```
 daily/
@@ -204,7 +220,7 @@ daily/
 
 ```bash
 ping-dataexport -s DB01 -q "SELECT * FROM sales" -m relativedate -col txn_date \
-    -df 2026-01-10 -dr 3 -od rel -bn sales
+    -df 2026-01-10 -dr 3 -dir rel -pf sales
 ```
 ```
 rel/
@@ -219,7 +235,7 @@ at the anchor date; omit `-df` to anchor on today):**
 
 ```bash
 ping-dataexport -s DB01 -q "SELECT * FROM sales" -m monthbydate -col txn_date \
-    -df 2026-03-15 -mr 3 -od monthly -bn sales
+    -df 2026-03-15 -mr 3 -dir monthly -pf sales
 ```
 ```
 monthly/
@@ -232,7 +248,7 @@ monthly/
 **`splitrow` — rotate to a new file every N rows:**
 
 ```bash
-ping-dataexport -s DB01 -q "SELECT * FROM sales ORDER BY id" -m splitrow -row 100000 -od split -bn part
+ping-dataexport -s DB01 -q "SELECT * FROM sales ORDER BY id" -m splitrow -row 100000 -dir split -pf part
 ```
 ```
 split/
@@ -244,7 +260,7 @@ split/
 **`watermark` — incremental: only rows newer than the last run:**
 
 ```bash
-ping-dataexport -s DB01 -q "SELECT * FROM sales" -m watermark -col txn_date -od incr -bn sales
+ping-dataexport -s DB01 -q "SELECT * FROM sales" -m watermark -col txn_date -dir incr -pf sales
 ```
 ```
 incr/
@@ -270,7 +286,7 @@ file — see *Output and logs* below):
 
 Put recurring exports in a job file so you never retype long commands. Each
 `[Section]` is **one job**: run one with `-j SectionName`, or all of them at
-once with `-pl`. Every key is simply a CLI option written as a config key:
+once with `-p`. Every key is simply a CLI option written as a config key:
 
 ```ini
 [DailySales]
@@ -293,8 +309,8 @@ Output=out/full_dump.parquet
 
 ```bash
 ping-dataexport -j DailySales                 # one section (job.ini by default, -jf elsewhere)
-ping-dataexport -j DailySales -od other_dir   # CLI options override the section
-ping-dataexport -pl 4                         # ALL sections in parallel, 4 workers
+ping-dataexport -j DailySales -dir other_dir   # CLI options override the section
+ping-dataexport -p 4                          # ALL sections in parallel, 4 workers
 ```
 
 Every job.ini key and the CLI option it mirrors (keys are case-insensitive):
@@ -304,11 +320,11 @@ Every job.ini key and the CLI option it mirrors (keys are case-insensitive):
 | `Source` | `-s` / `--source` | which config.ini DB section to export from |
 | `Query` | `-q` / `--query` | the SQL to run; indent continuation lines for multi-line queries |
 | `Output` | `-o` / `--output` | single output file path |
-| `OutputDir` | `-od` / `--outputdir` | output directory (needed when `Mode=` is set) |
-| `BaseName` | `-bn` / `--basename` | base filename for mode exports |
+| `OutputDir` | `-dir` / `--outputdir` | output directory (needed when `Mode=` is set) |
+| `BaseName` | `-pf` / `--prefix` | output filename prefix for mode exports |
 | `Format` | `-f` / `--format` | `csv` / `txt` / `parquet` (else inferred from `Output` extension) |
 | `Gzip` | `-gz` / `--gzip` | `Yes`/`No` — gzip the output (CSV/TXT only) |
-| `Sep` | `-sp` / `--sep` | field separator (default `,`; `\t` = tab) |
+| `Sep` | `-sep` / `--sep` | field separator (default `,`; `\t` = tab) |
 | `Quote` | `-quo` / `--quote` | quote character (default `"`) |
 | `StripNewLine` | `-stnl` / `--stripnewline` | `space` \| `blank` \| `escape` \| `doubleescape` |
 | `StripMetaChar` | `-stmc` / `--stripmetachar` | `Yes`/`No` — strip invisible/control characters |
@@ -356,7 +372,7 @@ only, no metadata lookups.
 - Every run logs structured lines to stdout and to a log file:
   `-lf path` > `LogFile=` in config.ini > default
   `{ExportFolder}/logs/log_{jobname}.txt`.
-- CLI exit codes: `0` success, `1` failure (in `-pl` parallel mode: `1` if any
+- CLI exit codes: `0` success, `1` failure (in `-p` parallel mode: `1` if any
   job failed).
 
 ## ODBC prerequisites (ODBC sources only)

{ping_dataexport-0.2.1 → ping_dataexport-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ping-dataexport"
-version = "0.2.1"
-description = "Universal database data export to CSV/TXT/Parquet — streaming, typed, no pandas"
+version = "0.3.0"
+description = "PING's Data Export Tool - To Parquet/CSV/TEXT as Accelerator for Data & AI Project"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE"]

{ping_dataexport-0.2.1 → ping_dataexport-0.3.0}/src/ping_dataexport/__init__.py

@@ -8,4 +8,4 @@ The package uses relative imports only and has no import-time side effects, so
 the directory can be copied into any project and imported directly.
 """
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"

{ping_dataexport-0.2.1 → ping_dataexport-0.3.0}/src/ping_dataexport/cli.py

@@ -58,15 +58,16 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("-q", "--query", help="SQL query (required unless --job is used)")
 
     p.add_argument("-o", "--output", help="single output file path")
-    p.add_argument("-od", "--outputdir", help="output directory (required with --mode)")
-    p.add_argument("-bn", "--basename", help="base filename for mode exports")
+    p.add_argument("-dir", "-od", "--outputdir", help="output directory (required with --mode)")
+    p.add_argument("-pf", "-bn", "--prefix", "--basename", dest="basename",
+                   help="output filename prefix for mode exports")
 
     p.add_argument("-f", "--format", choices=FORMATS, help="output format (auto from extension)")
     p.add_argument("-gz", "--gzip", action="store_true", default=None,
                    help="gzip compress output (csv/txt only)")
 
     p.add_argument("-quo", "--quote", help='quote character (default ")')
-    p.add_argument("-sp", "--sep", help="field separator (default ,) — \\t maps to tab")
+    p.add_argument("-sep", "--sep", help="field separator (default ,) — \\t maps to tab")
     p.add_argument("-stnl", "--stripnewline", choices=STRIP_NEWLINE_MODES,
                    help="newline handling in text columns")
     p.add_argument("-stmc", "--stripmetachar", action="store_true", default=None,
@@ -91,7 +92,7 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("-lf", "--logfile", help="log file path")
     p.add_argument("-t", "--test", action="store_true", default=False,
                    help="test mode: preview only, no files")
-    p.add_argument("-pl", "--parallel", nargs="?", const=0, type=int, metavar="N",
+    p.add_argument("-p", "-pl", "--parallel", nargs="?", const=0, type=int, metavar="N",
                    help="run ALL job sections in parallel with N workers (default: CPU count)")
     return p
 

{ping_dataexport-0.2.1 → ping_dataexport-0.3.0}/src/ping_dataexport/job/validator.py

@@ -25,15 +25,15 @@ class JobValidator:
             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")
+            e(spec, "--output cannot be mixed with --outputdir/--prefix")
 
         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")
+                e(spec, f"--mode {spec.mode} requires both --outputdir and --prefix")
         elif spec.outputdir or spec.basename:
-            e(spec, "--outputdir/--basename require --mode")
+            e(spec, "--outputdir/--prefix require --mode")
 
         if spec.mode in _MODES_NEEDING_COLUMN and not spec.column:
             e(spec, f"--mode {spec.mode} requires --column")

{ping_dataexport-0.2.1 → ping_dataexport-0.3.0/src/ping_dataexport.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: ping-dataexport
-Version: 0.2.1
-Summary: Universal database data export to CSV/TXT/Parquet — streaming, typed, no pandas
+Version: 0.3.0
+Summary: PING's Data Export Tool - To Parquet/CSV/TEXT as Accelerator for Data & AI Project
 Author: vorapol
 License-Expression: Apache-2.0
 Keywords: export,database,csv,parquet,etl,data-platform,airflow
@@ -46,7 +46,7 @@ Dynamic: license-file
   `decimal128(p,s)`, คอลัมน์ int ที่มี NULL ยังคงเป็น int, วันที่ยังคงเป็นวันที่
   และไม่ใช้ pandas เด็ดขาด
 - **ฐานข้อมูลที่รองรับ** — SQLite (Library มาตรฐาน ไม่ต้องติดตั้งอะไรเพิ่ม),
-  SQL Server (MS ODBC / FreeTDS), Oracle (โหมด thin แบบเ Native หรือ ODBC)
+  SQL Server (MS ODBC / FreeTDS), Oracle (โหมด thin แบบ Native หรือ ODBC)
   และแหล่งข้อมูล ODBC ใดก็ได้
 - **ใช้งานได้สองทาง** — ผ่าน CLI `ping-dataexport` หรือผ่าน Library API (`ping_dataexport.api`)
   ที่ออกแบบมาสำหรับ Airflow
@@ -151,7 +151,7 @@ PasswordBase64=c2VjcmV0    ; base64("secret")
 file defaults to `./config.ini` (`-cf` to point elsewhere).
 
 ```bash
-# preview to the console (no -o/-od): prints the first rows
+# preview to the console (no -o/-dir): prints the first rows
 ping-dataexport -s SQLITE01 -q "SELECT * FROM sales"
 
 # single file — format inferred from the extension (.csv/.txt/.parquet)
@@ -169,11 +169,11 @@ All options:
 | `-s` | `--source` | DB config section name (e.g. `DB01`) |
 | `-q` | `--query` | SQL query |
 | `-o` | `--output` | single output file (format from extension, or `-f`) |
-| `-od` | `--outputdir` | output directory (required for `-m` modes) |
-| `-bn` | `--basename` | base filename for mode exports |
+| `-dir` | `--outputdir` | output directory (required for `-m` modes); `-od` still works as a legacy alias |
+| `-pf` | `--prefix` | output filename prefix for mode exports; `-bn`/`--basename` still work as legacy aliases |
 | `-f` | `--format` | `csv`, `txt`, `parquet` |
 | `-gz` | `--gzip` | gzip the output (CSV/TXT only) |
-| `-sp` | `--sep` | field separator (default `,`; `\t` maps to tab) |
+| `-sep` | `--sep` | field separator (default `,`; `\t` maps to tab) |
 | `-quo` | `--quote` | quote character (default `"`) |
 | `-stnl` | `--stripnewline` | newline handling in text columns: `space` \| `blank` \| `escape` \| `doubleescape` |
 | `-stmc` | `--stripmetachar` | strip invisible/control characters from text columns |
@@ -188,21 +188,37 @@ All options:
 | `-rm` | `--removeexisting` | `Yes`: clear the output directory before exporting |
 | `-j` | `--job` | run one job.ini section — see section 5 |
 | `-jf` | `--jobfile` | job file path (default `./job.ini`) |
-| `-pl` | `--parallel` | run ALL job sections in parallel with N workers (default: CPU count) |
+| `-p` | `--parallel` | run ALL job sections in parallel with N workers (default: CPU count); `-pl` still works as a legacy alias |
 | `-n` | `--name` | job name shown in logs and the default log filename |
 | `-cf` | `--configfile` | config file path (default `./config.ini`) |
 | `-lf` | `--logfile` | log file path |
 | `-t` | `--test` | test mode: validate + preview, no files |
 
+### Which options must go together
+
+| If you use… | You must also have… | Notes |
+|-------------|--------------------|-------|
+| (anything) | `-s` + `-q` | the two basics — always required, unless `-j` supplies them from a job file |
+| `-o` | nothing else | single file; **cannot** be combined with `-dir`/`-pf` |
+| `-m` (any mode) | `-dir` + `-pf` | every mode writes multiple files, so it needs a directory + filename prefix |
+| `-dir` or `-pf` | `-m` | they only make sense for mode exports |
+| `-m groupby` / `watermark` | `-col` | the column to group / track |
+| `-m date` | `-col` + `-df` + `-dt` | the date column and an explicit range |
+| `-m relativedate` | `-col` + `-dr` | `-df` optional (defaults to today) |
+| `-m monthbydate` | `-col` + `-mr` | `-df` optional (defaults to today) |
+| `-m splitrow` | `-row` | no `-col` needed |
+| `-gz` | CSV/TXT output | rejected with parquet (it compresses itself) |
+| no `-o` and no `-dir` | — | console preview only (first `PreviewRow` rows, nothing written) |
+
 ## 4. Export modes (partitioned outputs)
 
-Modes split one query into multiple files. All need `-od` (output directory)
-+ `-bn` (base filename); partition values are always bound SQL parameters.
+Modes split one query into multiple files. All need `-dir` (output directory)
++ `-pf` (filename prefix); partition values are always bound SQL parameters.
 
 **`groupby` — one file per distinct value of a column:**
 
 ```bash
-ping-dataexport -s DB01 -q "SELECT * FROM sales" -m groupby -col region -od by_region -bn sales
+ping-dataexport -s DB01 -q "SELECT * FROM sales" -m groupby -col region -dir by_region -pf sales
 ```
 ```
 by_region/
@@ -217,7 +233,7 @@ by_region/
 
 ```bash
 ping-dataexport -s DB01 -q "SELECT * FROM sales" -m date -col txn_date \
-    -df 2026-01-01 -dt 2026-01-05 -od daily -bn sales
+    -df 2026-01-01 -dt 2026-01-05 -dir daily -pf sales
 ```
 ```
 daily/
@@ -233,7 +249,7 @@ daily/
 
 ```bash
 ping-dataexport -s DB01 -q "SELECT * FROM sales" -m relativedate -col txn_date \
-    -df 2026-01-10 -dr 3 -od rel -bn sales
+    -df 2026-01-10 -dr 3 -dir rel -pf sales
 ```
 ```
 rel/
@@ -248,7 +264,7 @@ at the anchor date; omit `-df` to anchor on today):**
 
 ```bash
 ping-dataexport -s DB01 -q "SELECT * FROM sales" -m monthbydate -col txn_date \
-    -df 2026-03-15 -mr 3 -od monthly -bn sales
+    -df 2026-03-15 -mr 3 -dir monthly -pf sales
 ```
 ```
 monthly/
@@ -261,7 +277,7 @@ monthly/
 **`splitrow` — rotate to a new file every N rows:**
 
 ```bash
-ping-dataexport -s DB01 -q "SELECT * FROM sales ORDER BY id" -m splitrow -row 100000 -od split -bn part
+ping-dataexport -s DB01 -q "SELECT * FROM sales ORDER BY id" -m splitrow -row 100000 -dir split -pf part
 ```
 ```
 split/
@@ -273,7 +289,7 @@ split/
 **`watermark` — incremental: only rows newer than the last run:**
 
 ```bash
-ping-dataexport -s DB01 -q "SELECT * FROM sales" -m watermark -col txn_date -od incr -bn sales
+ping-dataexport -s DB01 -q "SELECT * FROM sales" -m watermark -col txn_date -dir incr -pf sales
 ```
 ```
 incr/
@@ -299,7 +315,7 @@ file — see *Output and logs* below):
 
 Put recurring exports in a job file so you never retype long commands. Each
 `[Section]` is **one job**: run one with `-j SectionName`, or all of them at
-once with `-pl`. Every key is simply a CLI option written as a config key:
+once with `-p`. Every key is simply a CLI option written as a config key:
 
 ```ini
 [DailySales]
@@ -322,8 +338,8 @@ Output=out/full_dump.parquet
 
 ```bash
 ping-dataexport -j DailySales                 # one section (job.ini by default, -jf elsewhere)
-ping-dataexport -j DailySales -od other_dir   # CLI options override the section
-ping-dataexport -pl 4                         # ALL sections in parallel, 4 workers
+ping-dataexport -j DailySales -dir other_dir   # CLI options override the section
+ping-dataexport -p 4                          # ALL sections in parallel, 4 workers
 ```
 
 Every job.ini key and the CLI option it mirrors (keys are case-insensitive):
@@ -333,11 +349,11 @@ Every job.ini key and the CLI option it mirrors (keys are case-insensitive):
 | `Source` | `-s` / `--source` | which config.ini DB section to export from |
 | `Query` | `-q` / `--query` | the SQL to run; indent continuation lines for multi-line queries |
 | `Output` | `-o` / `--output` | single output file path |
-| `OutputDir` | `-od` / `--outputdir` | output directory (needed when `Mode=` is set) |
-| `BaseName` | `-bn` / `--basename` | base filename for mode exports |
+| `OutputDir` | `-dir` / `--outputdir` | output directory (needed when `Mode=` is set) |
+| `BaseName` | `-pf` / `--prefix` | output filename prefix for mode exports |
 | `Format` | `-f` / `--format` | `csv` / `txt` / `parquet` (else inferred from `Output` extension) |
 | `Gzip` | `-gz` / `--gzip` | `Yes`/`No` — gzip the output (CSV/TXT only) |
-| `Sep` | `-sp` / `--sep` | field separator (default `,`; `\t` = tab) |
+| `Sep` | `-sep` / `--sep` | field separator (default `,`; `\t` = tab) |
 | `Quote` | `-quo` / `--quote` | quote character (default `"`) |
 | `StripNewLine` | `-stnl` / `--stripnewline` | `space` \| `blank` \| `escape` \| `doubleescape` |
 | `StripMetaChar` | `-stmc` / `--stripmetachar` | `Yes`/`No` — strip invisible/control characters |
@@ -385,7 +401,7 @@ only, no metadata lookups.
 - Every run logs structured lines to stdout and to a log file:
   `-lf path` > `LogFile=` in config.ini > default
   `{ExportFolder}/logs/log_{jobname}.txt`.
-- CLI exit codes: `0` success, `1` failure (in `-pl` parallel mode: `1` if any
+- CLI exit codes: `0` success, `1` failure (in `-p` parallel mode: `1` if any
   job failed).
 
 ## ODBC prerequisites (ODBC sources only)