linkforge-core 1.4.0__py3-none-any.whl

linkforge/core/_utils/string_utils.py

@@ -0,0 +1,96 @@
+"""String utility functions."""
+
+from __future__ import annotations
+
+from ..exceptions import RobotValidationError, ValidationErrorCode
+
+
+def sanitize_name(name: str | None, allow_hyphen: bool = True) -> str:
+    """Sanitize a name for robot model and Python identifier compatibility.
+
+    Replaces invalid characters with underscores and ensures it doesn't
+    start with a digit.
+
+    Args:
+        name: Original name
+        allow_hyphen: Whether to allow hyphens (valid in many formats like URDF/SDF, invalid in Python)
+
+    Returns:
+        Sanitized name
+    """
+    if not name:
+        return ""
+
+    # Prevent ReDoS: limit input length before processing
+    if len(name) > 1000:
+        raise RobotValidationError(
+            ValidationErrorCode.OUT_OF_RANGE,
+            f"Name length {len(name)} exceeds 1000 characters",
+            target="NameLength",
+            value=len(name),
+        )
+
+    # Replace spaces with underscores
+    name = name.replace(" ", "_")
+
+    # Character iteration (safer than regex)
+    allowed_special = ("_", "-") if allow_hyphen else ("_",)
+    sanitized = "".join(c if c.isalnum() or c in allowed_special else "_" for c in name)
+
+    # Ensure it doesn't start with a digit
+    if sanitized and sanitized[0].isdigit():
+        sanitized = f"_{sanitized}"
+
+    return sanitized
+
+
+def is_valid_name(name: str, allow_hyphen: bool = True) -> bool:
+    """Check if a name is valid for robot components.
+
+    A valid name:
+    - Is not empty
+    - Does not start with a digit
+    - Contains only alphanumeric characters, underscores, and optionally hyphens
+
+    Args:
+        name: Name to validate
+        allow_hyphen: Whether to allow hyphens (valid in URDF/SDF, invalid in Python)
+
+    Returns:
+        True if name is valid, False otherwise
+
+    Examples:
+        >>> is_valid_name("base_link")
+        True
+        >>> is_valid_name("base-link")
+        True
+        >>> is_valid_name("base-link", allow_hyphen=False)
+        False
+        >>> is_valid_name("2nd_link")
+        False
+        >>> is_valid_name("base link")
+        False
+    """
+    if not name:
+        return False
+
+    # Must not start with a digit
+    if name[0].isdigit():
+        return False
+
+    # All characters must be alphanumeric or allowed special chars
+    allowed_special = ("_", "-") if allow_hyphen else ("_",)
+    return all(c.isalnum() or c in allowed_special for c in name)
+
+
+def format_scientific(value: float) -> str:
+    """Format a float to scientific notation for UI display."""
+    return f"{value:.2e}"
+
+
+def parse_scientific(value: str, fallback: float) -> float:
+    """Parse a scientific notation string back to float."""
+    try:
+        return float(value)
+    except ValueError:
+        return fallback

linkforge/core/_utils/xml_utils.py

@@ -0,0 +1,396 @@
+"""XML utility functions for LinkForge."""
+
+import math
+import xml.etree.ElementTree as ET
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any
+
+from ..constants import (
+    MAX_REASONABLE_FLOAT,
+    MAX_REASONABLE_INT,
+    MAX_XML_DEPTH,
+    XACRO_URIS,
+)
+from ..exceptions import RobotMathError, RobotValidationError, ValidationErrorCode
+from ..models import Vector3
+
+# Register XACRO namespace to ensure standard 'xacro:' prefix in exports
+ET.register_namespace("xacro", next(iter(XACRO_URIS)))
+
+
+def strip_xml_namespace(tag: str) -> str:
+    """Strip XML namespace (Clark notation) from a tag string.
+
+    Example:
+        '{http://www.ros.org/wiki/xacro}macro' -> 'macro'
+        'robot' -> 'robot'
+
+    Args:
+        tag: The XML tag string to process.
+
+    Returns:
+        The local tag name without the namespace.
+    """
+    if tag.startswith("{"):
+        return tag.split("}", 1)[-1]
+    return tag
+
+
+def get_xml_namespace(tag: str) -> str | None:
+    """Extract XML namespace URI from a tag string in Clark notation.
+
+    Example:
+        '{http://www.ros.org/wiki/xacro}macro' -> 'http://www.ros.org/wiki/xacro'
+        'robot' -> None
+
+    Args:
+        tag: The XML tag string to process.
+
+    Returns:
+        The namespace URI if present, otherwise None.
+    """
+    if tag.startswith("{"):
+        return tag[1:].split("}", 1)[0]
+    return None
+
+
+def validate_xml_depth(element: ET.Element, depth: int = 0) -> None:
+    """Validate XML depth to prevent billion laughs attack.
+
+    Args:
+        element: XML element to validate
+        depth: Current nesting depth
+
+    Raises:
+        RobotValidationError: If depth exceeds MAX_XML_DEPTH
+    """
+    if depth > MAX_XML_DEPTH:
+        raise RobotValidationError(
+            ValidationErrorCode.OUT_OF_RANGE,
+            f"XML nesting depth {depth} exceeds limit {MAX_XML_DEPTH}",
+            target="XMLDepth",
+            value=depth,
+        )
+
+    for child in element:
+        validate_xml_depth(child, depth + 1)
+
+
+def get_xml_header(element: ET.Element, version: str) -> str:
+    """Standardized header comment for XML files.
+
+    Args:
+        element: Root XML element (to extract robot name)
+        version: LinkForge version
+
+    Returns:
+        Header string containing XML declaration and meta comment
+    """
+    return f"""<?xml version="1.0"?>
+<!--
+  Robot: {element.get("name", "robot")}
+  Generated by: LinkForge v{version}
+  https://github.com/arounamounchili/linkforge
+  Date: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+-->
+"""
+
+
+def indent_xml(element: ET.Element, space: str = "  ", level: int = 0) -> None:
+    """Format XML elements with indentation.
+
+    Args:
+        element: XML element to indent
+        space: Indentation string
+        level: Starting level
+    """
+    ET.indent(element, space=space, level=level)
+
+
+def serialize_xml(
+    element: ET.Element,
+    pretty_print: bool = True,
+    version: str = "unknown",
+    namespaces: dict[str, str] | None = None,
+) -> str:
+    """Convert XML element to standardized LinkForge string.
+
+    Args:
+        element: XML element to serialize
+        pretty_print: Whether to indent
+        version: LinkForge version for header
+        namespaces: Optional dict of {prefix: uri} to register
+
+    Returns:
+        XML string
+    """
+    if namespaces:
+        for prefix, uri in namespaces.items():
+            ET.register_namespace(prefix, uri)
+
+    if pretty_print:
+        indent_xml(element)
+
+    xml_str = ET.tostring(element, encoding="unicode")
+
+    # Ensure namespaces are explicitly present on root if ElementTree dropped them
+    if namespaces:
+        for prefix, uri in namespaces.items():
+            ns_attr = f'xmlns:{prefix}="{uri}"'
+            # Using a more robust check for root tag insertion
+            if ns_attr not in xml_str and "<robot" in xml_str:
+                xml_str = xml_str.replace("<robot", f"<robot {ns_attr}", 1)
+
+    return get_xml_header(element, version) + xml_str
+
+
+def parse_float(
+    text: str | None,
+    attribute_name: str = "value",
+    default: float | None = None,
+    check_name: str | None = None,
+) -> float:
+    """Parse float value from XML with comprehensive validation.
+
+    Args:
+        text: String to parse
+        attribute_name: Context for error messages
+        default: Default value if text is None
+        check_name: Alias for attribute_name used in some parsers
+
+    Returns:
+        Parsed float
+
+    Raises:
+        RobotMathError: If input is invalid
+        RobotValidationError: If attribute is missing
+    """
+    # Alias check_name if provided
+    report_name = check_name or attribute_name
+
+    if text is not None and not text.strip():
+        text = None
+
+    if text is None:
+        if default is not None:
+            return default
+        raise RobotValidationError(
+            ValidationErrorCode.VALUE_EMPTY,
+            f"Missing required attribute: {report_name}",
+            target=report_name,
+        )
+
+    try:
+        value = float(text)
+        if math.isnan(value) or math.isinf(value):
+            raise RobotMathError(
+                ValidationErrorCode.INVALID_VALUE,
+                f"Non-finite float value '{value}' in {report_name}",
+                target=report_name,
+                value=value,
+            )
+
+        # Sanity check for reasonable values (Standard LinkForge limit)
+        # Physics constants like kp (stiffness) can be very large (e.g. 1e12)
+        if not (-MAX_REASONABLE_FLOAT < value < MAX_REASONABLE_FLOAT):
+            raise RobotMathError(
+                ValidationErrorCode.OUT_OF_RANGE,
+                f"Float value '{value}' in {report_name} is outside reasonable range",
+                target=report_name,
+                value=value,
+            )
+
+        return value
+    except ValueError:
+        raise RobotMathError(
+            ValidationErrorCode.INVALID_VALUE,
+            f"Invalid float format '{text}' in {report_name}",
+            target=report_name,
+            value=text,
+        ) from None
+
+
+def parse_int(
+    text: str | None,
+    attribute_name: str = "value",
+    default: int | None = None,
+    check_name: str | None = None,
+) -> int:
+    """Parse integer value from XML with comprehensive validation.
+
+    Args:
+        text: String to parse
+        attribute_name: Context for error messages
+        default: Default value if text is None
+        check_name: Alias for attribute_name for consistent reporting
+
+    Returns:
+        Parsed integer
+
+    Raises:
+        RobotMathError: If input format is invalid or value is out of range
+        RobotValidationError: If attribute is missing and no default is provided
+    """
+    report_name = check_name or attribute_name
+
+    if text is not None and not text.strip():
+        text = None
+
+    if text is None:
+        if default is not None:
+            return default
+        raise RobotValidationError(
+            ValidationErrorCode.VALUE_EMPTY,
+            f"Missing required attribute: {report_name}",
+            target=report_name,
+        )
+
+    try:
+        value = int(text)
+        # Sanity check for reasonable values (standard LinkForge limit)
+        if not (-MAX_REASONABLE_INT < value < MAX_REASONABLE_INT):
+            raise RobotMathError(
+                ValidationErrorCode.OUT_OF_RANGE,
+                f"Integer value '{value}' in {report_name} is outside reasonable range",
+                target=report_name,
+                value=value,
+            )
+        return value
+    except ValueError:
+        raise RobotMathError(
+            ValidationErrorCode.INVALID_VALUE,
+            f"Invalid integer format '{text}' in {report_name}",
+            target=report_name,
+            value=text,
+        ) from None
+
+
+def parse_vector3(text: str) -> Vector3:
+    """Parse space-separated vector3 string.
+
+    Args:
+        text: Space-separated string (e.g. "1.0 2.0 3.0")
+
+    Returns:
+        Vector3 model
+
+    Raises:
+        RobotValidationError: If vector format is invalid or components are missing
+        RobotMathError: If component values are invalid
+    """
+    parts = text.strip().split()
+    if len(parts) != 3:
+        raise RobotValidationError(
+            ValidationErrorCode.INVALID_VALUE,
+            f"Expected 3 values for Vector3, got {len(parts)}",
+            target="Vector3",
+            value=text,
+        )
+    try:
+        x = parse_float(parts[0], "x")
+        y = parse_float(parts[1], "y")
+        z = parse_float(parts[2], "z")
+        return Vector3(x, y, z)
+    except (RobotMathError, RobotValidationError):
+        raise
+
+
+def parse_optional_bool(elem: ET.Element, tag: str, default: str = "false") -> bool | None:
+    """Parse optional boolean element.
+
+    Args:
+        elem: Parent XML element
+        tag: Sub-element tag to find
+        default: Default string value if tag is found but content is empty
+
+    Returns:
+        Boolean value if tag exists, else None
+    """
+    if elem.find(f"{{*}}{tag}") is not None:
+        return elem.findtext(f"{{*}}{tag}", default).lower() == "true"
+    return None
+
+
+def parse_optional_float(elem: ET.Element, tag: str, default: float | None = 0.0) -> float | None:
+    """Parse optional float element.
+
+    Args:
+        elem: Parent XML element
+        tag: Sub-element tag to find
+        default: Default float value if tag content is missing
+
+    Returns:
+        Parsed float if tag exists, else None
+
+    Raises:
+        RobotMathError: If input value is invalid or out of range
+        RobotValidationError: If parsing logic fails
+    """
+    if elem.find(f"{{*}}{tag}") is not None:
+        text = elem.findtext(f"{{*}}{tag}")
+        return parse_float(text, tag, default=default)
+    return None
+
+
+def xml_add_text(parent: ET.Element, tag: str, value: Any) -> ET.Element:
+    """Create a sub-element with text content.
+
+    Args:
+        parent: The parent XML element.
+        tag: The tag name for the new element.
+        value: The text content to set. Will be converted to string if not None.
+
+    Returns:
+        The newly created XML element.
+    """
+    elem = ET.SubElement(parent, tag)
+    if value is not None:
+        elem.text = str(value)
+    return elem
+
+
+def xml_add_vector(
+    parent: ET.Element,
+    tag: str,
+    vector: Vector3,
+    formatter: Callable[[float], str],
+) -> ET.Element:
+    """Create a sub-element for a vector relying on a formatter for the values.
+
+    Args:
+        parent: The parent XML element.
+        tag: The tag name for the new element.
+        vector: The Vector3 object containing the values.
+        formatter: A callable that takes a float and returns a string (e.g., format_float).
+
+    Returns:
+        The newly created XML element with the formatted text string.
+    """
+    # Create text from formatted components
+    text_val = f"{formatter(vector.x)} {formatter(vector.y)} {formatter(vector.z)}"
+    return xml_add_text(parent, tag, text_val)
+
+
+def create_xml_element(
+    parent: ET.Element,
+    tag: str,
+    formatter: Callable[[Any], str] | None = None,
+    **kwargs: Any,
+) -> ET.Element:
+    """Create an XML element, stripping None values and converting types to str.
+
+    Args:
+        parent: Parent XML element
+        tag: Tag name for the new element
+        formatter: Optional callable to format values before string conversion
+        **kwargs: Attributes for the new element
+
+    Returns:
+        The newly created XML element
+    """
+    if formatter:
+        attrib = {k: formatter(v) for k, v in kwargs.items() if v is not None}
+    else:
+        attrib = {k: str(v) for k, v in kwargs.items() if v is not None}
+    return ET.SubElement(parent, tag, attrib)

linkforge/core/base.py

@@ -0,0 +1,218 @@
+"""Base classes for Robot Generators and Parsers.
+
+This module defines the abstract base classes that facilitate translation
+between the LinkForge Intermediate Representation (IR) and various external
+robot description formats.
+
+Core Components:
+    - RobotGenerator: Abstract base for format-specific exporters (URDF, SRDF).
+    - RobotParser: Abstract base for format-specific importers.
+    - IResourceResolver: Protocol for resolving package:// and file:// URIs.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Generic, Protocol, TypeVar, runtime_checkable
+
+from ._utils.path_utils import normalize_uri_to_path, resolve_package_path
+from .exceptions import (
+    LinkForgeError,
+    RobotGeneratorError,
+    RobotModelError,
+    RobotParserError,
+    XacroDetectedError,
+)
+
+if TYPE_CHECKING:
+    from .models.robot import Robot
+
+# Generic type for the output format (e.g., str for XML, dict for JSON)
+T = TypeVar("T")
+
+__all__ = [
+    "RobotGenerator",
+    "RobotParser",
+    "IResourceResolver",
+    "FileSystemResolver",
+    "NetworkResolver",
+    "LinkForgeError",
+    "RobotGeneratorError",
+    "RobotModelError",
+    "RobotParserError",
+    "XacroDetectedError",
+]
+
+
+class RobotGenerator(ABC, Generic[T]):
+    """Abstract base class for all Robot Generators."""
+
+    @abstractmethod
+    def generate(self, robot: Robot, **kwargs: Any) -> T:
+        """Generate the output representation from the Robot model.
+
+        Args:
+            robot: The generic Robot model (Intermediate Representation)
+            **kwargs: Format-specific generation options
+
+        Returns:
+            The generated output (e.g. XML string, JSON dict)
+        """
+        pass
+
+    def write(self, robot: Robot, filepath: Path, **kwargs: Any) -> None:
+        """Write the generated output to a file.
+
+        This is a template method that handles directory creation and
+        delegates the actual writing to the _save_to_file hook.
+
+        Args:
+            robot: Robot model to export
+            filepath: Destination file path
+            **kwargs: Options passed to generate() and _save_to_file()
+        """
+        try:
+            # Ensure parent directory exists
+            filepath.parent.mkdir(parents=True, exist_ok=True)
+
+            content = self.generate(robot, **kwargs)
+            self._save_to_file(content, filepath, **kwargs)
+        except Exception as e:
+            if isinstance(e, LinkForgeError):
+                raise
+            raise RobotGeneratorError(str(filepath), str(e)) from e
+
+    def _save_to_file(self, content: T, filepath: Path, **_kwargs: Any) -> None:
+        """Default I/O hook for saving content.
+
+        Supports both string (text) and binary (bytes) content by default.
+        Formats requiring specialized serialization should override this.
+
+        Args:
+            content: Generated content from generate()
+            filepath: Target file path
+            **kwargs: Additional options
+        """
+        if isinstance(content, str):
+            filepath.write_text(content, encoding="utf-8")
+        elif isinstance(content, bytes):
+            filepath.write_bytes(content)
+        else:
+            raise RobotGeneratorError(self.__class__.__name__, type(content))
+
+
+class RobotParser(ABC, Generic[T]):
+    """Abstract base class for all Robot Parsers."""
+
+    @abstractmethod
+    def parse(self, filepath: Path, **kwargs: Any) -> T:
+        """Parse a file into a model.
+
+        Args:
+            filepath: Path to the input file
+            **kwargs: Format-specific parsing options
+
+        Returns:
+            The parsed model (e.g. Robot, SemanticRobotDescription)
+        """
+        pass
+
+    @abstractmethod
+    def parse_string(self, content: str, **kwargs: Any) -> T:
+        """Parse a string representation into a model.
+
+        Args:
+            content: The string content to parse
+            **kwargs: Format-specific parsing options
+
+        Returns:
+            The parsed model (e.g. Robot, SemanticRobotDescription)
+        """
+        pass
+
+
+@runtime_checkable
+class IResourceResolver(Protocol):
+    """Protocol for resolving resource URIs (e.g. package://, file://, https://)."""
+
+    def resolve(self, uri: str, relative_to: Path | None = None) -> Path:
+        """Resolve a URI to a local filesystem Path.
+
+        Args:
+            uri: The resource URI to resolve.
+            relative_to: Optional base directory for relative path resolution.
+
+        Returns:
+            The resolved absolute Path.
+
+        Raises:
+            FileNotFoundError: If the resource cannot be located.
+        """
+        ...
+
+
+class FileSystemResolver:
+    """Default resolver for local file paths, file://, and package:// URIs."""
+
+    def __init__(self, additional_search_paths: list[Path] | None = None) -> None:
+        """Initialize the resolver.
+
+        Args:
+            additional_search_paths: Optional list of paths to check before ROS_PACKAGE_PATH.
+        """
+        self.additional_search_paths = additional_search_paths
+
+    def resolve(self, uri: str, relative_to: Path | None = None) -> Path:
+        """Resolve standard file paths, file:// URIs, and package:// URIs."""
+        # Handle package:// URIs
+        if "package://" in uri or "package:/" in uri:
+            # We use an empty Path if relative_to is not provided,
+            # though package resolution usually doesn't strictly need it if ROS_PACKAGE_PATH is set.
+            resolved = resolve_package_path(
+                uri, relative_to or Path.cwd(), additional_search_paths=self.additional_search_paths
+            )
+            if resolved and resolved.exists():
+                return resolved.absolute()
+            raise FileNotFoundError(uri)
+
+        # Handle file:// URIs
+        if uri.startswith("file://"):
+            path = normalize_uri_to_path(uri)
+            if path.exists():
+                return path.absolute()
+            raise FileNotFoundError(uri)
+
+        # Handle standard paths (absolute or relative)
+        path = Path(uri)
+        if path.is_absolute():
+            if path.exists():
+                return path.absolute()
+        elif relative_to is not None:
+            # Try relative to the provided directory
+            rel_path = (relative_to / path).resolve()
+            if rel_path.exists():
+                return rel_path
+
+        # Final fallback: current working directory if it exists there
+        if path.exists():
+            return path.absolute()
+
+        raise FileNotFoundError(uri)
+
+
+class NetworkResolver:
+    """Mock network resolver for URL-based meshes.
+
+    This is a placeholder for future cloud integrations (e.g. AWS S3, HTTP).
+    Currently raises a NotImplementedError if a network URI is detected.
+    """
+
+    def resolve(self, uri: str, relative_to: Path | None = None) -> Path:
+        """Simulate network resolution."""
+        if any(uri.startswith(p) for p in ("http://", "https://", "s3://")):
+            # In a real implementation, this would download to a /tmp cache
+            raise NotImplementedError(uri)
+
+        # Fallback to standard filesystem if it's a local path
+        return FileSystemResolver().resolve(uri, relative_to=relative_to)