Pyogrio: Vectorized Spatial Vector File I/O

Warnings

• breaking In version 0.12.0, the `read_dataframe` function started returning JSON fields as Python `dict`s or `list`s, whereas they were previously returned as raw strings. This change affects how JSON-type columns are handled programmatically.
  Fix: Update your code to expect `dict` or `list` types for JSON columns read from data sources.
• breaking As of version 0.12.0, Pyogrio dropped official support for GDAL versions 3.4 and 3.5. Users are now required to use GDAL 3.6 or newer.
  Fix: Ensure your environment has GDAL 3.6 or a newer compatible version installed. Conda-forge installations typically handle this dependency.
• gotcha Pyogrio's binary wheels often bundle a specific GDAL version, which might conflict with a system-installed GDAL or one linked by other geospatial libraries like Fiona. This can lead to `DriverError` or `NullPointerError`.
  Fix: Check the GDAL version Pyogrio is using via `pyogrio.__gdal_version_string__`. If conflicts arise, consider uninstalling then reinstalling Fiona with `--no-binary fiona` (e.g., `pip uninstall fiona; pip install fiona --no-binary fiona`) or use a conda-forge environment for consistent GDAL versions.
• gotcha In `read_dataframe`, datetime columns with mixed time zone offsets are converted to UTC by default. This might alter original offset information if not explicitly handled.
  Fix: To retain original offsets or convert datetimes to strings, use the `datetime_as_string=True` or `mixed_offsets_as_utc=False` parameters in `read_dataframe`.
• gotcha MacOS binary wheels for Pyogrio are built specifically for macOS 12 and newer. Users on older macOS versions (e.g., macOS 11 or earlier) will need to build Pyogrio from source, which requires a pre-installed GDAL development environment.
  Fix: Upgrade macOS to version 12+ or follow the instructions for building Pyogrio from source if on an older OS.
• gotcha Utilizing the `use_arrow=True` option in `read_dataframe` or `write_dataframe` for performance benefits requires the `pyarrow` library to be installed. Additionally, writing with Arrow (`use_arrow=True` in `write_dataframe`) specifically requires GDAL >= 3.8, while reading with Arrow requires GDAL >= 3.6.
  Fix: Install `pyarrow` (`pip install pyarrow`) and ensure your GDAL version meets the minimum requirements (3.6 for reading, 3.8 for writing).
• gotcha Pyogrio does not perform validation of attribute values or geometry types before attempting to write data to an output file. Providing invalid types may result in crashes during the write operation with cryptic error messages.
  Fix: Ensure that the data types in your GeoDataFrame columns are compatible with the target OGR driver's schema before writing. Convert incompatible types (e.g., lists, tuples) to supported formats (e.g., strings) if necessary.

Install

• pip install pyogrio PyPI
• conda install -c conda-forge pyogrio Conda-forge

Imports

• read_dataframe

  from pyogrio import read_dataframe

• write_dataframe

  from pyogrio import write_dataframe

• list_drivers

  from pyogrio import list_drivers

• read_info

  from pyogrio import read_info

Quickstart

This quickstart demonstrates how to create a basic GeoPandas GeoDataFrame, write it to a GeoPackage file using `pyogrio.write_dataframe`, and then read the data back into a GeoDataFrame using `pyogrio.read_dataframe`.

import geopandas as gpd
from pyogrio import read_dataframe, write_dataframe
from shapely.geometry import Point
import os

# Create a dummy GeoDataFrame
data = {'name': ['Location A', 'Location B'], 'value': [10, 20]}
geometry = [Point(1, 1), Point(2, 2)]
gdf = gpd.GeoDataFrame(data, geometry=geometry, crs="EPSG:4326")

# Define output path
output_file = "my_geodata.gpkg"

# Write GeoDataFrame to a GeoPackage file
print(f"Writing data to {output_file}...")
write_dataframe(gdf, output_file, driver="GPKG", layer="my_points")
print("Write complete.")

# Read GeoDataFrame from the GeoPackage file
print(f"Reading data from {output_file}...")
read_gdf = read_dataframe(output_file, layer="my_points")
print("Read complete.")
print(read_gdf)

# Clean up the created file
# os.remove(output_file)
# print(f"Cleaned up {output_file}.")