tabalyst 0.6.0__tar.gz → 0.6.1__tar.gz

{tabalyst-0.6.0/src/tabalyst.egg-info → tabalyst-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabalyst
-Version: 0.6.0
+Version: 0.6.1
 Summary: Open-source toolkit for understanding and working with unfamiliar data.
 Author: Gregory Borelli
 License-Expression: MPL-2.0
@@ -75,6 +75,7 @@ changes often: update it before each new test.
 | One JSON file | `tabalyst report data.json` | `data.report.html` beside the source |
 | One JSONL file | `tabalyst report events.jsonl` | `events.report.html` beside the source |
 | One Excel workbook | `tabalyst report sales.xlsx` | `sales.report.html` beside the source |
+| Every table of a workbook | `tabalyst report shop.xlsx --all-collections` | `shop.costs.html`, `shop.sales.html`, ... beside the source |
 | From a scan document | `tabalyst report --scan data.scan.json` | `data.html` beside the scan |
 
 The simplest command keeps the source filename:
@@ -143,9 +144,17 @@ tabalyst report sales.xlsx
 
 Cells keep their Excel type, and dates are read as dates. A workbook with one
 table needs nothing else. When several sheets or tables are equally plausible,
-Tabalyst stops and lists them instead of choosing: pass `--collection Costs` (or
-`'$.Sales.Orders'` for a named table), or see [Tabalyst Inspect](#tabalyst-inspect).
-Older `.xls` files are not read: save them as `.xlsx`.
+Tabalyst stops and prints one command per table to copy and run, such as
+`tabalyst report shop.xlsx --collection Costs` (or `Sales.Orders` for a named
+table), or see [Tabalyst Inspect](#tabalyst-inspect). To report every table at
+once, use `--all-collections`:
+
+```console
+tabalyst report shop.xlsx --all-collections -d reports
+```
+
+This writes `shop.costs.html` and `shop.costs.json` for each table, named after
+the file and the sheet. Older `.xls` files are not read: save them as `.xlsx`.
 
 ### Multiple files
 
@@ -417,7 +426,9 @@ scan = tabalyst.scan("orders.json")
 scans = tabalyst.generate_scans(["data/*.json"], output_dir="scans")
 
 inspection = tabalyst.inspect("orders.json")
-inspections = tabalyst.generate_inspections(["data/*.json", "logs/*.jsonl", "*.xlsx"])
+inspections = tabalyst.generate_inspections(
+    ["data/*.json", "logs/*.jsonl", "*.xlsx"]
+)
 reports = tabalyst.generate_reports(["scans/*.scan.json"], from_scan=True)
 ```
 
@@ -503,8 +514,30 @@ Additional documentation:
 Please report defects and feature requests through the
 [GitHub issue tracker](https://github.com/loribel-labs/tabalyst/issues).
 
+## For AI assistants
+
+To get help from an AI assistant, paste this prompt into a chat that can read
+web pages:
+
+```text
+Read the complete Tabalyst documentation at
+https://docs.tabalyst.com/llms-full.txt, then help me use Tabalyst well.
+Ask me what my data looks like and what I want to learn from it, then suggest
+the right commands and options. Base your answers only on that documentation.
+```
+
+If the assistant cannot open links, paste the content of the file instead.
+
+The documentation site publishes plain-text versions of its pages:
+[llms.txt](https://docs.tabalyst.com/llms.txt) lists every page with a
+one-line description, and
+[llms-full.txt](https://docs.tabalyst.com/llms-full.txt) holds the whole
+documentation in one file. Every page is also available as Markdown by adding
+`.md` to its URL, for example
+[report.md](https://docs.tabalyst.com/report.md).
+
 ## License
 
 Tabalyst is released under the [Mozilla Public License 2.0](LICENSE).
 
-Created by Gregory Borelli — Catalyseur Numérique.
+Created by Gregory Borelli. Open source project by Loribel Labs.

{tabalyst-0.6.0 → tabalyst-0.6.1}/README.md

@@ -37,6 +37,7 @@ changes often: update it before each new test.
 | One JSON file | `tabalyst report data.json` | `data.report.html` beside the source |
 | One JSONL file | `tabalyst report events.jsonl` | `events.report.html` beside the source |
 | One Excel workbook | `tabalyst report sales.xlsx` | `sales.report.html` beside the source |
+| Every table of a workbook | `tabalyst report shop.xlsx --all-collections` | `shop.costs.html`, `shop.sales.html`, ... beside the source |
 | From a scan document | `tabalyst report --scan data.scan.json` | `data.html` beside the scan |
 
 The simplest command keeps the source filename:
@@ -105,9 +106,17 @@ tabalyst report sales.xlsx
 
 Cells keep their Excel type, and dates are read as dates. A workbook with one
 table needs nothing else. When several sheets or tables are equally plausible,
-Tabalyst stops and lists them instead of choosing: pass `--collection Costs` (or
-`'$.Sales.Orders'` for a named table), or see [Tabalyst Inspect](#tabalyst-inspect).
-Older `.xls` files are not read: save them as `.xlsx`.
+Tabalyst stops and prints one command per table to copy and run, such as
+`tabalyst report shop.xlsx --collection Costs` (or `Sales.Orders` for a named
+table), or see [Tabalyst Inspect](#tabalyst-inspect). To report every table at
+once, use `--all-collections`:
+
+```console
+tabalyst report shop.xlsx --all-collections -d reports
+```
+
+This writes `shop.costs.html` and `shop.costs.json` for each table, named after
+the file and the sheet. Older `.xls` files are not read: save them as `.xlsx`.
 
 ### Multiple files
 
@@ -379,7 +388,9 @@ scan = tabalyst.scan("orders.json")
 scans = tabalyst.generate_scans(["data/*.json"], output_dir="scans")
 
 inspection = tabalyst.inspect("orders.json")
-inspections = tabalyst.generate_inspections(["data/*.json", "logs/*.jsonl", "*.xlsx"])
+inspections = tabalyst.generate_inspections(
+    ["data/*.json", "logs/*.jsonl", "*.xlsx"]
+)
 reports = tabalyst.generate_reports(["scans/*.scan.json"], from_scan=True)
 ```
 
@@ -465,8 +476,30 @@ Additional documentation:
 Please report defects and feature requests through the
 [GitHub issue tracker](https://github.com/loribel-labs/tabalyst/issues).
 
+## For AI assistants
+
+To get help from an AI assistant, paste this prompt into a chat that can read
+web pages:
+
+```text
+Read the complete Tabalyst documentation at
+https://docs.tabalyst.com/llms-full.txt, then help me use Tabalyst well.
+Ask me what my data looks like and what I want to learn from it, then suggest
+the right commands and options. Base your answers only on that documentation.
+```
+
+If the assistant cannot open links, paste the content of the file instead.
+
+The documentation site publishes plain-text versions of its pages:
+[llms.txt](https://docs.tabalyst.com/llms.txt) lists every page with a
+one-line description, and
+[llms-full.txt](https://docs.tabalyst.com/llms-full.txt) holds the whole
+documentation in one file. Every page is also available as Markdown by adding
+`.md` to its URL, for example
+[report.md](https://docs.tabalyst.com/report.md).
+
 ## License
 
 Tabalyst is released under the [Mozilla Public License 2.0](LICENSE).
 
-Created by Gregory Borelli — Catalyseur Numérique.
+Created by Gregory Borelli. Open source project by Loribel Labs.

{tabalyst-0.6.0 → tabalyst-0.6.1}/pyproject.toml

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

{tabalyst-0.6.0 → tabalyst-0.6.1}/src/tabalyst/batch.py

@@ -90,6 +90,16 @@ def resolve_input_specs(input_specs: Sequence[str | Path]) -> list[Path]:
     return sources
 
 
+def output_directory(output_dir: str | Path | None) -> Path | None:
+    """``--output-dir`` as a path, refused when it is an existing file."""
+    if output_dir is None:
+        return None
+    destination = Path(output_dir)
+    if destination.exists() and not destination.is_dir():
+        raise ReportError(f"Output directory path is a file: {destination}")
+    return destination
+
+
 def plan_outputs(
     input_specs: Sequence[str | Path],
     *,
@@ -108,9 +118,7 @@ def plan_outputs(
     if output is not None and len(sources) != 1:
         raise ConfigurationError("--output can only be used with one input file.")
 
-    destination = Path(output_dir) if output_dir is not None else None
-    if destination is not None and destination.exists() and not destination.is_dir():
-        raise ReportError(f"Output directory path is a file: {destination}")
+    destination = output_directory(output_dir)
     return [
         (
             source,

{tabalyst-0.6.0 → tabalyst-0.6.1}/src/tabalyst/cli/inspect.py

@@ -17,6 +17,7 @@ from tabalyst.inspect_service import (
     InspectResult,
     generate_inspections,
 )
+from tabalyst.inspector.choices import choice_lines
 
 _BASES = {
     "root_array": "the root array",
@@ -50,16 +51,12 @@ def _choices(success: InspectResult) -> list[str]:
     detection = success.document.detection
     if detection.selection.basis != "ambiguous":
         return []
-    source = str(success.source)
-    if " " in source:
-        source = f'"{source}"'
-    lines = ["Choose the collection to analyze:"]
-    lines.extend(
-        f"  tabalyst report {source} --collection '{candidate.path}'"
-        for candidate in detection.candidates
-        if candidate.eligible
+    return choice_lines(
+        "report",
+        success.source,
+        [candidate.path for candidate in detection.candidates if candidate.eligible],
+        noun="table" if success.document.inspect.kind == "excel" else "collection",
     )
-    return lines
 
 
 def _print_success(success: InspectResult, *, verbose: bool) -> None:

{tabalyst-0.6.0 → tabalyst-0.6.1}/src/tabalyst/cli/report.py

@@ -16,6 +16,7 @@ from tabalyst.cli.terminal import (
     batch_exit_code,
     collection_paths,
     error_exit_code,
+    error_text,
 )
 from tabalyst.errors import TabalystError
 from tabalyst.report_service import BatchReportResult, ReportSuccess, generate_reports
@@ -70,6 +71,8 @@ def _print_batch_result(
                         details.append(f"delimiter {source['delimiter']!r}")
                     typer.echo("  " + " | ".join(details), err=True)
 
+    for source, warning in batch.plan.warnings:
+        typer.echo(f"Warning [{source}]: {warning}", err=True)
     for success in batch.successes:
         for warning in success.warnings:
             typer.echo(f"Warning [{success.job.source}]: {warning}", err=True)
@@ -81,7 +84,10 @@ def _print_batch_result(
                 err=True,
             )
     for failure in batch.failures:
-        typer.echo(f"Error [{failure.job.source}]: {failure.error}", err=True)
+        typer.echo(
+            f"Error [{failure.job.source}]: {error_text(failure.error, 'report')}",
+            err=True,
+        )
 
     if len(batch.plan.jobs) > 1 and (not quiet or batch.failures):
         typer.echo(
@@ -96,8 +102,8 @@ def report_command(
         typer.Argument(
             metavar="INPUT...",
             help=(
-                "One or more CSV or JSON files, or scan documents with --scan, "
-                "or non-recursive glob patterns."
+                "One or more CSV, JSON, JSONL or Excel (.xlsx, .xlsm) files, or "
+                "scan documents with --scan, or non-recursive glob patterns."
             ),
         ),
     ],
@@ -114,7 +120,10 @@ def report_command(
         typer.Option(
             "--output-dir",
             "-d",
-            help="Directory for reports named after their source files.",
+            help=(
+                "Directory for reports named after their source files; "
+                "required by --all-collections with several inputs."
+            ),
         ),
     ] = None,
     delimiter: Annotated[
@@ -133,6 +142,17 @@ def report_command(
         list[str] | None,
         typer.Option("--collection", help=COLLECTION_HELP),
     ] = None,
+    all_collections: Annotated[
+        bool,
+        typer.Option(
+            "--all-collections",
+            help=(
+                "Report every visible collection of a JSON file or Excel "
+                "workbook, as <name>.<collection>.html and .json; needs -d "
+                "with several inputs."
+            ),
+        ),
+    ] = False,
     from_scan: Annotated[
         bool,
         typer.Option(
@@ -202,9 +222,10 @@ def report_command(
             on_progress=progress,
             from_scan=from_scan,
             workers=workers,
+            all_collections=all_collections,
         )
     except TabalystError as exc:
-        typer.echo(f"Error: {exc}", err=True)
+        typer.echo(f"Error: {error_text(exc, 'report')}", err=True)
         raise typer.Exit(error_exit_code(exc)) from exc
 
     _print_batch_result(batch, quiet=quiet, verbose=verbose)

{tabalyst-0.6.0 → tabalyst-0.6.1}/src/tabalyst/cli/scan.py

@@ -16,6 +16,7 @@ from tabalyst.cli.terminal import (
     batch_exit_code,
     collection_paths,
     error_exit_code,
+    error_text,
 )
 from tabalyst.errors import TabalystError
 from tabalyst.scan_service import BatchScanResult, ScanSuccess, generate_scans
@@ -86,13 +87,18 @@ def _print_batch_result(
                         err=True,
                     )
 
+    for source, warning in batch.plan.warnings:
+        typer.echo(f"Warning [{source}]: {warning}", err=True)
     for success in batch.successes:
         if success.result.status == "partial":
             _print_partial(success)
         for warning in success.warnings:
             typer.echo(f"Warning [{success.job.source}]: {warning}", err=True)
     for failure in batch.failures:
-        typer.echo(f"Error [{failure.job.source}]: {failure.error}", err=True)
+        typer.echo(
+            f"Error [{failure.job.source}]: {error_text(failure.error, 'scan')}",
+            err=True,
+        )
 
     if len(batch.plan.jobs) > 1 and (not quiet or batch.failures):
         typer.echo(
@@ -198,7 +204,7 @@ def scan_command(
             project_storage=True,
         )
     except TabalystError as exc:
-        typer.echo(f"Error: {exc}", err=True)
+        typer.echo(f"Error: {error_text(exc, 'scan')}", err=True)
         raise typer.Exit(error_exit_code(exc)) from exc
 
     _print_batch_result(batch, quiet=quiet, verbose=verbose)

{tabalyst-0.6.0 → tabalyst-0.6.1}/src/tabalyst/cli/terminal.py

@@ -10,8 +10,13 @@ from typing import ClassVar
 import typer
 
 from tabalyst.errors import ConfigurationError, InputError, TabalystError
+from tabalyst.inspector.choices import (
+    UndecidedCollection,
+    choice_lines,
+    expand_collection,
+)
 from tabalyst.progress import ProgressEvent, ProgressPhase
-from tabalyst.scanner.paths import ITEMS, format_absolute, parse_path
+from tabalyst.scanner.readers.excel_common import EXCEL_SUFFIXES
 
 COLLECTION_HELP = (
     "JSON collection: an array path such as '$.data.items[]', or its short "
@@ -21,29 +26,28 @@ COLLECTION_HELP = (
 
 
 def collection_paths(values: list[str] | None) -> list[str] | None:
-    """``--collection`` values as absolute paths. Without the leading ``$``, the
-    value is the keys leading to the array, so ``data.items`` is
-    ``$.data.items[]``, and ``.`` is the root array, ``$[]``; a collection is always an array, so ``[]`` is implied."""
+    """``--collection`` values as absolute paths (see ``expand_collection``)."""
     if values is None:
         return None
     paths = []
     for value in values:
-        if value.startswith("$"):
-            paths.append(value)
-            continue
-        if value == ".":
-            paths.append(format_absolute((ITEMS,)))
-            continue
         try:
-            path = parse_path(value, numeric_keys=True)
+            paths.append(expand_collection(value))
         except ValueError as exc:
             raise typer.BadParameter(str(exc), param_hint="--collection") from exc
-        if not path or path[-1] != ITEMS:
-            path = (*path, ITEMS)
-        paths.append(format_absolute(path))
     return paths
 
 
+def error_text(error: TabalystError, command: str) -> str:
+    """The message of an error, with the commands to copy when a source has
+    several equally plausible collections."""
+    if isinstance(error, UndecidedCollection) and error.eligible:
+        noun = "table" if error.source.suffix.lower() in EXCEL_SUFFIXES else "collection"
+        lines = choice_lines(command, error.source, error.eligible, noun=noun)
+        return "\n".join([str(error), *lines])
+    return str(error)
+
+
 def error_exit_code(error: TabalystError) -> int:
     if isinstance(error, ConfigurationError):
         return 2

tabalyst-0.6.1/src/tabalyst/inspector/choices.py

@@ -0,0 +1,114 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Choosing a collection from the command line.
+
+``--collection`` takes a short form (``Costs``, ``data.items``) or an absolute
+path (``'$["Sales Q1"]'``). This module expands the former, writes the shortest
+value that names a path, and renders the commands to copy when a source has
+several equally plausible collections.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from collections.abc import Sequence
+from pathlib import Path
+
+from tabalyst.errors import ConfigurationError
+from tabalyst.scanner.paths import ITEMS, Items, Key, format_absolute, parse_path
+
+_BARE_KEY = re.compile(r"[A-Za-z0-9_]+")
+
+
+class UndecidedCollection(ConfigurationError):
+    """A source has no collection to analyze, and the command line, the
+    configuration and the detection did not decide one.
+
+    ``eligible`` holds the absolute paths the user can choose from when the
+    detection found several equally plausible ones, empty otherwise. The
+    message stands alone; the command line adds the commands to copy.
+    """
+
+    def __init__(
+        self, message: str, *, source: Path, eligible: Sequence[str] = ()
+    ) -> None:
+        super().__init__(message)
+        self.source = source
+        self.eligible = tuple(eligible)
+
+
+def expand_collection(value: str) -> str:
+    """A ``--collection`` value as an absolute path.
+
+    Without the leading ``$``, the value is the keys leading to the array, so
+    ``data.items`` is ``$.data.items[]``, and ``.`` is the root array, ``$[]``;
+    a collection is always an array, so ``[]`` is implied. Raises ``ValueError``
+    for a value that is not a path.
+    """
+    if value.startswith("$"):
+        return value
+    if value == ".":
+        return format_absolute((ITEMS,))
+    path = parse_path(value, numeric_keys=True)
+    if not path or path[-1] != ITEMS:
+        path = (*path, ITEMS)
+    return format_absolute(path)
+
+
+def _without_items(path: tuple) -> tuple:
+    return path[:-1] if path and isinstance(path[-1], Items) else path
+
+
+def collection_argument(path: str) -> str:
+    """The value of ``--collection`` that names ``path``, as typed in a shell.
+
+    The short form when it expands back to the same path (``Costs``,
+    ``Sales.Orders``, ``data.items``); otherwise the absolute path in single
+    quotes (``'$["Sales Q1"]'``).
+    """
+    segments = _without_items(parse_path(path))
+    if not segments:
+        return "."
+    names = [segment.name for segment in segments if isinstance(segment, Key)]
+    if len(names) == len(segments) and all(_BARE_KEY.fullmatch(n) for n in names):
+        short = ".".join(names)
+        if _without_items(parse_path(expand_collection(short))) == segments:
+            return short
+    return f"'{path}'"
+
+
+def quoted_source(source: str | Path) -> str:
+    text = str(source)
+    return f'"{text}"' if " " in text else text
+
+
+def choice_lines(
+    command: str, source: str | Path, paths: Sequence[str], *, noun: str = "collection"
+) -> list[str]:
+    """The lines that offer to rerun ``command`` once per eligible path, then
+    once for all of them, ready to copy."""
+    name = quoted_source(source)
+    lines = [f"Choose the {noun} to analyze:"]
+    lines.extend(
+        f"  tabalyst {command} {name} --collection {collection_argument(path)}"
+        for path in paths
+    )
+    if command == "report":
+        lines.append(f"Or report every {noun}: tabalyst report {name} --all-collections")
+    return lines
+
+
+def collection_slug(path: str, position: int) -> str:
+    """A file-name part for a collection: its keys, lower case, accents removed,
+    anything else a hyphen (``$["Sales Q1"]`` is ``sales-q1``). ``position`` is
+    the 1-based rank of the collection, for a name with nothing to keep."""
+    names = [s.name for s in _without_items(parse_path(path)) if isinstance(s, Key)]
+    text = unicodedata.normalize("NFKD", "-".join(names))
+    text = "".join(char for char in text if not unicodedata.combining(char))
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    if slug:
+        return slug
+    return "root" if not names else f"collection-{position}"

{tabalyst-0.6.0 → tabalyst-0.6.1}/src/tabalyst/inspector/resolution.py

@@ -20,6 +20,7 @@ from typing import Any, Literal
 
 from tabalyst.config import merge_settings
 from tabalyst.errors import ConfigurationError
+from tabalyst.inspector.choices import UndecidedCollection
 from tabalyst.inspector.excel_inspect import inspect_workbook
 from tabalyst.inspector.excel_inspect import parameters as excel_parameters
 from tabalyst.inspector.json_inspect import inspect_source
@@ -183,6 +184,30 @@ def resolve_interpretation(
     )
 
 
+def detect_collections(
+    source: str | Path,
+    *,
+    scan_layer: dict[str, Any] | None = None,
+    location: StorageLocation | None = None,
+) -> tuple[InspectDocument, tuple[str, ...]]:
+    """The automatic detection of a JSON or Excel source: every candidate
+    collection, whatever the selection, and the notices to print.
+
+    It is the detection ``resolve_interpretation`` makes, cached the same way,
+    and ignores the visible Inspect file and the collection that a
+    configuration file names: it lists what the source holds.
+    """
+    source = Path(source)
+    source_format = source_format_of(source)
+    if source_format not in ("json", "excel"):
+        raise ValueError(f"{source.name} has no collections to detect.")
+    layer = scan_layer or {}
+    if source_format == "excel":
+        layer = _without_collections(layer)
+    document, _, notices, _ = _detect(source, layer, location, None)
+    return document, notices
+
+
 def check_result(interpretation: Interpretation, result: ScanResult) -> tuple[str, ...]:
     """Compare a scan result with the interpretation it was made with.
 
@@ -423,7 +448,7 @@ def _suspension(
     visible: VisibleInspect | None,
     detected: InspectDocument | None,
     notices: Sequence[str] = (),
-) -> ConfigurationError:
+) -> UndecidedCollection:
     if visible is not None:
         candidates = visible.candidates
         basis = visible.selection_basis
@@ -469,7 +494,15 @@ def _suspension(
         )
     # What was found out on the way, such as a cache that could not be written.
     lines.extend(notices)
-    return ConfigurationError("\n".join(lines))
+    return UndecidedCollection(
+        "\n".join(lines), source=source, eligible=_choices(basis, eligible)
+    )
+
+
+def _choices(basis: str | None, eligible: Sequence[CandidateSummary]) -> list[str]:
+    """What the user can choose from: only when the detection found several
+    equally plausible candidates."""
+    return [item.path for item in eligible] if basis == "ambiguous" else []
 
 
 def _excel_suspension(
@@ -479,7 +512,7 @@ def _excel_suspension(
     eligible: Sequence[CandidateSummary],
     visible: VisibleInspect | None,
     notices: Sequence[str],
-) -> ConfigurationError:
+) -> UndecidedCollection:
     if basis == "ambiguous":
         why = f"{len(eligible)} tables of {source.name} are equally plausible."
     elif basis == "candidates_truncated":
@@ -511,7 +544,9 @@ def _excel_suspension(
             "config.structure.dataset_path in the file it writes."
         )
     lines.extend(notices)
-    return ConfigurationError("\n".join(lines))
+    return UndecidedCollection(
+        "\n".join(lines), source=source, eligible=_choices(basis, eligible)
+    )
 
 
 _REASONS = {

tabalyst-0.6.1/src/tabalyst/option_notices.py

@@ -0,0 +1,54 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Notices for command-line options that a source cannot use.
+
+``--delimiter`` and ``--encoding`` read CSV files, ``--collection`` and
+``--all-collections`` choose among the collections of a JSON file or the tables
+of a workbook. On another kind of source they have nothing to act on: they are
+ignored, and the user is told so instead of believing they applied.
+"""
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from tabalyst.scanner.identity import source_format_of
+
+_ONE_DATASET = {
+    "csv": "a CSV file holds one table",
+    "jsonl": "a JSONL file holds one dataset, its lines",
+}
+
+
+def ignored_options(
+    source: Path,
+    *,
+    delimiter: str | None = None,
+    encoding: str | None = None,
+    collections: Sequence[str] | None = None,
+    all_collections: bool = False,
+) -> list[str]:
+    """Sentences for the options given that ``source`` does not use."""
+    source_format = source_format_of(source)
+    notices: list[str] = []
+    if source_format != "csv":
+        names = [
+            name
+            for name, value in (("--delimiter", delimiter), ("--encoding", encoding))
+            if value is not None
+        ]
+        if names:
+            verb = "is" if len(names) == 1 else "are"
+            notices.append(
+                f"{' and '.join(names)} {verb} ignored: {source.name} is not a CSV file."
+            )
+    reason = _ONE_DATASET.get(source_format)
+    if reason is not None:
+        if collections:
+            notices.append(f"--collection is ignored: {reason}.")
+        if all_collections:
+            notices.append(
+                f"--all-collections has no effect: {reason}, reported as usual."
+            )
+    return notices