tabalyst 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabalyst
-Version: 0.2.1
+Version: 0.3.0
 Summary: Open-source toolkit for understanding and working with unfamiliar data.
 Author: Gregory Borelli
 License-Expression: MIT
@@ -51,9 +51,12 @@ the shared toolkit architecture is being established.
 Tabalyst supports Python 3.11, 3.12, 3.13, and 3.14.
 
 ```console
-pip install tabalyst
+pip install --upgrade tabalyst
 ```
 
+The same command installs Tabalyst or updates it. Tabalyst is in alpha and
+changes often: update it before each new test.
+
 ## Tabalyst Report
 
 | Use case | Command | Destination |
@@ -170,6 +173,34 @@ tabalyst --version
 
 `python -m tabalyst` accepts the same commands.
 
+## Tabalyst Sample
+
+Create a smaller CSV without modifying the source:
+
+```console
+tabalyst sample customers.csv --sample-method random --rows 1000 --seed 42
+```
+
+The default output is `customers.sample.csv` beside the source. Use `-o` to
+name the output for one input, or `-d` to sample several files into one
+directory:
+
+```console
+tabalyst sample customers.csv --sample-method first --rows 100 -o test.csv
+tabalyst sample *.csv --sample-method random --percent 5 -d samples/
+```
+
+Available methods are `first`, `last`, `random` and `stratified`. Stratified
+sampling approximately preserves the distribution of a selected field:
+
+```console
+tabalyst sample customers.csv --sample-method stratified --field province --rows 1000 --seed 42
+```
+
+Sampling reads CSV records as a stream. Random and stratified sampling keep
+only the requested sample, plus stratum counts, in memory. Existing outputs
+require `--force`, and an input file is never overwritten.
+
 ## What the report analyzes
 
 - Dataset dimensions, missing cells, duplicates, and quality observations.
@@ -200,6 +231,13 @@ batch = tabalyst.generate_reports(
     ["*.csv"],
     output_dir="reports",
 )
+
+sample = tabalyst.sample_csv(
+    "customers.csv",
+    method="random",
+    rows=1000,
+    seed=42,
+)
 ```
 
 `analyze()` returns the JSON-serializable profile for one report.
@@ -224,7 +262,7 @@ Configuration files are strict JSON. A minimal file is:
 
 Explicit CLI or Python arguments override the configuration file, which overrides
 Tabalyst defaults. See the
-[configuration reference](https://github.com/loribel-labs/tabalyst/blob/main/docs/configuration.md)
+[configuration reference](https://github.com/loribel-labs/tabalyst/blob/main/docs/en/reference/configuration.md)
 for all analysis settings.
 
 ## Local-first behavior and current limits
@@ -233,8 +271,9 @@ Tabalyst performs analysis locally and adds no telemetry or remote processing.
 Generated JSON and HTML may contain source values and should be shared
 accordingly.
 
-The complete CSV is currently loaded into memory. File and phase progress is
-available now; row percentages, throughput estimates, recursive directory input,
+Report analysis currently loads the complete CSV into memory. Sampling uses a
+streaming reader with bounded row storage. File and phase progress is available
+for reports; row percentages, throughput estimates, recursive directory input,
 and parallel batch execution will require later ingestion work.
 
 ## Examples and development
@@ -251,8 +290,8 @@ python -m build
 
 Additional documentation:
 
-- [Architecture](https://github.com/loribel-labs/tabalyst/blob/main/docs/architecture.md)
-- [Configuration](https://github.com/loribel-labs/tabalyst/blob/main/docs/configuration.md)
+- [Architecture](https://github.com/loribel-labs/tabalyst/blob/main/docs/dev/architecture.md)
+- [Configuration](https://github.com/loribel-labs/tabalyst/blob/main/docs/en/reference/configuration.md)
 - [Release procedure](https://github.com/loribel-labs/tabalyst/blob/main/RELEASING.md)
 
 Please report defects and feature requests through the

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

@@ -17,9 +17,12 @@ the shared toolkit architecture is being established.
 Tabalyst supports Python 3.11, 3.12, 3.13, and 3.14.
 
 ```console
-pip install tabalyst
+pip install --upgrade tabalyst
 ```
 
+The same command installs Tabalyst or updates it. Tabalyst is in alpha and
+changes often: update it before each new test.
+
 ## Tabalyst Report
 
 | Use case | Command | Destination |
@@ -136,6 +139,34 @@ tabalyst --version
 
 `python -m tabalyst` accepts the same commands.
 
+## Tabalyst Sample
+
+Create a smaller CSV without modifying the source:
+
+```console
+tabalyst sample customers.csv --sample-method random --rows 1000 --seed 42
+```
+
+The default output is `customers.sample.csv` beside the source. Use `-o` to
+name the output for one input, or `-d` to sample several files into one
+directory:
+
+```console
+tabalyst sample customers.csv --sample-method first --rows 100 -o test.csv
+tabalyst sample *.csv --sample-method random --percent 5 -d samples/
+```
+
+Available methods are `first`, `last`, `random` and `stratified`. Stratified
+sampling approximately preserves the distribution of a selected field:
+
+```console
+tabalyst sample customers.csv --sample-method stratified --field province --rows 1000 --seed 42
+```
+
+Sampling reads CSV records as a stream. Random and stratified sampling keep
+only the requested sample, plus stratum counts, in memory. Existing outputs
+require `--force`, and an input file is never overwritten.
+
 ## What the report analyzes
 
 - Dataset dimensions, missing cells, duplicates, and quality observations.
@@ -166,6 +197,13 @@ batch = tabalyst.generate_reports(
     ["*.csv"],
     output_dir="reports",
 )
+
+sample = tabalyst.sample_csv(
+    "customers.csv",
+    method="random",
+    rows=1000,
+    seed=42,
+)
 ```
 
 `analyze()` returns the JSON-serializable profile for one report.
@@ -190,7 +228,7 @@ Configuration files are strict JSON. A minimal file is:
 
 Explicit CLI or Python arguments override the configuration file, which overrides
 Tabalyst defaults. See the
-[configuration reference](https://github.com/loribel-labs/tabalyst/blob/main/docs/configuration.md)
+[configuration reference](https://github.com/loribel-labs/tabalyst/blob/main/docs/en/reference/configuration.md)
 for all analysis settings.
 
 ## Local-first behavior and current limits
@@ -199,8 +237,9 @@ Tabalyst performs analysis locally and adds no telemetry or remote processing.
 Generated JSON and HTML may contain source values and should be shared
 accordingly.
 
-The complete CSV is currently loaded into memory. File and phase progress is
-available now; row percentages, throughput estimates, recursive directory input,
+Report analysis currently loads the complete CSV into memory. Sampling uses a
+streaming reader with bounded row storage. File and phase progress is available
+for reports; row percentages, throughput estimates, recursive directory input,
 and parallel batch execution will require later ingestion work.
 
 ## Examples and development
@@ -217,8 +256,8 @@ python -m build
 
 Additional documentation:
 
-- [Architecture](https://github.com/loribel-labs/tabalyst/blob/main/docs/architecture.md)
-- [Configuration](https://github.com/loribel-labs/tabalyst/blob/main/docs/configuration.md)
+- [Architecture](https://github.com/loribel-labs/tabalyst/blob/main/docs/dev/architecture.md)
+- [Configuration](https://github.com/loribel-labs/tabalyst/blob/main/docs/en/reference/configuration.md)
 - [Release procedure](https://github.com/loribel-labs/tabalyst/blob/main/RELEASING.md)
 
 Please report defects and feature requests through the

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tabalyst"
-version = "0.2.1"
+version = "0.3.0"
 description = "Open-source toolkit for understanding and working with unfamiliar data."
 readme = "README.md"
 requires-python = ">=3.11"

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

@@ -6,6 +6,10 @@ from tabalyst.config import AnalysisConfig as AnalysisConfig
 from tabalyst.errors import ConfigurationError, InputError, ReportError, TabalystError
 from tabalyst.report_service import generate_reports as generate_reports
 from tabalyst.reporting import render_report as render_report
+from tabalyst.sampling import SampleMethod as SampleMethod
+from tabalyst.sampling import SampleResult as SampleResult
+from tabalyst.sampling import sample_csv as sample_csv
+from tabalyst.sampling_service import generate_samples as generate_samples
 from tabalyst.service import analyze
 from tabalyst.service import analyze_csv as analyze_csv
 
@@ -17,6 +21,8 @@ __all__ = [
     "__version__",
     "analyze",
     "generate_reports",
+    "generate_samples",
+    "sample_csv",
 ]
 
 # Alpha compatibility imports remain available, but are not part of the 0.1.0 API.

{tabalyst-0.2.1 → tabalyst-0.3.0}/src/tabalyst/cli/app.py

@@ -6,6 +6,7 @@ import typer
 
 from tabalyst import __version__
 from tabalyst.cli.report import report_command
+from tabalyst.cli.sample import sample_command
 
 app = typer.Typer(
     add_completion=False,
@@ -37,6 +38,7 @@ def root(
 
 
 app.command("report")(report_command)
+app.command("sample")(sample_command)
 
 
 def main() -> None:

tabalyst-0.3.0/src/tabalyst/cli/sample.py

@@ -0,0 +1,132 @@
+"""CLI adapter for CSV sampling."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from tabalyst.errors import ConfigurationError, InputError, TabalystError
+from tabalyst.sampling import SampleMethod, SampleResult
+from tabalyst.sampling_service import generate_samples
+
+
+def _print_result(result: SampleResult) -> None:
+    typer.echo("Sample created successfully.", err=True)
+    typer.echo("", err=True)
+    typer.echo(f"Source:        {result.source}", err=True)
+    typer.echo(f"Method:        {result.method.value}", err=True)
+    if result.field is not None:
+        typer.echo(f"Field:         {result.field}", err=True)
+    typer.echo(f"Source rows:   {result.source_rows:,}", err=True)
+    typer.echo(f"Sample rows:   {result.sample_rows:,}", err=True)
+    typer.echo(f"Sample rate:   {result.sample_rate:.2f}%", err=True)
+    if result.seed is not None and result.method in {
+        SampleMethod.RANDOM,
+        SampleMethod.STRATIFIED,
+    }:
+        typer.echo(f"Seed:          {result.seed}", err=True)
+    typer.echo(f"Output:        {result.output.resolve()}", err=True)
+
+
+def sample_command(
+    inputs: Annotated[
+        list[str],
+        typer.Argument(
+            metavar="INPUT...",
+            help="One or more CSV files or non-recursive glob patterns.",
+        ),
+    ],
+    method: Annotated[
+        SampleMethod,
+        typer.Option("--sample-method", help="Sampling strategy."),
+    ],
+    rows: Annotated[
+        int | None,
+        typer.Option("--rows", help="Number of data rows to select."),
+    ] = None,
+    percent: Annotated[
+        float | None,
+        typer.Option("--percent", help="Percentage of data rows to select."),
+    ] = None,
+    field: Annotated[
+        str | None,
+        typer.Option("--field", help="Field used for stratified sampling."),
+    ] = None,
+    seed: Annotated[
+        int | None,
+        typer.Option("--seed", help="Seed for reproducible random selection."),
+    ] = None,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Output CSV filename."),
+    ] = None,
+    output_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--output-dir",
+            "-d",
+            help="Directory for samples named after their source files.",
+        ),
+    ] = None,
+    config: Annotated[
+        Path | None,
+        typer.Option("--config", "-c", help="JSON configuration file."),
+    ] = None,
+    delimiter: Annotated[
+        str | None,
+        typer.Option("--delimiter", help="One-character CSV delimiter."),
+    ] = None,
+    encoding: Annotated[
+        str | None,
+        typer.Option("--encoding", help="CSV text encoding."),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Replace an existing sample file."),
+    ] = False,
+) -> None:
+    """Create a CSV sample without modifying the source file."""
+
+    try:
+        batch = generate_samples(
+            inputs,
+            method=method,
+            rows=rows,
+            percent=percent,
+            field=field,
+            seed=seed,
+            output=output,
+            output_dir=output_dir,
+            config_path=config,
+            delimiter=delimiter,
+            encoding=encoding,
+            force=force,
+        )
+    except TabalystError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        if isinstance(exc, ConfigurationError):
+            code = 2
+        elif isinstance(exc, InputError):
+            code = 4
+        else:
+            code = 1
+        raise typer.Exit(code) from exc
+
+    for index, success in enumerate(batch.successes):
+        if index:
+            typer.echo("", err=True)
+        _print_result(success.result)
+    for failure in batch.failures:
+        typer.echo(f"Error [{failure.job.source}]: {failure.error}", err=True)
+    if len(batch.plan.jobs) > 1:
+        typer.echo(
+            f"{len(batch.successes)} succeeded, {len(batch.failures)} failed",
+            err=True,
+        )
+    if batch.failures:
+        code = (
+            4
+            if all(isinstance(item.error, InputError) for item in batch.failures)
+            else 1
+        )
+        raise typer.Exit(code)