pytae 3.2.0__tar.gz → 3.3.0__tar.gz

{pytae-3.2.0 → pytae-3.3.0}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project are documented in this file.
 
+## [3.3.0] - 2026-09-13
+
+### Added
+- `-replace` flag: replace values at a point in the pipeline (pandas `replace()`). Value is `key=value` tokens: `v=` (required) an `old:new` mapping, `c=` (optional) restrict to specific columns, `exact=` (optional bool, default `true`) — `true` matches whole cell values, `false` matches a substring anywhere in the cell.
+- `-clean_columns` flag: clean column header names, in a fixed order (`strip` -> `strip_special` -> `squeeze` -> `fill` -> `case` -> `dedupe`). Booleans accept a bare key as shorthand for `=true`; `fill` defaults to `'_'` when bare; `case` (`lower`/`upper`/`proper`) always needs a value.
+- `-file`/`-merge`/`-concat` flags: a new multi-file pipeline mode. `-file "path1=alias1; path2=alias2"` loads two or more named files (with optional per-file `,dlim=`/`,encoding=` overrides) instead of the positional `path`; `-merge` (pandas `merge()`, repeatable) or `-concat` (pandas `concat()`, always resets the index, repeatable) then combine them — both accept the literal alias `df` to fold in one more file onto the running result. See `docs/CLI_MULTI_FILE.md`.
+- `-sql` extended: usable as the founding op in `-file` mode instead of `-merge`/`-concat`, with every `-file` alias registered as its own queryable duckdb table (in addition to `df`, once something has produced a current view).
+- `docs/CLI_MULTI_FILE.md`: dedicated reference for `-file`/`-merge`/`-concat`.
+- `docs/PLOTTING.md`: dedicated `Plotter` reference with rendered example images (scatter, grouped bar, pie, secondary axis, multi-panel mosaic dashboard, post-`finalize()` axis looping) using pytae's bundled sample datasets.
+
+### Changed
+- The positional `path` argument is now optional — required only when not using `-file`; `-file` and the positional `path` are mutually exclusive.
+- `src/pytae/cli.py` split into `cli.py` (argparse + main loop), `cli_parsing.py` (flag-value parsers), and `cli_pipeline.py` (`_Pipeline` + ordered argparse actions) — internal refactor, no behavior change.
+- `README.md` restructured into three top-level sections, in order: CLI, Plotting, Library.
+- `docs/CLI.md`: intro updated to mention `-replace`/`-clean_columns`/`-merge`/`-concat`; its Plotting and Multi-file sections now summarize and link out to the new dedicated `docs/PLOTTING.md`/`docs/CLI_MULTI_FILE.md` pages instead of holding the full reference inline.
+
 ## [3.2.0] - 2026-09-13
 
 ### Added

pytae-3.3.0/CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing
+
+```bash
+pip install -e ".[dev,notebooks]"
+pytest                                        # unit tests
+git config core.hooksPath .githooks           # run notebooks/*.ipynb before each commit
+python scripts/run_notebooks.py               # or run the notebook check manually
+```
+
+Notebooks are intentionally not part of the `pytest` suite (they're slower and exercise plotting/IO end-to-end); the pre-commit hook is the enforcement point instead.

{pytae-3.2.0 → pytae-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytae
-Version: 3.2.0
+Version: 3.3.0
 Summary: A package to enhance common tasks in data and plotting
 Project-URL: Homepage, https://github.com/maddytae/pytae
 Project-URL: Bug Tracker, https://github.com/maddytae/pytae/issues
@@ -49,39 +49,42 @@ Pandas extensions for everyday data-science tasks (filtering, selection, reshapi
 pip install pytae
 ```
 
-## Library
-
-Pandas extensions registered on `pd.DataFrame` — import `pytae` and the methods attach automatically.
-
-- **Plotting** — `Plotter`: method-chainable plots on `pandas.plot` (`pip install pytae[plot]`)
-- **Filtering** — `qry()`: dict-based filters (equality, lists, `in`/`not in`, comparisons, intervals)
-- **Selection** — `select()`: columns by name, regex, dtype, or name pattern
-- **Reshaping** — `long()` / `wide()`: melt numeric columns to rows, pivot back to columns
-- **Aggregation** — `agg_df()`: auto-detects group columns and aggregates the rest
-- **Utilities** — `to_clip()`, `handle_missing()`, `cols()`, `group_x()`
-
-See [docs/LIBRARY.md](https://github.com/maddytae/pytae/blob/master/docs/LIBRARY.md) for examples of each.
-
 ## CLI
 
 ```bash
 pytae data.parquet -head
 pytae data.parquet -qry "'species': 'Adelie'" -select species,body_mass_g -convert -o subset.csv
 pytae data.parquet -sql "select species, avg(body_mass_g) from df group by species"
+pytae -file "data1.parquet=df1; data2.parquet=df2" -merge "left=df1,right=df2,on='id'"
 ```
 
-See [docs/CLI.md](https://github.com/maddytae/pytae/blob/master/docs/CLI.md) for the full flag reference.
+See [docs/CLI.md](https://github.com/maddytae/pytae/blob/master/docs/CLI.md) for the full flag reference, and [docs/CLI_MULTI_FILE.md](https://github.com/maddytae/pytae/blob/master/docs/CLI_MULTI_FILE.md) for `-file`/`-merge`/`-concat`.
 
-## Development
+## Plotting
 
-```bash
-pip install -e ".[dev,notebooks]"
-pytest                                        # unit tests
-git config core.hooksPath .githooks           # run notebooks/*.ipynb before each commit
-python scripts/run_notebooks.py               # or run the notebook check manually
+`Plotter`: method-chainable plots on top of `pandas.plot()` (`pip install pytae[plot]`).
+
+```python
+from pytae.plotting import Plotter
+
+Plotter().data(penguins).plot(
+    x="bill_length_mm", y="bill_depth_mm", kind="scatter", by="species"
+).finalize()
 ```
 
-Notebooks are intentionally not part of the `pytest` suite (they're slower and exercise plotting/IO end-to-end); the pre-commit hook is the enforcement point instead.
+See [docs/PLOTTING.md](https://github.com/maddytae/pytae/blob/master/docs/PLOTTING.md) for more examples with sample data.
+
+## Library
+
+Pandas extensions registered on `pd.DataFrame` — import `pytae` and the methods attach automatically.
+
+- **Filtering** — `qry()`: dict-based filters (equality, lists, `in`/`not in`, comparisons, intervals)
+- **Selection** — `select()`: columns by name, regex, dtype, or name pattern
+- **Reshaping** — `long()` / `wide()`: melt numeric columns to rows, pivot back to columns
+- **Aggregation** — `agg_df()`: auto-detects group columns and aggregates the rest
+- **Utilities** — `to_clip()`, `handle_missing()`, `cols()`, `group_x()`
+
+See [docs/LIBRARY.md](https://github.com/maddytae/pytae/blob/master/docs/LIBRARY.md) for examples of each.
 
 ## License
 

{pytae-3.2.0 → pytae-3.3.0}/README.md

@@ -13,39 +13,42 @@ Pandas extensions for everyday data-science tasks (filtering, selection, reshapi
 pip install pytae
 ```
 
-## Library
-
-Pandas extensions registered on `pd.DataFrame` — import `pytae` and the methods attach automatically.
-
-- **Plotting** — `Plotter`: method-chainable plots on `pandas.plot` (`pip install pytae[plot]`)
-- **Filtering** — `qry()`: dict-based filters (equality, lists, `in`/`not in`, comparisons, intervals)
-- **Selection** — `select()`: columns by name, regex, dtype, or name pattern
-- **Reshaping** — `long()` / `wide()`: melt numeric columns to rows, pivot back to columns
-- **Aggregation** — `agg_df()`: auto-detects group columns and aggregates the rest
-- **Utilities** — `to_clip()`, `handle_missing()`, `cols()`, `group_x()`
-
-See [docs/LIBRARY.md](https://github.com/maddytae/pytae/blob/master/docs/LIBRARY.md) for examples of each.
-
 ## CLI
 
 ```bash
 pytae data.parquet -head
 pytae data.parquet -qry "'species': 'Adelie'" -select species,body_mass_g -convert -o subset.csv
 pytae data.parquet -sql "select species, avg(body_mass_g) from df group by species"
+pytae -file "data1.parquet=df1; data2.parquet=df2" -merge "left=df1,right=df2,on='id'"
 ```
 
-See [docs/CLI.md](https://github.com/maddytae/pytae/blob/master/docs/CLI.md) for the full flag reference.
+See [docs/CLI.md](https://github.com/maddytae/pytae/blob/master/docs/CLI.md) for the full flag reference, and [docs/CLI_MULTI_FILE.md](https://github.com/maddytae/pytae/blob/master/docs/CLI_MULTI_FILE.md) for `-file`/`-merge`/`-concat`.
 
-## Development
+## Plotting
 
-```bash
-pip install -e ".[dev,notebooks]"
-pytest                                        # unit tests
-git config core.hooksPath .githooks           # run notebooks/*.ipynb before each commit
-python scripts/run_notebooks.py               # or run the notebook check manually
+`Plotter`: method-chainable plots on top of `pandas.plot()` (`pip install pytae[plot]`).
+
+```python
+from pytae.plotting import Plotter
+
+Plotter().data(penguins).plot(
+    x="bill_length_mm", y="bill_depth_mm", kind="scatter", by="species"
+).finalize()
 ```
 
-Notebooks are intentionally not part of the `pytest` suite (they're slower and exercise plotting/IO end-to-end); the pre-commit hook is the enforcement point instead.
+See [docs/PLOTTING.md](https://github.com/maddytae/pytae/blob/master/docs/PLOTTING.md) for more examples with sample data.
+
+## Library
+
+Pandas extensions registered on `pd.DataFrame` — import `pytae` and the methods attach automatically.
+
+- **Filtering** — `qry()`: dict-based filters (equality, lists, `in`/`not in`, comparisons, intervals)
+- **Selection** — `select()`: columns by name, regex, dtype, or name pattern
+- **Reshaping** — `long()` / `wide()`: melt numeric columns to rows, pivot back to columns
+- **Aggregation** — `agg_df()`: auto-detects group columns and aggregates the rest
+- **Utilities** — `to_clip()`, `handle_missing()`, `cols()`, `group_x()`
+
+See [docs/LIBRARY.md](https://github.com/maddytae/pytae/blob/master/docs/LIBRARY.md) for examples of each.
 
 ## License
 

{pytae-3.2.0 → pytae-3.3.0}/docs/CLI.md

@@ -1,6 +1,6 @@
 # pytae — CLI Reference
 
-Inspect and convert tabular files (`.parquet`, `.csv`, `.txt`, `.dat`, `.sas7bdat`). The CLI is the same verbs as the library: `qry()`, `select()`, `agg_df()`, `group_x()`, `handle_missing()`, `long()`, `wide()`.
+Inspect and convert tabular files (`.parquet`, `.csv`, `.txt`, `.dat`, `.sas7bdat`). The CLI mirrors pytae's own library verbs — `qry()`, `select()`, `agg_df()`, `group_x()`, `handle_missing()`, `long()`, `wide()` — plus CLI-native operations like value replacement (`-replace`), header cleanup (`-clean_columns`), and multi-file merges/concats (`-file`/`-merge`/`-concat`).
 
 ## Contents
 
@@ -9,6 +9,7 @@ Inspect and convert tabular files (`.parquet`, `.csv`, `.txt`, `.dat`, `.sas7bda
 - [Column selection — `-select`](#select)
 - [Row filtering — `-qry` / `-query`](#filtering)
 - [SQL — `-sql`](#sql)
+- [Value replacement — `-replace`](#replace)
 - [Aggregation (auto group columns) — `-agg_df`](#agg-df)
 - [Aggregation (explicit group columns) — `-group_by` + `-agg`](#group-by-agg)
 - [Broadcast — `-group_x`](#group-x)
@@ -17,8 +18,10 @@ Inspect and convert tabular files (`.parquet`, `.csv`, `.txt`, `.dat`, `.sas7bda
 - [Listing — `-cols` / `-dtype` / `-nulls`](#listing)
 - [Sorting rows — `-sort_by`](#sort-by)
 - [Missing values — `-handle_missing`](#handle-missing)
+- [Header cleanup — `-clean_columns`](#clean-columns)
 - [Reshape — `-long` / `-wide`](#reshape)
 - [Cross-tabulation — `-crosstab`](#crosstab)
+- [Multi-file operations — `-file` / `-merge` / `-concat`](CLI_MULTI_FILE.md)
 - [Conversion — `-convert` / `-rename`](#convert)
 - [Display extras](#display-extras)
 - [Pandas defaults vs pytae-specific](#pandas-vs-pytae)
@@ -230,6 +233,32 @@ Mixing a spaced identifier and a string literal in one `-sql` value means the sh
 
 ---
 
+<a id="replace"></a>
+## Value replacement — `-replace`
+
+`-replace` swaps cell values at this point in the pipeline, same as `df.replace()`. Its value is `key=value` tokens (comma-separated, quote a value if it needs an internal comma — same convention as `-crosstab`'s `index=`):
+
+- `v=` (**required**) — the `old:new` mapping, comma-separated pairs, e.g. `v='old:new,alpha:bravo'`.
+- `c=` (optional) — restrict the replace to specific columns, e.g. `c='col a,col b'`. Omit it to replace across every column, like plain `df.replace()`.
+- `exact=` (optional, `true`/`false`, default `true`) — `true` only replaces a cell whose **entire value** matches a key exactly; `false` replaces a key **anywhere it occurs as a substring**, leaving the rest of the cell untouched (keys are escaped so they're matched literally, not as regex patterns).
+
+```bash
+# whole df, exact match only
+pytae data.parquet -replace "v='a magician:the magic,alpha:bravo'"
+
+# only touch col a and colb
+pytae data.parquet -replace "c='col a,colb',v='a magician:the magic,alpha:bravo'"
+
+# substring match: replaces the key wherever it appears inside a cell
+pytae data.parquet -replace "v='a magician:the magic,alpha:bravo',exact=false"
+```
+
+With `exact=true` (default), a cell like `"not a magician exactly"` is left unchanged because it isn't *exactly* `"a magician"`. With `exact=false`, that same cell becomes `"not the magic exactly"` — but watch out for partial-word matches: a short key like `alpha` will also match inside `"analphabet"`, turning it into `"anbravobet"`.
+
+Chains like any other op — runs on the current view and replaces it, so put `-replace` before/after `-select`/`-qry` depending on whether you want it scoped to a narrower view.
+
+---
+
 <a id="agg-df"></a>
 ## Aggregation (auto group columns) — `-agg_df`
 
@@ -396,6 +425,43 @@ pytae penguins.parquet -handle_missing NA -select species,sex -value_counts
 
 ---
 
+<a id="clean-columns"></a>
+## Header cleanup — `-clean_columns`
+
+`-clean_columns` cleans up messy column **header names** (not cell values — see [`-replace`](#replace) for that). Its value is `key[=value]` tokens, comma-separated, applied in a fixed order regardless of how you write them: **strip → strip_special → squeeze → fill → case → dedupe**.
+
+| Key | Type | Bare (no `=value`) | Default when omitted |
+|---|---|---|---|
+| `strip` | bool | means `true` | `false` — trims leading/trailing whitespace |
+| `strip_special` | bool | means `true` | `false` — removes anything that isn't a letter, digit, underscore, or whitespace (e.g. `%`, `$`, `#`, `!`, parentheses) |
+| `squeeze` | bool | means `true` | `false` — collapses runs of internal whitespace to a single space |
+| `fill` | string | defaults to `'_'` | omit the key entirely for **no fill** (whitespace left as-is) |
+| `case` | `lower`\|`upper`\|`proper` | **not allowed** — always needs a value | omitted — case left unchanged |
+| `dedupe` | bool | means `true` | `false` — numbers collisions after cleaning: `revenue`, `revenue_1`, `revenue_2`, … |
+
+`fill` replaces **each individual whitespace character** with the fill string — not each *run* of whitespace. That means `"col   b"` (3 spaces) with `fill` alone becomes `"col___b"` (3 underscores); add `squeeze` first to collapse it to one separator instead.
+
+```bash
+# strip ends, fill remaining whitespace with '_' (default), lowercase
+pytae data.parquet -clean_columns "strip,fill,case=lower"
+
+# custom fill character instead of the default '_'
+pytae data.parquet -clean_columns "fill='$'"   # "col a" -> "col$a"
+
+# Proper/Title Case, no fill (spaces are left alone)
+pytae data.parquet -clean_columns "case=proper"   # "col a" -> "Col A"
+
+# collapse repeated internal whitespace and strip punctuation before filling,
+# then number any resulting duplicate names
+pytae data.parquet -clean_columns "strip,squeeze,strip_special,fill,case=lower,dedupe=true"
+```
+
+With the last example, headers `"  Col A  "`, `"col   b"`, `"Col A"`, `"100% Match!"` become `col_a`, `col_b`, `col_a_1` (deduped against the first `col_a`), and `100_match` (the `%`/`!` punctuation is stripped by `strip_special` before the remaining space is filled).
+
+Chains like any other op — runs on the current view and replaces its column names, so put it before/after `-select` depending on whether you want to select by the original or cleaned names.
+
+---
+
 <a id="reshape"></a>
 ## Reshape — `-long` / `-wide`
 
@@ -463,6 +529,18 @@ pytae penguins.parquet -crosstab "index='species',columns='sex'" -dropna false
 
 ---
 
+<a id="merge"></a>
+## Multi-file operations — `-file` / `-merge` / `-concat`
+
+Everything above operates on **one** file (the positional `path`). `-file` + `-merge`/`-concat`/`-sql` are a separate mode for combining **two or more named files** into a single pipeline, replacing the positional `path` entirely. See **[docs/CLI_MULTI_FILE.md](CLI_MULTI_FILE.md)** for the full reference and examples.
+
+```bash
+pytae -file "data1.parquet=df1; data2.parquet=df2" \
+      -merge "left=df1,right=df2,on='col a:cola,colb:colb',how=inner"
+```
+
+---
+
 <a id="convert"></a>
 ## Conversion — `-convert` / `-rename`
 
@@ -702,7 +780,9 @@ pytae 'folder/*.parquet' -convert
 | `-select SPEC` | Restrict columns at this point in the pipeline (union in one spec; repeat to filter remaining) |
 | `-qry CONDITIONS` | Filter rows at this point (`df.qry()`); surrounding `{}` optional |
 | `-query EXPR` | Filter rows at this point (`df.query()`) |
-| `-sql QUERY` | Run a SQL query at this point via duckdb; view is table `df` |
+| `-sql QUERY` | Run a SQL query at this point via duckdb; view is table `df` (in `-file` mode, each alias is also queryable, and may be used instead of `-merge`/`-concat`) |
+| `-replace KEY=VALUE,...` | Replace values at this point (`df.replace()`); `v=` required, `c=`/`exact=` optional |
+| `-clean_columns KEY=VALUE,...` | Clean header names, in order strip -> strip_special -> squeeze -> fill -> case -> dedupe |
 | `-sort_by COLUMNS [asc\|desc]` | Sort rows (default: ascending) |
 
 **Aggregate & reshape**
@@ -719,6 +799,14 @@ pytae 'folder/*.parquet' -convert
 | `-crosstab KEY=VALUE,...` | Cross-tabulate into a matrix (`index` comma-separated list, `columns` single column, optional `values`+`aggfunc`, `normalize`, `margins`, `margins_name`) |
 | `-dropna true\|false` | Drop NA keys for `-agg_df`/`-agg`/`-value_counts`/`-crosstab` (default true) |
 
+**Multi-file operations**
+
+| Flag | Description |
+|---|---|
+| `-file PATH=ALIAS;...` | Load named files instead of the positional `path`; `;`-separated, each optionally followed by `,dlim=`/`,encoding=`; requires `-merge`, `-concat`, or `-sql` as the first op |
+| `-merge KEY=VALUE,...` | Join `-file` aliases (`left`, `right`, `on`, optional `how` default `inner`, optional `validate`); repeatable, `left=`/`right=` accept `df` for the running result; or use `-sql` instead |
+| `-concat KEY=VALUE,...` | Stack `-file` aliases row-wise (`frames=`, an ordered list, accepts `df` for the running result); repeatable; always resets the index |
+
 **Convert & I/O**
 
 | Flag | Description |

pytae-3.3.0/docs/CLI_MULTI_FILE.md

@@ -0,0 +1,86 @@
+# pytae — Multi-file operations (`-file` / `-merge` / `-concat`)
+
+See [CLI Reference](CLI.md) for everything else. This page covers `-file`-based multi-file mode — loading **two or more named files** into a single pipeline instead of the usual one (the positional `path`).
+
+`-file` is a separate mode, paired with `-merge` (join), `-concat` (stack), or `-sql` (raw SQL) as the founding op. `-file` **replaces** the positional `path` entirely — you can't mix a positional path with `-file`.
+
+```bash
+pytae -file "data1.parquet=df1; data2.parquet=df2" \
+      -merge "left=df1,right=df2,on='col a:cola,colb:colb',how=inner"
+```
+
+## `-file` — load named inputs
+
+Value is `;`-separated entries (at least two — any number is fine), each `PATH=ALIAS` optionally followed by `,dlim=`/`,encoding=` overrides for reading *that* file (handy when joining mismatched formats, e.g. a pipe-delimited `.txt` with a `.csv`):
+
+```bash
+pytae -file "data1.parquet=df1; data2.parquet=df2" ...
+pytae -file "a.csv=a; b.csv=b; c.csv=c" ...   # three (or more) files are fine
+pytae -file "sales.txt=sales,dlim='|'; customers.csv=customers,encoding='latin-1'" ...
+```
+
+## `-merge` — join `-file` aliases
+
+Must be the **first** operation when `-file` is used, unless [`-sql`](#sql-alternative) or `-concat` starts it instead. **Repeatable** — each occurrence runs one more `pd.merge()`, so you can fold in one file at a time. Value is `key=value` tokens:
+
+| Key | Required? | Meaning |
+|---|---|---|
+| `left=` / `right=` | required | a `-file` alias, or the literal `df` for the pipeline's current result so far (only valid once something earlier has produced one) |
+| `on=` | required | shared join column(s) (comma list) when names match on both sides, or `left:right` pairs when they differ — **quote the whole value** if it has more than one column/pair, e.g. `on='col a:cola,colb:colb'` |
+| `how=` | optional (default `inner`) | `inner`/`left`/`right`/`outer`/`cross`, passed straight to pandas `merge()` |
+| `validate=` | optional | e.g. `one_to_one`/`one_to_many`/`many_to_one`/`many_to_many`, passed straight to pandas `merge()` |
+
+```bash
+# join column names differ between the two files
+pytae -file "data1.parquet=df1; data2.parquet=df2" \
+      -merge "left=df1,right=df2,on='col a:cola',how=inner"
+
+# join column name is shared, outer join, then keep going like any other pipeline
+pytae -file "a.csv=a; b.csv=b" -merge "left=a,right=b,on='id',how=outer" -select id,x,y -shape
+
+# validate the join is truly one-to-one, erroring otherwise
+pytae -file "a.csv=a; b.csv=b" -merge "left=a,right=b,on='id',validate=one_to_one"
+
+# fold a third file in: (a ⋈ b) ⋈ c — 'df' means "the result so far"
+pytae -file "a.csv=a; b.csv=b; c.csv=c" \
+      -merge "left=a,right=b,on='id'" \
+      -merge "left=df,right=c,on='id'"
+```
+
+## `-concat` — stack `-file` aliases (pandas `concat()`)
+
+Must be the **first** operation when `-file` is used, unless `-merge` or [`-sql`](#sql-alternative) starts it instead. **Repeatable**, and its `frames=` list already accepts more than two names in one call. The index is always reset (`ignore_index=True`) — not configurable, always on. Value is `key=value` tokens:
+
+| Key | Required? | Meaning |
+|---|---|---|
+| `frames=` | required | an ordered, comma-separated list of `-file` aliases (or `df` for the pipeline's current result so far) — **quote the whole value**, e.g. `frames='df1,df2,df3'` |
+
+```bash
+# stack three files in one call
+pytae -file "a.csv=a; b.csv=b; c.csv=c" -concat "frames='a,b,c'"
+
+# or stack incrementally, folding more files onto the running result
+pytae -file "a.csv=a; b.csv=b; c.csv=c" -concat "frames='a,b'" -concat "frames='df,c'"
+```
+
+<a id="sql-alternative"></a>
+## `-sql` as an alternative to `-merge`/`-concat`
+
+`-sql` may be used **instead of `-merge`/`-concat`** as the founding op in `-file` mode. Every `-file` alias is registered as its own duckdb table (by its alias name), so you can write the join (or `union all`, for stacking) yourself — more flexible than `-merge`'s/`-concat`'s `key=value` syntax (arbitrary conditions, multiple joins, inline aggregation, …):
+
+```bash
+pytae -file "data1.parquet=df1; data2.parquet=df2" \
+      -sql 'select * from df1 inner join df2 on df1."col a" = df2.cola'
+```
+
+Once something in the pipeline has produced a current view (e.g. after `-merge`/`-concat`, or a later `-sql` call), `df` also becomes queryable — same as single-file mode:
+
+```bash
+pytae -file "a.csv=a; b.csv=b" -merge "left=a,right=b,on='id'" -sql "select count(*) as n from df"
+```
+
+## Notes
+
+- `-convert` after a merge/concat requires `-o`/`--output` explicitly (there's no single source file to derive a default `.csv` name from).
+- Glob-pattern batch mode (`pytae 'data/*.parquet' -convert`) is a different, unrelated feature — it can't be combined with `-file`.
+

{pytae-3.2.0 → pytae-3.3.0}/docs/LIBRARY.md

@@ -11,7 +11,7 @@ penguins = pt.sample("penguins")          # or pt.sample_data["penguins"]
 
 ## 1) Plotting — `Plotter`
 
-Method-chainable plots on top of `pandas.plot`. Requires matplotlib (`pip install pytae[plot]`). [plotter.ipynb](https://github.com/maddytae/pytae/blob/master/notebooks/plotter.ipynb)
+Method-chainable plots on top of `pandas.plot`. Requires matplotlib (`pip install pytae[plot]`). See **[docs/PLOTTING.md](PLOTTING.md)** for more examples (bar, pie, multi-panel dashboards, …) with sample data, or [plotter.ipynb](https://github.com/maddytae/pytae/blob/master/notebooks/plotter.ipynb) for the full notebook.
 
 ```python
 from pytae.plotting import Plotter

pytae-3.3.0/docs/PLOTTING.md

@@ -0,0 +1,158 @@
+# pytae — Plotting (`Plotter`)
+
+`Plotter` is a method-chainable wrapper around `pandas.plot()` (which itself wraps matplotlib). Chain `.data()` → `.plot()` → `.plot()` → `.finalize()`; each `.plot()` call remembers the previous call's kwargs unless you change `.data()` or the plot `kind`. Requires matplotlib: `pip install pytae[plot]`.
+
+All examples below use pytae's bundled sample datasets (`pytae.sample_data[...]`) — no files to download. See [notebooks/plotter.ipynb](https://github.com/maddytae/pytae/blob/master/notebooks/plotter.ipynb) for the full runnable notebook version, and [docs/LIBRARY.md](LIBRARY.md) for the rest of pytae's library.
+
+## Scatter — colored by category
+
+```python
+import pytae as pt
+
+penguins = pt.sample_data["penguins"]
+
+k = pt.Plotter(figsize=(6, 4.5))
+(k
+ .data(penguins)
+ .plot(kind="scatter", x="bill_length_mm", y="bill_depth_mm", c="species", cmap="viridis",
+       title="Penguin bill dimensions by species")
+ .finalize()
+)
+k.fig
+```
+
+![Scatter plot of penguin bill dimensions by species](images/plotting_scatter.png)
+
+## Grouped bar — aggregated automatically
+
+`by=` splits into groups, `aggfunc=` (default `'sum'`) aggregates — no manual `groupby()`/`pivot()` needed:
+
+```python
+tips = pt.sample_data["tips"]
+color = {"Male": "steelblue", "Female": "salmon"}
+
+k = pt.Plotter(figsize=(6, 4.5))
+(k
+ .data(tips)
+ .plot(kind="bar", x="day", y="total_bill", by="sex", aggfunc="mean", color=color,
+       title="Average bill by day and sex")
+ .finalize()
+)
+k.fig
+```
+
+![Grouped bar chart of average bill by day and sex](images/plotting_bar.png)
+
+## Secondary axis — two metrics, two scales, one panel
+
+Append `^` to a mosaic key (`on='A^'`) to plot on a secondary y-axis that shares the same x-axis as panel `'A'` — useful when two series live on very different scales (here, dollars vs. tip amount):
+
+```python
+tips = pt.sample_data["tips"]
+
+k = pt.Plotter(figsize=(6.5, 4.5))
+(k
+ .data(tips)
+ .plot(kind="bar", x="day", y="total_bill", aggfunc="mean", color="#c7ddf2", legend=False,
+       title="Average bill (bars) vs average tip (line) by day")
+ .plot(kind="line", x="day", y="tip", aggfunc="mean", on="A^", color="crimson", marker="o")
+ .finalize(consolidate_legends=True, ncols=2, bbox_to_anchor=(0.75, -0.05))
+)
+k.fig
+```
+
+![Bar chart of average bill with a secondary-axis line for average tip, by day](images/plotting_secondary_axis.png)
+
+The second `.plot()` call reuses `x="day"`/`aggfunc="mean"` from context but targets `on="A^"` instead of `'A'`, so it shares panel `'A'`'s x-axis while getting its own y-scale. Any mosaic panel works this way — `on='B^'`, `on='C^'`, etc. — and `finalize(hide_secondary_y=True)` hides the secondary y-axis's ticks/labels/spine entirely if you only wanted it for scaling, not for display.
+
+```python
+tips = pt.sample_data["tips"]
+color = {"Lunch": "orange", "Dinner": "green"}
+
+k = pt.Plotter(figsize=(5, 5))
+(k
+ .data(tips)
+ .plot(kind="pie", y="tip", by="time", aggfunc="mean", autopct="%1.1f%%", colors=color,
+       explode=(0, 0.05), title="Average tip share by meal time")
+ .finalize()
+)
+k.fig
+```
+
+![Pie chart of average tip share by meal time](images/plotting_pie.png)
+
+## Multi-panel dashboard — mosaic layout, mixed plot kinds, consolidated legend
+
+Pass a mosaic string to lay out several named axes (`'A'`, `'B'`, …); switch `.data()` between panels and mix plot kinds freely. `finalize(consolidate_legends=True)` merges every panel's legend into one:
+
+```python
+fmri = pt.sample_data["fmri"]
+tips = pt.sample_data["tips"]
+healthexp = pt.sample_data["healthexp"]
+
+color = {"cue": "steelblue", "stim": "darkorange"}
+
+mosaic = """
+AB
+CD
+"""
+k = pt.Plotter(mosaic, figsize=(9, 7))
+(k
+ .data(fmri)
+ .plot(x="timepoint", y="signal", by="event", aggfunc="mean", kind="line", color=color,
+       on="A", title="Signal over time by event")
+ .data(tips)
+ .plot(kind="scatter", x="total_bill", y="tip", c="size", cmap="viridis", on="B",
+       title="Tip vs bill, colored by party size")
+ .data(healthexp)
+ .plot(kind="area", x="Year", y="Spending_USD", by="Country", aggfunc="mean", on="C",
+       legend=False, title="Health spending over time")
+ .data(tips)
+ .plot(kind="kde", column="tip", by="day", on="D", title="Tip distribution by day")
+ .finalize(consolidate_legends=True, ncols=4, bbox_to_anchor=(0.75, -0.02))
+)
+k.fig
+```
+
+![Four-panel dashboard combining line, scatter, area, and kde plots](images/plotting_dashboard.png)
+
+## Enhancing a plot after `finalize()` — looping over axes
+
+`k.axd` is the mosaic-key → `Axes` dict (`k.fig.axes` gives every matplotlib `Axes`, including secondary ones added via `on='X^'`). Once `.finalize()` has run, loop over either to apply the same tweak everywhere — gridlines, tick rotation, reference lines, annotations, anything matplotlib supports directly on an `Axes`:
+
+```python
+# ... continuing from the dashboard above, after .finalize()
+for ax_key, ax in k.axd.items():
+    if "^" in ax_key:       # skip secondary axes if you only want primaries styled
+        continue
+    ax.grid(True, alpha=0.3, linestyle="--")
+    for label in ax.get_xticklabels():
+        label.set_rotation(30)
+        label.set_ha("right")
+
+k.fig
+```
+
+![Same four-panel dashboard with gridlines added and x tick labels rotated in a loop](images/plotting_dashboard_enhanced.png)
+
+This is the general escape hatch for anything `Plotter` doesn't expose as a kwarg — since `k.fig`/`k.axd` are plain matplotlib objects, nothing about `Plotter` stops you from dropping into regular matplotlib calls afterward (`ax.axhline()`, `ax.annotate()`, `ax.set_ylim()`, …) before the final `k.fig.savefig(...)`.
+
+## Other plot kinds
+
+Everything `pandas.plot()` supports works through `.plot(kind=...)`: `line`, `bar`/`barh`, `area`, `hist`, `kde`/`density`, `scatter`, `hexbin`, `pie`. A few notes:
+
+- `by=`/`aggfunc=` (default `sum`) auto-aggregate for `line`/`bar`/`barh`/`area`/`pie` — pass `aggregate=False` if your data is already one row per `x`/`by` combination.
+- `hist`/`kde`/`density` take `column=` (the value column) instead of `y=`.
+- `scatter`/`hexbin` don't aggregate; use `c=`/`cmap=` (scatter) or `C=`/`reduce_C_function=` (hexbin) to encode a third variable instead of `by=`.
+- `on='A'` targets a specific mosaic panel; `on='A^'` plots on a secondary y-axis sharing panel `'A'`'s x-axis.
+- `style=`/`width=` (dicts keyed by series name) set per-line dash style/line width on `line` plots — set once via `.plot()`, not as a matplotlib property afterward.
+
+## `finalize()` options
+
+| Option | Effect |
+|---|---|
+| `consolidate_legends` | One merged legend across all panels instead of per-panel legends |
+| `bbox_to_anchor`, `ncols` | Position/columns for the consolidated legend |
+| `legend`, `legend_primary`, `legend_secondary` | Master switch, and per-axis-type switches for primary vs. secondary (`^`) axes |
+| `legend_loc`, `legend_frameon` | Location and frame for per-panel legends |
+| `hide_secondary_y` | Hide tick labels/spine on secondary (`^`) axes |

{pytae-3.2.0 → pytae-3.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytae"
-version = "3.2.0"
+version = "3.3.0"
 description = "A package to enhance common tasks in data and plotting"
 authors = [{ name = "Madhukar Kumar Jha", email = "madhukar.k.jha@gmail.com" }]
 readme = "README.md"