geosplit 0.1.0__py3-none-any.whl

geo_splitter/__init__.py

@@ -0,0 +1,6 @@
+"""Split GeoJSON files and convert GeoJSON to or from GeoPackage."""
+
+from .core import GeoSplitterError, split_geojson
+
+__all__ = ["GeoSplitterError", "split_geojson"]
+__version__ = "0.1.0"

geo_splitter/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

geo_splitter/cli.py

@@ -0,0 +1,72 @@
+"""Command-line interface for GeoSplit."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .convert import convert_file
+from .core import GeoSplitterError, parse_size, split_geojson
+
+
+def _parsers() -> tuple[argparse.ArgumentParser, dict[str, argparse.ArgumentParser]]:
+    parser = argparse.ArgumentParser(
+        prog="geosplit", description="Split GeoJSON and convert GeoJSON <-> GeoPackage."
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    split = commands.add_parser("split", help="split a GeoJSON FeatureCollection")
+    split.add_argument("input", help="source .geojson file")
+    split.add_argument("output_dir", help="directory for split files")
+    mode = split.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--features", type=int, metavar="COUNT", help="maximum features per file")
+    mode.add_argument("--size", type=parse_size, metavar="SIZE", help="maximum size, e.g. 10MB or 512KiB")
+    split.add_argument("--prefix", help="output filename prefix (default: input filename)")
+    split.add_argument("--force", action="store_true", help="replace matching output files")
+
+    convert = commands.add_parser("convert", help="convert GeoJSON to or from GeoPackage")
+    convert.add_argument("input", help="source .geojson, .json, or .gpkg file")
+    convert.add_argument("output", help="destination .geojson, .json, or .gpkg file")
+    convert.add_argument("--layer", help="source GeoPackage layer")
+    convert.add_argument("--output-layer", help="destination GeoPackage layer name")
+    convert.add_argument("--force", action="store_true", help="replace the output file")
+
+    help_command = commands.add_parser("help", help="show general or command-specific help")
+    help_command.add_argument("topic", nargs="?", choices=("split", "convert"), help="command to explain")
+    return parser, commands.choices
+
+
+def help_text(topic: str | None = None) -> str:
+    """Return general help or detailed help for a command."""
+    parser, commands = _parsers()
+    return (commands[topic] if topic else parser).format_help()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser, _ = _parsers()
+    try:
+        args = parser.parse_args(argv)
+        if args.command == "help":
+            print(help_text(args.topic), end="")
+        elif args.command == "split":
+            paths = split_geojson(
+                args.input,
+                args.output_dir,
+                features_per_file=args.features,
+                max_bytes=args.size,
+                prefix=args.prefix,
+                force=args.force,
+            )
+            print(f"Created {len(paths)} file(s) in {paths[0].parent}")
+        else:
+            path = convert_file(
+                args.input, args.output, layer=args.layer, output_layer=args.output_layer, force=args.force
+            )
+            print(f"Created {path}")
+        return 0
+    except GeoSplitterError as error:
+        parser.exit(2, f"error: {error}\n")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

geo_splitter/convert.py

@@ -0,0 +1,55 @@
+"""Optional GeoJSON and GeoPackage conversion support."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .core import GeoSplitterError
+
+_GEOJSON = {".geojson", ".json"}
+
+
+def convert_file(
+    source: str | Path,
+    destination: str | Path,
+    *,
+    layer: str | None = None,
+    output_layer: str | None = None,
+    force: bool = False,
+) -> Path:
+    """Convert one GeoJSON file to GeoPackage, or one GeoPackage layer to GeoJSON."""
+    source, destination = Path(source), Path(destination)
+    source_suffix, destination_suffix = source.suffix.lower(), destination.suffix.lower()
+    source_is_gpkg, destination_is_gpkg = source_suffix == ".gpkg", destination_suffix == ".gpkg"
+    if source_is_gpkg == destination_is_gpkg or {source_suffix, destination_suffix} - (_GEOJSON | {".gpkg"}):
+        raise GeoSplitterError("Conversion requires one .geojson/.json file and one .gpkg file.")
+    if not source.is_file():
+        raise GeoSplitterError(f"Input does not exist or is not a file: {source}")
+    if layer and not source_is_gpkg:
+        raise GeoSplitterError("--layer only applies when reading a GeoPackage.")
+    if output_layer and not destination_is_gpkg:
+        raise GeoSplitterError("--output-layer only applies when writing a GeoPackage.")
+    if destination.exists() and not force:
+        raise GeoSplitterError(f"Output already exists: {destination}. Use --force to replace it.")
+    try:
+        import geopandas as gpd
+    except ImportError as error:
+        raise GeoSplitterError("GeoPackage support is not installed. Run: pip install 'geosplit[gpkg]'") from error
+
+    if source_is_gpkg:
+        layers = gpd.list_layers(source)["name"].tolist()
+        if not layers:
+            raise GeoSplitterError("GeoPackage contains no layers.")
+        if layer is None and len(layers) != 1:
+            raise GeoSplitterError(f"GeoPackage has multiple layers; choose one with --layer: {', '.join(layers)}")
+        if layer is not None and layer not in layers:
+            raise GeoSplitterError(f"Layer {layer!r} not found. Available layers: {', '.join(layers)}")
+        frame, driver, kwargs = gpd.read_file(source, layer=layer or layers[0]), "GeoJSON", {}
+    else:
+        frame, driver, kwargs = gpd.read_file(source), "GPKG", {"layer": output_layer or destination.stem}
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    if destination.exists():
+        destination.unlink()
+    frame.to_file(destination, driver=driver, index=False, **kwargs)
+    return destination

geo_splitter/core.py

@@ -0,0 +1,117 @@
+"""Core GeoJSON splitting logic."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+JsonObject = dict[str, Any]
+_SIZE = re.compile(r"^(\d+(?:\.\d+)?)\s*(B|KB|KIB|MB|MIB|GB|GIB)?$", re.I)
+_UNITS = {
+    "B": 1,
+    "KB": 1_000,
+    "KIB": 1_024,
+    "MB": 1_000_000,
+    "MIB": 1_048_576,
+    "GB": 1_000_000_000,
+    "GIB": 1_073_741_824,
+}
+
+
+class GeoSplitterError(ValueError):
+    """Raised when an input or requested operation is invalid."""
+
+
+def parse_size(value: str) -> int:
+    """Convert values such as ``500KB`` or ``2.5MiB`` to bytes."""
+    if not (match := _SIZE.fullmatch(value.strip())):
+        raise GeoSplitterError(f"Invalid size {value!r}; try 500KB, 2MB, or 1GiB.")
+    amount, unit = match.groups()
+    size = int(float(amount) * _UNITS[unit.upper() if unit else "B"])
+    if size < 1:
+        raise GeoSplitterError("Size must be at least 1 byte.")
+    return size
+
+
+def _compact(value: Any) -> bytes:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode()
+
+
+def _load(path: Path) -> JsonObject:
+    try:
+        document = json.loads(path.read_text(encoding="utf-8-sig"))
+    except (OSError, UnicodeError) as error:
+        raise GeoSplitterError(f"Cannot read {path}: {error}") from error
+    except json.JSONDecodeError as error:
+        raise GeoSplitterError(f"Invalid JSON in {path}: {error}") from error
+    if not isinstance(document, dict) or document.get("type") != "FeatureCollection":
+        raise GeoSplitterError("Input must be a GeoJSON FeatureCollection.")
+    if not isinstance(document.get("features"), list):
+        raise GeoSplitterError("GeoJSON 'features' must be an array.")
+    return document
+
+
+def _chunks_by_size(metadata: JsonObject, features: list[Any], limit: int) -> list[list[Any]]:
+    # A trailing newline is included because output files contain one.
+    fixed = len(_compact({**metadata, "features": []})) + 1
+    if fixed > limit:
+        raise GeoSplitterError(f"The GeoJSON metadata alone exceeds the {limit}-byte limit.")
+
+    chunks: list[list[Any]] = [[]]
+    used = fixed
+    for index, feature in enumerate(features, 1):
+        feature_size = len(_compact(feature))
+        addition = feature_size + bool(chunks[-1])
+        if fixed + feature_size > limit:
+            raise GeoSplitterError(f"Feature {index} cannot fit within the {limit}-byte limit.")
+        if used + addition > limit:
+            chunks.append([])
+            used = fixed
+            addition -= 1
+        chunks[-1].append(feature)
+        used += addition
+    return chunks
+
+
+def split_geojson(
+    source: str | Path,
+    output_dir: str | Path,
+    *,
+    features_per_file: int | None = None,
+    max_bytes: int | None = None,
+    prefix: str | None = None,
+    force: bool = False,
+) -> list[Path]:
+    """Split a FeatureCollection and return the output paths.
+
+    Exactly one of ``features_per_file`` and ``max_bytes`` must be supplied.
+    Size limits include the complete compact GeoJSON document and final newline.
+    """
+    if (features_per_file is None) == (max_bytes is None):
+        raise GeoSplitterError("Choose exactly one split mode: feature count or file size.")
+    if features_per_file is not None and features_per_file < 1:
+        raise GeoSplitterError("Features per file must be at least 1.")
+    if max_bytes is not None and max_bytes < 1:
+        raise GeoSplitterError("Maximum file size must be at least 1 byte.")
+
+    source, output_dir = Path(source), Path(output_dir)
+    document = _load(source)
+    features = document.pop("features")
+    # A collection-wide bbox becomes incorrect after splitting, so omit it.
+    document.pop("bbox", None)
+    chunks = (
+        [features[i : i + features_per_file] for i in range(0, len(features), features_per_file)] or [[]]
+        if features_per_file is not None
+        else _chunks_by_size(document, features, max_bytes)  # type: ignore[arg-type]
+    )
+    stem, width = prefix or source.stem, max(3, len(str(len(chunks))))
+    paths = [output_dir / f"{stem}_{i:0{width}d}.geojson" for i in range(1, len(chunks) + 1)]
+    if not force and (existing := next((path for path in paths if path.exists()), None)):
+        raise GeoSplitterError(f"Output already exists: {existing}. Use --force to replace it.")
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    for path, chunk in zip(paths, chunks, strict=True):
+        path.write_bytes(_compact({**document, "features": chunk}) + b"\n")
+    return paths

geosplit-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: geosplit
+Version: 0.1.0
+Summary: Split GeoJSON by feature count or file size and convert GeoJSON to and from GeoPackage
+Author: GeoSplit contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: geojson,geopackage,gis,splitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: gpkg
+Requires-Dist: geopandas>=1.0; extra == 'gpkg'
+Description-Content-Type: text/markdown
+
+# GeoSplit
+
+A focused command-line tool that:
+
+- splits a GeoJSON `FeatureCollection` by feature count;
+- splits it by a strict maximum file size; and
+- converts GeoJSON to GeoPackage, or a GeoPackage layer back to GeoJSON.
+
+The splitter has no runtime dependencies. GeoPackage support is optional.
+
+View general or command-specific help at any time:
+
+```bash
+geosplit help
+geosplit help split
+geosplit help convert
+```
+
+## Install
+
+Requires Python 3.10 or newer. Download or clone the project, open a terminal in its folder, then run:
+
+```bash
+pip install .
+```
+
+Include conversion support:
+
+```bash
+pip install ".[gpkg]"
+```
+
+## Split GeoJSON
+
+By feature count:
+
+```bash
+geosplit split world.geojson output --features 1000
+```
+
+By maximum file size:
+
+```bash
+geosplit split world.geojson output --size 10MB
+```
+
+Sizes accept `B`, `KB`, `KiB`, `MB`, `MiB`, `GB`, and `GiB`. Each resulting file is a complete, compact GeoJSON document whose on-disk size does not exceed the requested limit. If one feature cannot fit by itself, the command stops with a clear error.
+
+Use `--prefix countries` to customize output names or `--force` to replace matching files. A source collection's top-level `bbox` is omitted because it would no longer describe each split collection; other top-level metadata is retained.
+
+## Convert formats
+
+```bash
+# GeoJSON to GeoPackage
+geosplit convert roads.geojson roads.gpkg
+
+# Choose the new GeoPackage layer name
+geosplit convert roads.geojson map.gpkg --output-layer roads
+
+# GeoPackage to GeoJSON
+geosplit convert map.gpkg roads.geojson --layer roads
+```
+
+If a GeoPackage contains exactly one layer, `--layer` is optional. Existing destinations are protected unless `--force` is supplied.
+
+## License
+
+MIT

geosplit-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+geo_splitter/__init__.py,sha256=3Jbw4scUmWEAjkugMgCfOS2wfFlyof_8NOx5KcDxa6A,191
+geo_splitter/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+geo_splitter/cli.py,sha256=36gmV16sk0K-GCfz9P9-LSVDnciTBgwwqEc_99ZT_EM,3046
+geo_splitter/convert.py,sha256=8MJdgzCPmEpeLMjZdEJsQs7SK_EH5VHJtOjKAZ1KV7E,2531
+geo_splitter/core.py,sha256=1M-OiJTEHTYqtE6uXOwxepAip6D6wBviEK2STujQNJU,4517
+geosplit-0.1.0.dist-info/METADATA,sha256=4x4syE3TK2KGfSOJLBB9rwrYzXMMWFx2ZysiU8yH4m4,2414
+geosplit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+geosplit-0.1.0.dist-info/entry_points.txt,sha256=c5A6pF1agZaBjT9-xvYs_HFKkCLmpTVUXVFI0fW3FRs,51
+geosplit-0.1.0.dist-info/licenses/LICENSE,sha256=EX3PsbXz3IlIdxy4w15CY9QAcfuocWvfs29IA_DHtBM,1078
+geosplit-0.1.0.dist-info/RECORD,,

geosplit-0.1.0.dist-info/WHEEL

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

geosplit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+geosplit = geo_splitter.cli:main

geosplit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GeoSplit contributors
+
+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.