pyogrio 0.9.0__cp312-cp312-manylinux_2_28_aarch64.whl → 0.11.0__cp312-cp312-manylinux_2_28_aarch64.whl

pyogrio/util.py

@@ -1,13 +1,19 @@
-from pathlib import Path
+"""Utility functions."""
+
 import re
 import sys
+from packaging.version import Version
+from pathlib import Path
+from typing import Union
 from urllib.parse import urlparse
 
-from packaging.version import Version
+from pyogrio._vsi import vsimem_rmtree_toplevel as _vsimem_rmtree_toplevel
+
+MULTI_EXTENSIONS = (".gpkg.zip", ".shp.zip")
 
 
 def get_vsi_path_or_buffer(path_or_buffer):
-    """Get vsi-prefixed path or bytes buffer depending on type of path_or_buffer
+    """Get VSI-prefixed path or bytes buffer depending on type of path_or_buffer.
 
     If path_or_buffer is a bytes object, it will be returned directly and will
     be read into an in-memory dataset when passed to one of the Cython functions.
@@ -21,15 +27,17 @@ def get_vsi_path_or_buffer(path_or_buffer):
     Parameters
     ----------
     path_or_buffer : str, pathlib.Path, bytes, or file-like
+        A dataset path or URI, raw buffer, or file-like object with a read method.
 
     Returns
     -------
     str or bytes
-    """
 
-    # force path objects to string to specifically ignore their read method
+    """
+    # treat Path objects here already to ignore their read method + to avoid backslashes
+    # on Windows.
     if isinstance(path_or_buffer, Path):
-        return vsi_path(str(path_or_buffer))
+        return vsi_path(path_or_buffer)
 
     if isinstance(path_or_buffer, bytes):
         return path_or_buffer
@@ -38,7 +46,7 @@ def get_vsi_path_or_buffer(path_or_buffer):
         bytes_buffer = path_or_buffer.read()
 
         # rewind buffer if possible so that subsequent operations do not need to rewind
-        if hasattr(path_or_buffer, "seek"):
+        if hasattr(path_or_buffer, "seekable") and path_or_buffer.seekable():
             path_or_buffer.seek(0)
 
         return bytes_buffer
@@ -46,16 +54,14 @@ def get_vsi_path_or_buffer(path_or_buffer):
     return vsi_path(str(path_or_buffer))
 
 
-def vsi_path(path: str) -> str:
-    """
-    Ensure path is a local path or a GDAL-compatible vsi path.
-
-    """
-
-    if "/vsimem/" in path:
-        raise ValueError(
-            "path cannot contain /vsimem/ directly; to use an in-memory dataset a bytes object must be passed instead"
-        )
+def vsi_path(path: Union[str, Path]) -> str:
+    """Ensure path is a local path or a GDAL-compatible VSI path."""
+    # Convert Path objects to string, but for VSI paths, keep posix style path.
+    if isinstance(path, Path):
+        if sys.platform == "win32" and path.as_posix().startswith("/vsi"):
+            path = path.as_posix()
+        else:
+            path = str(path)
 
     # path is already in GDAL format
     if path.startswith("/vsi"):
@@ -64,15 +70,23 @@ def vsi_path(path: str) -> str:
     # Windows drive letters (e.g. "C:\") confuse `urlparse` as they look like
     # URL schemes
     if sys.platform == "win32" and re.match("^[a-zA-Z]\\:", path):
+        # If it is not a zip file or it is multi-extension zip file that is directly
+        # supported by a GDAL driver, return the path as is.
         if not path.split("!")[0].endswith(".zip"):
             return path
+        if path.split("!")[0].endswith(MULTI_EXTENSIONS):
+            return path
 
         # prefix then allow to proceed with remaining parsing
         path = f"zip://{path}"
 
     path, archive, scheme = _parse_uri(path)
 
-    if scheme or archive or path.endswith(".zip"):
+    if (
+        scheme
+        or archive
+        or (path.endswith(".zip") and not path.endswith(MULTI_EXTENSIONS))
+    ):
         return _construct_vsi_path(path, archive, scheme)
 
     return path
@@ -98,12 +112,11 @@ SCHEMES = {
     # those are for now not added as supported URI
 }
 
-CURLSCHEMES = set([k for k, v in SCHEMES.items() if v == "curl"])
+CURLSCHEMES = {k for k, v in SCHEMES.items() if v == "curl"}
 
 
 def _parse_uri(path: str):
-    """
-    Parse a URI
+    """Parse a URI.
 
     Returns a tuples of (path, archive, scheme)
 
@@ -138,19 +151,19 @@ def _parse_uri(path: str):
 
 
 def _construct_vsi_path(path, archive, scheme) -> str:
-    """Convert a parsed path to a GDAL VSI path"""
-
+    """Convert a parsed path to a GDAL VSI path."""
     prefix = ""
     suffix = ""
     schemes = scheme.split("+")
 
-    if "zip" not in schemes and (archive.endswith(".zip") or path.endswith(".zip")):
+    if "zip" not in schemes and (
+        archive.endswith(".zip")
+        or (path.endswith(".zip") and not path.endswith(MULTI_EXTENSIONS))
+    ):
         schemes.insert(0, "zip")
 
     if schemes:
-        prefix = "/".join(
-            "vsi{0}".format(SCHEMES[p]) for p in schemes if p and p != "file"
-        )
+        prefix = "/".join(f"vsi{SCHEMES[p]}" for p in schemes if p and p != "file")
 
         if schemes[-1] in CURLSCHEMES:
             suffix = f"{schemes[-1]}://"
@@ -159,15 +172,15 @@ def _construct_vsi_path(path, archive, scheme) -> str:
         if archive:
             return "/{}/{}{}/{}".format(prefix, suffix, archive, path.lstrip("/"))
         else:
-            return "/{}/{}{}".format(prefix, suffix, path)
+            return f"/{prefix}/{suffix}{path}"
 
     return path
 
 
 def _preprocess_options_key_value(options):
-    """
-    Preprocess options, eg `spatial_index=True` gets converted
-    to `SPATIAL_INDEX="YES"`.
+    """Preprocess options.
+
+    For example, `spatial_index=True` gets converted to `SPATIAL_INDEX="YES"`.
     """
     if not isinstance(options, dict):
         raise TypeError(f"Expected options to be a dict, got {type(options)}")
@@ -191,6 +204,7 @@ def _mask_to_wkb(mask):
     Parameters
     ----------
     mask : Shapely geometry
+        The geometry to convert to WKB.
 
     Returns
     -------
@@ -201,8 +215,8 @@ def _mask_to_wkb(mask):
     ValueError
         raised if Shapely >= 2.0 is not available or mask is not a Shapely
         Geometry object
-    """
 
+    """
     if mask is None:
         return mask
 
@@ -221,3 +235,26 @@ def _mask_to_wkb(mask):
         raise ValueError("'mask' parameter must be a Shapely geometry")
 
     return shapely.to_wkb(mask)
+
+
+def vsimem_rmtree_toplevel(path: Union[str, Path]):
+    """Remove the parent directory of the file path recursively.
+
+    This is used for final cleanup of an in-memory dataset, which may have been
+    created within a directory to contain sibling files.
+
+    Additional VSI handlers may be chained to the left of /vsimem/ in path and
+    will be ignored.
+
+    Remark: function is defined here to be able to run tests on it.
+
+    Parameters
+    ----------
+    path : str or pathlib.Path
+        path to in-memory file
+
+    """
+    if isinstance(path, Path):
+        path = path.as_posix()
+
+    _vsimem_rmtree_toplevel(path)

pyogrio-0.11.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: pyogrio
+Version: 0.11.0
+Summary: Vectorized spatial vector file format I/O using GDAL/OGR
+Author: pyogrio contributors
+Author-email: "Brendan C. Ward" <bcward@astutespruce.com>
+Maintainer: pyogrio contributors
+License: MIT License
+        
+        Copyright (c) 2020-2024 Brendan C. Ward and pyogrio 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.
+        
+Project-URL: Home, https://pyogrio.readthedocs.io/
+Project-URL: Repository, https://github.com/geopandas/pyogrio
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: certifi
+Requires-Dist: numpy
+Requires-Dist: packaging
+Provides-Extra: dev
+Requires-Dist: cython; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: benchmark
+Requires-Dist: pytest-benchmark; extra == "benchmark"
+Provides-Extra: geopandas
+Requires-Dist: geopandas; extra == "geopandas"
+Dynamic: license-file
+
+# pyogrio - bulk-oriented spatial vector file I/O using GDAL/OGR
+
+Pyogrio provides fast, bulk-oriented read and write access to 
+[GDAL/OGR](https://gdal.org/en/latest/drivers/vector/index.html) vector data
+sources, such as ESRI Shapefile, GeoPackage, GeoJSON, and several others.
+Vector data sources typically have geometries, such as points, lines, or
+polygons, and associated records with potentially many columns worth of data.
+
+The typical use is to read or write these data sources to/from
+[GeoPandas](https://github.com/geopandas/geopandas) `GeoDataFrames`. Because
+the geometry column is optional, reading or writing only non-spatial data is
+also possible. Hence, GeoPackage attribute tables, DBF files, or CSV files are
+also supported.
+
+Pyogrio is fast because it uses pre-compiled bindings for GDAL/OGR to read and
+write the data records in bulk. This approach avoids multiple steps of
+converting to and from Python data types within Python, so performance becomes
+primarily limited by the underlying I/O speed of data source drivers in
+GDAL/OGR.
+
+We have seen \>5-10x speedups reading files and \>5-20x speedups writing files
+compared to using row-per-row approaches (e.g. Fiona).
+
+Read the documentation for more information:
+[https://pyogrio.readthedocs.io](https://pyogrio.readthedocs.io/en/latest/).
+
+## Requirements
+
+Supports Python 3.9 - 3.13 and GDAL 3.4.x - 3.9.x.
+
+Reading to GeoDataFrames requires `geopandas>=0.12` with `shapely>=2`.
+
+Additionally, installing `pyarrow` in combination with GDAL 3.6+ enables
+a further speed-up when specifying `use_arrow=True`.
+
+## Installation
+
+Pyogrio is currently available on
+[conda-forge](https://anaconda.org/conda-forge/pyogrio)
+and [PyPI](https://pypi.org/project/pyogrio/)
+for Linux, MacOS, and Windows.
+
+Please read the
+[installation documentation](https://pyogrio.readthedocs.io/en/latest/install.html)
+for more information.
+
+## Supported vector formats
+
+Pyogrio supports most common vector data source formats (provided they are also
+supported by GDAL/OGR), including ESRI Shapefile, GeoPackage, GeoJSON, and
+FlatGeobuf.
+
+Please see the [list of supported formats](https://pyogrio.readthedocs.io/en/latest/supported_formats.html)
+for more information.
+
+## Getting started
+
+Please read the [introduction](https://pyogrio.readthedocs.io/en/latest/supported_formats.html)
+for more information and examples to get started using Pyogrio.
+
+You can also check out the [API documentation](https://pyogrio.readthedocs.io/en/latest/api.html)
+for full details on using the API.
+
+## Credits
+
+This project is made possible by the tremendous efforts of the GDAL, Fiona, and
+Geopandas communities.
+
+-   Core I/O methods and supporting functions adapted from [Fiona](https://github.com/Toblerity/Fiona)
+-   Inspired by [Fiona PR](https://github.com/Toblerity/Fiona/pull/540/files)