netload 0.1.0__py3-none-any.whl

netload/__init__.py

@@ -0,0 +1,68 @@
+"""netload: a lightweight parser for PTV Visum ``.net`` files."""
+
+from __future__ import annotations
+
+from .exceptions import (
+    VisumNetEncodingError,
+    VisumNetError,
+    VisumNetParseError,
+)
+from .network import Network
+from .parser import parse_net, parse_net_with_encoding
+from .table import Table
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Network",
+    "Table",
+    "VisumNetEncodingError",
+    "VisumNetError",
+    "VisumNetParseError",
+    "parse_net",
+    "read_net",
+]
+
+
+def read_net(
+    path: str,
+    encoding: str | None = None,
+    sep: str = ";",
+    infer_types: bool = False,
+) -> Network:
+    """Read a PTV Visum ``.net`` file and return a :class:`Network`.
+
+    Parameters
+    ----------
+    path:
+        Path of the ``.net`` file.
+    encoding:
+        Optional explicit encoding. When omitted, the encoding is detected
+        automatically (BOM, then UTF-8, then Windows-1251).
+    sep:
+        Field separator used inside tables (default ``";"``).
+    infer_types:
+        When ``True``, apply a light numeric type inference on every column.
+        The default preserves the original string values.
+
+    Returns
+    -------
+    A :class:`Network` exposing every parsed table as a
+    ``pandas.DataFrame``.
+
+    Raises
+    ------
+    FileNotFoundError
+        If ``path`` does not exist.
+    netload.exceptions.VisumNetEncodingError
+        If the file cannot be decoded.
+    netload.exceptions.VisumNetParseError
+        If the file structure is invalid.
+    """
+    tables, resolved_encoding = parse_net_with_encoding(
+        path,
+        encoding=encoding,
+        sep=sep,
+        infer_types=infer_types,
+    )
+    return Network(tables, source=path, encoding=resolved_encoding)

netload/cli.py

@@ -0,0 +1,182 @@
+"""Command line interface for :mod:`netload`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="netload",
+        description=(
+            "Read and transform any PTV Visum/Simetra .net network file "
+            "into CSV, JSON or GeoJSON."
+        ),
+    )
+    parser.add_argument("input", help="Path to the .net file")
+    parser.add_argument(
+        "--list-tables",
+        action="store_true",
+        help="List the parsed tables with their fields (columns)",
+    )
+    parser.add_argument(
+        "--export-csv",
+        metavar="DIR",
+        help="Export every table to CSV files inside DIR",
+    )
+    parser.add_argument(
+        "--export-json",
+        metavar="DIR",
+        help="Export every table to JSON files inside DIR",
+    )
+    parser.add_argument(
+        "--export-geojson",
+        metavar="DIR",
+        help="Export tables with geometry to GeoJSON files inside DIR",
+    )
+    parser.add_argument(
+        "--tables",
+        metavar="NAME[,NAME...]",
+        help=(
+            "Limit the export to specific tables (comma-separated, e.g. "
+            "NODE,LINK). Default: all tables."
+        ),
+    )
+    parser.add_argument(
+        "--table",
+        metavar="NAME",
+        help="Select a single table to transform (used with --to-*)",
+    )
+    parser.add_argument(
+        "--to-csv",
+        metavar="FILE",
+        help="Write the selected table to a CSV file",
+    )
+    parser.add_argument(
+        "--to-json",
+        metavar="FILE",
+        help="Write the selected table to a JSON file",
+    )
+    parser.add_argument(
+        "--to-geojson",
+        metavar="FILE",
+        help="Write the selected table to a GeoJSON file",
+    )
+    parser.add_argument(
+        "--sep",
+        default=";",
+        help="Field separator used by the file and CSV export (default: ';')",
+    )
+    parser.add_argument(
+        "--encoding",
+        default=None,
+        help="Force a file encoding (default: auto-detect)",
+    )
+    return parser
+
+
+def _print_summary(tables: dict) -> None:
+    print("Visum network loaded successfully")
+    print()
+    print("Tables:")
+    for name, table in tables.items():
+        print(f"- {name}: {len(table.df)} rows")
+
+
+def _print_tables_with_fields(tables: dict) -> None:
+    print("Visum network loaded successfully")
+    print()
+    print("Tables and fields:")
+    for name, table in tables.items():
+        fields = ", ".join(table.df.columns) or "(no columns)"
+        print(f"- {name}: {len(table.df)} rows")
+        print(f"    fields: {fields}")
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    from .parser import parse_net
+
+    try:
+        tables = parse_net(args.input, encoding=args.encoding, sep=args.sep)
+    except FileNotFoundError:
+        print(f"error: file not found: {args.input}", file=sys.stderr)
+        return 2
+
+    from .network import Network
+
+    network = Network(tables, source=args.input, encoding="")
+
+    if args.table is not None:
+        return _transform_single_table(network, args)
+
+    if args.list_tables:
+        _print_tables_with_fields(network.tables)
+    else:
+        _print_summary(network.tables)
+
+    written = []
+    selected = None
+    if args.tables:
+        selected = [name.strip() for name in args.tables.split(",") if name.strip()]
+
+    if args.export_csv:
+        written += network.export_csv(args.export_csv, sep=args.sep, tables=selected)
+        print(f"\nExported {len(written)} CSV files to {args.export_csv}")
+    if args.export_json:
+        written += network.export_json(args.export_json, tables=selected)
+        print(f"\nExported {len(written)} JSON files to {args.export_json}")
+    if args.export_geojson:
+        written += network.export_geojson(args.export_geojson, tables=selected)
+        print(f"\nExported {len(written)} GeoJSON files to {args.export_geojson}")
+
+    return 0
+
+
+def _transform_single_table(network: Network, args: argparse.Namespace) -> int:
+    from .exceptions import VisumNetError
+    from .exporters import export_table_csv, export_table_geojson, export_table_json
+
+    if args.table not in network:
+        print(
+            f"error: table {args.table!r} not found. Available: "
+            f"{', '.join(network.table_names)}",
+            file=sys.stderr,
+        )
+        return 2
+
+    targets = [
+        flag
+        for flag in ("to_csv", "to_json", "to_geojson")
+        if getattr(args, flag) is not None
+    ]
+    if not targets:
+        print("error: --table requires at least one of --to-csv/--to-json/--to-geojson",
+              file=sys.stderr)
+        return 2
+
+    df = network[args.table]
+    for flag in targets:
+        path = getattr(args, flag)
+        if flag == "to_csv":
+            export_table_csv(df, path, sep=args.sep)
+        elif flag == "to_json":
+            export_table_json(df, path)
+        else:
+            if not export_table_geojson(df, path):
+                print(
+                    f"warning: table {args.table!r} has no geometry; "
+                    f"GeoJSON not written",
+                    file=sys.stderr,
+                )
+                continue
+        print(f"Exported table {args.table} -> {path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

netload/exceptions.py

@@ -0,0 +1,45 @@
+"""Public exceptions for :mod:`netload`."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class VisumNetError(Exception):
+    """Base exception for all errors raised by :mod:`netload`."""
+
+
+class VisumNetParseError(VisumNetError):
+    """Raised when a ``.net`` file cannot be parsed correctly.
+
+    Attributes
+    ----------
+    source:
+        Path of the file being parsed.
+    line:
+        Line number where the problem occurred (1-based), if known.
+    message:
+        Human readable description of the problem.
+    """
+
+    def __init__(self, source: str, message: str, line: Optional[int] = None) -> None:
+        self.source = source
+        self.line = line
+        self.message = message
+        location = f"{source}:{line}" if line is not None else source
+        super().__init__(f"{location}: {message}")
+
+
+class VisumNetEncodingError(VisumNetError):
+    """Raised when the encoding of a ``.net`` file cannot be determined/decoded.
+
+    Attributes
+    ----------
+    source:
+        Path of the file being parsed.
+    """
+
+    def __init__(self, source: str, message: str) -> None:
+        self.source = source
+        self.message = message
+        super().__init__(f"{source}: {message}")

netload/exporters.py

@@ -0,0 +1,249 @@
+"""Export helpers: CSV, JSON and GeoJSON."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence
+
+import pandas as pd
+
+from .exceptions import VisumNetError
+from .wkt import parse_wkt
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .network import Network
+    from .table import Table
+
+# Column names that are known to hold WKT geometry in .net files.
+_WKT_COLUMNS = ("WKTSURFACE", "WKTPOLY", "GEOMETRY")
+
+
+def _resolve_tables(
+    network: "Network", tables: Optional[Sequence[str]]
+) -> List["Table"]:
+    """Return the tables to export.
+
+    When ``tables`` is ``None`` every table is returned (file order);
+    otherwise only the requested table names (file order is preserved).
+    """
+    if tables is None:
+        return list(network.tables.values())
+
+    resolved: List["Table"] = []
+    for name in tables:
+        if name not in network.tables:
+            raise VisumNetError(
+                f"table {name!r} not found in the network "
+                f"(tables: {', '.join(network.table_names) or 'none'})"
+            )
+        resolved.append(network.tables[name])
+    return resolved
+
+
+# -- small helpers ----------------------------------------------------------
+
+
+def _records_to_jsonable(df: pd.DataFrame) -> List[Dict[str, Any]]:
+    """Convert a DataFrame to a list of JSON-safe records (NaN -> None)."""
+    object_frame = df.astype(object).where(pd.notna(df), None)
+    return object_frame.to_dict("records")
+
+
+def _geometry_for_row(row: pd.Series, geometry_col: Optional[str]) -> Optional[Dict[str, Any]]:
+    if geometry_col is None:
+        return None
+    value = row.get(geometry_col)
+    if value is None or (isinstance(value, float) and pd.isna(value)):
+        return None
+    return parse_wkt(str(value))
+
+
+# -- single-table exporters -------------------------------------------------
+
+
+def export_table_csv(
+    df: pd.DataFrame,
+    path: str | os.PathLike[str],
+    sep: str = ";",
+    encoding: str = "utf-8",
+) -> None:
+    """Write one DataFrame to a CSV file."""
+    df.to_csv(
+        path,
+        sep=sep,
+        index=False,
+        encoding=encoding,
+        lineterminator="\n",
+    )
+
+
+def export_table_json(
+    df: pd.DataFrame,
+    path: str | os.PathLike[str],
+    encoding: str = "utf-8",
+) -> None:
+    """Write one DataFrame to a JSON array of records."""
+    with open(path, "w", encoding=encoding) as handle:
+        json.dump(
+            _records_to_jsonable(df),
+            handle,
+            ensure_ascii=False,
+            indent=2,
+        )
+
+
+def _pick_geometry_column(df: pd.DataFrame) -> Optional[str]:
+    columns = set(df.columns)
+    for candidate in _WKT_COLUMNS:
+        if candidate in columns:
+            return candidate
+    return None
+
+
+def table_geometry_kind(df: pd.DataFrame) -> Optional[str]:
+    """Describe the geometry of a table.
+
+    Returns ``"WKT"`` when a WKT geometry column exists, ``"XY"`` when the
+    table has ``XCOORD``/``YCOORD`` columns, otherwise ``None``.
+    """
+    if _pick_geometry_column(df) is not None:
+        return "WKT"
+    if "XCOORD" in df.columns and "YCOORD" in df.columns:
+        return "XY"
+    return None
+
+
+def export_table_geojson(
+    df: pd.DataFrame,
+    path: str | os.PathLike[str],
+    encoding: str = "utf-8",
+) -> bool:
+    """Write one DataFrame to a GeoJSON ``FeatureCollection``.
+
+    Geometry is taken from a WKT column (``WKTSURFACE``, ``WKTPOLY``,
+    ``GEOMETRY``) when available, otherwise from ``XCOORD``/``YCOORD`` as
+    Point features.
+
+    Returns ``False`` when the table has no geometry and nothing is written.
+    """
+    geometry_col = _pick_geometry_column(df)
+
+    if geometry_col is None and not (
+        "XCOORD" in df.columns and "YCOORD" in df.columns
+    ):
+        return False
+
+    geometry_keys = {geometry_col, "XCOORD", "YCOORD"} if geometry_col else {"XCOORD", "YCOORD"}
+    property_columns = [c for c in df.columns if c not in geometry_keys]
+
+    features: List[Dict[str, Any]] = []
+    for _, row in df.iterrows():
+        if geometry_col is not None:
+            geometry = _geometry_for_row(row, geometry_col)
+        else:
+            x = row.get("XCOORD")
+            y = row.get("YCOORD")
+            if x is None or y is None or pd.isna(x) or pd.isna(y):
+                geometry = None
+            else:
+                geometry = {"type": "Point", "coordinates": [float(x), float(y)]}
+        properties = {
+            col: row.get(col) for col in property_columns
+        }
+        for key in list(properties):
+            value = properties[key]
+            if value is not None and isinstance(value, float) and pd.isna(value):
+                properties[key] = None
+        features.append({"type": "Feature", "geometry": geometry, "properties": properties})
+
+    feature_collection: Dict[str, Any] = {
+        "type": "FeatureCollection",
+        "features": features,
+    }
+
+    with open(path, "w", encoding=encoding) as handle:
+        json.dump(feature_collection, handle, ensure_ascii=False, indent=2)
+
+    return True
+
+
+# -- network-level exporters -------------------------------------------------
+
+
+def export_tables(
+    network: "Network",
+    output_dir: str | os.PathLike[str],
+    sep: str = ";",
+    encoding: str = "utf-8",
+    skip_empty: bool = True,
+    tables: Optional[Sequence[str]] = None,
+) -> List[str]:
+    """Write one CSV file per table of ``network`` into ``output_dir``.
+
+    When ``tables`` is given (e.g. ``["NODE", "LINK"]``), only those tables
+    are exported; by default every table is exported.
+    """
+    out_dir = Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    written: List[str] = []
+    for table in _resolve_tables(network, tables):
+        if skip_empty and len(table.df) == 0:
+            continue
+        path = out_dir / f"{table.name}.csv"
+        export_table_csv(table.df, path, sep=sep, encoding=encoding)
+        written.append(str(path))
+    return written
+
+
+def export_json(
+    network: "Network",
+    output_dir: str | os.PathLike[str],
+    encoding: str = "utf-8",
+    skip_empty: bool = True,
+    tables: Optional[Sequence[str]] = None,
+) -> List[str]:
+    """Write one JSON file (array of records) per table into ``output_dir``.
+
+    When ``tables`` is given, only those tables are exported; by default
+    every table is exported.
+    """
+    out_dir = Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    written: List[str] = []
+    for table in _resolve_tables(network, tables):
+        if skip_empty and len(table.df) == 0:
+            continue
+        path = out_dir / f"{table.name}.json"
+        export_table_json(table.df, path, encoding=encoding)
+        written.append(str(path))
+    return written
+
+
+def export_geojson(
+    network: "Network",
+    output_dir: str | os.PathLike[str],
+    encoding: str = "utf-8",
+    skip_empty: bool = True,
+    tables: Optional[Sequence[str]] = None,
+) -> List[str]:
+    """Write a GeoJSON file for every requested table that has geometry.
+
+    When ``tables`` is given, only those tables are considered; by default
+    every table is considered. Tables without any geometry (no WKT column,
+    no ``XCOORD``/``YCOORD``) are skipped.
+    """
+    out_dir = Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    written: List[str] = []
+    for table in _resolve_tables(network, tables):
+        if skip_empty and len(table.df) == 0:
+            continue
+        path = out_dir / f"{table.name}.geojson"
+        if export_table_geojson(table.df, path, encoding=encoding):
+            written.append(str(path))
+    return written