decx 0.1.0__tar.gz

decx-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.3
+Name: decx
+Version: 0.1.0
+Summary: Automated PowerPoint report generation from Excel data via COM
+Keywords: powerpoint,excel,automation,com,windows,reporting
+Author: Albert Li
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Requires-Dist: pywin32>=311 ; sys_platform == 'win32'
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/albertxli/decx
+Description-Content-Type: text/markdown
+
+# decx
+
+Automated PowerPoint report generation from Excel data via COM.
+
+`decx` reads data from Excel workbooks and updates linked OLE objects, tables, delta indicators, color coding, and charts in PowerPoint presentations — all driven from the command line.
+
+## Requirements
+
+- **Windows** (COM automation requires Windows)
+- **Microsoft PowerPoint** (installed and licensed)
+- **Microsoft Excel** (installed and licensed)
+- **Python 3.11+**
+
+## Installation
+
+```bash
+uv add decx
+```
+
+Or with pip:
+
+```bash
+pip install decx
+```
+
+## Usage
+
+### Update presentations
+
+```bash
+# Single presentation with one Excel file
+decx update report.pptx --excel data.xlsx
+
+# Batch mode with explicit pptx:xlsx pairs
+decx update --pair "us.pptx:us_data.xlsx" --pair "mx.pptx:mx_data.xlsx"
+
+# Skip specific steps
+decx update report.pptx --excel data.xlsx --skip-links --skip-charts
+
+# Use a custom config file
+decx update report.pptx --excel data.xlsx --config my_config.yaml
+
+# Verbose output for debugging
+decx update report.pptx --excel data.xlsx --verbose
+```
+
+### Initialize config
+
+Write the default `config.yaml` to the current directory:
+
+```bash
+decx init
+```
+
+### Info
+
+```bash
+decx info
+```
+
+### Version
+
+```bash
+decx --version
+```
+
+## Configuration
+
+`decx` ships with sensible defaults. Run `decx init` to generate a `config.yaml` you can customize:
+
+```yaml
+heatmap:
+  color_minimum: '#F8696B'
+  color_midpoint: '#FFEB84'
+  color_maximum: '#63BE7B'
+  dark_font: '#000000'
+  light_font: '#FFFFFF'
+
+ccst:
+  positive_color: '#33CC33'
+  negative_color: '#ED0590'
+  neutral_color: '#595959'
+  positive_prefix: '+'
+  symbol_removal: '%'
+
+delta:
+  template_positive: tmpl_delta_pos
+  template_negative: tmpl_delta_neg
+  template_none: tmpl_delta_none
+  template_slide: 1
+
+links:
+  set_manual: true
+```
+
+## Pipeline
+
+1. **Re-link OLE objects** — point linked Excel objects to a new data file
+2. **Populate tables** — read Excel ranges and write values into PowerPoint tables
+3. **Delta indicators** — swap arrow shapes based on positive/negative values
+4. **Color coding** — apply color rules to `_ccst` tables
+5. **Update charts** — refresh linked chart data sources
+
+## License
+
+MIT
+
+## Repository
+
+https://github.com/albertxli/decx

decx-0.1.0/README.md

@@ -0,0 +1,110 @@
+# decx
+
+Automated PowerPoint report generation from Excel data via COM.
+
+`decx` reads data from Excel workbooks and updates linked OLE objects, tables, delta indicators, color coding, and charts in PowerPoint presentations — all driven from the command line.
+
+## Requirements
+
+- **Windows** (COM automation requires Windows)
+- **Microsoft PowerPoint** (installed and licensed)
+- **Microsoft Excel** (installed and licensed)
+- **Python 3.11+**
+
+## Installation
+
+```bash
+uv add decx
+```
+
+Or with pip:
+
+```bash
+pip install decx
+```
+
+## Usage
+
+### Update presentations
+
+```bash
+# Single presentation with one Excel file
+decx update report.pptx --excel data.xlsx
+
+# Batch mode with explicit pptx:xlsx pairs
+decx update --pair "us.pptx:us_data.xlsx" --pair "mx.pptx:mx_data.xlsx"
+
+# Skip specific steps
+decx update report.pptx --excel data.xlsx --skip-links --skip-charts
+
+# Use a custom config file
+decx update report.pptx --excel data.xlsx --config my_config.yaml
+
+# Verbose output for debugging
+decx update report.pptx --excel data.xlsx --verbose
+```
+
+### Initialize config
+
+Write the default `config.yaml` to the current directory:
+
+```bash
+decx init
+```
+
+### Info
+
+```bash
+decx info
+```
+
+### Version
+
+```bash
+decx --version
+```
+
+## Configuration
+
+`decx` ships with sensible defaults. Run `decx init` to generate a `config.yaml` you can customize:
+
+```yaml
+heatmap:
+  color_minimum: '#F8696B'
+  color_midpoint: '#FFEB84'
+  color_maximum: '#63BE7B'
+  dark_font: '#000000'
+  light_font: '#FFFFFF'
+
+ccst:
+  positive_color: '#33CC33'
+  negative_color: '#ED0590'
+  neutral_color: '#595959'
+  positive_prefix: '+'
+  symbol_removal: '%'
+
+delta:
+  template_positive: tmpl_delta_pos
+  template_negative: tmpl_delta_neg
+  template_none: tmpl_delta_none
+  template_slide: 1
+
+links:
+  set_manual: true
+```
+
+## Pipeline
+
+1. **Re-link OLE objects** — point linked Excel objects to a new data file
+2. **Populate tables** — read Excel ranges and write values into PowerPoint tables
+3. **Delta indicators** — swap arrow shapes based on positive/negative values
+4. **Color coding** — apply color rules to `_ccst` tables
+5. **Update charts** — refresh linked chart data sources
+
+## License
+
+MIT
+
+## Repository
+
+https://github.com/albertxli/decx

decx-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "decx"
+version = "0.1.0"
+description = "Automated PowerPoint report generation from Excel data via COM"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [{name = "Albert Li"}]
+keywords = ["powerpoint", "excel", "automation", "com", "windows", "reporting"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Win32 (MS Windows)",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business",
+]
+dependencies = [
+    "pywin32>=311; sys_platform == 'win32'",
+    "pyyaml>=6.0.3",
+]
+
+[project.scripts]
+decx = "decx.cli:main"
+
+[project.urls]
+Repository = "https://github.com/albertxli/decx"
+
+[dependency-groups]
+dev = ["pytest>=9.0"]
+
+[tool.pytest.ini_options]
+markers = ["integration: tests that require COM (Windows + PowerPoint + Excel)"]
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"

decx-0.1.0/src/decx/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+from decx.config import load_config, DEFAULT_CONFIG

decx-0.1.0/src/decx/chart_updater.py

@@ -0,0 +1,44 @@
+"""Step 2: Update linked chart data sources."""
+
+import logging
+
+from decx.shape_finder import collect_linked_charts
+
+log = logging.getLogger(__name__)
+
+# ppUpdateOptionManual = 1 (verified via PowerPoint type library)
+PP_UPDATE_OPTION_MANUAL = 1
+
+
+def update_charts(session, excel_path: str, inventory=None) -> int:
+    """Re-link all embedded charts to the specified Excel file.
+
+    Sets chart links to manual update mode after updating.
+
+    When inventory is provided, uses pre-collected charts list
+    instead of scanning all slides.
+
+    Returns the count of updated charts.
+    """
+    if inventory is not None:
+        charts = inventory.charts
+    else:
+        charts = collect_linked_charts(session.presentation)
+
+    if not charts:
+        log.info("No linked charts found")
+        return 0
+
+    updated = 0
+    for chart_shape in charts:
+        try:
+            chart_shape.LinkFormat.SourceFullName = excel_path
+            chart_shape.LinkFormat.Update()
+            chart_shape.LinkFormat.AutoUpdate = PP_UPDATE_OPTION_MANUAL
+            updated += 1
+            log.debug("Updated chart: %s", chart_shape.Name)
+        except Exception as e:
+            log.warning("Failed to update chart '%s': %s", chart_shape.Name, e)
+
+    log.info("Updated %d chart(s)", updated)
+    return updated

decx-0.1.0/src/decx/cli.py

@@ -0,0 +1,287 @@
+"""CLI entry point for decx — PowerPoint Excel report automation."""
+
+import argparse
+import glob
+import logging
+import os
+import sys
+import time
+
+import yaml
+
+from decx import __version__
+from decx.config import load_config, DEFAULT_CONFIG
+from decx.session import Session
+from decx import linker, table_updater, delta_updater, color_coder, chart_updater
+from decx.shape_finder import build_presentation_inventory
+
+
+def resolve_paths(patterns: list[str]) -> list[str]:
+    """Resolve glob patterns to absolute file paths."""
+    paths = []
+    for pattern in patterns:
+        expanded = glob.glob(pattern)
+        if expanded:
+            paths.extend(os.path.abspath(p) for p in expanded)
+        else:
+            # Treat as literal path
+            paths.append(os.path.abspath(pattern))
+    return paths
+
+
+def parse_pair(pair_str: str) -> tuple[str, str]:
+    """Parse a 'pptx:xlsx' pair string into (pptx_path, excel_path)."""
+    if ":" not in pair_str:
+        print(f"Invalid pair format: '{pair_str}'. Expected 'file.pptx:data.xlsx'")
+        sys.exit(1)
+    # Split on last ':' to handle Windows drive letters like C:\path
+    # Find the colon that separates pptx from xlsx (not a drive letter colon)
+    # Strategy: split on ':', rejoin if we accidentally split a drive letter
+    parts = pair_str.split(":")
+    if len(parts) == 3:
+        # e.g. C:\file.pptx:C:\data.xlsx -> impossible, both have drive letters
+        # More likely: file.pptx:C:\data.xlsx or C:\file.pptx:data.xlsx
+        # Try: first part is just a drive letter -> rejoin
+        if len(parts[0]) == 1 and parts[0].isalpha():
+            # "C:\file.pptx:data.xlsx" -> pptx="C:\file.pptx", excel="data.xlsx"
+            pptx = f"{parts[0]}:{parts[1]}"
+            excel = parts[2]
+        else:
+            # "file.pptx:C:\data.xlsx" -> pptx="file.pptx", excel="C:\data.xlsx"
+            pptx = parts[0]
+            excel = f"{parts[1]}:{parts[2]}"
+    elif len(parts) == 4:
+        # "C:\file.pptx:C:\data.xlsx"
+        pptx = f"{parts[0]}:{parts[1]}"
+        excel = f"{parts[2]}:{parts[3]}"
+    elif len(parts) == 2:
+        pptx, excel = parts
+    else:
+        print(f"Invalid pair format: '{pair_str}'")
+        sys.exit(1)
+    return os.path.abspath(pptx), os.path.abspath(excel)
+
+
+def process_presentation(
+    pptx_path: str,
+    excel_path: str,
+    config: dict,
+    options: argparse.Namespace,
+) -> dict:
+    """Process a single presentation through the full pipeline.
+
+    Returns a dict with counts: links, tables, deltas, colors, charts.
+    """
+    results = {"links": 0, "tables": 0, "deltas": 0, "colors": 0, "charts": 0}
+
+    with Session(pptx_path, excel_path) as session:
+        # Build shape inventory ONCE — all steps use O(1) lookups from this
+        inventory = build_presentation_inventory(session.presentation)
+
+        if not options.skip_links:
+            results["links"] = linker.update_links(
+                session, excel_path, config, inventory=inventory
+            )
+
+        results["tables"] = table_updater.update_tables(
+            session, config, inventory=inventory
+        )
+
+        if not options.skip_deltas:
+            results["deltas"] = delta_updater.update_deltas(
+                session, config, inventory=inventory
+            )
+
+        if not options.skip_coloring:
+            results["colors"] = color_coder.apply_color_coding(
+                session, config, inventory=inventory
+            )
+
+        if not options.skip_charts:
+            results["charts"] = chart_updater.update_charts(
+                session, excel_path, inventory=inventory
+            )
+
+        session.save()
+
+    return results
+
+
+def _run_pairs(pairs: list[tuple[str, str]], config: dict, args: argparse.Namespace):
+    """Run the pipeline for a list of (pptx_path, excel_path) pairs."""
+    grand_total = {"links": 0, "tables": 0, "deltas": 0, "colors": 0, "charts": 0}
+    t_start = time.perf_counter()
+    processed = 0
+
+    for pptx_path, excel_path in pairs:
+        if not os.path.exists(pptx_path):
+            print(f"PPT not found, skipping: {pptx_path}")
+            continue
+        if not os.path.exists(excel_path):
+            print(f"Excel not found, skipping: {excel_path}")
+            continue
+
+        print(f"Processing: {os.path.basename(pptx_path)} <- {os.path.basename(excel_path)}")
+        t_file = time.perf_counter()
+
+        results = process_presentation(pptx_path, excel_path, config, args)
+
+        elapsed = time.perf_counter() - t_file
+        print(
+            f"  Done in {elapsed:.2f}s — "
+            f"{results['links']} links, "
+            f"{results['tables']} tables, "
+            f"{results['deltas']} deltas, "
+            f"{results['colors']} colored, "
+            f"{results['charts']} charts"
+        )
+
+        for key in grand_total:
+            grand_total[key] += results[key]
+        processed += 1
+
+    total_elapsed = time.perf_counter() - t_start
+    print(
+        f"\nAll done! {processed} file(s) in {total_elapsed:.2f}s\n"
+        f"  {grand_total['links']} link(s) updated\n"
+        f"  {grand_total['tables']} table(s) refreshed\n"
+        f"  {grand_total['deltas']} delta(s) updated\n"
+        f"  {grand_total['colors']} table(s) color-coded\n"
+        f"  {grand_total['charts']} chart(s) updated"
+    )
+
+
+def cmd_update(args: argparse.Namespace):
+    """Handle the 'update' subcommand — main pipeline."""
+    # Logging
+    level = logging.DEBUG if args.verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    # Config
+    config = load_config(args.config)
+
+    # --- Mode 1: --pair for explicit pptx:xlsx pairs ---
+    if args.pair:
+        pairs = [parse_pair(p) for p in args.pair]
+        _run_pairs(pairs, config, args)
+        return
+
+    # --- Mode 2: presentations + --excel (or file picker) ---
+    if not args.presentations:
+        print("Error: Provide presentation file(s) or use --pair for batch pairs.")
+        sys.exit(1)
+
+    excel_path = args.excel
+    if not excel_path:
+        from decx.file_picker import pick_excel_file
+        excel_path = pick_excel_file()
+        if not excel_path:
+            print("No Excel file selected. Exiting.")
+            sys.exit(1)
+    excel_path = os.path.abspath(excel_path)
+
+    if not os.path.exists(excel_path):
+        print(f"Excel file not found: {excel_path}")
+        sys.exit(1)
+
+    pptx_files = resolve_paths(args.presentations)
+    if not pptx_files:
+        print("No presentation files found.")
+        sys.exit(1)
+
+    pairs = [(p, excel_path) for p in pptx_files]
+    _run_pairs(pairs, config, args)
+
+
+def cmd_info(args: argparse.Namespace):
+    """Handle the 'info' subcommand — placeholder."""
+    print("Coming soon")
+
+
+def cmd_init(args: argparse.Namespace):
+    """Handle the 'init' subcommand — write default config.yaml to current directory."""
+    output_path = os.path.join(os.getcwd(), "config.yaml")
+    if os.path.exists(output_path):
+        print(f"config.yaml already exists at {output_path}")
+        sys.exit(1)
+    with open(output_path, "w", encoding="utf-8") as f:
+        yaml.dump(DEFAULT_CONFIG, f, default_flow_style=False, sort_keys=False)
+    print(f"Wrote default config to {output_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="decx",
+        description="Automated PowerPoint report generation from Excel data via COM",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # --- update subcommand ---
+    update_parser = subparsers.add_parser(
+        "update",
+        help="Run the main update pipeline on presentations",
+        epilog=(
+            "Examples:\n"
+            "  decx update report.pptx --excel data.xlsx\n"
+            "  decx update report.pptx                        (file picker opens)\n"
+            '  decx update --pair "us.pptx:us.xlsx" --pair "mx.pptx:mx.xlsx"\n'
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    update_parser.add_argument(
+        "presentations",
+        nargs="*",
+        help="One or more .pptx file paths (supports glob patterns). Used with --excel.",
+    )
+    update_parser.add_argument(
+        "--excel", "-e",
+        default=None,
+        help="Path to the Excel data file. If omitted, a file dialog will open.",
+    )
+    update_parser.add_argument(
+        "--pair", "-p",
+        action="append",
+        default=None,
+        metavar="PPT:XLSX",
+        help="A pptx:xlsx pair. Can be repeated for batch processing multiple pairs.",
+    )
+    update_parser.add_argument(
+        "--config", "-c",
+        default=None,
+        help="Path to config.yaml (default: built-in defaults)",
+    )
+    update_parser.add_argument("--skip-links", action="store_true", help="Skip Step 1a (re-link OLE)")
+    update_parser.add_argument("--skip-deltas", action="store_true", help="Skip Step 1c (delta arrows)")
+    update_parser.add_argument("--skip-coloring", action="store_true", help="Skip Step 1d (_ccst coloring)")
+    update_parser.add_argument("--skip-charts", action="store_true", help="Skip Step 2 (chart links)")
+    update_parser.add_argument("--verbose", "-v", action="store_true", help="Enable debug logging")
+
+    # --- info subcommand ---
+    subparsers.add_parser("info", help="Show project information (coming soon)")
+
+    # --- init subcommand ---
+    subparsers.add_parser("init", help="Write default config.yaml to current directory")
+
+    args = parser.parse_args()
+
+    if args.command == "update":
+        cmd_update(args)
+    elif args.command == "info":
+        cmd_info(args)
+    elif args.command == "init":
+        cmd_init(args)
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()