GeoPolars Documentation

GeoPolars is an extension of the Polars DataFrame library designed for geospatial data. It aims to provide:

1. High Performance: Faster multithreaded operations compared to GeoPandas.
2. Interoperability: Better data interoperability without memory copies by utilizing a GeoArrow core.

Note: GeoPolars is currently a prototype and is not considered production-ready.

GeoPolars is a geospatial extension for the Polars DataFrame library. It provides geospatial capabilities for both Rust and Python, utilizing the GeoArrow memory model for internal data representation.

Key Features:

• Internal Memory Model: Uses GeoArrow.
• Implementation: Written in Rust with Python bindings.
• Performance: Multithreading capable.

WARNING

GeoPolars is currently a prototype and is not considered production-ready.

The geopolars namespace contains all public objects, functions, and methods. The API is organized into several core modules:

• GeoSeries: For handling 1D geospatial data.
• GeoDataFrame: For handling 2D geospatial datasets.
• GeoLazyFrame: For deferred/lazy geospatial operations.
• Expressions: For defining geospatial transformations within Polars-style contexts.
• Functions: For standalone geospatial utility functions.
• IO: For reading and writing geospatial data formats.
• Datatypes: For geospatial-specific data types.
• Config: For library configuration.
• Testing: For geospatial testing utilities.
• Exceptions: For geospatial-specific error handling.

To build a Python wheel intended for release, run the following command. This will generate a wheel for your current system's architecture and place it in the dist/ directory.

poetry run poe build

To build the project for development, use the poe develop command. This uses Maturin to build and package the Python and Rust code into a Python wheel and installs it into the Poetry-managed virtual environment (.venv/).

Note: This command compiles the Rust binary with --debug flags. While compilation is faster, runtime performance will be significantly slower.

To build with a release configuration (faster runtime, slower compilation), use:

poetry run poe develop-release

After building, you can verify the installation by opening IPython:

poetry run ipython

Inside IPython, you should be able to run import geopolars successfully.

GeoPolars is currently in alpha. To install the pre-release version from PyPI, use the --pre flag with pip. Binary wheels are provided for many platforms, so a compilation of the underlying Rust code is typically not required.

pip install --pre geopolars

GeoPolars uses mike to deploy documentation, allowing multiple versions to be hosted simultaneously.

To deploy a specific version and set it as the latest version, use the following pattern:

# Deploy a specific version as latest
poetry run mike deploy --push --no-redirect 0.1.0-alpha.4 latest

# Deploy the 'latest' alias
poetry run mike deploy --push --no-redirect VERSION latest

To use GeoPolars in a Rust project, add the geopolars crate via crates.io. Detailed API documentation is available on docs.rs.

# Add to your Cargo.toml
geopolars = "0.1.0-alpha.4"

To serve the documentation locally for previewing changes, use mkdocs via poetry:

poetry run mkdocs serve