pou2md 0.1.0__py3-none-any.whl

pou2md/__init__.py

@@ -0,0 +1,8 @@
+"""
+POU to Markdown Converter
+
+Converts TwinCAT 3 .TcPOU files into Mermaid class diagrams and flowcharts
+embedded in Markdown files.
+"""
+
+__version__ = "0.1.0"

pou2md/__main__.py

@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python 3.10 fallback
+    import tomli as tomllib
+
+from .converter import TcPOUConverter
+from .manifest import clean_stale_outputs, manifest_path, save_manifest
+from .errors import TcPOUError
+
+
+class _JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        return json.dumps({
+            "level": record.levelname,
+            "message": record.getMessage(),
+            "logger": record.name,
+        })
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m pou2md",
+        description="Convert TwinCAT 3 .TcPOU files into Mermaid diagrams in Markdown.",
+    )
+    parser.add_argument(
+        "input",
+        nargs="?",
+        default=".",
+        help="Path to a .TcPOU file or directory containing .TcPOU files (default: .).",
+    )
+    parser.add_argument("--config", type=Path, help="Load defaults from a TOML configuration file.")
+    parser.add_argument("--version", action="version", version=_package_version())
+    parser.add_argument(
+        "-o",
+        "--output",
+        help="Output directory or output file path (e.g. -o output/ or -o unified.md).",
+    )
+    parser.add_argument(
+        "-r",
+        "--recursive",
+        action="store_true",
+        help="Recursively scan subdirectories for .TcPOU files.",
+    )
+    parser.add_argument(
+        "-u",
+        "--unified",
+        action="store_true",
+        help="Save all converted POUs into a single Markdown file.",
+    )
+    parser.add_argument(
+        "--single-folder",
+        action="store_true",
+        help="Also save individual Markdown files (the default unless --unified is used alone).",
+    )
+    parser.add_argument(
+        "--copy-folder-structure",
+        action="store_true",
+        help="Save individual Markdown files using the input folder structure instead of flattened names.",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="PATTERN",
+        help="Exclude matching filename or relative path pattern; may be repeated.",
+    )
+    parser.add_argument("--poll-interval", type=float, default=1.0, help="Watcher polling interval in seconds.")
+    parser.add_argument("--debounce-delay", type=float, default=0.25, help="Delay after a detected change in seconds.")
+    parser.add_argument("--retry-count", type=int, default=3, help="Conversion attempts after a transient save failure.")
+    parser.add_argument("--retry-delay", type=float, default=0.5, help="Delay between conversion attempts in seconds.")
+    parser.add_argument("-v", "--verbose", action="store_true", help="Enable diagnostic logging.")
+    parser.add_argument("--quiet", action="store_true", help="Suppress normal status messages.")
+    parser.add_argument("--log-format", choices=("text", "json"), default="text", help="Logging output format.")
+    parser.add_argument("--dry-run", action="store_true", help="Show planned outputs without writing files.")
+    parser.add_argument("--clean", action="store_true", help="Remove stale outputs recorded by the manifest.")
+    parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="Print Markdown output to stdout instead of saving to a file.",
+    )
+    parser.add_argument(
+        "--curve",
+        choices=["step", "stepAfter", "linear", "basis", "none"],
+        default="step",
+        help="Mermaid flowchart curve style (default: 'step' for straight orthogonal lines with horizontal node entry).",
+    )
+    parser.add_argument(
+        "--no-bifurcate",
+        dest="bifurcate",
+        action="store_false",
+        default=True,
+        help="Disable bifurcation junction nodes (draw separate wires instead of a branching junction).",
+    )
+    parser.add_argument(
+        "--repeat-inputs",
+        action="store_true",
+        default=False,
+        help="Repeat input variable blocks per connection in CFC (avoids long cross-diagram wires).",
+    )
+    parser.add_argument(
+        "-w",
+        "--watch",
+        action="store_true",
+        help="Watch input file or directory for changes and automatically re-convert.",
+    )
+
+    preliminary = argparse.ArgumentParser(add_help=False)
+    preliminary.add_argument("--config", type=Path)
+    preliminary_args, _ = preliminary.parse_known_args()
+    if preliminary_args.config:
+        try:
+            config = tomllib.loads(preliminary_args.config.read_text(encoding="utf-8"))
+        except (OSError, tomllib.TOMLDecodeError) as error:
+            parser.error(f"could not load config '{preliminary_args.config}': {error}")
+        parser.set_defaults(**_config_defaults(config))
+
+    args = parser.parse_args()
+    input_path = Path(args.input)
+
+    if args.quiet and args.verbose:
+        parser.error("--quiet and --verbose cannot be used together")
+    if args.poll_interval <= 0 or args.debounce_delay < 0 or args.retry_count < 1 or args.retry_delay < 0:
+        parser.error("watch timing values must be positive (debounce/retry delays may be zero)")
+    if input_path.is_dir() and args.copy_folder_structure and not args.recursive:
+        parser.error("--copy-folder-structure requires --recursive for directory input")
+    if input_path.is_dir() and args.stdout and not args.unified:
+        parser.error("--stdout for directory input requires --unified")
+    if args.clean and not args.output:
+        parser.error("--clean requires --output")
+    if args.clean and not input_path.is_dir():
+        parser.error("--clean requires directory input")
+    if args.dry_run and args.watch:
+        parser.error("--dry-run cannot be combined with --watch")
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(_JsonFormatter() if args.log_format == "json" else logging.Formatter("[%(levelname)s] %(message)s"))
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else (logging.ERROR if args.quiet else logging.INFO),
+        handlers=[handler],
+    )
+
+    if not input_path.exists():
+        print(f"Error: Path '{input_path}' does not exist.", file=sys.stderr)
+        return 1
+    validation_error = _validate_paths(input_path, args)
+    if validation_error:
+        parser.error(validation_error)
+
+    curve_setting = None if args.curve == "none" else args.curve
+    converter = TcPOUConverter(
+        curve=curve_setting,
+        bifurcate=args.bifurcate,
+        repeat_inputs=args.repeat_inputs,
+    )
+
+    if args.watch:
+        if input_path.is_dir() and not args.output and not args.stdout:
+            print(
+                "Error: Please specify an output target with -o / --output, or use --stdout.",
+                file=sys.stderr,
+            )
+            return 1
+        from .watcher import start_watcher
+
+        return start_watcher(
+            input_path=input_path,
+            converter=converter,
+            output=args.output,
+            recursive=args.recursive,
+            unified=args.unified,
+            single_folder=(not args.unified) or args.single_folder or args.copy_folder_structure,
+            copy_folder_structure=args.copy_folder_structure,
+            to_stdout=args.stdout or (input_path.is_file() and not args.output),
+            poll_interval=args.poll_interval,
+            debounce_delay=args.debounce_delay,
+            retry_count=args.retry_count,
+            retry_delay=args.retry_delay,
+            exclude=tuple(args.exclude),
+            quiet=args.quiet,
+        )
+
+    try:
+        if input_path.is_file():
+            md_text, out_file = converter.convert_file(
+                input_path,
+                output_dir=args.output if not args.stdout else None,
+            )
+        elif input_path.is_dir():
+            if not args.output and not args.stdout:
+                parser.error("Please specify an output target with -o / --output, or use --stdout.")
+
+            written, unified_text = converter.convert_directory(
+                input_dir=input_path,
+                output_dir=args.output if not args.stdout else None,
+                recursive=args.recursive,
+                unified=args.unified,
+                single_folder=(not args.unified) or args.single_folder or args.copy_folder_structure,
+                copy_folder_structure=args.copy_folder_structure,
+                exclude=tuple(args.exclude),
+                dry_run=args.dry_run,
+            )
+
+            if args.output:
+                manifest = manifest_path(args.output)
+                current_outputs = set(written)
+                stale = clean_stale_outputs(manifest, current_outputs, dry_run=args.dry_run) if args.clean else []
+                if not args.dry_run:
+                    save_manifest(manifest, current_outputs, metadata=_manifest_metadata(args))
+            else:
+                stale = []
+
+            if args.dry_run:
+                for path in written:
+                    print(f"Would generate: {path}")
+                for path in stale:
+                    print(f"Would remove: {path}")
+            elif args.stdout or (args.unified and not args.output):
+                if hasattr(sys.stdout, "reconfigure"):
+                    sys.stdout.reconfigure(encoding="utf-8")
+                if unified_text:
+                    print(unified_text)
+            elif not args.quiet:
+                print(f"Generated {len(written)} output file(s).")
+            return 0
+    except TcPOUError as error:
+        logging.getLogger(__name__).error("%s", error)
+        return 1
+    if args.stdout or not args.output:
+        if hasattr(sys.stdout, "reconfigure"):
+            sys.stdout.reconfigure(encoding="utf-8")
+        print(md_text)
+    elif not args.quiet:
+        print(f"Generated: {out_file}")
+
+    return 0
+
+
+def _package_version() -> str:
+    try:
+        return version("pou2md")
+    except PackageNotFoundError:
+        return "0.1.0"
+
+
+def _config_defaults(config: dict[str, object]) -> dict[str, object]:
+    allowed = {
+        "input", "output", "recursive", "unified", "single_folder",
+        "copy_folder_structure", "exclude", "poll_interval", "debounce_delay",
+        "retry_count", "retry_delay", "verbose", "quiet", "log_format",
+        "dry_run", "clean", "stdout", "curve", "bifurcate", "repeat_inputs", "watch",
+    }
+    return {key: value for key, value in config.items() if key in allowed}
+
+
+def _manifest_metadata(args: argparse.Namespace) -> dict[str, object]:
+    return {
+        "version": _package_version(),
+        "recursive": args.recursive,
+        "unified": args.unified,
+        "single_folder": (not args.unified) or args.single_folder or args.copy_folder_structure,
+        "copy_folder_structure": args.copy_folder_structure,
+        "exclude": args.exclude,
+    }
+
+
+def _validate_paths(input_path: Path, args: argparse.Namespace) -> str | None:
+    if not args.output:
+        return None
+    output = Path(args.output).resolve()
+    source = input_path.resolve()
+    if input_path.is_file() and output == source:
+        return "output path cannot overwrite the input .TcPOU file"
+    if input_path.is_dir() and output == source:
+        return "output directory cannot be the input directory"
+    if input_path.is_dir() and source in output.parents:
+        return "output directory cannot be inside the input directory"
+    return None
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pou2md/converter.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import fnmatch
+import logging
+import os
+import time
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from .model.flow_graph import FlowGraph
+from .parser.cfc_parser import CFCParser
+from .parser.declaration import DeclarationParser
+from .parser.nwl_parser import NWLParser
+from .parser.st_parser import STParser
+from .writer.markdown import MarkdownWriter
+from .errors import TcPOUInputError, TcPOUOutputError, TcPOUParseError
+
+LOGGER = logging.getLogger(__name__)
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    """Write content through a sibling temporary file, then replace the target."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        with open(temporary, "w", encoding="utf-8", newline="") as f:
+            f.write(content)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(temporary, path)
+    finally:
+        try:
+            temporary.unlink(missing_ok=True)
+        except OSError:
+            LOGGER.debug("Could not remove temporary output %s", temporary, exc_info=True)
+
+
+def _read_file_with_retry(path: Path, max_retries: int = 3, delay: float = 0.1) -> str:
+    """Read a file with retries to handle transient file locks during editor saves."""
+    for attempt in range(max_retries):
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                return f.read()
+        except (PermissionError, OSError):
+            if attempt == max_retries - 1:
+                raise
+            time.sleep(delay)
+    return ""
+
+
+class TcPOUConverter:
+    """Orchestrator to convert TwinCAT 3 .TcPOU files into Mermaid Markdown documents."""
+
+    def __init__(
+        self,
+        curve: str | None = "step",
+        bifurcate: bool = True,
+        repeat_inputs: bool = False,
+    ):
+        self.repeat_inputs = repeat_inputs
+        self.declaration_parser = DeclarationParser()
+        self.nwl_parser = NWLParser()
+        self.cfc_parser = CFCParser()
+        self.st_parser = STParser()
+        self.markdown_writer = MarkdownWriter(curve=curve, bifurcate=bifurcate)
+
+    def convert_content(self, xml_content: str, filename: str = "POU.TcPOU") -> str:
+        """Parse XML string content and return generated Markdown text."""
+        try:
+            root = ET.fromstring(xml_content)
+        except ET.ParseError as error:
+            raise TcPOUParseError(filename, error) from error
+
+        # 1. Declaration
+        decl_elem = root.find(".//Declaration")
+        decl_text = decl_elem.text if decl_elem is not None else ""
+        decl = self.declaration_parser.parse(decl_text or "")
+
+        # 2. Implementation
+        impl_elem = root.find(".//Implementation")
+        graph: FlowGraph
+
+        if impl_elem is not None:
+            st_elem = impl_elem.find("./ST")
+            nwl_elem = impl_elem.find("./NWL")
+            cfc_elem = impl_elem.find("./CFC")
+
+            if st_elem is not None:
+                graph = self.st_parser.parse(st_elem)
+            elif nwl_elem is not None:
+                graph = self.nwl_parser.parse(nwl_elem)
+            elif cfc_elem is not None:
+                graph = self.cfc_parser.parse(
+                    cfc_elem, repeat_inputs=self.repeat_inputs
+                )
+            else:
+                graph = FlowGraph(language="UNKNOWN")
+        else:
+            graph = FlowGraph(language="NONE")
+
+        # 3. Generate Markdown
+        return self.markdown_writer.generate(decl, graph, filename)
+
+    def convert_file(
+        self,
+        file_path: Path | str,
+        output_dir: Path | str | None = None,
+        custom_filename: str | None = None,
+        dry_run: bool = False,
+    ) -> tuple[str, Path | None]:
+        """Convert a single .TcPOU file, optionally writing to an output directory."""
+        path = Path(file_path)
+        try:
+            content = _read_file_with_retry(path)
+        except OSError as error:
+            raise TcPOUInputError(f"could not read '{path}': {error}") from error
+
+        md_output = self.convert_content(content, filename=path.name)
+
+        out_path: Path | None = None
+        if output_dir:
+            out_target = Path(output_dir)
+            if out_target.suffix.lower() == ".md" and not out_target.is_dir():
+                out_path = out_target
+                if not dry_run:
+                    out_path.parent.mkdir(parents=True, exist_ok=True)
+            else:
+                if not dry_run:
+                    out_target.mkdir(parents=True, exist_ok=True)
+                fname = custom_filename if custom_filename else f"{path.stem}.md"
+                out_path = out_target / fname
+                if not dry_run:
+                    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+            if not dry_run:
+                try:
+                    _atomic_write(out_path, md_output)
+                except OSError as error:
+                    raise TcPOUOutputError(f"could not write '{out_path}': {error}") from error
+
+        return md_output, out_path
+
+    def convert_directory(
+        self,
+        input_dir: Path | str,
+        output_dir: Path | str | None = None,
+        recursive: bool = False,
+        unified: bool = False,
+        single_folder: bool | None = None,
+        copy_folder_structure: bool = False,
+        exclude: tuple[str, ...] = (),
+        unified_filename: str = "unified.md",
+        dry_run: bool = False,
+    ) -> tuple[list[Path], str | None]:
+        """
+        Convert all .TcPOU files in a directory.
+
+        Parameters:
+            input_dir: Root directory to scan for .TcPOU files.
+            output_dir: Destination directory or file path for outputs.
+            recursive: If True, search subdirectories.
+            unified: If True, combine all converted POUs into a single Markdown document.
+            single_folder: If True, write individual Markdown files.
+            copy_folder_structure: If True, preserve source subdirectories for individual files.
+            exclude: Filename or relative-path patterns to skip.
+            unified_filename: Default filename if output_dir is a directory when unified=True.
+
+        Returns:
+            A tuple of (written_file_paths, unified_markdown_text).
+        """
+        if single_folder is None:
+            single_folder = not unified
+
+        in_dir = Path(input_dir)
+        candidates = in_dir.rglob("*") if recursive else in_dir.iterdir()
+        pou_files = sorted(
+            (
+                path for path in candidates
+                if path.is_file()
+                and path.suffix.lower() == ".tcpou"
+                and not _is_excluded(path, in_dir, exclude)
+            ),
+            key=lambda path: str(path).lower(),
+        )
+
+        written_files: list[Path] = []
+        unified_text: str | None = None
+
+        if unified:
+            merged_sections: list[str] = []
+            for pou_file in pou_files:
+                md_text, _ = self.convert_file(pou_file)
+                merged_sections.append(md_text.rstrip())
+
+            unified_text = "\n\n---\n\n".join(merged_sections) + "\n"
+
+            if output_dir:
+                out_target = Path(output_dir)
+                if out_target.suffix.lower() == ".md":
+                    out_path = out_target
+                    if not dry_run:
+                        out_path.parent.mkdir(parents=True, exist_ok=True)
+                else:
+                    if not dry_run:
+                        out_target.mkdir(parents=True, exist_ok=True)
+                    out_path = out_target / unified_filename
+
+                if not dry_run:
+                    try:
+                        _atomic_write(out_path, unified_text)
+                    except OSError as error:
+                        raise TcPOUOutputError(f"could not write '{out_path}': {error}") from error
+                written_files.append(out_path)
+
+        if single_folder:
+            individual_output = Path(output_dir) if output_dir else None
+            if individual_output and individual_output.suffix.lower() == ".md":
+                individual_output = individual_output.parent
+
+            individual_files: list[Path] = []
+            for pou_file in pou_files:
+                if recursive and copy_folder_structure:
+                    rel = pou_file.relative_to(in_dir)
+                    custom_filename = str(rel.with_suffix(".md"))
+                elif recursive:
+                    rel = pou_file.relative_to(in_dir)
+                    parts = list(rel.parent.parts) + [pou_file.stem]
+                    custom_filename = "--".join(parts) + ".md"
+                else:
+                    custom_filename = f"{pou_file.stem}.md"
+
+                _, out_path = self.convert_file(
+                    pou_file,
+                    output_dir=individual_output,
+                    custom_filename=custom_filename,
+                    dry_run=dry_run,
+                )
+                if out_path:
+                    individual_files.append(out_path)
+
+            written_files.extend(individual_files)
+
+        return written_files, unified_text
+
+
+def _is_excluded(path: Path, root: Path, patterns: tuple[str, ...]) -> bool:
+    relative = path.relative_to(root)
+    candidates = (path.name, str(relative), relative.as_posix())
+    return any(
+        fnmatch.fnmatch(candidate, pattern)
+        for pattern in patterns
+        for candidate in candidates
+    )

pou2md/errors.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+
+class TcPOUError(Exception):
+    """Base class for conversion errors that can be shown without a traceback."""
+
+
+class TcPOUParseError(TcPOUError):
+    def __init__(self, filename: str, error: Exception):
+        self.filename = filename
+        self.original = error
+        position = getattr(error, "position", None)
+        location = f" at line {position[0]}, column {position[1]}" if position else ""
+        super().__init__(f"failed to parse '{filename}'{location}: {error}")
+
+
+class TcPOUInputError(TcPOUError):
+    """Raised when an input file cannot be read."""
+
+
+class TcPOUOutputError(TcPOUError):
+    """Raised when generated output cannot be written."""

pou2md/manifest.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from collections.abc import Iterable
+from pathlib import Path
+
+MANIFEST_NAME = ".pou2md-manifest.json"
+
+
+def manifest_path(output: str | Path) -> Path:
+    target = Path(output)
+    return target.parent / MANIFEST_NAME if target.suffix.lower() == ".md" else target / MANIFEST_NAME
+
+
+def load_manifest(path: Path) -> set[Path]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        root = path.parent.resolve()
+        outputs = set()
+        for item in data.get("outputs", []):
+            candidate = (path.parent / Path(item)).resolve()
+            if candidate == root or root in candidate.parents:
+                outputs.add(candidate)
+        return outputs
+    except (FileNotFoundError, OSError, json.JSONDecodeError, TypeError):
+        return set()
+
+
+def save_manifest(
+    path: Path,
+    outputs: Iterable[Path],
+    dry_run: bool = False,
+    metadata: dict[str, object] | None = None,
+) -> None:
+    if dry_run:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    root = path.parent.resolve()
+    relative_outputs = sorted(
+        str(output.resolve().relative_to(root))
+        for output in outputs
+        if output.resolve() != path.resolve() and root in output.resolve().parents
+    )
+    payload = {
+        "version": 2,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "outputs": relative_outputs,
+        "metadata": metadata or {},
+    }
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        temporary.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def clean_stale_outputs(manifest: Path, current_outputs: set[Path], dry_run: bool = False) -> list[Path]:
+    stale = sorted(load_manifest(manifest) - current_outputs)
+    if not dry_run:
+        for output in stale:
+            try:
+                output.unlink(missing_ok=True)
+            except OSError:
+                continue
+        save_manifest(manifest, current_outputs)
+        for parent in sorted({output.parent for output in stale}, reverse=True):
+            try:
+                parent.rmdir()
+            except OSError:
+                pass
+    return stale

pou2md/model/__init__.py

@@ -0,0 +1,12 @@
+from .declaration import Variable, VarGroup, PouDeclaration
+from .flow_graph import FlowNode, FlowEdge, NetworkDiagram, FlowGraph
+
+__all__ = [
+    "Variable",
+    "VarGroup",
+    "PouDeclaration",
+    "FlowNode",
+    "FlowEdge",
+    "NetworkDiagram",
+    "FlowGraph",
+]