tabpull 0.1.0__py3-none-any.whl

tabpull/filters.py

@@ -0,0 +1,172 @@
+import re
+from collections.abc import Sequence
+from dataclasses import replace
+from datetime import date
+
+from tabpull import ui
+from tabpull.jobs import Job, JobError, RangeFilter, ValuesFilter
+
+# Tableau's range-filter API only accepts a Date or a number.
+_US_DATE = re.compile(r'^(\d{1,2})/(\d{1,2})/(\d{4})$')
+_ISO_DATE = re.compile(r'^(\d{4})-(\d{2})-(\d{2})$')
+_NUMBER = re.compile(r'^-?\d+(\.\d+)?$')
+
+
+def resolved_filters(job: Job) -> list[ValuesFilter | RangeFilter]:
+    if not job.sheets:
+        msg = f'job {job.name!r}: needs at least one sheet'
+        raise JobError(msg)
+    default = job.sheets[0]
+    resolved: list[ValuesFilter | RangeFilter] = []
+    for item in job.filters:
+        if item.sheet:
+            resolved.append(item)
+            continue
+        _note_default_sheet(job, item.field, default)
+        resolved.append(replace(item, sheet=default))
+    return resolved
+
+
+def _note_default_sheet(job: Job, field_name: str, sheet: str) -> None:
+    ui.emit(
+        f'  {job.name}: filter {field_name!r} names no sheet; '
+        f'applying it on {sheet!r}, the first sheet in the job.'
+    )
+
+
+def same_filter(
+    item: ValuesFilter | RangeFilter,
+    existing: ValuesFilter | RangeFilter,
+    default_sheet: str,
+) -> bool:
+    """Report whether `item` is the same filter row as `existing`.
+
+    Field names must match. A sheetless item matches that field on every
+    sheet, which is how a run override with no `` @Sheet`` replaces it
+    everywhere. Otherwise the saved sheet, or the job's first sheet when
+    the saved row names none, must equal the item's sheet.
+    """
+    return existing.field == item.field and (
+        not item.sheet or (existing.sheet or default_sheet) == item.sheet
+    )
+
+
+def filters_for_run(job: Job, overrides: Sequence[ValuesFilter | RangeFilter]) -> Job:
+    if not overrides:
+        return job
+    default = job.sheets[0]
+    filters: list[ValuesFilter | RangeFilter] = list(job.filters)
+    for item in overrides:
+        if any(same_filter(item, existing, default) for existing in filters):
+            filters = [
+                replace(item, sheet=item.sheet or existing.sheet)
+                if same_filter(item, existing, default)
+                else existing
+                for existing in filters
+            ]
+            continue
+        if not item.sheet:
+            _note_default_sheet(job, item.field, default)
+        filters.append(replace(item, sheet=item.sheet or default))
+    return replace(job, filters=filters)
+
+
+def params_for_run(job: Job, overrides: Sequence[tuple[str, str]]) -> Job:
+    if not overrides:
+        return job
+    return replace(job, params={**job.params, **dict(overrides)})
+
+
+def _calendar_day(year: int, month: int, day: int, original: str) -> date:
+    try:
+        return date(year, month, day)
+    except ValueError:
+        msg = f'{original!r} is not a real date; use YYYY-MM-DD or M/D/YYYY'
+        raise JobError(msg) from None
+
+
+def normalize_range_bound(value: str | None) -> str | None:
+    if value is None:
+        return None
+    text = value.strip()
+    if not text:
+        return None
+    if _NUMBER.fullmatch(text):
+        return text
+    us = _US_DATE.fullmatch(text)
+    if us is not None:
+        month, day, year = (int(part) for part in us.groups())
+        return _calendar_day(year, month, day, value).isoformat()
+    iso = _ISO_DATE.fullmatch(text)
+    if iso is not None:
+        year, month, day = (int(part) for part in iso.groups())
+        return _calendar_day(year, month, day, value).isoformat()
+    msg = (
+        f'{value!r} is a relative date or a date computed at run time; '
+        'use YYYY-MM-DD or M/D/YYYY'
+    )
+    raise JobError(msg)
+
+
+def split_values(value: str) -> list[str]:
+    return [v.strip() for v in value.split('|')]
+
+
+def parse_filter_spec(spec: str) -> ValuesFilter | RangeFilter:
+    body, sep, sheet = spec.rpartition(' @')
+    if not sep:
+        body, sheet = spec, ''
+    field_name, eq, value = body.partition('=')
+    sheet = sheet.strip()
+    if not eq or not field_name.strip():
+        msg = (
+            f'filter {spec!r} should look like Field=a|b or Field=min..max, '
+            'with an optional " @Sheet"'
+        )
+        raise JobError(msg)
+    if '..' in value:
+        low, _, high = value.partition('..')
+        if not low.strip() and not high.strip():
+            msg = (
+                f'filter {spec!r} should look like Field=a|b or Field=min..max, '
+                'with an optional " @Sheet"'
+            )
+            raise JobError(msg)
+        return make_filter(field_name, sheet, low=low, high=high)
+    return make_filter(field_name, sheet, values=value)
+
+
+def make_filter(
+    field_name: str,
+    sheet: str,
+    *,
+    values: str | None = None,
+    low: str | None = None,
+    high: str | None = None,
+) -> ValuesFilter | RangeFilter:
+    sheet = sheet.strip()
+    if not field_name.strip():
+        msg = 'filter needs a field name'
+        raise JobError(msg)
+    if values is not None:
+        return ValuesFilter(field_name, split_values(values), sheet)
+    low, high = (low or '').strip() or None, (high or '').strip() or None
+    if low is None and high is None:
+        msg = f'range filter {field_name!r} needs a min, a max, or both'
+        raise JobError(msg)
+    normalize_range_bound(low)
+    normalize_range_bound(high)
+    return RangeFilter(field_name, sheet, low, high)
+
+
+def format_filter(item: ValuesFilter | RangeFilter) -> str:
+    spec = f'{item.field}={item.shown}'
+    return f'{spec} @{item.sheet}' if item.sheet else spec
+
+
+def parse_param_spec(spec: str) -> tuple[str, str]:
+    key, sep, value = spec.partition('=')
+    if not sep or not key.strip():
+        msg = f'param {spec!r} should look like Name=value'
+        raise JobError(msg)
+    return key.strip(), value.strip()

tabpull/home.py

@@ -0,0 +1,187 @@
+import argparse
+import json
+import re
+import shlex
+import sys
+import tomllib
+from collections.abc import Sequence
+from pathlib import Path
+
+from rich import box
+from rich.markup import escape
+from rich.panel import Panel
+from rich.table import Table
+
+from tabpull import ui
+from tabpull.jobs import Job, JobError, load_jobs
+from tabpull.tableau import MissingSettingsError, list_sites, load_site
+
+_TOON_NUMBER = re.compile(r'^[+-]?[0-9]+(?:\.[0-9]+)?(?:e[+-]?[0-9]+)?$', re.IGNORECASE)
+_TOON_QUOTE = re.compile(r'[,:"\\\[\]{}\x00-\x1f]')
+
+
+def _toon(value: object) -> str:
+    text = str(value)
+    if isinstance(value, int):
+        return text
+    if (
+        text in {'', 'true', 'false', 'null'}
+        or text != text.strip(' \t')
+        or text.startswith(('-', '#'))
+        or _TOON_NUMBER.match(text)
+        or _TOON_QUOTE.search(text)
+    ):
+        return json.dumps(text, ensure_ascii=False)
+    return text
+
+
+def _toon_table(
+    name: str, fields: Sequence[str], rows: Sequence[Sequence[object]]
+) -> list[str]:
+    head = f'{name}[{len(rows)}]{{{",".join(fields)}}}:'
+    return [head, *('  ' + ','.join(map(_toon, row)) for row in rows)]
+
+
+def file_flags(args: argparse.Namespace) -> list[str]:
+    flags = []
+    if args.jobs:
+        flags += ['--jobs', str(args.jobs)]
+    if args.out:
+        flags += ['--out', str(args.out)]
+    return flags
+
+
+def sso_badge(name: str, server: str) -> str:
+    if server == '(incomplete)':
+        return '[red]incomplete[/]'
+    if load_site(name).auth_path.exists():
+        return '[green]● saved[/]'
+    return '[yellow]● not signed in[/]'
+
+
+def _home_help(
+    args: argparse.Namespace,
+    sites: Sequence[Sequence[str]],
+    jobs: Sequence[Job],
+) -> list[str]:
+    help_lines: list[str] = []
+    if not sites:
+        help_lines.append('Run `tabpull setup` to connect a Tableau site')
+    quoted = shlex.join(file_flags(args))
+    flags = f' {quoted}' if quoted else ''
+    if jobs:
+        help_lines += [
+            f'Run `tabpull run{flags}` to export every job into the out folder',
+            f'Run `tabpull run <name>{flags}` to export one job',
+        ]
+    if sites:
+        jobs_flag = f' --jobs {shlex.quote(str(args.jobs))}' if args.jobs else ''
+        help_lines.append(
+            f'Run `tabpull add --view <Workbook/View> --sheet "<sheet>"{jobs_flag}` to save a job'
+        )
+    return help_lines
+
+
+def _print_home(
+    sites: Sequence[Sequence[str]],
+    jobs: Sequence[Job],
+    jobs_error: str | None,
+    jobs_file: Path,
+    out_dir: Path,
+) -> None:
+    if sites:
+        sites_table = Table(box=box.SIMPLE_HEAD, expand=True)
+        for col in ('site', 'server', 'tableau site', 'sso'):
+            sites_table.add_column(col)
+        for name, server, site in sites:
+            sites_table.add_row(
+                f'[bold]{escape(name)}[/]',
+                escape(server),
+                escape(site),
+                sso_badge(name, server),
+            )
+        sites_body: Table | str = sites_table
+    else:
+        sites_body = '0 configured'
+    ui.console.print(
+        Panel(
+            sites_body,
+            title='[bold]Sites[/]',
+            title_align='left',
+            border_style='blue',
+        )
+    )
+    jobs_body: Table | str
+    if jobs_error is not None:
+        jobs_body = escape(jobs_error)
+    elif jobs:
+        jobs_table = Table(box=box.SIMPLE_HEAD, expand=True)
+        for col in ('job', 'site', 'view', 'sheets', 'filters'):
+            jobs_table.add_column(col)
+        for job in jobs:
+            jobs_table.add_row(
+                f'[bold]{escape(job.name)}[/]',
+                escape(job.site),
+                escape(job.view),
+                '\n'.join(escape(sheet) for sheet in job.sheets),
+                str(len(job.filters)),
+            )
+        jobs_body = jobs_table
+    else:
+        jobs_body = '0 saved'
+    ui.console.print(
+        Panel(jobs_body, title='[bold]Jobs[/]', title_align='left', border_style='blue')
+    )
+    ui.console.print(
+        f'  [dim]jobs file[/] {escape(ui.home_path(jobs_file))}\n'
+        f'  [dim]exports  [/] {escape(ui.home_path(out_dir))}/<job>/<sheet>.csv'
+    )
+
+
+def site_rows() -> list[list[str]]:
+    rows = []
+    for name in list_sites():
+        try:
+            settings = load_site(name)
+        except (MissingSettingsError, ValueError):
+            rows.append([name, '(incomplete)', ''])
+        else:
+            rows.append([name, settings.server, settings.site])
+    return rows
+
+
+def show_home(args: argparse.Namespace, jobs_file: Path, out_dir: Path) -> None:
+    sites = site_rows()
+    jobs_error: str | None = None
+    try:
+        jobs = load_jobs(jobs_file)
+    except (JobError, tomllib.TOMLDecodeError, OSError) as e:
+        jobs_error = f'unreadable: {e}'
+        jobs = []
+    help_lines = _home_help(args, sites, jobs)
+    if ui.rich_output():
+        _print_home(sites, jobs, jobs_error, jobs_file, out_dir)
+        if help_lines:
+            body = '\n'.join(f'  {escape(line)}' for line in help_lines)
+            ui.console.print(f'\n  [bold]next[/]\n{body}\n')
+        return
+    lines = [
+        f'bin: {_toon(ui.home_path(sys.argv[0]))}',
+        'description: Export Tableau dashboard sheet crosstabs to CSV',
+        f'jobs_file: {_toon(ui.home_path(jobs_file))}',
+        f'out: {_toon(ui.home_path(out_dir))}',
+    ]
+    if sites:
+        lines += _toon_table('sites', ('name', 'server', 'site'), sites)
+    else:
+        lines.append('sites: 0 configured')
+    if jobs_error is not None:
+        lines.append(f'jobs: {_toon(jobs_error)}')
+    elif jobs:
+        rows = [[j.name, j.site, j.view, len(j.sheets)] for j in jobs]
+        lines += _toon_table('jobs', ('name', 'site', 'view', 'sheets'), rows)
+    else:
+        lines.append('jobs: 0 saved')
+    lines.append(f'help[{len(help_lines)}]:')
+    lines += [f'  {line}' for line in help_lines]
+    print('\n'.join(lines))

tabpull/jobs.py

@@ -0,0 +1,201 @@
+import json
+import re
+import tomllib
+from collections.abc import Sequence
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import ClassVar
+
+
+@dataclass(frozen=True)
+class ValuesFilter:
+    field: str
+    values: list[str]
+    sheet: str = ''
+    kind: ClassVar[str] = 'values'
+
+    @property
+    def pick_list(self) -> str:
+        return '|'.join(self.values)
+
+    @property
+    def bounds(self) -> tuple[str, str]:
+        return '', ''
+
+    @property
+    def shown(self) -> str:
+        return self.pick_list
+
+
+@dataclass(frozen=True)
+class RangeFilter:
+    field: str
+    sheet: str
+    min: str | None = None
+    max: str | None = None
+    kind: ClassVar[str] = 'range'
+
+    @property
+    def pick_list(self) -> str:
+        return ''
+
+    @property
+    def bounds(self) -> tuple[str, str]:
+        return self.min or '', self.max or ''
+
+    @property
+    def shown(self) -> str:
+        return '..'.join(self.bounds)
+
+
+@dataclass(frozen=True)
+class Job:
+    name: str
+    view: str
+    sheets: list[str]
+    site: str
+    filters: list[ValuesFilter | RangeFilter] = field(default_factory=list)
+    params: dict[str, str] = field(default_factory=dict)
+
+
+class JobError(Exception):
+    pass
+
+
+def _parse_filter(raw: object) -> ValuesFilter | RangeFilter:
+    if not isinstance(raw, dict):
+        msg = f'filter {raw!r} is not a table'
+        raise JobError(msg)
+    raw = dict(raw)
+    raw['sheet'] = str(raw.get('sheet') or '').strip()
+    if 'values' not in raw:
+        bounds = [raw.get('min'), raw.get('max')]
+        if any(bound is not None and not isinstance(bound, str) for bound in bounds):
+            msg = (
+                f'range filter {raw.get("field")!r}: quote min and max, '
+                'as in min = "2024-01-01"'
+            )
+            raise JobError(msg)
+        if not any((bound or '').strip() for bound in bounds):
+            msg = f'range filter {raw.get("field")!r} needs a min, a max, or both'
+            raise JobError(msg)
+    try:
+        return ValuesFilter(**raw) if 'values' in raw else RangeFilter(**raw)
+    except TypeError as e:
+        msg = str(e)
+        raise JobError(msg) from e
+
+
+def parse_job(raw: object) -> Job:
+    if not isinstance(raw, dict):
+        msg = f'job {raw!r} is not a table'
+        raise JobError(msg)
+    raw = dict(raw)
+    name = raw.get('name', '?')
+    if not raw.get('sheets'):
+        msg = f'job {name!r}: needs at least one sheet'
+        raise JobError(msg)
+    site = raw.get('site')
+    if not isinstance(site, str) or not site.strip():
+        msg = f'job {name!r}: needs a site'
+        raise JobError(msg)
+    raw['site'] = site.strip()
+    try:
+        filters = [_parse_filter(item) for item in raw.pop('filters', [])]
+        return Job(**raw, filters=filters)
+    except (TypeError, KeyError, JobError) as e:
+        msg = f'job {raw.get("name", "?")!r}: {e}'
+        raise JobError(msg) from e
+
+
+def _jobs_from_text(text: str) -> list[Job]:
+    raw_jobs = tomllib.loads(text).get('job', [])
+    if not isinstance(raw_jobs, list):
+        msg = '`job` must be an array of tables'
+        raise JobError(msg)
+    return [parse_job(raw) for raw in raw_jobs]
+
+
+def load_jobs(path: Path) -> list[Job]:
+    if not path.exists():
+        return []
+    return _jobs_from_text(path.read_text(encoding='utf-8'))
+
+
+def save_jobs(path: Path, jobs: Sequence[Job]) -> None:
+    text = '\n'.join(job_to_toml(job) for job in jobs)
+    _jobs_from_text(text)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    scratch = path.with_name(path.name + '.tmp')
+    scratch.write_text(text, encoding='utf-8')
+    scratch.replace(path)
+
+
+def saved_jobs_or_exit(path: Path) -> list[Job]:
+    try:
+        jobs = load_jobs(path)
+    except (JobError, tomllib.TOMLDecodeError, OSError) as e:
+        msg = f'{path}: {e}'
+        raise SystemExit(msg) from e
+    if not jobs:
+        msg = f'No jobs in {path}. Run: tabpull add'
+        raise SystemExit(msg)
+    return jobs
+
+
+def check_known(names: Sequence[str], jobs: Sequence[Job]) -> None:
+    if unknown := sorted(set(names) - {job.name for job in jobs}):
+        saved = ', '.join(job.name for job in jobs) or 'none'
+        msg = f'Unknown jobs: {", ".join(unknown)}. Saved jobs: {saved}'
+        raise JobError(msg)
+
+
+def update_job(path: Path, old_name: str, job: Job) -> list[Job]:
+    jobs = load_jobs(path)
+    check_known([old_name], jobs)
+    index = next(i for i, saved in enumerate(jobs) if saved.name == old_name)
+    if job.name != old_name and any(saved.name == job.name for saved in jobs):
+        msg = f'A job named {job.name!r} already exists in {path}.'
+        raise JobError(msg)
+    jobs[index] = job
+    save_jobs(path, jobs)
+    return jobs
+
+
+def delete_jobs(path: Path, names: Sequence[str]) -> list[Job]:
+    jobs = load_jobs(path)
+    check_known(names, jobs)
+    kept = [job for job in jobs if job.name not in names]
+    save_jobs(path, kept)
+    return kept
+
+
+def _toml(value: object) -> str:
+    if isinstance(value, list):
+        return '[' + ', '.join(_toml(v) for v in value) + ']'
+    if isinstance(value, dict):
+        return (
+            '{ '
+            + ', '.join(f'{json.dumps(k)} = {_toml(v)}' for k, v in value.items())
+            + ' }'
+        )
+    return json.dumps(value, ensure_ascii=False)
+
+
+def job_to_toml(job: Job) -> str:
+    fields = asdict(job)
+    fields['filters'] = [
+        {k: v for k, v in item.items() if v or isinstance(v, list)}
+        for item in fields['filters']
+    ]
+    lines = [
+        '[[job]]',
+        f'name = {_toml(fields.pop("name"))}',
+        f'site = {_toml(fields.pop("site"))}',
+    ]
+    lines += [f'{key} = {_toml(value)}' for key, value in fields.items() if value]
+    return '\n'.join(lines) + '\n'
+
+
+def slug(text: str) -> str:
+    return re.sub(r'[^\w.-]+', '_', text).strip('_') or 'export'

tabpull/remove.py

@@ -0,0 +1,88 @@
+import tomllib
+from collections.abc import Sequence
+from pathlib import Path
+
+import questionary
+from rich.markup import escape
+from rich.panel import Panel
+
+from tabpull import ui
+from tabpull.jobs import Job, JobError, delete_jobs, saved_jobs_or_exit
+
+
+def _saved(jobs: Sequence[Job]) -> str:
+    return ', '.join(job.name for job in jobs)
+
+
+def _pick(jobs: Sequence[Job]) -> list[str]:
+    picked = ui.ask(
+        questionary.checkbox(
+            'Jobs to remove',
+            choices=[
+                questionary.Choice(
+                    f'{job.name}  {job.site}  {job.view}', value=job.name
+                )
+                for job in jobs
+            ],
+            style=ui.STYLE,
+        )
+    )
+    if not picked:
+        return []
+    shown = ', '.join(picked)
+    if not ui.ask(
+        questionary.confirm(f'Remove {shown}?', default=False, style=ui.STYLE)
+    ):
+        return []
+    return list(picked)
+
+
+def _names_to_remove(jobs: Sequence[Job], names: Sequence[str]) -> list[str]:
+    if names:
+        return list(names)
+    if not ui.interactive():
+        msg = f'Pass job names to remove. Saved jobs: {_saved(jobs)}'
+        raise SystemExit(msg)
+    return _pick(jobs)
+
+
+def _report(path: Path, removed: Sequence[Job]) -> None:
+    names = ', '.join(job.name for job in removed)
+    if not ui.rich_output():
+        print(f'Removed {names} from {path}')
+        return
+    lines = [
+        f'[bold]{escape(job.name)}[/]  {escape(job.site)}  {escape(job.view)}'
+        for job in removed
+    ]
+    lines.append(escape(str(path)))
+    ui.console.print(
+        Panel(
+            '\n'.join(lines),
+            title='[green]✓ Removed[/]',
+            title_align='left',
+            border_style='green',
+        )
+    )
+
+
+def _rewrite(path: Path, jobs: Sequence[Job], names: Sequence[str]) -> None:
+    drop = set(names)
+    removed = [job for job in jobs if job.name in drop]
+    try:
+        delete_jobs(path, names)
+    except JobError as e:
+        raise SystemExit(str(e)) from e
+    except (tomllib.TOMLDecodeError, OSError) as e:
+        msg = f'{path}: {e}'
+        raise SystemExit(msg) from e
+    _report(path, removed)
+
+
+def remove_jobs(path: Path, names: Sequence[str]) -> None:
+    jobs = saved_jobs_or_exit(path)
+    chosen = _names_to_remove(jobs, names)
+    if not chosen:
+        print('Nothing removed.')
+        return
+    _rewrite(path, jobs, chosen)