env-able 0.2.0__py3-none-any.whl

env_able/__init__.py

@@ -0,0 +1,11 @@
+__version__ = "0.2.0"
+
+from .vector import Intersect, Buffer, Clip
+from .morph import morph
+
+
+def main():
+    print(f"env-able | ready (v{__version__})")
+
+
+main()

env_able/morph.py

@@ -0,0 +1,680 @@
+"""
+env_able.morph — universal format translation layer
+
+e.morph(input_path, output_path, **kwargs)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import geopandas as gpd
+import pandas as pd
+import fiona
+
+
+# ── Format registry ──────────────────────────────────────────────────────────
+
+_EXT_TO_FORMAT: Dict[str, str] = {
+    ".shp":     "shp",
+    ".gpkg":    "gpkg",
+    ".gdb":     "gdb",
+    ".csv":     "csv",
+    ".xlsx":    "xlsx",
+    ".xls":     "xls",
+    ".dbf":     "dbf",
+    ".geojson": "geojson",
+    ".json":    "json",
+}
+
+_FORMAT_TO_DRIVER: Dict[str, Optional[str]] = {
+    "shp":     "ESRI Shapefile",
+    "gpkg":    "GPKG",
+    "gdb":     "OpenFileGDB",
+    "csv":     None,
+    "xlsx":    None,
+    "xls":     None,
+    "dbf":     "ESRI Shapefile",
+    "geojson": "GeoJSON",
+    "json":    None,
+}
+
+_SPATIAL_FORMATS     = {"shp", "gpkg", "gdb", "geojson"}
+_TABULAR_FORMATS     = {"csv", "xlsx", "xls", "dbf"}
+_PANDAS_FORMATS      = {"csv", "xlsx", "xls"}
+_MULTI_LAYER_FORMATS = {"gpkg", "gdb"}
+
+_GEOJSON_CRS = "EPSG:4326"
+
+_WKT_COL_NAMES = {"geometry", "geom", "wkt", "shape", "geo", "wkt_geom", "the_geom"}
+_LAT_COL_NAMES = {"lat", "latitude", "y", "ylat", "y_coord", "ycoord", "y_lat"}
+_LON_COL_NAMES = {"lon", "long", "longitude", "x", "xlon", "x_coord", "xcoord", "x_lon"}
+
+
+# ── Utilities ─────────────────────────────────────────────────────────────────
+
+def _sanitize_name(name: str, max_len: int = 255) -> str:
+    name = re.sub(r'[<>:"/\\|?*\x00-\x1f]', "_", name)
+    name = name.strip(". ")
+    return name[:max_len] or "layer"
+
+
+def _safe_shp_fields(columns: List[str]) -> Dict[str, str]:
+    """Produce original → truncated mapping for shapefile 10-char field limit."""
+    seen: Dict[str, int] = {}
+    result: Dict[str, str] = {}
+    for col in columns:
+        safe = re.sub(r"[^A-Za-z0-9_]", "_", col)[:10]
+        if not safe or safe[0].isdigit():
+            safe = ("F_" + safe)[:10]
+        base = safe
+        counter = 0
+        while safe in seen and seen[safe] != col:
+            counter += 1
+            suffix = str(counter)
+            safe = base[: 10 - len(suffix)] + suffix
+        seen[safe] = col
+        if safe != col:
+            result[col] = safe
+    return result
+
+
+def _detect_format(path: Path) -> Optional[str]:
+    return _EXT_TO_FORMAT.get(path.suffix.lower())
+
+
+def _list_fiona_layers(path: Path) -> List[str]:
+    try:
+        return fiona.listlayers(str(path))
+    except Exception:
+        return []
+
+
+def _looks_like_wkt(value: Any) -> bool:
+    if not isinstance(value, str):
+        return False
+    s = value.strip().upper()
+    return any(s.startswith(k) for k in (
+        "POINT", "LINESTRING", "POLYGON", "MULTIPOINT",
+        "MULTILINESTRING", "MULTIPOLYGON", "GEOMETRYCOLLECTION",
+    ))
+
+
+def _looks_like_lat(series: pd.Series) -> bool:
+    try:
+        num = pd.to_numeric(series.dropna(), errors="coerce").dropna()
+        return len(num) > 0 and num.between(-90, 90).all()
+    except Exception:
+        return False
+
+
+def _looks_like_lon(series: pd.Series) -> bool:
+    try:
+        num = pd.to_numeric(series.dropna(), errors="coerce").dropna()
+        return len(num) > 0 and num.between(-180, 180).all()
+    except Exception:
+        return False
+
+
+# ── Smart geometry detection ──────────────────────────────────────────────────
+
+@dataclass
+class _GeomHint:
+    kind: str           # "wkt" | "xy" | "none"
+    wkt_col: Optional[str] = None
+    x_col: Optional[str] = None
+    y_col: Optional[str] = None
+    confidence: str = "low"   # "high" | "medium" | "low"
+
+    @property
+    def found(self) -> bool:
+        return self.kind != "none"
+
+
+def _detect_geometry(df: pd.DataFrame) -> _GeomHint:
+    """
+    Scan a DataFrame for geometry columns without user hints.
+
+    Priority:
+      1. Column name matches known WKT names → confirm by sampling values
+      2. Column name matches known lat/lon names → confirm by value range
+      3. Any column whose values parse as WKT
+      4. Any numeric pair that looks like lat/lon by value range
+    """
+    cols_lower = {c: c.lower().strip() for c in df.columns}
+
+    # ── pass 1: name-based WKT match ─────────────────────────────────────────
+    for col, lower in cols_lower.items():
+        if lower in _WKT_COL_NAMES:
+            sample = df[col].dropna().iloc[0] if not df[col].dropna().empty else None
+            if sample and _looks_like_wkt(sample):
+                return _GeomHint(kind="wkt", wkt_col=col, confidence="high")
+
+    # ── pass 2: name-based lat/lon match ─────────────────────────────────────
+    lat_col = next((c for c, l in cols_lower.items() if l in _LAT_COL_NAMES), None)
+    lon_col = next((c for c, l in cols_lower.items() if l in _LON_COL_NAMES), None)
+    if lat_col and lon_col:
+        return _GeomHint(kind="xy", x_col=lon_col, y_col=lat_col, confidence="high")
+
+    # ── pass 3: value-based WKT scan ─────────────────────────────────────────
+    for col in df.columns:
+        sample = df[col].dropna().iloc[0] if not df[col].dropna().empty else None
+        if sample and _looks_like_wkt(sample):
+            return _GeomHint(kind="wkt", wkt_col=col, confidence="medium")
+
+    # ── pass 4: value-based lat/lon scan ─────────────────────────────────────
+    numeric_cols = df.select_dtypes(include="number").columns.tolist()
+    lat_candidates = [c for c in numeric_cols if _looks_like_lat(df[c])]
+    lon_candidates = [c for c in numeric_cols if _looks_like_lon(df[c])]
+
+    if lat_candidates and lon_candidates:
+        y = lat_candidates[0]
+        x = next((c for c in lon_candidates if c != y), None)
+        if x:
+            return _GeomHint(kind="xy", x_col=x, y_col=y, confidence="medium")
+
+    return _GeomHint(kind="none")
+
+
+# ── InputSpec ─────────────────────────────────────────────────────────────────
+
+@dataclass
+class InputSpec:
+    path: Path
+    format: str
+    driver: Optional[str]
+    is_spatial: bool
+    is_multi_layer: bool
+    layers: List[str]
+    raw_path: str
+
+    @classmethod
+    def from_path(cls, raw: str) -> "InputSpec":
+        path = Path(raw)
+
+        if not path.exists():
+            raise FileNotFoundError(
+                f"env-able | morph: input not found — '{raw}'\n"
+                f"  Check the path and make sure the file or folder exists."
+            )
+
+        fmt = _detect_format(path)
+        if fmt is None:
+            raise ValueError(
+                f"env-able | morph: unrecognised input format for '{raw}'.\n"
+                f"  Supported: shp, gpkg, gdb, csv, xlsx, xls, dbf, geojson, json"
+            )
+
+        driver = _FORMAT_TO_DRIVER.get(fmt)
+        is_spatial = fmt in _SPATIAL_FORMATS
+        is_multi = fmt in _MULTI_LAYER_FORMATS
+
+        layers: List[str] = []
+        if is_multi:
+            layers = _list_fiona_layers(path)
+            if not layers:
+                raise ValueError(
+                    f"env-able | morph: no layers found in '{raw}'.\n"
+                    f"  The file may be empty or corrupted."
+                )
+        else:
+            layers = [path.stem]
+
+        if fmt == "json":
+            is_spatial = _json_is_geojson(path)
+
+        return cls(
+            path=path, format=fmt, driver=driver,
+            is_spatial=is_spatial, is_multi_layer=is_multi,
+            layers=layers, raw_path=raw,
+        )
+
+
+def _json_is_geojson(path: Path) -> bool:
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return isinstance(data, dict) and data.get("type") in (
+            "FeatureCollection", "Feature",
+            "Point", "LineString", "Polygon",
+            "MultiPoint", "MultiLineString", "MultiPolygon",
+        )
+    except Exception:
+        return False
+
+
+# ── OutputSpec ────────────────────────────────────────────────────────────────
+
+@dataclass
+class OutputSpec:
+    path: Path
+    format: str
+    driver: Optional[str]
+    is_spatial: bool
+    is_directory: bool
+    multiple_outputs: bool
+    layer_name: str
+    name: str
+    overwrite: bool = True
+    crs: Optional[str] = None
+    epsg: Optional[int] = None
+    geometry_type: Optional[str] = None
+    has_z: bool = False
+    has_m: bool = False
+    raw_path: str = ""
+
+    @classmethod
+    def from_path(cls, raw: str, inp: InputSpec, **kwargs) -> "OutputSpec":
+        path = Path(raw)
+        is_dir = raw.endswith("/") or raw.endswith("\\") or not path.suffix
+
+        if is_dir:
+            multiple = inp.is_multi_layer or len(inp.layers) > 1
+            return cls(
+                path=path, format="dir", driver=None,
+                is_spatial=inp.is_spatial, is_directory=True,
+                multiple_outputs=multiple, layer_name="", name=path.name,
+                raw_path=raw, crs=kwargs.get("crs"),
+            )
+
+        fmt = _detect_format(path)
+        if fmt is None:
+            raise ValueError(
+                f"env-able | morph: unrecognised output format for '{raw}'.\n"
+                f"  Supported: shp, gpkg, gdb, csv, xlsx, xls, dbf, geojson, json"
+            )
+
+        driver = _FORMAT_TO_DRIVER.get(fmt)
+        is_spatial = fmt in _SPATIAL_FORMATS
+
+        parts = path.stem.split(".")
+        if len(parts) >= 2:
+            name = _sanitize_name(parts[0])
+            layer_name = _sanitize_name(parts[-1])
+        else:
+            name = _sanitize_name(path.stem)
+            layer_name = name
+
+        multiple = (
+            (inp.is_multi_layer or len(inp.layers) > 1)
+            and fmt not in _MULTI_LAYER_FORMATS
+        )
+
+        crs = kwargs.get("crs")
+        if fmt == "geojson" and not crs:
+            crs = _GEOJSON_CRS
+
+        epsg: Optional[int] = None
+        if crs and str(crs).upper().startswith("EPSG:"):
+            try:
+                epsg = int(str(crs).split(":")[1])
+            except ValueError:
+                pass
+
+        return cls(
+            path=path, format=fmt, driver=driver,
+            is_spatial=is_spatial, is_directory=False,
+            multiple_outputs=multiple, layer_name=layer_name, name=name,
+            raw_path=raw, crs=crs, epsg=epsg,
+        )
+
+
+# ── Reader ────────────────────────────────────────────────────────────────────
+
+class _Reader:
+    def __init__(self, spec: InputSpec):
+        self.spec = spec
+
+    def spatial(self, layer: Optional[str] = None) -> gpd.GeoDataFrame:
+        s = self.spec
+        if s.format in {"shp", "dbf"}:
+            return gpd.read_file(str(s.path))
+        if s.format in {"gpkg", "gdb"}:
+            return gpd.read_file(str(s.path), layer=layer)
+        if s.format in {"geojson", "json"}:
+            return gpd.read_file(str(s.path))
+        raise ValueError(f"env-able | morph: cannot read '{s.format}' as spatial.")
+
+    def tabular(self) -> pd.DataFrame:
+        s = self.spec
+        if s.format == "csv":
+            return pd.read_csv(str(s.path))
+        if s.format == "xlsx":
+            return pd.read_excel(str(s.path), engine="openpyxl")
+        if s.format == "xls":
+            return pd.read_excel(str(s.path), engine="xlrd")
+        if s.format == "dbf":
+            try:
+                import dbfread
+                return pd.DataFrame(iter(dbfread.DBF(str(s.path))))
+            except ImportError:
+                gdf = gpd.read_file(str(s.path))
+                return pd.DataFrame(gdf.drop(columns="geometry", errors="ignore"))
+        if s.format == "json":
+            return pd.read_json(str(s.path))
+        raise ValueError(f"env-able | morph: cannot read '{s.format}' as tabular.")
+
+
+# ── Writer ────────────────────────────────────────────────────────────────────
+
+class _Writer:
+    def __init__(self, spec: OutputSpec):
+        self.spec = spec
+
+    def _ensure_dir(self, path: Path):
+        path.mkdir(parents=True, exist_ok=True)
+
+    def _apply_crs(self, gdf: gpd.GeoDataFrame, fmt: Optional[str] = None) -> gpd.GeoDataFrame:
+        target_crs = self.spec.crs
+        if fmt == "geojson":
+            target_crs = _GEOJSON_CRS
+        if not target_crs:
+            return gdf
+        if gdf.crs is None:
+            return gdf.set_crs(target_crs)
+        if str(gdf.crs) != str(target_crs):
+            return gdf.to_crs(target_crs)
+        return gdf
+
+    def _fix_shp_fields(self, gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame:
+        non_geom = [c for c in gdf.columns if c != "geometry"]
+        renames = _safe_shp_fields(non_geom)
+        if renames:
+            warnings.warn(
+                "env-able | morph: shapefile field names truncated to 10 chars:\n"
+                + "\n".join(f"  '{k}' → '{v}'" for k, v in renames.items()),
+                UserWarning, stacklevel=5,
+            )
+            gdf = gdf.rename(columns=renames)
+        return gdf
+
+    def spatial(self, gdf: gpd.GeoDataFrame, dest: Path, layer: str):
+        fmt = _detect_format(dest) if self.spec.is_directory else self.spec.format
+        gdf = self._apply_crs(gdf, fmt)
+        self._ensure_dir(dest.parent)
+
+        if fmt == "shp":
+            gdf = self._fix_shp_fields(gdf)
+            gdf.to_file(str(dest), driver="ESRI Shapefile")
+
+        elif fmt == "gpkg":
+            gdf.to_file(str(dest), layer=layer, driver="GPKG")
+
+        elif fmt == "gdb":
+            try:
+                gdf.to_file(str(dest), layer=layer, driver="OpenFileGDB")
+            except Exception as e:
+                raise IOError(
+                    f"env-able | morph: GDB write failed for '{dest}'.\n"
+                    f"  Your GDAL build may not support GDB creation.\n"
+                    f"  Try outputting to GPKG instead.\n"
+                    f"  Original error: {e}"
+                )
+
+        elif fmt in {"geojson", "json"}:
+            gdf.to_file(str(dest), driver="GeoJSON")
+
+        else:
+            raise ValueError(
+                f"env-able | morph: cannot write spatial data to '{fmt}'.\n"
+                f"  Spatial output formats: shp, gpkg, gdb, geojson, json"
+            )
+
+    def tabular(self, df: pd.DataFrame, dest: Path):
+        fmt = _detect_format(dest) if self.spec.is_directory else self.spec.format
+        self._ensure_dir(dest.parent)
+
+        if fmt == "csv":
+            df.to_csv(str(dest), index=False)
+        elif fmt == "xlsx":
+            df.to_excel(str(dest), index=False, engine="openpyxl")
+        elif fmt == "xls":
+            warnings.warn(
+                "env-able | morph: .xls is a legacy format — consider .xlsx.",
+                UserWarning, stacklevel=5,
+            )
+            df.to_excel(str(dest), index=False)
+        elif fmt in {"json", "geojson"}:
+            df.to_json(str(dest), orient="records", indent=2)
+        elif fmt == "dbf":
+            raise NotImplementedError(
+                "env-able | morph: writing standalone .dbf is not supported.\n"
+                "  Try CSV or XLSX instead."
+            )
+        else:
+            raise ValueError(f"env-able | morph: cannot write tabular data to '{fmt}'.")
+
+
+# ── MorphEngine ───────────────────────────────────────────────────────────────
+
+class MorphEngine:
+    def __init__(self, inp: InputSpec, out: OutputSpec, kwargs: Dict[str, Any]):
+        self.inp = inp
+        self.out = out
+        self.kwargs = kwargs
+        self.reader = _Reader(inp)
+        self.writer = _Writer(out)
+
+    def _resolve_output(self, layer: str) -> Tuple[Path, str]:
+        out = self.out
+        safe = _sanitize_name(layer)
+
+        if out.is_directory:
+            ext = ".gpkg" if self.inp.is_spatial else ".csv"
+            return out.path / f"{safe}{ext}", safe
+
+        if out.format in _MULTI_LAYER_FORMATS:
+            return out.path, safe
+
+        if out.multiple_outputs:
+            return out.path.parent / f"{safe}{out.path.suffix}", safe
+
+        return out.path, out.layer_name or safe
+
+    def _build_geometry(self, df: pd.DataFrame) -> gpd.GeoDataFrame:
+        x_col   = self.kwargs.get("x_col")
+        y_col   = self.kwargs.get("y_col")
+        wkt_col = self.kwargs.get("wkt_col")
+        crs     = self.kwargs.get("crs") or self.out.crs
+
+        if wkt_col or (x_col and y_col):
+            return self._build_from_explicit(df, x_col, y_col, wkt_col, crs)
+
+        hint = _detect_geometry(df)
+
+        if not hint.found:
+            raise ValueError(
+                "env-able | morph: could not find geometry columns in the source data.\n"
+                "  Scanned for common WKT and lat/lon column names — none matched.\n"
+                "  Provide explicit columns:\n"
+                "    e.morph(..., x_col='LON', y_col='LAT', crs='EPSG:4326')\n"
+                "    e.morph(..., wkt_col='GEOMETRY', crs='EPSG:4326')"
+            )
+
+        confidence_note = "" if hint.confidence == "high" else (
+            f"\n  Confidence: {hint.confidence} — verify the output looks correct."
+        )
+
+        if hint.kind == "wkt":
+            print(f"env-able | morph: auto-detected WKT column '{hint.wkt_col}'.{confidence_note}")
+            return self._build_from_explicit(df, None, None, hint.wkt_col, crs)
+
+        if hint.kind == "xy":
+            print(
+                f"env-able | morph: auto-detected coordinate columns "
+                f"x='{hint.x_col}' y='{hint.y_col}'.{confidence_note}"
+            )
+            return self._build_from_explicit(df, hint.x_col, hint.y_col, None, crs)
+
+        raise ValueError("env-able | morph: geometry detection failed unexpectedly.")
+
+    def _build_from_explicit(
+        self,
+        df: pd.DataFrame,
+        x_col: Optional[str],
+        y_col: Optional[str],
+        wkt_col: Optional[str],
+        crs: Optional[str],
+    ) -> gpd.GeoDataFrame:
+        if wkt_col:
+            if wkt_col not in df.columns:
+                raise ValueError(
+                    f"env-able | morph: wkt_col '{wkt_col}' not found.\n"
+                    f"  Available columns: {list(df.columns)}"
+                )
+            from shapely import wkt as swkt
+            gdf = gpd.GeoDataFrame(df, geometry=df[wkt_col].apply(swkt.loads))
+
+        elif x_col and y_col:
+            for col in (x_col, y_col):
+                if col not in df.columns:
+                    raise ValueError(
+                        f"env-able | morph: column '{col}' not found.\n"
+                        f"  Available columns: {list(df.columns)}"
+                    )
+            gdf = gpd.GeoDataFrame(
+                df, geometry=gpd.points_from_xy(df[x_col], df[y_col])
+            )
+        else:
+            raise ValueError(
+                "env-able | morph: provide x_col + y_col or wkt_col to build geometry."
+            )
+
+        if not crs:
+            raise ValueError(
+                "env-able | morph: crs is required when building geometry from tabular data.\n"
+                "  Example: e.morph('data.csv', 'data.shp', crs='EPSG:4326')\n"
+                "  If you're not sure, EPSG:4326 (WGS84) is a safe starting point for lat/lon data."
+            )
+
+        return gdf.set_crs(crs)
+
+    def run(self) -> List[str]:
+        inp, out = self.inp, self.out
+        outputs: List[str] = []
+
+        # tabular → tabular
+        if inp.format in _TABULAR_FORMATS and out.format in _TABULAR_FORMATS | {"json"}:
+            df = self.reader.tabular()
+            dest, _ = self._resolve_output(inp.path.stem)
+            self.writer.tabular(df, dest)
+            print(f"env-able | morph: {inp.raw_path} → {dest} ({len(df)} rows)")
+            return [str(dest)]
+
+        # tabular → spatial
+        if inp.format in _TABULAR_FORMATS and (out.format in _SPATIAL_FORMATS or out.is_directory):
+            df = self.reader.tabular()
+            gdf = self._build_geometry(df)
+            dest, layer = self._resolve_output(out.layer_name or inp.path.stem)
+            self.writer.spatial(gdf, dest, layer)
+            print(f"env-able | morph: {inp.raw_path} → {dest} ({len(gdf)} features, {gdf.crs})")
+            return [str(dest)]
+
+        # JSON → depends on content
+        if inp.format == "json":
+            if inp.is_spatial:
+                gdf = self.reader.spatial()
+                dest, layer = self._resolve_output(inp.path.stem)
+                self.writer.spatial(gdf, dest, layer)
+                print(f"env-able | morph: {inp.raw_path} → {dest} ({len(gdf)} features)")
+            else:
+                df = self.reader.tabular()
+                if out.format in _SPATIAL_FORMATS or out.is_directory:
+                    gdf = self._build_geometry(df)
+                    dest, layer = self._resolve_output(inp.path.stem)
+                    self.writer.spatial(gdf, dest, layer)
+                    print(f"env-able | morph: {inp.raw_path} → {dest} ({len(gdf)} features)")
+                else:
+                    dest, _ = self._resolve_output(inp.path.stem)
+                    self.writer.tabular(df, dest)
+                    print(f"env-able | morph: {inp.raw_path} → {dest} ({len(df)} rows)")
+            return [str(dest)]
+
+        # spatial → tabular (geometry dropped)
+        if inp.is_spatial and out.format in _TABULAR_FORMATS | {"json"}:
+            layer = inp.layers[0] if inp.layers else None
+            gdf = self.reader.spatial(layer)
+            df = pd.DataFrame(gdf.drop(columns="geometry", errors="ignore"))
+            if inp.is_multi_layer and len(inp.layers) > 1:
+                warnings.warn(
+                    f"env-able | morph: source has {len(inp.layers)} layers but "
+                    f"'{out.format}' is single-table. Only '{layer}' was exported.\n"
+                    f"  Use a directory output (trailing slash) to export all layers.",
+                    UserWarning, stacklevel=3,
+                )
+            self.writer.tabular(df, out.path)
+            print(f"env-able | morph: {inp.raw_path} → {out.path} ({len(df)} rows, geometry dropped)")
+            return [str(out.path)]
+
+        # spatial → spatial
+        if inp.is_spatial and (out.format in _SPATIAL_FORMATS or out.is_directory):
+            layers = inp.layers if inp.layers else [None]
+
+            for layer in layers:
+                gdf = self.reader.spatial(layer)
+
+                if gdf.empty:
+                    warnings.warn(
+                        f"env-able | morph: layer '{layer}' has no features — skipping.",
+                        UserWarning, stacklevel=3,
+                    )
+                    continue
+
+                dest, out_layer = self._resolve_output(layer or inp.path.stem)
+                self.writer.spatial(gdf, dest, out_layer)
+                outputs.append(str(dest))
+                print(f"env-able | morph: [{layer}] → {dest} ({len(gdf)} features, {gdf.crs})")
+
+            return outputs
+
+        raise ValueError(
+            f"env-able | morph: no conversion path from '{inp.format}' to '{out.format}'.\n"
+            f"  This combination may not be supported yet."
+        )
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+def morph(input_path: str, output_path: str, **kwargs) -> List[str]:
+    """
+    Intelligently convert one spatial or tabular data source to another.
+
+    Supported formats: shp, gpkg, gdb, csv, xlsx, xls, dbf, geojson, json
+
+    Parameters
+    ----------
+    input_path : str
+        Path to the source file or geodatabase.
+    output_path : str
+        Desired output path. Extension determines the format.
+        Trailing slash → directory output (one file per layer).
+        Dot notation → named layer: "roads.parcels.gpkg"
+    **kwargs
+        x_col   : str  — X/longitude column (auto-detected if not provided)
+        y_col   : str  — Y/latitude column  (auto-detected if not provided)
+        wkt_col : str  — WKT geometry column (auto-detected if not provided)
+        crs     : str  — coordinate system e.g. 'EPSG:4326' (required for tabular → spatial)
+
+    Returns
+    -------
+    list[str] — output file paths written
+
+    Examples
+    --------
+    e.morph("roads.shp", "roads.gpkg")
+    e.morph("county.gdb", "county.gpkg")
+    e.morph("county.gdb", "output_folder/")
+    e.morph("data.csv", "data.geojson", crs="EPSG:4326")
+    e.morph("data.csv", "data.shp", x_col="LON", y_col="LAT", crs="EPSG:4269")
+    e.morph("roads.gpkg", "roads.parcels.gpkg")
+    e.morph("data.json", "data.gpkg")
+    """
+    inp = InputSpec.from_path(input_path)
+    out = OutputSpec.from_path(output_path, inp, **kwargs)
+    engine = MorphEngine(inp, out, kwargs)
+    return engine.run()

env_able/vector.py

@@ -0,0 +1,308 @@
+import os
+import geopandas as gpd
+from shapely.validation import make_valid
+
+# Unit conversion to meters
+_UNITS = {
+    "meters":       1.0,
+    "metres":       1.0,
+    "m":            1.0,
+    "kilometers":   1000.0,
+    "kilometres":   1000.0,
+    "km":           1000.0,
+    "miles":        1609.344,
+    "mi":           1609.344,
+    "feet":         0.3048,
+    "ft":           0.3048,
+    "usfeet":       0.30480060960121924,
+    "us_feet":      0.30480060960121924,
+    "us feet":      0.30480060960121924,
+    "nautical miles": 1852.0,
+    "nm":           1852.0,
+}
+
+
+def _load(item, label):
+    if isinstance(item, gpd.GeoDataFrame):
+        return item
+    if not os.path.exists(item):
+        raise FileNotFoundError(
+            f"env-able | {label}: file not found — '{item}'\n"
+            f"  Check the path and make sure the file exists."
+        )
+    try:
+        gdf = gpd.read_file(item)
+    except Exception as e:
+        raise ValueError(
+            f"env-able | {label}: could not read '{item}'\n"
+            f"  Is it a valid shapefile, GeoPackage, or GeoJSON?\n"
+            f"  Original error: {e}"
+        )
+    if gdf.empty:
+        raise ValueError(
+            f"env-able | {label}: '{item}' loaded but contains no features."
+        )
+    return gdf
+
+
+def _fix_geometries(gdf, label):
+    invalid = ~gdf.geometry.is_valid
+    if invalid.any():
+        count = invalid.sum()
+        print(f"env-able | warning | {label}: {count} invalid geometry(s) found — auto-fixing.")
+        gdf = gdf.copy()
+        gdf.geometry = gdf.geometry.apply(lambda g: make_valid(g) if not g.is_valid else g)
+    return gdf
+
+
+def _check_overlap(gdf1, gdf2):
+    b1 = gdf1.total_bounds
+    b2 = gdf2.total_bounds
+    if b1[2] < b2[0] or b1[0] > b2[2] or b1[3] < b2[1] or b1[1] > b2[3]:
+        raise ValueError(
+            f"env-able | intersect: layers do not spatially overlap.\n"
+            f"  Layer 1 extent: {b1}\n"
+            f"  Layer 2 extent: {b2}\n"
+            f"  Make sure both layers cover the same geographic area."
+        )
+
+
+def Intersect(input_layer, intersect_layer, output=None):
+    """
+    Computes geometric intersection of input features against a polygon layer.
+
+    Parameters
+    ----------
+    input_layer : str or GeoDataFrame
+        Point, line, or polygon layer to intersect.
+    intersect_layer : str or GeoDataFrame
+        Polygon layer to intersect against. Must be polygon geometry.
+    output : str, optional
+        File path to write the result (e.g. "result.gpkg", "result.shp").
+        If None, returns a GeoDataFrame.
+
+    Returns
+    -------
+    GeoDataFrame clipped to the intersection.
+    """
+
+    input_layer = _load(input_layer, "input_layer")
+    intersect_layer = _load(intersect_layer, "intersect_layer")
+
+    # CRS checks
+    for label, lyr in [("input_layer", input_layer), ("intersect_layer", intersect_layer)]:
+        if lyr.crs is None:
+            raise ValueError(
+                f"env-able | Intersect: {label} has no CRS defined.\n"
+                f"  Set a CRS before running Intersect.\n"
+                f"  Example: gdf = gdf.set_crs('EPSG:4326')"
+            )
+
+    # intersect layer must be polygon
+    intersect_types = set(intersect_layer.geometry.geom_type.unique())
+    if not intersect_types.issubset({"Polygon", "MultiPolygon"}):
+        raise ValueError(
+            f"env-able | Intersect: intersect_layer must be polygon geometry.\n"
+            f"  Got: {intersect_types}\n"
+            f"  The intersect layer defines the boundary — it must be a polygon."
+        )
+
+    # reproject intersect layer to match input if needed
+    if intersect_layer.crs != input_layer.crs:
+        print(
+            f"env-able | warning | Intersect: CRS mismatch detected.\n"
+            f"  input_layer CRS     : {input_layer.crs}\n"
+            f"  intersect_layer CRS : {intersect_layer.crs}\n"
+            f"  Auto-reprojecting intersect_layer to match input."
+        )
+        intersect_layer = intersect_layer.to_crs(input_layer.crs)
+
+    # fix invalid geometries
+    input_layer = _fix_geometries(input_layer, "input_layer")
+    intersect_layer = _fix_geometries(intersect_layer, "intersect_layer")
+
+    # overlap check
+    _check_overlap(input_layer, intersect_layer)
+
+    # run intersect
+    result = gpd.overlay(input_layer, intersect_layer, how="intersection", keep_geom_type=True)
+
+    if result.empty:
+        print(
+            "env-able | warning | Intersect returned no features.\n"
+            "  The layers overlap spatially but share no coincident features.\n"
+            "  Check your data — this is often a CRS or snapping issue."
+        )
+        return result
+
+    # write output
+    if output:
+        try:
+            result.to_file(output)
+            print(f"env-able | Intersect: result written to '{output}' ({len(result)} features).")
+        except Exception as e:
+            raise IOError(
+                f"env-able | Intersect: could not write to '{output}'\n"
+                f"  Original error: {e}"
+            )
+    else:
+        print(f"env-able | Intersect: complete — {len(result)} features returned.")
+
+    return result
+
+
+def Buffer(input_layer, distance, unit="meters", output=None):
+    """
+    Buffers input features by a given distance and unit.
+
+    Parameters
+    ----------
+    input_layer : str or GeoDataFrame
+        File path or GeoDataFrame to buffer.
+    distance : float
+        Buffer distance.
+    unit : str
+        Unit of distance. Options:
+            meters / m, kilometers / km, miles / mi,
+            feet / ft, usfeet / us_feet, nautical miles / nm
+    output : str, optional
+        File path to write the result. If None, returns a GeoDataFrame.
+
+    Returns
+    -------
+    GeoDataFrame with buffered geometries.
+    """
+
+    gdf = _load(input_layer, "input")
+
+    if gdf.crs is None:
+        raise ValueError(
+            "env-able | Buffer: input layer has no CRS defined.\n"
+            "  Set a CRS before buffering.\n"
+            "  Example: gdf = gdf.set_crs('EPSG:4326')"
+        )
+
+    unit_key = unit.lower().strip()
+    if unit_key not in _UNITS:
+        raise ValueError(
+            f"env-able | Buffer: unrecognised unit '{unit}'.\n"
+            f"  Valid options: {', '.join(sorted(set(_UNITS.keys())))}"
+        )
+
+    distance_m = distance * _UNITS[unit_key]
+
+    gdf = _fix_geometries(gdf, "input")
+
+    # if geographic CRS (degrees), reproject to a metre-based CRS for buffering
+    if gdf.crs.is_geographic:
+        print(
+            f"env-able | warning | Buffer: input CRS is geographic ({gdf.crs}).\n"
+            f"  Reprojecting to EPSG:3857 (Web Mercator) for accurate distance buffering.\n"
+            f"  Result will be returned in EPSG:3857."
+        )
+        gdf = gdf.to_crs("EPSG:3857")
+        buffer_distance = distance_m
+    else:
+        # convert distance_m to the CRS native unit
+        crs_unit = gdf.crs.axis_info[0].unit_name.lower()
+        if "foot" in crs_unit or "feet" in crs_unit:
+            buffer_distance = distance_m / 0.3048
+        else:
+            buffer_distance = distance_m  # assume metres
+
+    result = gdf.copy()
+    result.geometry = gdf.geometry.buffer(buffer_distance)
+
+    print(f"env-able | Buffer: complete — {len(result)} features buffered by {distance} {unit}.")
+
+    if output:
+        try:
+            result.to_file(output)
+            print(f"env-able | Buffer: result written to '{output}'.")
+        except Exception as e:
+            raise IOError(
+                f"env-able | Buffer: could not write to '{output}'\n"
+                f"  Original error: {e}"
+            )
+
+    return result
+
+
+def Clip(input_layer, clip_layer, output=None):
+    """
+    Clips input features to the extent of a polygon clip layer.
+
+    Parameters
+    ----------
+    input_layer : str or GeoDataFrame
+        Features to clip (point, line, or polygon).
+    clip_layer : str or GeoDataFrame
+        Polygon layer defining the clip boundary.
+    output : str, optional
+        File path to write the result. If None, returns a GeoDataFrame.
+
+    Returns
+    -------
+    GeoDataFrame clipped to the clip boundary.
+    """
+
+    gdf = _load(input_layer, "input")
+    clip = _load(clip_layer, "clip")
+
+    # CRS checks
+    for i, lyr in enumerate([gdf, clip]):
+        if lyr.crs is None:
+            raise ValueError(
+                f"env-able | Clip: input[{i}] has no CRS defined.\n"
+                f"  Set a CRS before clipping.\n"
+                f"  Example: gdf = gdf.set_crs('EPSG:4326')"
+            )
+
+    # clip layer must be polygon
+    clip_types = set(clip.geometry.geom_type.unique())
+    if not clip_types.issubset({"Polygon", "MultiPolygon"}):
+        raise ValueError(
+            f"env-able | Clip: clip layer must be polygon geometry.\n"
+            f"  Got: {clip_types}\n"
+            f"  The clip boundary must be a polygon."
+        )
+
+    # reproject clip to match input if needed
+    if clip.crs != gdf.crs:
+        print(
+            f"env-able | warning | Clip: CRS mismatch detected.\n"
+            f"  Input CRS : {gdf.crs}\n"
+            f"  Clip CRS  : {clip.crs}\n"
+            f"  Auto-reprojecting clip layer to match input."
+        )
+        clip = clip.to_crs(gdf.crs)
+
+    # fix geometries
+    gdf = _fix_geometries(gdf, "input")
+    clip = _fix_geometries(clip, "clip")
+
+    # overlap check
+    _check_overlap(gdf, clip)
+
+    result = gdf.clip(clip)
+
+    if result.empty:
+        print(
+            "env-able | warning | Clip returned no features.\n"
+            "  The layers overlap spatially but no features fell within the clip boundary."
+        )
+        return result
+
+    print(f"env-able | Clip: complete — {len(result)} features returned.")
+
+    if output:
+        try:
+            result.to_file(output)
+            print(f"env-able | Clip: result written to '{output}'.")
+        except Exception as e:
+            raise IOError(
+                f"env-able | Clip: could not write to '{output}'\n"
+                f"  Original error: {e}"
+            )
+
+    return result

env_able-0.2.0.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: env-able
+Version: 0.2.0
+Summary: AI-ready GIS toolkit for energy and subsurface workflows.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: fiona
+Requires-Dist: geopandas
+Requires-Dist: openpyxl
+Requires-Dist: xlrd
+Description-Content-Type: text/markdown
+
+# env-able
+
+An open source spatial analysis library built for AI-driven GIS workflows. Designed to give AI systems like Claude reliable, hallucination-free tools for spatial operations in energy and subsurface contexts.
+
+## Install
+
+```bash
+pip install env-able
+```
+
+## Functions
+
+### `e.Intersect(input_layer, intersect_layer, output=None)`
+Computes geometric intersection of input features against a polygon boundary.
+- `input_layer` — point, line, or polygon (file path or GeoDataFrame)
+- `intersect_layer` — polygon layer defining the intersection boundary
+- `output` — file path to save result (`.gpkg`, `.shp`, etc.) — omit to return a GeoDataFrame
+
+```python
+import env_able as e
+e.Intersect("wells.shp", "boundary.shp", "result.gpkg")
+```
+
+---
+
+### `e.Buffer(input_layer, distance, unit="meters", output=None)`
+Buffers input features by a given distance and unit.
+- `input_layer` — point, line, or polygon (file path or GeoDataFrame)
+- `distance` — numeric buffer distance
+- `unit` — `meters`, `km`, `miles`, `feet`, `usfeet`, `nautical miles`
+- `output` — file path to save result — omit to return a GeoDataFrame
+
+```python
+e.Buffer("wells.shp", 1, "miles", "wells_buffer.gpkg")
+```
+
+---
+
+### `e.Clip(input_layer, clip_layer, output=None)`
+Clips input features to the extent of a polygon clip boundary.
+- `input_layer` — point, line, or polygon (file path or GeoDataFrame)
+- `clip_layer` — polygon layer defining the clip boundary
+- `output` — file path to save result — omit to return a GeoDataFrame
+
+```python
+e.Clip("roads.shp", "county.shp", "roads_clipped.gpkg")
+```
+
+---
+
+### `e.morph(input_path, output_path, **kwargs)`
+Universal format translation. Converts between shp, gpkg, gdb, csv, xlsx, xls, dbf, geojson, json with automatic CRS handling, field name fixes, and multi-layer support.
+
+- `input_path` — source file or geodatabase
+- `output_path` — destination file. Extension sets the format. Use trailing `/` for directory output (one file per layer). Use dot notation for named layers: `roads.parcels.gpkg`
+- `x_col`, `y_col` — column names for X/Y coordinates (auto-detected if not provided)
+- `wkt_col` — column containing WKT geometry (auto-detected if not provided)
+- `crs` — coordinate reference system e.g. `EPSG:4326` (required for tabular → spatial)
+
+```python
+e.morph("roads.shp", "roads.gpkg")
+e.morph("county.gdb", "county.gpkg")
+e.morph("county.gdb", "output_folder/")
+e.morph("owners.csv", "owners.geojson", crs="EPSG:4269")
+e.morph("owners.csv", "owners.shp", x_col="LONGITUDE", y_col="LATITUDE", crs="EPSG:4269")
+e.morph("roads.gpkg", "roads.parcels.gpkg")
+e.morph("data.json", "data.gpkg")
+```
+
+**Smart behavior:**
+- GDB / GPKG with multiple layers → detects all layers automatically
+- CRS mismatch → auto-reprojects
+- Shapefile field name limit (10 chars) → auto-truncates with warnings
+- Invalid output path → plain English error
+- Empty layers → skipped with a warning, not a crash
+
+---
+
+## Changelog
+
+### v0.1.0 — 2026-07-14
+- Initial release of env-able
+- `Intersect()`, `Buffer()`, `Clip()` with full guardrails
+- `morph()` — universal format translation
+- Smart geometry detection for WKT and lat/lon columns
+- GeoJSON, JSON support with auto WGS84 reprojection
+- Multi-layer GDB/GPKG support

env_able-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+env_able/__init__.py,sha256=N1WtPOLeqkeCKlFujncOFoZCHqjnhBkqn--yi1nU7Hg,174
+env_able/morph.py,sha256=jJbsgAHxdLYt_I5JWC26jybSVIuJ0LAyCnKqUmjtY1s,25964
+env_able/vector.py,sha256=EMHfwqkQKJGvqGxtL5U8iPBdWa0SbbhJo4rGK9f7yBg,10053
+env_able-0.2.0.dist-info/METADATA,sha256=cbhMfSMmzUG3IBeycs_-auDrlKgfNEOlyeIOpA6p0f0,3599
+env_able-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+env_able-0.2.0.dist-info/licenses/LICENSE,sha256=fe2sDjqFxN-_mnF9irpbjuM_YUKEUS_iJCYEU9JpD5w,1065
+env_able-0.2.0.dist-info/RECORD,,

env_able-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

env_able-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 env-able
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.