zendt 0.1.0__py3-none-any.whl

zendt/__init__.py

@@ -0,0 +1,3 @@
+from zendt.main import apply, flow, rules_list
+
+__all__ = ['apply', 'flow', 'rules_list']

zendt/__main__.py

@@ -0,0 +1,4 @@
+from zendt.cli import app
+
+if __name__ == '__main__':
+    app()

zendt/cli.py

@@ -0,0 +1,167 @@
+import sys
+from typing import Annotated
+
+import pandas as pd
+import typer
+
+from zendt.config.create import create_config
+from zendt.config.edit import edit_config
+from zendt.engine.output import write_output
+from zendt.errors import ZendtError
+from zendt.main import apply, flow, rules_list
+
+app = typer.Typer(
+    name='zendt',
+    help='Apply JDM (GoRules) rules to data from the terminal.',
+    no_args_is_help=True,
+)
+
+SourceOption = typer.Option(
+    None,
+    '--source',
+    '-s',
+    help='GitHub URL, local path, or id of a configured source.',
+)
+
+FindOption = typer.Option(
+    None,
+    '--find',
+    '-f',
+    help='Search for rules whose name contains the specified word.',
+)
+
+VersionOption = typer.Option(
+    None,
+    '--version',
+    '-v',
+    help='Rule version to apply for git repositories.',
+)
+
+AuthOption = typer.Option(
+    None,
+    '--authentication',
+    '-a',
+    help=(
+        'Name of the environment variable that holds the token '
+        '(private repositories).'
+    ),
+)
+
+InputOption = typer.Option(
+    None,
+    '--input',
+    '-i',
+    help='Input file to process.',
+)
+
+OutputOption = typer.Option(
+    None,
+    '--output',
+    '-o',
+    help='Output file to save.',
+)
+
+PrintHeadOption = typer.Option(
+    False,
+    '--printhead',
+    '-ph',
+    help='Print a preview of the result on screen.',
+)
+
+CreateConfigOption = typer.Option(
+    False,
+    '--create',
+    '-c',
+    help='Create a zendt.json configuration file.',
+)
+
+EditConfigOption = typer.Option(
+    False,
+    '--edit',
+    '-e',
+    help='Edit the zendt.json configuration file.',
+)
+
+
+def echo_head(frame: pd.DataFrame) -> None:
+    """Preview on the terminal.
+
+    Keep it off stdout when that stream carries the csv.
+    """
+    typer.echo(frame.head(), err=not sys.stdout.isatty())
+
+
+@app.command('config')
+def config(
+    create: bool = CreateConfigOption,
+    edit: bool = EditConfigOption,
+) -> None:
+    """Manage the zendt.json configuration file."""
+    if create:
+        create_config()
+    elif edit:
+        edit_config()
+
+
+@app.command('list')
+def list_rules_command(
+    source: str = SourceOption,
+    find: str = FindOption,
+    version: str = VersionOption,
+    authentication: str = AuthOption,
+) -> None:
+    """List the JDM rules found in SOURCE."""
+    try:
+        names = rules_list(source, find, version, authentication)
+    except ZendtError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=exc.exit_code) from exc
+
+    typer.echo('Rules found in provided sources:')
+    for name in names:
+        typer.echo(name)
+
+
+@app.command('apply')
+def apply_command(
+    rules: Annotated[
+        list[str], typer.Argument(help='Names of the rules to apply.')
+    ],
+    source: str = SourceOption,
+    authentication: str = AuthOption,
+    version: str = VersionOption,
+    input: str = InputOption,
+    output: str = OutputOption,
+    printhead: bool = PrintHeadOption,
+) -> None:
+    """Apply the JDM rules passed as arguments."""
+    try:
+        result = apply(rules, source, authentication, version, input)
+        write_output(result, output)
+        if printhead:
+            echo_head(result)
+    except ZendtError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=exc.exit_code) from exc
+
+
+@app.command('flow')
+def flow_command(
+    flow_id: Annotated[str, typer.Argument(help='Configured flow ID.')],
+    input: str = InputOption,
+    output: str = OutputOption,
+    printhead: bool = PrintHeadOption,
+) -> None:
+    """Apply a pre-configured flow."""
+    try:
+        result = flow(flow_id, input)
+    except ZendtError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=exc.exit_code) from exc
+
+    destination = output
+    if destination is None:
+        destination = result.attrs.get('output')
+    write_output(result, destination)
+    if printhead:
+        echo_head(result)

zendt/config/create.py

@@ -0,0 +1,166 @@
+from pathlib import Path
+
+import typer
+
+from zendt.config.helper import save_config
+from zendt.utils.paths import is_remote
+
+
+def create_source() -> dict:
+    """Create a new source."""
+    typer.echo('Enter a unique name for your source (ID):')
+    source_id = typer.prompt('Source ID')
+
+    typer.echo('Enter the source location (local path or git URL):')
+    source_location = typer.prompt('Source location')
+
+    if is_remote(source_location):
+        is_private = typer.confirm('Is this a private repository?')
+        if is_private:
+            typer.echo(
+                'Enter the name of the environment variable for the '
+                'authentication token [do not enter the token]:'
+            )
+            source_authentication = typer.prompt('Source Authentication')
+        else:
+            source_authentication = None
+
+        version = typer.confirm(
+            'Would you like to specify a version for this source? '
+            'If no, the ref in the URL is used, or HEAD when the URL has none.'
+        )
+        if version:
+            typer.echo('Enter the source version:')
+            source_version = typer.prompt('Source Version')
+        else:
+            source_version = None
+    else:
+        source_authentication = None
+        source_version = None
+
+    source = {}
+    source['id'] = source_id
+    source['source'] = source_location
+    if source_authentication:
+        source['authentication'] = source_authentication
+    if source_version:
+        source['version'] = source_version
+
+    return source
+
+
+def take_source(sources: list[dict], source: dict) -> bool:
+    """Append a source when its id is usable.
+
+    False leaves the list unchanged.
+    """
+    source_id = source.get('id', '')
+    if not source_id or '/' in source_id:
+        typer.echo(
+            "Source id is required and cannot contain '/'. "
+            'Source was not added.'
+        )
+        return False
+    if any(item.get('id') == source_id for item in sources):
+        typer.echo(
+            f"Source '{source_id}' already exists. Source was not added."
+        )
+        return False
+    sources.append(source)
+    return True
+
+
+def create_flow() -> dict:
+    """Create a new flow."""
+    flow_id = typer.prompt('Enter a unique name for your flow (ID):')
+    flow_description = typer.prompt('Describe your flow in a few words:')
+
+    flow_rules = [
+        rule.strip()
+        for rule in typer.prompt(
+            'Enter the rule(s) for your flow, comma separated:'
+        ).split(',')
+    ]
+
+    input_file = typer.confirm(
+        'Would you like to specify a input file for your flow? '
+        'Accepted formats: csv, csv.gz, xlsx, json'
+    )
+    if input_file:
+        flow_input = typer.prompt('Flow Input Path [example: data/input.csv]:')
+    else:
+        flow_input = None
+
+    output_file = typer.confirm(
+        'Would you like to specify a output file for your flow? '
+        'Accepted formats: csv, csv.gz, xlsx, json'
+    )
+    if output_file:
+        flow_output = typer.prompt(
+            'Flow Output Path [example: data/output.csv]:'
+        )
+    else:
+        flow_output = None
+
+    flow = {}
+    flow['id'] = flow_id
+    flow['description'] = flow_description
+    flow['rules'] = flow_rules
+    if flow_input:
+        flow['input'] = flow_input
+    if flow_output:
+        flow['output'] = flow_output
+
+    return flow
+
+
+def take_flow(flows: list[dict], flow: dict) -> bool:
+    """Append a flow when its id and rules are usable.
+
+    False leaves the list unchanged.
+    """
+    flow_id = flow.get('id', '')
+    if not flow_id:
+        typer.echo('Flow id is required. Flow was not added.')
+        return False
+    if any(item.get('id') == flow_id for item in flows):
+        typer.echo(f"Flow '{flow_id}' already exists. Flow was not added.")
+        return False
+    flow['rules'] = [rule for rule in flow.get('rules') or [] if rule]
+    if not flow['rules']:
+        typer.echo('A flow needs at least one rule. Flow was not added.')
+        return False
+    flows.append(flow)
+    return True
+
+
+def create_config() -> None:
+    """Create a new config file."""
+
+    path = Path.cwd() / 'zendt.json'
+    if path.exists():
+        if not typer.confirm(
+            f'Config file already exists at {path}. '
+            'Would you like to overwrite it?'
+        ):
+            typer.echo('Config file not overwritten.')
+            return
+
+    config = {
+        'sources': [],
+        'flows': [],
+    }
+
+    typer.echo("Let's create the first source...")
+    while True:
+        if take_source(config['sources'], create_source()):
+            if not typer.confirm('Do you want to add another source?'):
+                break
+
+    if typer.confirm('Would you like to create a flow?'):
+        while True:
+            if take_flow(config['flows'], create_flow()):
+                if not typer.confirm('Do you want to add another flow?'):
+                    break
+
+    save_config(config)

zendt/config/edit.py

@@ -0,0 +1,252 @@
+import json
+from pathlib import Path
+
+import typer
+
+from zendt.config.create import (
+    create_flow,
+    create_source,
+    take_flow,
+    take_source,
+)
+from zendt.config.helper import save_config
+from zendt.utils.paths import is_remote
+
+
+def open_config() -> dict | None:
+    """Load zendt.json from the current directory."""
+    path = Path.cwd() / 'zendt.json'
+    if not path.exists():
+        typer.echo(
+            'Config file not found. Please create it first using '
+            "'zendt config --create'."
+        )
+        return None
+    try:
+        config = json.loads(path.read_text(encoding='utf-8'))
+    except Exception as exc:
+        typer.echo(f'Error loading config file: {exc}')
+        return None
+
+    if not isinstance(config, dict) or not isinstance(
+        config.get('sources'), list
+    ):
+        typer.echo("Config file is missing a 'sources' array.")
+        return None
+    if 'flows' not in config:
+        config['flows'] = []
+    elif not isinstance(config['flows'], list):
+        typer.echo("Config file 'flows' must be an array.")
+        return None
+    return config
+
+
+def edit_config() -> None:
+    """Edit sources and flows in zendt.json."""
+    config = open_config()
+    if config is None:
+        return
+
+    while True:
+        typer.echo('What would you like to edit?')
+        typer.echo('1. Sources')
+        typer.echo('2. Flows')
+        typer.echo('3. Save and exit')
+        choice = typer.prompt('Enter your choice').strip()
+        if choice == '1':
+            edit_sources(config)
+        elif choice == '2':
+            edit_flows(config)
+        elif choice == '3':
+            if save_config(config):
+                return
+        else:
+            typer.echo('Invalid choice.')
+
+
+def edit_sources(config: dict) -> None:
+    """Create, delete, or edit a source."""
+    list_items(config['sources'], 'sources')
+    typer.echo('1. Create')
+    typer.echo('2. Delete')
+    typer.echo('3. Edit')
+    typer.echo('4. Back')
+    choice = typer.prompt('Enter your choice').strip()
+    if choice == '1':
+        add_source(config)
+    elif choice == '2':
+        delete_by_id(config['sources'], 'source', keep_one=True)
+    elif choice == '3':
+        edit_source(config)
+    elif choice == '4':
+        return
+    else:
+        typer.echo('Invalid choice.')
+
+
+def edit_flows(config: dict) -> None:
+    """Create, delete, or edit a flow."""
+    list_items(config['flows'], 'flows')
+    typer.echo('1. Create')
+    typer.echo('2. Delete')
+    typer.echo('3. Edit')
+    typer.echo('4. Back')
+    choice = typer.prompt('Enter your choice').strip()
+    if choice == '1':
+        add_flow(config)
+    elif choice == '2':
+        delete_by_id(config['flows'], 'flow')
+    elif choice == '3':
+        edit_flow(config)
+    elif choice == '4':
+        return
+    else:
+        typer.echo('Invalid choice.')
+
+
+def list_items(items: list[dict], kind: str) -> None:
+    if not items:
+        typer.echo(f'No {kind} yet.')
+        return
+    typer.echo(f'Current {kind}:')
+    for item in items:
+        item_id = item.get('id', '?')
+        if kind == 'sources':
+            typer.echo(f'  {item_id}: {item.get("source", "")}')
+        else:
+            rules = ', '.join(item.get('rules') or [])
+            typer.echo(f'  {item_id}: {rules}')
+
+
+def find_by_id(items: list[dict], item_id: str) -> dict | None:
+    for item in items:
+        if item.get('id') == item_id:
+            return item
+    return None
+
+
+def add_source(config: dict) -> None:
+    take_source(config['sources'], create_source())
+
+
+def add_flow(config: dict) -> None:
+    take_flow(config['flows'], create_flow())
+
+
+def delete_by_id(
+    items: list[dict], kind: str, *, keep_one: bool = False
+) -> None:
+    item_id = typer.prompt(f'Enter the {kind} ID').strip()
+    item = find_by_id(items, item_id)
+    if item is None:
+        typer.echo(f'{kind.capitalize()} not found.')
+        return
+    if keep_one and len(items) <= 1:
+        typer.echo(
+            'At least one source is required. Add another source '
+            'before deleting this one.'
+        )
+        return
+    if not typer.confirm(f"Delete {kind} '{item_id}'?"):
+        typer.echo(f'{kind.capitalize()} was not deleted.')
+        return
+    items.remove(item)
+
+
+def prompt_keep(
+    label: str, current: str | None, *, allow_clear: bool = False
+) -> str | None:
+    """Ask for a new value. Enter keeps the current one.
+
+    '-' clears optional fields.
+    """
+    shown = current if current else '(none)'
+    hint = "enter to keep, '-' to clear" if allow_clear else 'enter to keep'
+    value = typer.prompt(
+        f'{label} [{hint}: {shown}]',
+        default=current or '',
+        show_default=False,
+    ).strip()
+    if allow_clear and value == '-':
+        return None
+    if not value:
+        return current
+    return value
+
+
+def set_optional(item: dict, key: str, value: str | None) -> None:
+    if value:
+        item[key] = value
+    else:
+        item.pop(key, None)
+
+
+def edit_source(config: dict) -> None:
+    source_id = typer.prompt('Enter the source ID').strip()
+    source = find_by_id(config['sources'], source_id)
+    if source is None:
+        typer.echo('Source not found.')
+        return
+
+    typer.echo(f'Editing source {source_id}...')
+    location = prompt_keep('Source location', source.get('source'))
+    if not location:
+        typer.echo('Source location is required. This source was not changed.')
+        return
+    source['source'] = location
+
+    if not is_remote(location):
+        had_remote_fields = 'authentication' in source or 'version' in source
+        source.pop('authentication', None)
+        source.pop('version', None)
+        if had_remote_fields:
+            typer.echo(
+                'Authentication and version were removed because '
+                'this source is local.'
+            )
+        return
+
+    authentication = prompt_keep(
+        'Source authentication (env var name, not the token)',
+        source.get('authentication'),
+        allow_clear=True,
+    )
+    version = prompt_keep(
+        'Source version', source.get('version'), allow_clear=True
+    )
+    set_optional(source, 'authentication', authentication)
+    set_optional(source, 'version', version)
+
+
+def edit_flow(config: dict) -> None:
+    flow_id = typer.prompt('Enter the flow ID').strip()
+    flow = find_by_id(config['flows'], flow_id)
+    if flow is None:
+        typer.echo('Flow not found.')
+        return
+
+    typer.echo(f'Editing flow {flow_id}...')
+    description = prompt_keep(
+        'Description', flow.get('description'), allow_clear=True
+    )
+    rules_value = prompt_keep(
+        'Rules (comma separated)', ', '.join(flow.get('rules') or [])
+    )
+    rules = [
+        part.strip() for part in (rules_value or '').split(',') if part.strip()
+    ]
+    if not rules:
+        typer.echo(
+            'A flow needs at least one rule. This flow was not changed.'
+        )
+        return
+    set_optional(flow, 'description', description)
+    flow['rules'] = rules
+    flow_input = prompt_keep(
+        'Input path', flow.get('input'), allow_clear=True
+    )
+    flow_output = prompt_keep(
+        'Output path', flow.get('output'), allow_clear=True
+    )
+    set_optional(flow, 'input', flow_input)
+    set_optional(flow, 'output', flow_output)

zendt/config/helper.py

@@ -0,0 +1,26 @@
+import json
+from pathlib import Path
+
+import typer
+
+from zendt.errors import ConfigError
+from zendt.rules.configs import validate_parameters
+
+
+def save_config(config: dict) -> bool:
+    """Write zendt.json. Returns False when the file was left unchanged."""
+    try:
+        validate_parameters(config)
+    except ConfigError as exc:
+        typer.echo(str(exc))
+        typer.echo('Config file was not saved.')
+        return False
+
+    path = Path.cwd() / 'zendt.json'
+    try:
+        path.write_text(json.dumps(config, indent=4), encoding='utf-8')
+    except Exception as exc:
+        typer.echo(f'Error writing config file: {exc}')
+        return False
+    typer.echo('Saved zendt.json.')
+    return True