| Name | polars-st JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | Spatial extension for Polars DataFrames |
| upload_time | 2025-08-05 03:47:54 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | LGPL-2.1 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](#)
# Polars ST
Polars ST provides spatial operations on [Polars](https://github.com/pola-rs/polars) DataFrames, Series, and Expressions. Just like [Shapely](https://github.com/shapely/shapely/) and [GeoPandas](https://github.com/geopandas/geopandas), it make use of the [GEOS](https://github.com/libgeos/geos) library, meaning that its API is mostly identical to theirs.
* Documentation: https://oreilles.github.io/polars-st/
```pycon
>>> import polars_st as st
>>> gdf = st.GeoDataFrame({
... "category": ["A", "A", "B"],
... "geometry": [
... "POLYGON((0 0, 0 4, 4 2, 0 0))",
... "POLYGON((4 0, 4 4, 0 2, 4 0))",
... "POLYGON((0 0, 2 2, 2 0, 0 0))",
... ]
... })
>>> gdf = gdf.group_by("category").agg(st.intersection_all()).with_columns(area=st.area())
>>> gdf.with_columns(st.to_wkt())
shape: (2, 3)
┌──────────┬─────────────────────────────────────┬──────┐
│ category ┆ geometry ┆ area │
│ --- ┆ --- ┆ --- │
│ str ┆ str ┆ f64 │
╞══════════╪═════════════════════════════════════╪══════╡
│ B ┆ POLYGON ((0 0, 2 2, 2 0, 0 0)) ┆ 2.0 │
│ A ┆ POLYGON ((4 2, 2 1, 0 2, 2 3, 4 2)) ┆ 4.0 │
└──────────┴─────────────────────────────────────┴──────┘
```
## Installation
Polars ST is published on PyPI so you can install it with your preferred package manager.
```sh
pip install polars-st
```
## How it works
Geometries are stored as EWKB in regular Polars Binary columns. EWKB is a extension to the WKB standard popularized by PostGIS, that also stores information about the CRS of each geometry as an integer code called SRID.
For every spatial operations, the WKB will be parsed into a Geometry object so the operation can be done. If the operation result is a geometry, it will then be serialized back to WKB. Because of that round-trip, some operations might turn out to be slower than GeoPandas. In most cases however, the performance penalty will be marginal and you will fully benefit from the parallelization capabilities of Polars.
## About GeoPolars
[GeoPolars](https://github.com/geopolars/geopolars) is an very promising tool for manipulating geographic data in Polars based on the [GeoArrow](https://github.com/geoarrow/geoarrow) specification. It however seems to be quite a long way from being ready and feature-complete, mostly due to Polars lack of support for [Arrow Extension Types](https://github.com/pola-rs/polars/issues/9112) and [subclassing of core datatypes](https://github.com/pola-rs/polars/issues/2846#issuecomment-1711799869).
`polars-st` stores geometry as EWKB in regular Binary columns and delegates core functionality to GEOS, which allows it to be ready now, with full support for Z / M coordinates, curved geometry types (CircularString, CurvePolygon, ...) and Series with mixed geometry type and SRIDs.
## About Polars
This project is not affiliated with Polars. The design language was deliberately made very close to that of Polars to highlight the fact that this is an exclusive extension to Polars, and as a tribute to the effectiveness of the original design.
## About GEOS
In order to save myself (and yourself) from the burden of GEOS version-specific features and bugs, `polars-st` statically link to GEOS `main`. This means that all documented features are guaranteed to be available. This also means that this project is LGPL licensed, the same way GEOS is.
## License
Copyright (C) 2024 Aurèle Ferotin
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
USA
Raw data
{
"_id": null,
"home_page": null,
"name": "polars-st",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/88/14/19c0bfa3737672f101e90d0610bb5e9a227522c3ca47f3e737dbbf614862/polars_st-0.3.0.tar.gz",
"platform": null,
"description": "[](#)\n\n# Polars ST\n\nPolars ST provides spatial operations on [Polars](https://github.com/pola-rs/polars) DataFrames, Series, and Expressions. Just like [Shapely](https://github.com/shapely/shapely/) and [GeoPandas](https://github.com/geopandas/geopandas), it make use of the [GEOS](https://github.com/libgeos/geos) library, meaning that its API is mostly identical to theirs.\n\n* Documentation: https://oreilles.github.io/polars-st/\n\n```pycon\n>>> import polars_st as st\n>>> gdf = st.GeoDataFrame({\n... \"category\": [\"A\", \"A\", \"B\"],\n... \"geometry\": [\n... \"POLYGON((0 0, 0 4, 4 2, 0 0))\",\n... \"POLYGON((4 0, 4 4, 0 2, 4 0))\",\n... \"POLYGON((0 0, 2 2, 2 0, 0 0))\",\n... ]\n... })\n>>> gdf = gdf.group_by(\"category\").agg(st.intersection_all()).with_columns(area=st.area())\n>>> gdf.with_columns(st.to_wkt())\nshape: (2, 3)\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 category \u2506 geometry \u2506 area \u2502\n\u2502 --- \u2506 --- \u2506 --- \u2502\n\u2502 str \u2506 str \u2506 f64 \u2502\n\u255e\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2561\n\u2502 B \u2506 POLYGON ((0 0, 2 2, 2 0, 0 0)) \u2506 2.0 \u2502\n\u2502 A \u2506 POLYGON ((4 2, 2 1, 0 2, 2 3, 4 2)) \u2506 4.0 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Installation\n\nPolars ST is published on PyPI so you can install it with your preferred package manager.\n\n```sh\npip install polars-st\n```\n\n## How it works\n\nGeometries are stored as EWKB in regular Polars Binary columns. EWKB is a extension to the WKB standard popularized by PostGIS, that also stores information about the CRS of each geometry as an integer code called SRID.\n\nFor every spatial operations, the WKB will be parsed into a Geometry object so the operation can be done. If the operation result is a geometry, it will then be serialized back to WKB. Because of that round-trip, some operations might turn out to be slower than GeoPandas. In most cases however, the performance penalty will be marginal and you will fully benefit from the parallelization capabilities of Polars.\n\n\n## About GeoPolars\n\n[GeoPolars](https://github.com/geopolars/geopolars) is an very promising tool for manipulating geographic data in Polars based on the [GeoArrow](https://github.com/geoarrow/geoarrow) specification. It however seems to be quite a long way from being ready and feature-complete, mostly due to Polars lack of support for [Arrow Extension Types](https://github.com/pola-rs/polars/issues/9112) and [subclassing of core datatypes](https://github.com/pola-rs/polars/issues/2846#issuecomment-1711799869).\n\n`polars-st` stores geometry as EWKB in regular Binary columns and delegates core functionality to GEOS, which allows it to be ready now, with full support for Z / M coordinates, curved geometry types (CircularString, CurvePolygon, ...) and Series with mixed geometry type and SRIDs.\n\n## About Polars\n\nThis project is not affiliated with Polars. The design language was deliberately made very close to that of Polars to highlight the fact that this is an exclusive extension to Polars, and as a tribute to the effectiveness of the original design.\n\n\n## About GEOS\n\nIn order to save myself (and yourself) from the burden of GEOS version-specific features and bugs, `polars-st` statically link to GEOS `main`. This means that all documented features are guaranteed to be available. This also means that this project is LGPL licensed, the same way GEOS is.\n\n## License\n\nCopyright (C) 2024 Aur\u00e8le Ferotin\n\nThis library is free software; you can redistribute it and/or\nmodify it under the terms of the GNU Lesser General Public\nLicense as published by the Free Software Foundation; either\nversion 2.1 of the License, or (at your option) any later version.\n\nThis library is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\nLesser General Public License for more details.\n\nYou should have received a copy of the GNU Lesser General Public\nLicense along with this library; if not, write to the Free Software\nFoundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301\nUSA\n\n",
"bugtrack_url": null,
"license": "LGPL-2.1",
"summary": "Spatial extension for Polars DataFrames",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://oreilles.github.io/polars-st/",
"Homepage": "https://github.com/Oreilles/polars-st",
"Issues": "https://github.com/Oreilles/polars-st/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "94b75844c73bd8ab305ae92f30365a612e1b6000eba747dda18f82b3763ae1e3",
"md5": "e35586a5b3fe662b857512fd173c3976",
"sha256": "92e2bf02e5ae56a1dfe602dd1abc6f50ed04eb87474ada4e0b2eb1641e42d715"
},
"downloads": -1,
"filename": "polars_st-0.3.0-cp39-abi3-macosx_10_12_x86_64.whl",
"has_sig": false,
"md5_digest": "e35586a5b3fe662b857512fd173c3976",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.10",
"size": 45931493,
"upload_time": "2025-08-05T03:47:52",
"upload_time_iso_8601": "2025-08-05T03:47:52.232084Z",
"url": "https://files.pythonhosted.org/packages/94/b7/5844c73bd8ab305ae92f30365a612e1b6000eba747dda18f82b3763ae1e3/polars_st-0.3.0-cp39-abi3-macosx_10_12_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "042ecd5134bd793cdf56f0e5ec3b9c9786857618ad56aa7dcc23f758b39829df",
"md5": "ff18df1b15429176e9deace81e87a4d3",
"sha256": "af092e95016c99adc2550ecfda07bce79c668948fdc2a12689b7633c7a51d80a"
},
"downloads": -1,
"filename": "polars_st-0.3.0-cp39-abi3-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "ff18df1b15429176e9deace81e87a4d3",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.10",
"size": 43114687,
"upload_time": "2025-08-05T03:47:49",
"upload_time_iso_8601": "2025-08-05T03:47:49.112124Z",
"url": "https://files.pythonhosted.org/packages/04/2e/cd5134bd793cdf56f0e5ec3b9c9786857618ad56aa7dcc23f758b39829df/polars_st-0.3.0-cp39-abi3-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2fa9655561cdb8eef8aec7390755cb872a40affa061aa9516f93db21c4887335",
"md5": "b047d58ef836b9072ec810ef0d8a385a",
"sha256": "a47c937e8ba111937a94537f334f94c5e437499d50cb8a6034e7d7798604f86c"
},
"downloads": -1,
"filename": "polars_st-0.3.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "b047d58ef836b9072ec810ef0d8a385a",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.10",
"size": 36924960,
"upload_time": "2025-08-05T03:47:42",
"upload_time_iso_8601": "2025-08-05T03:47:42.147341Z",
"url": "https://files.pythonhosted.org/packages/2f/a9/655561cdb8eef8aec7390755cb872a40affa061aa9516f93db21c4887335/polars_st-0.3.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "aa531b2d7a05a8fa23f25da176950ead840166f703e23f3a8121fe47b52c6ce1",
"md5": "6dfaeb878b1a70e58111914b39bb17f0",
"sha256": "6498b1b6d7abbb160c9aeeec60ea21065ce342a36e24d739c3fc2e5c5b0a82ca"
},
"downloads": -1,
"filename": "polars_st-0.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "6dfaeb878b1a70e58111914b39bb17f0",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.10",
"size": 40277370,
"upload_time": "2025-08-05T03:47:46",
"upload_time_iso_8601": "2025-08-05T03:47:46.145379Z",
"url": "https://files.pythonhosted.org/packages/aa/53/1b2d7a05a8fa23f25da176950ead840166f703e23f3a8121fe47b52c6ce1/polars_st-0.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "18714d1eab9d9a09c133f216b7e51caf4bd5f214b87292275335bf76d2288f6f",
"md5": "1d2919bd333e0f90ebb8dd923190c106",
"sha256": "6051637933efa716eec079419acc0ebd85bfe9b3f7c65b308b6d1c1b0322872a"
},
"downloads": -1,
"filename": "polars_st-0.3.0-cp39-abi3-win_amd64.whl",
"has_sig": false,
"md5_digest": "1d2919bd333e0f90ebb8dd923190c106",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.10",
"size": 42951994,
"upload_time": "2025-08-05T03:47:56",
"upload_time_iso_8601": "2025-08-05T03:47:56.407019Z",
"url": "https://files.pythonhosted.org/packages/18/71/4d1eab9d9a09c133f216b7e51caf4bd5f214b87292275335bf76d2288f6f/polars_st-0.3.0-cp39-abi3-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "881419c0bfa3737672f101e90d0610bb5e9a227522c3ca47f3e737dbbf614862",
"md5": "e2a8a4ff99c5fdcfb6fadadcf4e66d29",
"sha256": "f74a578c6f144509b834f331d718d68cb7b6d4b0cf41c05a11fd2372c764db50"
},
"downloads": -1,
"filename": "polars_st-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "e2a8a4ff99c5fdcfb6fadadcf4e66d29",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 226054,
"upload_time": "2025-08-05T03:47:54",
"upload_time_iso_8601": "2025-08-05T03:47:54.530173Z",
"url": "https://files.pythonhosted.org/packages/88/14/19c0bfa3737672f101e90d0610bb5e9a227522c3ca47f3e737dbbf614862/polars_st-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 03:47:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Oreilles",
"github_project": "polars-st",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "polars-st"
}
