sf-config-builder 0.1.1__py3-none-any.whl

sfconfig/diff.py

@@ -0,0 +1,145 @@
+"""SFDiff class for comparing Screaming Frog configurations."""
+
+from typing import Any, Dict, List, Optional
+
+
+class SFDiff:
+    """Represents a diff between two SF configs.
+
+    Example:
+        >>> diff = SFConfig.diff("old.seospiderconfig", "new.seospiderconfig")
+        >>> if diff.has_changes:
+        ...     print(f"Found {diff.change_count} differences:")
+        ...     print(diff)
+    """
+
+    def __init__(self, data: Dict[str, Any]):
+        """Initialize SFDiff with diff data from Java CLI.
+
+        Args:
+            data: Parsed JSON response from the Java CLI --diff command.
+        """
+        self._data = data
+
+    @property
+    def has_changes(self) -> bool:
+        """Check if there are any differences between the configs."""
+        return len(self.changes) > 0
+
+    @property
+    def change_count(self) -> int:
+        """Get the total number of differences."""
+        return self._data.get("totalDifferences", len(self.changes))
+
+    @property
+    def changes(self) -> List[Dict[str, Any]]:
+        """Get list of all changes.
+
+        Returns:
+            List of change dictionaries, each containing:
+            - path: The field path that changed
+            - valueA / old: The value in the first config
+            - valueB / new: The value in the second config
+        """
+        return self._data.get("differences", [])
+
+    @property
+    def config_version_a(self) -> str:
+        """Get the version of the first config."""
+        return self._data.get("configVersionA", "unknown")
+
+    @property
+    def config_version_b(self) -> str:
+        """Get the version of the second config."""
+        return self._data.get("configVersionB", "unknown")
+
+    def changes_for(self, prefix: str) -> List[Dict[str, Any]]:
+        """Get changes filtered by path prefix.
+
+        Args:
+            prefix: The path prefix to filter by (e.g., "mCrawlConfig").
+
+        Returns:
+            List of changes where the path starts with the given prefix.
+        """
+        return [c for c in self.changes if c.get("path", "").startswith(prefix)]
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the full diff as a dictionary.
+
+        Returns:
+            Dictionary containing:
+            - config_version_a: Version of first config
+            - config_version_b: Version of second config
+            - total_differences: Number of differences
+            - differences: List of change objects
+        """
+        return {
+            "config_version_a": self.config_version_a,
+            "config_version_b": self.config_version_b,
+            "total_differences": self.change_count,
+            "differences": self.changes,
+        }
+
+    def __str__(self) -> str:
+        """Return human-readable string representation of the diff."""
+        if not self.has_changes:
+            return "No changes"
+
+        lines = []
+        for change in self.changes:
+            path = change.get("path", "unknown")
+            # Handle both naming conventions from Java CLI
+            old = change.get("valueA", change.get("old", "?"))
+            new = change.get("valueB", change.get("new", "?"))
+
+            # Format values for display
+            old_str = self._format_value(old)
+            new_str = self._format_value(new)
+
+            lines.append(f"{path}: {old_str} -> {new_str}")
+
+        return "\n".join(lines)
+
+    def __repr__(self) -> str:
+        """Return developer-friendly representation."""
+        return f"<SFDiff changes={self.change_count}>"
+
+    def __len__(self) -> int:
+        """Return the number of changes."""
+        return self.change_count
+
+    def __bool__(self) -> bool:
+        """Return True if there are changes."""
+        return self.has_changes
+
+    def __iter__(self):
+        """Iterate over changes."""
+        return iter(self.changes)
+
+    @staticmethod
+    def _format_value(value: Any) -> str:
+        """Format a value for display.
+
+        Args:
+            value: The value to format.
+
+        Returns:
+            String representation of the value.
+        """
+        if value is None:
+            return "null"
+        if isinstance(value, str):
+            # Truncate long strings
+            if len(value) > 50:
+                return f'"{value[:47]}..."'
+            return f'"{value}"'
+        if isinstance(value, list):
+            if len(value) == 0:
+                return "[]"
+            if len(value) <= 3:
+                return str(value)
+            return f"[{len(value)} items]"
+        if isinstance(value, dict):
+            return f"{{{len(value)} keys}}"
+        return str(value)

sfconfig/exceptions.py

@@ -0,0 +1,26 @@
+"""Custom exceptions for sf-config-tool."""
+
+
+class SFConfigError(Exception):
+    """Base exception for sf-config-tool."""
+    pass
+
+
+class SFNotFoundError(SFConfigError):
+    """Screaming Frog is not installed or not found."""
+    pass
+
+
+class SFValidationError(SFConfigError):
+    """Invalid field path or value."""
+    pass
+
+
+class SFParseError(SFConfigError):
+    """Could not parse config file."""
+    pass
+
+
+class SFCrawlError(SFConfigError):
+    """Crawl execution failed."""
+    pass

sfconfig/paths.py

@@ -0,0 +1,217 @@
+"""Screaming Frog installation path detection."""
+
+import os
+import platform
+import shutil
+from pathlib import Path
+from typing import Optional
+
+from .exceptions import SFNotFoundError
+
+
+# Default installation paths by platform (list for multiple possible locations)
+SF_PATHS = {
+    "Darwin": ["/Applications/Screaming Frog SEO Spider.app/Contents/Resources/Java"],
+    "Windows": [
+        "C:/Program Files/Screaming Frog SEO Spider",
+        "C:/Program Files (x86)/Screaming Frog SEO Spider",
+    ],
+    "Linux": ["/usr/share/screamingfrogseospider"],
+}
+
+SF_CLI_NAMES = {
+    "Darwin": "ScreamingFrogSEOSpider",
+    "Windows": "ScreamingFrogSEOSpiderCli.exe",
+    "Linux": "screamingfrogseospider",
+}
+
+
+def get_platform() -> str:
+    """Get the current platform name."""
+    return platform.system()
+
+
+def get_sf_jar_path(sf_path: Optional[str] = None) -> str:
+    """Get path to SF's JAR files directory.
+
+    Args:
+        sf_path: Optional custom path to SF installation.
+                 If not provided, checks SF_PATH env var then common locations.
+
+    Returns:
+        Path to the directory containing SF's JAR files.
+
+    Raises:
+        SFNotFoundError: If Screaming Frog installation is not found.
+    """
+    # Try explicit argument first
+    if sf_path and os.path.exists(sf_path):
+        return sf_path
+
+    # Try custom path from env var
+    env_path = os.environ.get("SF_PATH")
+    if env_path and os.path.exists(env_path):
+        return env_path
+
+    # Try default paths for current platform
+    plat = get_platform()
+    paths = SF_PATHS.get(plat, [])
+
+    for path in paths:
+        if os.path.exists(path):
+            return path
+
+    raise SFNotFoundError(
+        "Screaming Frog not found.\n"
+        f"Checked: {paths}\n"
+        "Install from: https://www.screamingfrog.co.uk/seo-spider/\n"
+        "Or pass sf_path argument, or set SF_PATH environment variable."
+    )
+
+
+def get_sf_cli_path(sf_path: Optional[str] = None) -> str:
+    """Get path to SF CLI executable.
+
+    Args:
+        sf_path: Optional custom path to SF installation directory.
+
+    Returns:
+        Path to the Screaming Frog CLI executable.
+
+    Raises:
+        SFNotFoundError: If CLI executable is not found.
+    """
+    # Try custom path from env var
+    custom = os.environ.get("SF_CLI_PATH")
+    if custom and os.path.exists(custom):
+        return custom
+
+    plat = get_platform()
+    cli_name = SF_CLI_NAMES.get(plat, "screamingfrogseospider")
+
+    # If sf_path provided, derive CLI path from it
+    if sf_path:
+        if plat == "Darwin":
+            # macOS: /Applications/Screaming Frog SEO Spider.app/Contents/MacOS/ScreamingFrogSEOSpider
+            cli_path = sf_path.replace("/Contents/Resources/Java", f"/Contents/MacOS/{cli_name}")
+        else:
+            cli_path = os.path.join(sf_path, cli_name)
+        if os.path.exists(cli_path):
+            return cli_path
+
+    # Try default paths
+    paths = SF_PATHS.get(plat, [])
+    for base_path in paths:
+        if plat == "Darwin":
+            cli_path = base_path.replace("/Contents/Resources/Java", f"/Contents/MacOS/{cli_name}")
+        else:
+            cli_path = os.path.join(base_path, cli_name)
+        if os.path.exists(cli_path):
+            return cli_path
+
+    # On Linux, check if it's in PATH
+    if plat == "Linux":
+        which_result = shutil.which("screamingfrogseospider")
+        if which_result:
+            return which_result
+
+    raise SFNotFoundError(
+        "Screaming Frog CLI not found.\n"
+        "Or set SF_CLI_PATH environment variable."
+    )
+
+
+def get_java_path(sf_path: Optional[str] = None) -> str:
+    """Get path to Java executable.
+
+    Prefers SF's bundled JRE, falls back to system Java.
+
+    Args:
+        sf_path: Optional custom path to SF installation directory.
+
+    Returns:
+        Path to Java executable.
+
+    Raises:
+        SFNotFoundError: If no Java installation is found.
+    """
+    # Try custom path from env var
+    custom = os.environ.get("JAVA_HOME")
+    if custom:
+        java_path = os.path.join(custom, "bin", "java")
+        if get_platform() == "Windows":
+            java_path += ".exe"
+        if os.path.exists(java_path):
+            return java_path
+
+    plat = get_platform()
+    java_name = "java.exe" if plat == "Windows" else "java"
+
+    # If sf_path provided, try its bundled JRE
+    if sf_path:
+        if plat == "Darwin":
+            jre_path = sf_path.replace(
+                "/Contents/Resources/Java",
+                f"/Contents/PlugIns/jre.bundle/Contents/Home/bin/{java_name}"
+            )
+        else:
+            jre_path = os.path.join(sf_path, "jre", "bin", java_name)
+        if os.path.exists(jre_path):
+            return jre_path
+
+    # Try default SF paths for bundled JRE
+    paths = SF_PATHS.get(plat, [])
+    for base_path in paths:
+        if plat == "Darwin":
+            jre_path = base_path.replace(
+                "/Contents/Resources/Java",
+                f"/Contents/PlugIns/jre.bundle/Contents/Home/bin/{java_name}"
+            )
+        else:
+            jre_path = os.path.join(base_path, "jre", "bin", java_name)
+        if os.path.exists(jre_path):
+            return jre_path
+
+    # Fall back to system Java
+    which_result = shutil.which(java_name)
+    if which_result:
+        return which_result
+
+    raise SFNotFoundError(
+        "Java not found.\n"
+        "Screaming Frog installation may be corrupted or Java is not installed.\n"
+        "Set JAVA_HOME environment variable if Java is installed elsewhere."
+    )
+
+
+def get_classpath_separator() -> str:
+    """Get the classpath separator for the current platform."""
+    return ";" if get_platform() == "Windows" else ":"
+
+
+def get_default_config_path() -> Optional[Path]:
+    """Get path to SF's default config file location.
+
+    Returns:
+        Path to default config, or None if not found.
+    """
+    plat = get_platform()
+
+    if plat == "Windows":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            path = Path(appdata) / "Screaming Frog SEO Spider" / "spider.config"
+            if path.exists():
+                return path
+    elif plat == "Darwin":
+        home = Path.home()
+        path = home / "Library" / "Application Support" / "Screaming Frog SEO Spider" / "spider.config"
+        if path.exists():
+            return path
+    elif plat == "Linux":
+        home = Path.home()
+        path = home / ".ScreamingFrogSEOSpider" / "spider.config"
+        if path.exists():
+            return path
+
+    return None