tnfr 3.0.3__py3-none-any.whl → 8.5.0__py3-none-any.whl

tnfr/cli/utils.py

@@ -0,0 +1,51 @@
+"""Utilities for CLI modules."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from ..utils import normalize_optional_int
+
+
+def spec(opt: str, /, **kwargs: Any) -> tuple[str, dict[str, Any]]:
+    """Create an argument specification pair.
+
+    Parameters
+    ----------
+    opt:
+        Option string to register, e.g. ``"--foo"``.
+    **kwargs:
+        Keyword arguments forwarded to
+        :meth:`argparse.ArgumentParser.add_argument`.
+
+    Returns
+    -------
+    tuple[str, dict[str, Any]]
+        A pair suitable for collecting into argument specification sequences.
+        If ``dest`` is not provided it is
+        derived from ``opt`` by stripping leading dashes and replacing dots and
+        hyphens with underscores. ``default`` defaults to ``None`` so missing
+        options can be filtered easily.
+    """
+
+    kwargs = dict(kwargs)
+    kwargs.setdefault("dest", opt.lstrip("-").replace("-", "_").replace(".", "_"))
+    kwargs.setdefault("default", None)
+    return opt, kwargs
+
+
+def _parse_cli_variants(values: Iterable[Any] | None) -> list[int | None]:
+    """Return a stable list of integer/``None`` variants for the CLI options."""
+
+    if values is None:
+        return [None]
+    parsed: list[int | None] = []
+    seen: set[int | None] = set()
+    for raw in values:
+        coerced = normalize_optional_int(raw, strict=True)
+        if coerced in seen:
+            continue
+        seen.add(coerced)
+        parsed.append(coerced)
+    return parsed or [None]

tnfr/cli/utils.pyi

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+def spec(opt: str, /, **kwargs: Any) -> tuple[str, dict[str, Any]]: ...
+def _parse_cli_variants(values: Iterable[Any] | None) -> list[int | None]: ...

tnfr/cli/validate.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python
+"""CLI tool for TNFR validation.
+
+This tool provides two modes:
+1. Graph validation: Validate TNFR graphs from files (original behavior)
+2. Interactive sequence validation: User-friendly sequence validator (new)
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import networkx as nx
+
+from ..validation import (
+    InvariantSeverity,
+    TNFRValidator,
+    configure_validation,
+)
+
+
+def load_graph(filepath: str) -> nx.Graph:
+    """Load a graph from file.
+
+    Parameters
+    ----------
+    filepath : str
+        Path to graph file (supports .graphml, .gml, .json).
+
+    Returns
+    -------
+    nx.Graph
+        Loaded graph.
+    """
+    filepath_obj = Path(filepath)
+
+    if not filepath_obj.exists():
+        raise FileNotFoundError(f"Graph file not found: {filepath}")
+
+    # Determine format from extension
+    ext = filepath_obj.suffix.lower()
+
+    if ext == ".graphml":
+        return nx.read_graphml(filepath)
+    elif ext == ".gml":
+        return nx.read_gml(filepath)
+    elif ext == ".json":
+        with open(filepath, "r") as f:
+            data = json.load(f)
+        return nx.node_link_graph(data)
+    else:
+        raise ValueError(
+            f"Unsupported graph format: {ext}. Use .graphml, .gml, or .json"
+        )
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="TNFR Validation Tool - Validate graphs or sequences",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive sequence validator (NEW!)
+  tnfr-validate --interactive
+  tnfr-validate -i
+  
+  # Validate a graph file
+  tnfr-validate graph.graphml
+  
+  # Export to JSON
+  tnfr-validate graph.graphml --format json --output report.json
+  
+  # Export to HTML
+  tnfr-validate graph.graphml --format html --output report.html
+  
+  # Set minimum severity to WARNING
+  tnfr-validate graph.graphml --min-severity warning
+  
+  # Enable caching for multiple validations
+  tnfr-validate graph.graphml --cache
+        """,
+    )
+
+    parser.add_argument(
+        "--interactive",
+        "-i",
+        action="store_true",
+        help="Launch interactive sequence validator",
+    )
+
+    parser.add_argument(
+        "graph_file",
+        nargs="?",
+        help="Path to graph file (.graphml, .gml, or .json). Required unless using --interactive mode.",
+    )
+
+    parser.add_argument(
+        "--format",
+        choices=["text", "json", "html"],
+        default="text",
+        help="Output format (default: text)",
+    )
+
+    parser.add_argument(
+        "--output",
+        "-o",
+        help="Output file (default: stdout for text, or auto-generated for json/html)",
+    )
+
+    parser.add_argument(
+        "--min-severity",
+        choices=["info", "warning", "error", "critical"],
+        default="error",
+        help="Minimum severity to report (default: error)",
+    )
+
+    parser.add_argument(
+        "--cache", action="store_true", help="Enable validation result caching"
+    )
+
+    parser.add_argument(
+        "--no-semantic",
+        action="store_true",
+        help="Disable semantic sequence validation",
+    )
+
+    parser.add_argument(
+        "--phase-threshold",
+        type=float,
+        help="Phase coupling threshold in radians (default: π/2)",
+    )
+
+    parser.add_argument("--verbose", "-v", action="store_true", help="Verbose output")
+
+    parser.add_argument(
+        "--seed",
+        type=int,
+        help="Random seed for interactive validator (deterministic generation)",
+    )
+
+    args = parser.parse_args()
+
+    # Handle interactive mode
+    if args.interactive:
+        from .interactive_validator import run_interactive_validator
+
+        return run_interactive_validator(seed=args.seed)
+
+    # Require graph_file for non-interactive mode
+    if not args.graph_file:
+        parser.error("graph_file is required when not using --interactive mode")
+
+    # Configure validation
+    severity_map = {
+        "info": InvariantSeverity.INFO,
+        "warning": InvariantSeverity.WARNING,
+        "error": InvariantSeverity.ERROR,
+        "critical": InvariantSeverity.CRITICAL,
+    }
+
+    configure_validation(
+        validate_invariants=True,
+        enable_semantic_validation=not args.no_semantic,
+        min_severity=severity_map[args.min_severity],
+    )
+
+    if args.verbose:
+        print(f"Loading graph from: {args.graph_file}")
+
+    try:
+        # Load graph
+        graph = load_graph(args.graph_file)
+
+        if args.verbose:
+            print(
+                f"Graph loaded: {graph.number_of_nodes()} nodes, {graph.number_of_edges()} edges"
+            )
+
+        # Create validator
+        if args.phase_threshold:
+            validator = TNFRValidator(phase_coupling_threshold=args.phase_threshold)
+        else:
+            validator = TNFRValidator()
+
+        if args.cache:
+            validator.enable_cache(True)
+
+        # Validate
+        if args.verbose:
+            print("Running TNFR validation...")
+
+        violations = validator.validate_graph(graph)
+
+        # Generate output
+        if args.format == "text":
+            output = validator.generate_report(violations)
+        elif args.format == "json":
+            output = validator.export_to_json(violations)
+        elif args.format == "html":
+            output = validator.export_to_html(violations)
+
+        # Write output
+        if args.output:
+            output_path = Path(args.output)
+            with open(output_path, "w") as f:
+                f.write(output)
+            print(f"Report written to: {output_path}")
+        else:
+            # Print to stdout
+            print(output)
+
+        # Exit code based on violations
+        if violations:
+            # Check if there are any ERROR or CRITICAL violations
+            has_errors = any(
+                v.severity in [InvariantSeverity.ERROR, InvariantSeverity.CRITICAL]
+                for v in violations
+            )
+            sys.exit(1 if has_errors else 0)
+        else:
+            sys.exit(0)
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+
+            traceback.print_exc()
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

tnfr/compat/__init__.py

@@ -0,0 +1,85 @@
+"""Compatibility layer for optional dependencies.
+
+This module provides lightweight stubs and fallback interfaces for optional
+dependencies like numpy, matplotlib, and jsonschema. When these packages are
+not installed, the stubs allow type checking and imports to succeed without
+runtime errors, while maintaining TNFR semantic clarity.
+
+TYPE_CHECKING guards
+--------------------
+Use ``if TYPE_CHECKING:`` blocks to import optional typing-only dependencies.
+At runtime, fallback stubs are used instead.
+
+Example::
+
+    from typing import TYPE_CHECKING
+    if TYPE_CHECKING:
+        import numpy as np
+    else:
+        from tnfr.compat import numpy_stub as np
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "get_numpy_or_stub",
+    "get_matplotlib_or_stub",
+    "get_jsonschema_or_stub",
+    "numpy_stub",
+    "matplotlib_stub",
+    "jsonschema_stub",
+]
+
+from typing import Any
+
+# Import stubs so they're available as module attributes
+from . import numpy_stub, matplotlib_stub, jsonschema_stub
+
+
+def get_numpy_or_stub() -> Any:
+    """Return numpy module if available, otherwise return a stub.
+
+    Returns
+    -------
+    module or stub
+        The actual numpy module when installed, or a minimal stub providing
+        basic type compatibility for type checking.
+    """
+    try:
+        import numpy
+
+        return numpy
+    except ImportError:
+        return numpy_stub
+
+
+def get_matplotlib_or_stub() -> Any:
+    """Return matplotlib module if available, otherwise return a stub.
+
+    Returns
+    -------
+    module or stub
+        The actual matplotlib module when installed, or a minimal stub.
+    """
+    try:
+        import matplotlib
+
+        return matplotlib
+    except ImportError:
+        return matplotlib_stub
+
+
+def get_jsonschema_or_stub() -> Any:
+    """Return jsonschema module if available, otherwise return a stub.
+
+    Returns
+    -------
+    module or stub
+        The actual jsonschema module when installed, or a minimal stub.
+    """
+    try:
+        import jsonschema
+
+        return jsonschema
+    except ImportError:
+        return jsonschema_stub

tnfr/compat/dataclass.py

@@ -0,0 +1,136 @@
+"""Dataclass compatibility for Python 3.9+.
+
+Provides a wrapper for @dataclass that conditionally applies ``slots=True``
+only on Python 3.10+ where it is supported, maintaining compatibility with
+Python 3.9.
+"""
+
+import sys
+from dataclasses import dataclass as _dataclass
+from typing import Type, TypeVar, overload
+
+_T = TypeVar("_T")
+
+# Check if slots parameter is supported (Python 3.10+)
+_SLOTS_SUPPORTED = sys.version_info >= (3, 10)
+
+
+@overload
+def dataclass(
+    cls: Type[_T],
+    /,
+    *,
+    init: bool = True,
+    repr: bool = True,
+    eq: bool = True,
+    order: bool = False,
+    unsafe_hash: bool = False,
+    frozen: bool = False,
+    match_args: bool = True,
+    kw_only: bool = False,
+    slots: bool = False,
+) -> Type[_T]: ...
+
+
+@overload
+def dataclass(
+    cls: None = None,
+    /,
+    *,
+    init: bool = True,
+    repr: bool = True,
+    eq: bool = True,
+    order: bool = False,
+    unsafe_hash: bool = False,
+    frozen: bool = False,
+    match_args: bool = True,
+    kw_only: bool = False,
+    slots: bool = False,
+) -> Type[_T]: ...
+
+
+def dataclass(
+    cls=None,
+    /,
+    *,
+    init=True,
+    repr=True,
+    eq=True,
+    order=False,
+    unsafe_hash=False,
+    frozen=False,
+    match_args=True,
+    kw_only=False,
+    slots=False,
+):
+    """Compatibility wrapper for @dataclass supporting Python 3.9+.
+
+    On Python 3.10+, passes all parameters including ``slots`` to dataclass.
+    On Python 3.9, silently ignores ``slots`` parameter since it's not supported.
+
+    This allows code to use ``slots=True`` for performance benefits on newer
+    Python versions while maintaining backward compatibility with 3.9.
+
+    Parameters
+    ----------
+    cls : type, optional
+        Class to decorate (when used without parentheses).
+    init : bool, default True
+        Generate __init__ method.
+    repr : bool, default True
+        Generate __repr__ method.
+    eq : bool, default True
+        Generate __eq__ method.
+    order : bool, default False
+        Generate ordering methods.
+    unsafe_hash : bool, default False
+        Force generation of __hash__ method.
+    frozen : bool, default False
+        Make instances immutable.
+    match_args : bool, default True
+        Generate __match_args__ for pattern matching (Python 3.10+).
+    kw_only : bool, default False
+        Make all fields keyword-only.
+    slots : bool, default False
+        Generate __slots__ (Python 3.10+ only, ignored on 3.9).
+
+    Returns
+    -------
+    type
+        Decorated dataclass.
+
+    Examples
+    --------
+    >>> from tnfr.compat.dataclass import dataclass
+    >>> @dataclass(slots=True)  # Works on both 3.9 and 3.10+
+    ... class Point:
+    ...     x: float
+    ...     y: float
+    """
+
+    # Build kwargs based on Python version
+    kwargs = {
+        "init": init,
+        "repr": repr,
+        "eq": eq,
+        "order": order,
+        "unsafe_hash": unsafe_hash,
+        "frozen": frozen,
+    }
+
+    # Add parameters supported in Python 3.10+
+    if sys.version_info >= (3, 10):
+        kwargs["match_args"] = match_args
+        kwargs["kw_only"] = kw_only
+        kwargs["slots"] = slots
+
+    # Handle decorator with and without parentheses
+    def wrap(c):
+        return _dataclass(c, **kwargs)
+
+    if cls is None:
+        # Called with parentheses: @dataclass(...)
+        return wrap
+    else:
+        # Called without parentheses: @dataclass
+        return wrap(cls)

tnfr/compat/jsonschema_stub.py

@@ -0,0 +1,61 @@
+"""Lightweight stub for jsonschema when it's not installed.
+
+This stub provides minimal type compatibility for jsonschema when it's not
+installed, allowing type checking to succeed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["Draft7Validator", "exceptions"]
+
+
+class _NotInstalledError(RuntimeError):
+    """Raised when trying to use jsonschema operations without jsonschema installed."""
+
+    def __init__(self, operation: str = "jsonschema operation") -> None:
+        super().__init__(
+            f"Cannot perform {operation}: jsonschema is not installed. "
+            "Install it with: pip install jsonschema"
+        )
+
+
+class SchemaError(Exception):
+    """Stub for jsonschema.exceptions.SchemaError."""
+
+    pass
+
+
+class ValidationError(Exception):
+    """Stub for jsonschema.exceptions.ValidationError."""
+
+    pass
+
+
+class _ExceptionsStub:
+    """Stub for jsonschema.exceptions module."""
+
+    SchemaError = SchemaError
+    ValidationError = ValidationError
+
+
+class Draft7Validator:
+    """Stub for jsonschema.Draft7Validator."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        raise _NotInstalledError("Draft7Validator creation")
+
+    @classmethod
+    def check_schema(cls, schema: Any) -> None:
+        raise _NotInstalledError("Draft7Validator.check_schema")
+
+    def validate(self, instance: Any) -> None:
+        raise _NotInstalledError("Draft7Validator.validate")
+
+    def iter_errors(self, instance: Any) -> Any:
+        raise _NotInstalledError("Draft7Validator.iter_errors")
+
+
+# Module-level stubs
+exceptions = _ExceptionsStub()

tnfr/compat/matplotlib_stub.py

@@ -0,0 +1,73 @@
+"""Lightweight stub for matplotlib when it's not installed.
+
+This stub provides minimal type compatibility for matplotlib when it's not
+installed, allowing type checking to succeed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["pyplot", "axes", "figure"]
+
+
+class _NotInstalledError(RuntimeError):
+    """Raised when trying to use matplotlib operations without matplotlib installed."""
+
+    def __init__(self, operation: str = "matplotlib operation") -> None:
+        super().__init__(
+            f"Cannot perform {operation}: matplotlib is not installed. "
+            "Install it with: pip install tnfr[viz] or pip install matplotlib"
+        )
+
+
+class Axes:
+    """Stub for matplotlib.axes.Axes."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        raise _NotInstalledError("Axes creation")
+
+
+class Figure:
+    """Stub for matplotlib.figure.Figure."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        raise _NotInstalledError("Figure creation")
+
+
+class _PyPlotStub:
+    """Stub for matplotlib.pyplot module."""
+
+    @staticmethod
+    def subplots(*args: Any, **kwargs: Any) -> tuple[Figure, Axes]:
+        raise _NotInstalledError("pyplot.subplots")
+
+    @staticmethod
+    def savefig(*args: Any, **kwargs: Any) -> None:
+        raise _NotInstalledError("pyplot.savefig")
+
+    @staticmethod
+    def show(*args: Any, **kwargs: Any) -> None:
+        raise _NotInstalledError("pyplot.show")
+
+    @staticmethod
+    def figure(*args: Any, **kwargs: Any) -> Figure:
+        raise _NotInstalledError("pyplot.figure")
+
+
+class _AxesStub:
+    """Stub for matplotlib.axes module."""
+
+    Axes = Axes
+
+
+class _FigureStub:
+    """Stub for matplotlib.figure module."""
+
+    Figure = Figure
+
+
+# Module-level stubs
+pyplot = _PyPlotStub()
+axes = _AxesStub()
+figure = _FigureStub()