templify-cli 0.1.0__py3-none-any.whl

templify/__init__.py

@@ -0,0 +1 @@
+"""templify: fill document templates (docx, txt, md, html, json) with data (xlsx, json)."""

templify/cli/__init__.py

@@ -0,0 +1 @@
+"""The templify command line interface."""

templify/cli/dependencies/__init__.py

@@ -0,0 +1 @@
+"""Typer dependencies shared by the commands, injected with typer-di."""

templify/cli/dependencies/console.py

@@ -0,0 +1,9 @@
+"""The rich console used for command output."""
+
+from typing import Annotated
+
+from rich.console import Console
+from typer_di import Depends
+
+ConsoleDI = Annotated[Console, Depends(lambda: Console(color_system="truecolor"))]
+"""Injects a truecolor rich console."""

templify/cli/dependencies/data.py

@@ -0,0 +1,196 @@
+"""The data pipeline options: `--data`, `--order`, `--filter` and `--group-by`."""
+
+import json
+from pathlib import Path
+from typing import Annotated
+from zipfile import BadZipFile
+
+import typer
+from pyspecification import (
+    ArgumentError,
+    ExpressionWrapperDict,
+    Predicate,
+    PredicateCompiler,
+    PredicateDict,
+    RuleDoesNotExistError,
+    RuleKeyDoesNotExistError,
+)
+from typer_di import Depends
+
+from templify.filter_rules import rules
+from templify.models import Data
+from templify.readers import readers
+from templify.transformers import OrderByKey, filter_data, group_by_data, order_by_data
+
+# -----------------------
+# utils
+# -----------------------
+
+
+def _extract_extension(file: Path) -> str:
+    return file.suffix.lstrip(".")
+
+
+# -----------------------
+# read data
+# -----------------------
+
+
+def _check_if_extension_is_supported(file: Path) -> Path:
+    extension = _extract_extension(file)
+
+    if extension not in readers:
+        message = f"Extension {extension} is not supported"
+        raise typer.BadParameter(message)
+
+    return file
+
+
+def _read(
+    file: Annotated[
+        Path,
+        typer.Option(
+            "-d",
+            "--data",
+            help="Path to the data file",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            resolve_path=True,
+            callback=_check_if_extension_is_supported,
+        ),
+    ],
+) -> Data:
+    try:
+        return readers[_extract_extension(file)](file)
+    except (ValueError, BadZipFile) as e:
+        msg = f"Could not read data file '{file.name}': {e}"
+        raise typer.BadParameter(msg) from e
+
+
+# -----------------------
+# order data
+# -----------------------
+
+
+def _get_order_by_keys(
+    keys: Annotated[
+        list[str],
+        typer.Option(
+            "--order",
+            help="Columns to order by",
+            default_factory=list,
+            rich_help_panel="Data Options",
+        ),
+    ],
+) -> list[OrderByKey]:
+    return [OrderByKey(key) for key in keys]
+
+
+def _order(
+    data: Annotated[Data, Depends(_read)],
+    keys: Annotated[list[OrderByKey], Depends(_get_order_by_keys)],
+) -> Data:
+    try:
+        return order_by_data(data, keys) if keys else data
+    except KeyError as e:
+        raise typer.BadParameter(str(e)) from e
+
+
+# -----------------------
+# filter data
+# -----------------------
+
+
+def _get_compiler() -> PredicateCompiler:
+    return PredicateCompiler(
+        rules.rules,
+        lambda schema: Predicate(
+            lambda _: schema["operator"] == "all",
+            operator="logical",
+        ),
+    )
+
+
+def _get_filter_schema_dict(
+    json_string: Annotated[
+        str | None,
+        typer.Option(
+            "--filter",
+            help="JSON string containing the filter schema",
+            rich_help_panel="Data Options",
+        ),
+    ] = None,
+) -> ExpressionWrapperDict | PredicateDict | None:
+    if json_string is None:
+        return None
+
+    try:
+        return json.loads(json_string)
+    except json.JSONDecodeError as e:
+        raise typer.BadParameter(str(e)) from e
+
+
+def _filter(
+    data: Annotated[Data, Depends(_order)],
+    compiler: Annotated[PredicateCompiler, Depends(_get_compiler)],
+    schema: Annotated[
+        ExpressionWrapperDict | PredicateDict | None, Depends(_get_filter_schema_dict)
+    ],
+) -> Data:
+    if schema is None:
+        return data
+
+    try:
+        return filter_data(data, compiler, schema)
+    except (RuleKeyDoesNotExistError, RuleDoesNotExistError, ArgumentError) as e:
+        raise typer.BadParameter(str(e)) from e
+    except (TypeError, ValueError, AttributeError) as e:
+        msg = f"Filter failed on a data value (empty cell or wrong type?): {e}"
+        raise typer.BadParameter(msg) from e
+
+
+# -----------------------
+# group data
+# -----------------------
+
+
+def _group(
+    data: Annotated[Data, Depends(_filter)],
+    group_keys: Annotated[
+        list[str],
+        typer.Option(
+            "--group-by",
+            help="Columns to group by, each group holds its rows under --group-items",
+            default_factory=list,
+            rich_help_panel="Data Options",
+        ),
+    ],
+    group_items_key: Annotated[
+        str,
+        typer.Option(
+            "--group-items",
+            help="Name of the variable that holds each group rows",
+            rich_help_panel="Data Options",
+        ),
+    ] = "items",
+) -> Data:
+    if not group_keys:
+        return data
+
+    try:
+        return group_by_data(data, group_keys, group_items_key)
+    except (KeyError, ValueError) as e:
+        raise typer.BadParameter(str(e)) from e
+    except TypeError as e:
+        msg = f"Can not group by unhashable values (like lists or objects): {e}"
+        raise typer.BadParameter(msg) from e
+
+
+# -----------------------
+# DI
+# -----------------------
+
+
+DataDI = Annotated[Data, Depends(_group)]
+"""Injects the records read from `--data`, then ordered, filtered and grouped."""

templify/cli/dependencies/template.py

@@ -0,0 +1,96 @@
+"""The template and output options: `--template` and `--output`."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from jinja2 import TemplateError
+from typer_di import Depends
+
+from templify.writers import Writer, writers
+
+# -----------------------
+# template
+# -----------------------
+
+
+@dataclass(frozen=True)
+class Template:
+    """A template file and the writer chosen from its extension."""
+
+    path: Path
+    writer: Writer
+
+    @property
+    def extension(self) -> str:
+        """The template extension, lowercase and without the dot: `docx`."""
+        return self.path.suffix.lstrip(".").lower()
+
+
+def _check_if_extension_is_supported(file: Path) -> Path:
+    extension = file.suffix.lstrip(".")
+
+    if extension not in writers:
+        supported = ", ".join(writers.extensions)
+        message = f"Template extension '{extension}' is not supported, supported: {supported}"
+        raise typer.BadParameter(message)
+
+    return file
+
+
+def _get_template(
+    template_path: Annotated[
+        Path,
+        typer.Option(
+            "-t",
+            "--template",
+            help=f"Path to the template file ({', '.join(writers.extensions)})",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            resolve_path=True,
+            callback=_check_if_extension_is_supported,
+        ),
+    ],
+) -> Template:
+    try:
+        return Template(path=template_path, writer=writers.create(template_path))
+    except TemplateError as e:
+        msg = f"Template Error: {e}"
+        raise typer.BadParameter(msg) from e
+    except Exception as e:
+        msg = f"Could not load template '{template_path.name}': {e}"
+        raise typer.BadParameter(msg) from e
+
+
+# -----------------------
+# output
+# -----------------------
+
+
+def _get_output_dir(
+    output_path: Annotated[
+        Path,
+        typer.Option(
+            "-o",
+            "--output",
+            help="Path to the output directory",
+            file_okay=False,
+            dir_okay=True,
+            resolve_path=True,
+        ),
+    ],
+) -> Path:
+    return output_path
+
+
+# -----------------------
+# DI
+# -----------------------
+
+TemplateDI = Annotated[Template, Depends(_get_template)]
+"""Injects the `--template` file with the writer matching its extension."""
+
+OutputDirDI = Annotated[Path, Depends(_get_output_dir)]
+"""Injects the `--output` directory."""

templify/cli/help.py

@@ -0,0 +1,61 @@
+"""Long help texts of the commands."""
+
+SINGLE_TEMPLATE_HELP_TEXT = (
+    "Generate single template file (docx, txt, md, html, json, ...)\n"
+    "\n"
+    "Usage:\n"
+    "\n"
+    f"| {'name':<10} | {'age':<4}\n"
+    "-------------------\n"
+    f"| {'Abdullah':<10} | {'32':<4}\n"
+    f"| {'Rawaa':<10} | {'33':<4}\n"
+    f"| {'Rama':<10} | {'25':<4}\n"
+    "\n"
+    "Template:\n"
+    "\n"
+    "{% for person in data %}\n"
+    "Hello my name is {{ person['name'] }}, my age is {{ person['age'] }}\n"
+    "{{ page_break }}\n"
+    "{% endfor %}\n"
+    "\n"
+    "Command:\n"
+    "\n"
+    "templify s \\ \n"
+    "-t <your_path_to_template_file> \\ \n"
+    "-d <your_path_to_data_file> \\ \n"
+    "-o <your_path_to_output_directory> \n"
+    "\n"
+    "it will generate a single file with three pages like this:\n"
+    "\n"
+    "Page 1: Hello my name is Abdullah, my age is 32\n"
+    "Page 2: Hello my name is Rawaa, my age is 33\n"
+    "Page 3: Hello my name is Rama, my age is 25\n"
+)
+
+MULTIPLE_TEMPLATES_HELP_TEXT = (
+    "Generate multiple template files (docx, txt, md, html, json, ...)\n"
+    "\n"
+    "Usage:\n"
+    "\n"
+    f"| {'name':<10} | {'age':<4}\n"
+    "-------------------\n"
+    f"| {'Abdullah':<10} | {'32':<4}\n"
+    f"| {'Rawaa':<10} | {'33':<4}\n"
+    f"| {'Rama':<10} | {'25':<4}\n"
+    "\n"
+    "Template: Hello my name is {{ name }}, my age is {{ age }}\n"
+    "\n"
+    "Command:\n"
+    "\n"
+    "templify m \\ \n"
+    "-t <your_path_to_template_file> \\ \n"
+    "-d <your_path_to_data_file> \\ \n"
+    "-o <your_path_to_output_directory> \\ \n"
+    "-k name --index\n"
+    "\n"
+    "it will generate a multiple files like this:\n"
+    "\n"
+    "1 - Abdullah.docx  `Hello my name is Abdullah, my age is 32`\n"
+    "2 - Rawaa.docx     `Hello my name is Rawaa, my age is 33`\n"
+    "3 - Rama.docx      `Hello my name is Rama, my age is 25`\n"
+)

templify/cli/main.py

@@ -0,0 +1,165 @@
+# ruff: noqa: PLR0913
+"""The templify command line application."""
+
+from typing import Annotated, Any
+
+import typer
+from jinja2 import TemplateError
+from pyspecification import get_expression_json_schema
+from rich.markup import escape
+from rich.progress import track
+from rich.table import Table
+from typer_di import TyperDI
+from typer_swissknife import command
+
+from templify.cli.dependencies.console import ConsoleDI
+from templify.cli.dependencies.data import DataDI
+from templify.cli.dependencies.template import OutputDirDI, TemplateDI
+from templify.filter_rules import rules
+from templify.writers import InvalidOutputError, write_multiple, write_single
+
+from .help import MULTIPLE_TEMPLATES_HELP_TEXT, SINGLE_TEMPLATE_HELP_TEXT
+
+app = TyperDI(
+    name="templify",
+    help="A CLI application for templating documents",
+    no_args_is_help=True,
+)
+
+
+@command(
+    app,
+    name="filters-json-schema",
+    aliases=("filters-schema", "fjs"),
+    help="List the filter rules, their arguments and description",
+)
+def print_filter_schema(console: ConsoleDI) -> None:
+    """List the filter rules, their arguments and description."""
+    table = Table("Rule", "Arguments", "Description", box=None, header_style="bold")
+    expressions = get_expression_json_schema(rules.rules)["$defs"]["expression"]["oneOf"]
+
+    for expression in expressions:
+        if "name" not in expression.get("properties", {}):
+            continue  # the all / any wrapper, not a rule
+
+        properties = expression["properties"]
+        arguments = properties["kwargs"]["properties"].items()
+        table.add_row(
+            properties["name"]["const"],
+            escape(", ".join(f"{name}: {_type_name(schema)}" for name, schema in arguments)),
+            expression.get("description", ""),
+        )
+
+    console.print(table)
+
+
+def _type_name(schema: dict[str, Any]) -> str:
+    """Return a short type name for a json schema: `string`, `date`, `list[string]`, ..."""
+    if schema.get("type") == "array":
+        return f"list[{_type_name(schema.get('items', {}))}]"
+
+    return schema.get("format") or schema.get("type") or "any"
+
+
+@command(
+    app,
+    name="single-template",
+    aliases=("single", "s"),
+    no_args_is_help=True,
+    help=SINGLE_TEMPLATE_HELP_TEXT,
+)
+def generate_single_file(
+    console: ConsoleDI,
+    data: DataDI,
+    template: TemplateDI,
+    output_dir: OutputDirDI,
+    filename: Annotated[
+        str | None,
+        typer.Option(
+            "-f",
+            "--filename",
+            help="Output filename without extension [default: template filename]",
+        ),
+    ] = None,
+    data_variable: Annotated[
+        str,
+        typer.Option(
+            "-v",
+            "--data-variable",
+            help="Name of the variable that holds the data inside the template",
+        ),
+    ] = "data",
+) -> None:
+    """Generate a single file from all the records."""
+    try:
+        filepath = write_single(
+            template.writer,
+            data,
+            output_dir=output_dir,
+            filename=filename or template.path.stem,
+            extension=template.extension,
+            data_variable=data_variable,
+        )
+    except (TemplateError, InvalidOutputError) as e:
+        msg = f"Template Error: {e}"
+        raise typer.BadParameter(msg) from e
+    else:
+        console.print(f"[green]File generated successfully:[/] {filepath}")
+
+
+@command(
+    app,
+    name="multiple-templates",
+    aliases=("multiple", "m"),
+    no_args_is_help=True,
+    help=MULTIPLE_TEMPLATES_HELP_TEXT,
+)
+def generate_multiple_files(
+    console: ConsoleDI,
+    data: DataDI,
+    template: TemplateDI,
+    output_dir: OutputDirDI,
+    filename_key: Annotated[
+        str | None,
+        typer.Option(
+            "-k",
+            "--filename-key",
+            help="Column used to name each generated file [default: template-<index>]",
+        ),
+    ] = None,
+    include_index: Annotated[  # noqa: FBT002
+        bool,
+        typer.Option(
+            "-i",
+            "--index",
+            help="Prefix each filename with its row index",
+        ),
+    ] = False,
+) -> None:
+    """Generate one file per record (or per group)."""
+    files = write_multiple(
+        template.writer,
+        data,
+        output_dir=output_dir,
+        extension=template.extension,
+        filename_key=filename_key,
+        include_index=include_index,
+    )
+
+    try:
+        for _ in track(files, description="Generating", total=len(data), console=console):
+            pass
+    except (TemplateError, InvalidOutputError) as e:
+        msg = f"Template Error: {e}"
+        raise typer.BadParameter(msg) from e
+    else:
+        console.print(f"[green]{len(data)} files generated successfully in:[/] {output_dir}")
+
+
+def main() -> None:
+    """Run the templify command line application."""
+    app()
+
+
+if __name__ == "__main__":
+    main()