geosplit 0.1.0__tar.gz

geosplit-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,21 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: pytest
+      - run: ruff check .

geosplit-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+dist/
+.test-output/
+*.gpkg-shm
+*.gpkg-wal

geosplit-0.1.0/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.

geosplit-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,68 @@
+# 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/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "geosplit"
+version = "0.1.0"
+description = "Split GeoJSON by feature count or file size and convert GeoJSON to and from GeoPackage"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "GeoSplit contributors" }]
+keywords = ["geojson", "geopackage", "gis", "splitter"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: GIS",
+]
+
+[project.optional-dependencies]
+gpkg = ["geopandas>=1.0"]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+geosplit = "geo_splitter.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/geo_splitter"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"

geosplit-0.1.0/src/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"

geosplit-0.1.0/src/geo_splitter/__main__.py

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

geosplit-0.1.0/src/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())

geosplit-0.1.0/src/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

geosplit-0.1.0/src/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/tests/fixtures/sample.geojson

@@ -0,0 +1,12 @@
+{
+  "type": "FeatureCollection",
+  "name": "sample",
+  "bbox": [0, 0, 4, 4],
+  "features": [
+    {"type": "Feature", "properties": {"id": 0}, "geometry": {"type": "Point", "coordinates": [0, 0]}},
+    {"type": "Feature", "properties": {"id": 1}, "geometry": {"type": "Point", "coordinates": [1, 1]}},
+    {"type": "Feature", "properties": {"id": 2}, "geometry": {"type": "Point", "coordinates": [2, 2]}},
+    {"type": "Feature", "properties": {"id": 3}, "geometry": {"type": "Point", "coordinates": [3, 3]}},
+    {"type": "Feature", "properties": {"id": 4}, "geometry": {"type": "Point", "coordinates": [4, 4]}}
+  ]
+}

geosplit-0.1.0/tests/test_cli.py

@@ -0,0 +1,17 @@
+import json
+from pathlib import Path
+
+from geo_splitter.cli import help_text, main
+
+
+def test_split_command(tmp_path: Path, capsys) -> None:
+    source = tmp_path / "data.geojson"
+    source.write_text(json.dumps({"type": "FeatureCollection", "features": []}), encoding="utf-8")
+    assert main(["split", str(source), str(tmp_path / "out"), "--features", "10"]) == 0
+    assert "Created 1 file" in capsys.readouterr().out
+
+
+def test_help_command(capsys) -> None:
+    assert main(["help", "split"]) == 0
+    assert "--features" in capsys.readouterr().out
+    assert "convert" in help_text()

geosplit-0.1.0/tests/test_convert.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+import pytest
+
+from geo_splitter.convert import convert_file
+from geo_splitter.core import GeoSplitterError
+
+
+def test_requires_geojson_and_geopackage(tmp_path: Path) -> None:
+    source = tmp_path / "input.geojson"
+    source.write_text('{"type":"FeatureCollection","features":[]}', encoding="utf-8")
+    with pytest.raises(GeoSplitterError, match="requires one"):
+        convert_file(source, tmp_path / "output.json")
+
+
+def test_rejects_layer_for_geojson_input(tmp_path: Path) -> None:
+    source = tmp_path / "input.geojson"
+    source.write_text('{"type":"FeatureCollection","features":[]}', encoding="utf-8")
+    with pytest.raises(GeoSplitterError, match="only applies"):
+        convert_file(source, tmp_path / "output.gpkg", layer="places")

geosplit-0.1.0/tests/test_core.py

@@ -0,0 +1,55 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from geo_splitter.core import GeoSplitterError, parse_size, split_geojson
+
+
+@pytest.fixture
+def collection(tmp_path: Path) -> Path:
+    path = tmp_path / "places.geojson"
+    path.write_text(
+        json.dumps(
+            {
+                "type": "FeatureCollection",
+                "name": "places",
+                "bbox": [0, 0, 4, 4],
+                "features": [
+                    {"type": "Feature", "properties": {"id": i}, "geometry": {"type": "Point", "coordinates": [i, i]}}
+                    for i in range(5)
+                ],
+            }
+        ),
+        encoding="utf-8",
+    )
+    return path
+
+
+def test_parse_size() -> None:
+    assert parse_size("2 MB") == 2_000_000
+    assert parse_size("2MiB") == 2_097_152
+
+
+def test_split_by_feature_count(collection: Path, tmp_path: Path) -> None:
+    paths = split_geojson(collection, tmp_path / "out", features_per_file=2)
+    assert [len(json.loads(path.read_text())["features"]) for path in paths] == [2, 2, 1]
+    assert all("bbox" not in json.loads(path.read_text()) for path in paths)
+
+
+def test_split_by_exact_size(collection: Path, tmp_path: Path) -> None:
+    paths = split_geojson(collection, tmp_path / "out", max_bytes=260)
+    assert len(paths) > 1
+    assert sum(len(json.loads(path.read_text())["features"]) for path in paths) == 5
+    assert all(path.stat().st_size <= 260 for path in paths)
+
+
+def test_rejects_oversized_feature(collection: Path, tmp_path: Path) -> None:
+    with pytest.raises(GeoSplitterError, match="Feature 1"):
+        split_geojson(collection, tmp_path / "out", max_bytes=130)
+
+
+def test_does_not_overwrite_by_default(collection: Path, tmp_path: Path) -> None:
+    split_geojson(collection, tmp_path / "out", features_per_file=5)
+    with pytest.raises(GeoSplitterError, match="already exists"):
+        split_geojson(collection, tmp_path / "out", features_per_file=5)