gitmap-core 0.1.0__py3-none-any.whl

gitmap_core/diff.py

@@ -0,0 +1,283 @@
+"""JSON diffing and comparison module.
+
+Provides utilities for comparing web map JSON structures,
+detecting changes at the layer and property level.
+
+Execution Context:
+    Library module - imported by CLI diff and merge commands
+
+Dependencies:
+    - deepdiff: Deep dictionary comparison
+
+Metadata:
+    Version: 0.1.0
+    Author: GitMap Team
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Any
+
+from deepdiff import DeepDiff
+
+
+# ---- Data Classes -------------------------------------------------------------------------------------------
+
+
+@dataclass
+class LayerChange:
+    """Represents a change to a single layer.
+
+    Attributes:
+        layer_id: ID of the changed layer.
+        layer_title: Title of the layer.
+        change_type: Type of change (added, removed, modified).
+        details: Detailed change information.
+    """
+
+    layer_id: str
+    layer_title: str
+    change_type: str  # 'added', 'removed', 'modified'
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class MapDiff:
+    """Represents differences between two map states.
+
+    Attributes:
+        layer_changes: List of layer-level changes.
+        table_changes: List of table-level changes.
+        property_changes: Map-level property changes.
+        has_changes: Whether any changes were detected.
+    """
+
+    layer_changes: list[LayerChange] = field(default_factory=list)
+    table_changes: list[LayerChange] = field(default_factory=list)
+    property_changes: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def has_changes(
+            self,
+    ) -> bool:
+        """Check if any changes exist."""
+        return bool(self.layer_changes or self.table_changes or self.property_changes)
+
+    @property
+    def added_layers(
+            self,
+    ) -> list[LayerChange]:
+        """Get added layers."""
+        return [c for c in self.layer_changes if c.change_type == "added"]
+
+    @property
+    def removed_layers(
+            self,
+    ) -> list[LayerChange]:
+        """Get removed layers."""
+        return [c for c in self.layer_changes if c.change_type == "removed"]
+
+    @property
+    def modified_layers(
+            self,
+    ) -> list[LayerChange]:
+        """Get modified layers."""
+        return [c for c in self.layer_changes if c.change_type == "modified"]
+
+    @property
+    def added_tables(
+            self,
+    ) -> list[LayerChange]:
+        """Get added tables."""
+        return [c for c in self.table_changes if c.change_type == "added"]
+
+    @property
+    def removed_tables(
+            self,
+    ) -> list[LayerChange]:
+        """Get removed tables."""
+        return [c for c in self.table_changes if c.change_type == "removed"]
+
+    @property
+    def modified_tables(
+            self,
+    ) -> list[LayerChange]:
+        """Get modified tables."""
+        return [c for c in self.table_changes if c.change_type == "modified"]
+
+
+# ---- Diff Functions -----------------------------------------------------------------------------------------
+
+
+def diff_maps(
+        map1: dict[str, Any],
+        map2: dict[str, Any],
+) -> MapDiff:
+    """Compare two web map JSON structures.
+
+    Args:
+        map1: First map (typically current/index state).
+        map2: Second map (typically committed state).
+
+    Returns:
+        MapDiff object describing all differences.
+    """
+    result = MapDiff()
+
+    # Compare operational layers
+    layers1 = map1.get("operationalLayers", [])
+    layers2 = map2.get("operationalLayers", [])
+
+    layer_changes = diff_layers(layers1, layers2)
+    result.layer_changes = layer_changes
+
+    # Compare tables (same structure as layers)
+    tables1 = map1.get("tables", [])
+    tables2 = map2.get("tables", [])
+
+    table_changes = diff_layers(tables1, tables2)
+    result.table_changes = table_changes
+
+    # Compare map-level properties (excluding layers and tables)
+    map1_props = {k: v for k, v in map1.items() if k not in ("operationalLayers", "tables")}
+    map2_props = {k: v for k, v in map2.items() if k not in ("operationalLayers", "tables")}
+
+    if map1_props != map2_props:
+        deep_diff = DeepDiff(map2_props, map1_props, ignore_order=True)
+        result.property_changes = deep_diff.to_dict() if deep_diff else {}
+
+    return result
+
+
+def diff_layers(
+        layers1: list[dict[str, Any]],
+        layers2: list[dict[str, Any]],
+) -> list[LayerChange]:
+    """Compare two lists of operational layers.
+
+    Args:
+        layers1: First layer list (current state).
+        layers2: Second layer list (previous state).
+
+    Returns:
+        List of LayerChange objects.
+    """
+    changes = []
+
+    # Index layers by ID
+    index1 = {layer.get("id"): layer for layer in layers1 if layer.get("id")}
+    index2 = {layer.get("id"): layer for layer in layers2 if layer.get("id")}
+
+    # Find added layers (in layers1 but not layers2)
+    for layer_id, layer in index1.items():
+        if layer_id not in index2:
+            changes.append(LayerChange(
+                layer_id=str(layer_id),
+                layer_title=layer.get("title", "Untitled"),
+                change_type="added",
+            ))
+
+    # Find removed layers (in layers2 but not layers1)
+    for layer_id, layer in index2.items():
+        if layer_id not in index1:
+            changes.append(LayerChange(
+                layer_id=str(layer_id),
+                layer_title=layer.get("title", "Untitled"),
+                change_type="removed",
+            ))
+
+    # Find modified layers (in both but different)
+    for layer_id in index1:
+        if layer_id in index2:
+            layer1 = index1[layer_id]
+            layer2 = index2[layer_id]
+
+            if layer1 != layer2:
+                deep_diff = DeepDiff(layer2, layer1, ignore_order=True)
+                changes.append(LayerChange(
+                    layer_id=str(layer_id),
+                    layer_title=layer1.get("title", "Untitled"),
+                    change_type="modified",
+                    details=deep_diff.to_dict() if deep_diff else {},
+                ))
+
+    return changes
+
+
+def diff_json(
+        obj1: Any,
+        obj2: Any,
+        ignore_order: bool = True,
+) -> dict[str, Any]:
+    """Generic JSON diff using DeepDiff.
+
+    Args:
+        obj1: First object (current state).
+        obj2: Second object (previous state).
+        ignore_order: Whether to ignore list ordering.
+
+    Returns:
+        Dictionary of differences.
+    """
+    deep_diff = DeepDiff(obj2, obj1, ignore_order=ignore_order)
+    return deep_diff.to_dict() if deep_diff else {}
+
+
+# ---- Formatting Functions -----------------------------------------------------------------------------------
+
+
+def format_diff_summary(
+        map_diff: MapDiff,
+) -> str:
+    """Format MapDiff as human-readable summary.
+
+    Args:
+        map_diff: MapDiff object.
+
+    Returns:
+        Formatted string summary.
+    """
+    if not map_diff.has_changes:
+        return "No changes detected."
+
+    lines = []
+
+    if map_diff.added_layers:
+        lines.append(f"Added layers ({len(map_diff.added_layers)}):")
+        for change in map_diff.added_layers:
+            lines.append(f"  + {change.layer_title} ({change.layer_id})")
+
+    if map_diff.removed_layers:
+        lines.append(f"Removed layers ({len(map_diff.removed_layers)}):")
+        for change in map_diff.removed_layers:
+            lines.append(f"  - {change.layer_title} ({change.layer_id})")
+
+    if map_diff.modified_layers:
+        lines.append(f"Modified layers ({len(map_diff.modified_layers)}):")
+        for change in map_diff.modified_layers:
+            lines.append(f"  ~ {change.layer_title} ({change.layer_id})")
+
+    if map_diff.added_tables:
+        lines.append(f"Added tables ({len(map_diff.added_tables)}):")
+        for change in map_diff.added_tables:
+            lines.append(f"  + {change.layer_title} ({change.layer_id})")
+
+    if map_diff.removed_tables:
+        lines.append(f"Removed tables ({len(map_diff.removed_tables)}):")
+        for change in map_diff.removed_tables:
+            lines.append(f"  - {change.layer_title} ({change.layer_id})")
+
+    if map_diff.modified_tables:
+        lines.append(f"Modified tables ({len(map_diff.modified_tables)}):")
+        for change in map_diff.modified_tables:
+            lines.append(f"  ~ {change.layer_title} ({change.layer_id})")
+
+    if map_diff.property_changes:
+        lines.append("Map properties changed:")
+        for key in map_diff.property_changes:
+            lines.append(f"  * {key}")
+
+    return "\n".join(lines)
+
+

gitmap_core/maps.py

@@ -0,0 +1,385 @@
+"""Web map JSON operations module.
+
+Handles extraction, serialization, and staging of ArcGIS web map JSON
+data for version control operations.
+
+Execution Context:
+    Library module - imported by CLI commands and remote operations
+
+Dependencies:
+    - arcgis: Web map item access
+    - gitmap_core.models: Data models
+
+Metadata:
+    Version: 0.1.0
+    Author: GitMap Team
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import Any
+
+if TYPE_CHECKING:
+    from arcgis.gis import GIS
+    from arcgis.gis import Item
+
+
+# ---- Map Extraction Functions -------------------------------------------------------------------------------
+
+
+def get_webmap_json(
+        item: Item,
+) -> dict[str, Any]:
+    """Extract web map JSON from Portal item.
+
+    Args:
+        item: ArcGIS web map item.
+
+    Returns:
+        Web map JSON as dictionary.
+
+    Raises:
+        RuntimeError: If item is not a web map or extraction fails.
+    """
+    try:
+        if item.type != "Web Map":
+            msg = f"Item '{item.title}' is not a Web Map (type: {item.type})"
+            raise RuntimeError(msg)
+
+        # Get the web map data
+        webmap_data = item.get_data()
+
+        if not webmap_data:
+            msg = f"Failed to get data from web map '{item.title}'"
+            raise RuntimeError(msg)
+
+        return webmap_data
+
+    except Exception as extraction_error:
+        if isinstance(extraction_error, RuntimeError):
+            raise
+        msg = f"Failed to extract web map JSON: {extraction_error}"
+        raise RuntimeError(msg) from extraction_error
+
+
+def get_webmap_by_id(
+        gis: GIS,
+        item_id: str,
+) -> tuple[Item, dict[str, Any]]:
+    """Fetch web map item and its JSON by item ID.
+
+    Args:
+        gis: Authenticated GIS connection.
+        item_id: Portal item ID.
+
+    Returns:
+        Tuple of (Item, web map JSON dict).
+
+    Raises:
+        RuntimeError: If item not found or is not a web map.
+    """
+    try:
+        item = gis.content.get(item_id)
+
+        if not item:
+            msg = f"Item with ID '{item_id}' not found"
+            raise RuntimeError(msg)
+
+        webmap_json = get_webmap_json(item)
+        return item, webmap_json
+
+    except Exception as fetch_error:
+        if isinstance(fetch_error, RuntimeError):
+            raise
+        msg = f"Failed to fetch web map {item_id}: {fetch_error}"
+        raise RuntimeError(msg) from fetch_error
+
+
+def list_webmaps(
+        gis: GIS,
+        query: str = "",
+        owner: str = "",
+        tag: str = "",
+        max_results: int = 100,
+) -> list[dict[str, str]]:
+    """List available web maps from the Portal.
+
+    Args:
+        gis: Authenticated GIS connection.
+        query: Optional search query string to filter web maps (e.g., "title:MyMap").
+            Defaults to empty string to list all web maps.
+        owner: Optional owner username to filter web maps.
+        tag: Optional tag to filter web maps.
+        max_results: Maximum number of web maps to return (default: 100).
+
+    Returns:
+        List of dictionaries containing web map information (id, title, owner, type).
+
+    Raises:
+        RuntimeError: If web map search fails.
+    """
+    try:
+        # Build search query components
+        query_parts = ['type:"Web Map"']
+
+        if owner:
+            query_parts.append(f'owner:{owner}')
+
+        if tag:
+            query_parts.append(f'tags:{tag}')
+
+        if query:
+            query_parts.append(query)
+
+        # Combine all query parts with AND
+        search_query = ' AND '.join(query_parts)
+        items = gis.content.search(query=search_query, max_items=max_results)
+
+        result = []
+        for item in items:
+            result.append({
+                "id": getattr(item, "id", ""),
+                "title": getattr(item, "title", ""),
+                "owner": getattr(item, "owner", ""),
+                "type": getattr(item, "type", ""),
+            })
+        return result
+    except Exception as search_error:
+        msg = f"Failed to search web maps: {search_error}"
+        raise RuntimeError(msg) from search_error
+
+
+def list_services(
+        gis: GIS,
+        query: str = "",
+        owner: str = "",
+        service_type: str = "",
+        max_results: int = 100,
+) -> list[dict[str, str]]:
+    """List available services (Feature Services, Map Services, etc.) from the Portal.
+
+    Args:
+        gis: Authenticated GIS connection.
+        query: Optional search query string to filter services.
+        owner: Optional owner username to filter services.
+        service_type: Optional service type filter (e.g., "Feature Service", "Map Service").
+            Defaults to empty string to list Feature Services.
+        max_results: Maximum number of services to return (default: 100).
+
+    Returns:
+        List of dictionaries containing service information (id, title, owner, type, url).
+
+    Raises:
+        RuntimeError: If service search fails.
+    """
+    try:
+        # Build search query components
+        # Default to Feature Service if no type specified
+        if service_type:
+            query_parts = [f'type:"{service_type}"']
+        else:
+            query_parts = ['type:"Feature Service"']
+
+        if owner:
+            query_parts.append(f'owner:{owner}')
+
+        if query:
+            query_parts.append(query)
+
+        # Combine all query parts with AND
+        search_query = ' AND '.join(query_parts)
+        items = gis.content.search(query=search_query, max_items=max_results)
+
+        result = []
+        for item in items:
+            result.append({
+                "id": getattr(item, "id", ""),
+                "title": getattr(item, "title", ""),
+                "owner": getattr(item, "owner", ""),
+                "type": getattr(item, "type", ""),
+                "url": getattr(item, "url", ""),
+            })
+        return result
+    except Exception as search_error:
+        msg = f"Failed to search services: {search_error}"
+        raise RuntimeError(msg) from search_error
+
+
+# ---- Layer Operations ---------------------------------------------------------------------------------------
+
+
+def get_operational_layers(
+        map_data: dict[str, Any],
+) -> list[dict[str, Any]]:
+    """Extract operational layers from web map JSON.
+
+    Args:
+        map_data: Web map JSON dictionary.
+
+    Returns:
+        List of operational layer dictionaries.
+    """
+    return map_data.get("operationalLayers", [])
+
+
+def get_basemap_layers(
+        map_data: dict[str, Any],
+) -> list[dict[str, Any]]:
+    """Extract basemap layers from web map JSON.
+
+    Args:
+        map_data: Web map JSON dictionary.
+
+    Returns:
+        List of basemap layer dictionaries.
+    """
+    basemap = map_data.get("baseMap", {})
+    return basemap.get("baseMapLayers", [])
+
+
+def get_layer_by_id(
+        map_data: dict[str, Any],
+        layer_id: str,
+) -> dict[str, Any] | None:
+    """Find a layer by its ID.
+
+    Args:
+        map_data: Web map JSON dictionary.
+        layer_id: Layer ID to find.
+
+    Returns:
+        Layer dictionary or None if not found.
+    """
+    for layer in get_operational_layers(map_data):
+        if layer.get("id") == layer_id:
+            return layer
+    return None
+
+
+def get_layer_ids(
+        map_data: dict[str, Any],
+) -> list[str]:
+    """Get all operational layer IDs.
+
+    Args:
+        map_data: Web map JSON dictionary.
+
+    Returns:
+        List of layer IDs.
+    """
+    return [
+        layer.get("id", "")
+        for layer in get_operational_layers(map_data)
+        if layer.get("id")
+    ]
+
+
+# ---- Map Comparison Functions -------------------------------------------------------------------------------
+
+
+def compare_layers(
+        layers1: list[dict[str, Any]],
+        layers2: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Compare two lists of layers.
+
+    Args:
+        layers1: First layer list (e.g., from index).
+        layers2: Second layer list (e.g., from commit).
+
+    Returns:
+        Dictionary with added, removed, and modified layer info.
+    """
+    ids1 = {layer.get("id"): layer for layer in layers1 if layer.get("id")}
+    ids2 = {layer.get("id"): layer for layer in layers2 if layer.get("id")}
+
+    added = [ids1[id] for id in ids1 if id not in ids2]
+    removed = [ids2[id] for id in ids2 if id not in ids1]
+    modified = []
+
+    for layer_id in ids1:
+        if layer_id in ids2:
+            if ids1[layer_id] != ids2[layer_id]:
+                modified.append({
+                    "id": layer_id,
+                    "old": ids2[layer_id],
+                    "new": ids1[layer_id],
+                })
+
+    return {
+        "added": added,
+        "removed": removed,
+        "modified": modified,
+    }
+
+
+# ---- Serialization Functions --------------------------------------------------------------------------------
+
+
+def save_map_json(
+        map_data: dict[str, Any],
+        filepath: Path,
+) -> None:
+    """Save web map JSON to file.
+
+    Args:
+        map_data: Web map JSON dictionary.
+        filepath: Path to save file.
+    """
+    filepath.write_text(json.dumps(map_data, indent=2))
+
+
+def load_map_json(
+        filepath: Path,
+) -> dict[str, Any]:
+    """Load web map JSON from file.
+
+    Args:
+        filepath: Path to JSON file.
+
+    Returns:
+        Web map JSON dictionary.
+
+    Raises:
+        RuntimeError: If file cannot be loaded.
+    """
+    try:
+        return json.loads(filepath.read_text())
+    except Exception as load_error:
+        msg = f"Failed to load map JSON from {filepath}: {load_error}"
+        raise RuntimeError(msg) from load_error
+
+
+# ---- Map Creation Functions ---------------------------------------------------------------------------------
+
+
+def create_empty_webmap(
+        title: str = "New Map",
+        spatial_reference: int = 102100,
+) -> dict[str, Any]:
+    """Create an empty web map JSON structure.
+
+    Args:
+        title: Map title.
+        spatial_reference: Spatial reference WKID.
+
+    Returns:
+        Empty web map JSON dictionary.
+    """
+    return {
+        "operationalLayers": [],
+        "baseMap": {
+            "baseMapLayers": [],
+            "title": "Basemap",
+        },
+        "spatialReference": {
+            "wkid": spatial_reference,
+        },
+        "version": "2.28",
+        "authoringApp": "GitMap",
+        "authoringAppVersion": "0.1.0",
+    }
+
+