API参考

堆芯

pyogrio.detect_write_driver(path)

尝试通过扩展名或后缀推断路径的驱动程序。仅会检测到支持写入功能的驱动程序。

如果路径无法解析为单个驱动程序，则将引发Value错误。

参数:

path应力

退货:

应力: 司机的名称（如果检测到）

pyogrio.get_gdal_config_option(name)

获取GDAL配置选项的值。

参数:

name应力: 检索选项的名称

退货:

选项的值或无（如果未设置）: 'ON' / 'OFF' 归一化为 True / False 。

pyogrio.list_drivers(read=False, write=False)

列出GDAL中可用的驱动程序。

参数:

read: bool, optional (default: False): 如果为True，将仅返回已知支持读取功能的驱动程序。
write: bool, optional (default: False): 如果为True，将仅返回已知支持写入功能的驱动程序。

退货:

迪克特: 驱动程序名称到文件模式功能的映射： "r" ：阅读， "w" ：写。可用但支持未知的驱动程序标记为 "?"

pyogrio.list_layers(path_or_buffer, /)

列出OGR数据源中可用的层。

注：包括空间层和非空间层。

参数:

path_or_buffer字符串、pathlib。路径、字节或类似文件

退货:

nd数组形状（2，n）: 对的阵列 [<layer name>, <layer geometry type>] 注：几何是 None 对于非空间层。

pyogrio.read_bounds(path_or_buffer, /, layer=None, skip_features=0, max_features=None, where=None, bbox=None, mask=None)

读取每个要素的界限。

这可以用于协助空间索引和分区，以避免将所有特征读取到内存中。它大约比读取数据集的完整几何形状和属性快2- 3倍。

参数:

path_or_buffer字符串、pathlib。路径、字节或类似文件
layerint或char，可选（默认：第一层）: 如果提供了一个整数，则它对应于具有数据源的层的索引。如果提供了字符串，则它必须与数据源中的层的名称匹配。复制到数据源中的第一层。
skip_featuresint，可选（默认：0）: 在返回功能之前从文件开头跳过的功能数。必须少于文件中要素的总数。
max_featuresint，可选（默认：无）: 要从文件中读取的功能数量。必须小于文件中要素的总数减去 skip_features (if使用）。
where字符串，可选（默认：无）: Where Clause用于按属性值过滤层中的要素。使用受限制形式的SQL UTE Clause，定义在此处：http://ogdi.sourceforge.net/prop/6.2.CapabilitiesMetadata.html示例： "ISO_A3 = 'CAN'" ， "POP_EST > 10000000 AND POP_EST < 100000000"
bbox（xmin，ymin，xmax，ymax）的数组，可选（默认：无）: 如果存在，将用于过滤其几何图形与此框相交的记录。这必须与数据集位于同一个CRS中。如果GEOS存在并由GDAL使用，则仅返回与此bbox相交的几何图形;如果GEOS不可用或GDAL未使用，则将返回具有与此bbox相交的边界框的所有几何图形。
mask形状几何，可选（默认：无）: 如果存在，将用于过滤其几何图形与该几何图形相交的记录。这必须与数据集位于同一个CRS中。如果GDAL存在并使用GEOS，则仅返回与该几何体相交的几何体;如果GDAL不可用或不使用GEOS，则将返回具有与该几何体边界框相交的边界框的所有几何体。要求Shapely >= 2.0。将无法享受 bbox 关键字。

退货:

（fids，bounds）的多元组: fid是从数据集边界的DID字段读取的全局ID是ndArray，形状为（4，n），包含 xmin ， ymin ， xmax ， ymax

pyogrio.read_info(path_or_buffer, /, layer=None, encoding=None, force_feature_count=False, force_total_bounds=False, **kwargs)

阅读有关OGR数据源的信息。

crs ， geometry 和 total_bounds 将会是 None 和 features 对于非空间层，将为0。

features 如果这对该驾驶员来说是一项昂贵的操作，则为-1。您可以强制使用 force_feature_count 参数。

total_bounds 是数据集中所有要素的2维范围：（xmin，ymin，xmax，ymax）。如果这对于该驱动程序来说是一个昂贵的操作，或者如果数据源是非空间的，那么它将为无。您可以强制使用 force_total_bounds 参数。

fid_column 是数据源中DID字段的名称，如果DID以物理方式存储（例如在GPKG中）。如果DID只是一个序列， fid_column 将为“”（例如ESRI Shapetime）。

geometry_name 是数据数据源中存储主要几何图形的字段的名称，如果字段名称可以自定义（例如在GPKG中）。如果不支持自定义名称， geometry_name 将为“”（例如ESRI Shapetime）。

encoding 将会是 UTF-8 如果本地编码可能是 UTF-8 或者GDAL可以自动从检测到的原生编码转换为 UTF-8 。

参数:

path_or_buffer字符串、pathlib。路径、字节或类似文件
layer[type] ，可选: 数据源中层的名称或索引。默认情况下读取第一层。
encoding[type] ，可选（默认：无）: 如果存在，将用作从数据源读取字符串值的编码，除非可以直接从数据源推断编码。
force_feature_count布尔，可选（默认：False）: 如果即使功能计数很贵，也应该计算，则为真。
force_total_bounds布尔，可选（默认：False）: 如果即使计算总边界很贵，也应该计算，则为真。
**kwargs: 其他特定于驱动程序的数据集打开选项传递给OGR。无效的选项将触发警告。

退货:

迪克特

具有以下键的字典：：

{
    "layer_name": "<layer name>",
    "crs": "<crs>",
    "fields": <ndarray of field names>,
    "dtypes": <ndarray of field dtypes>,
    "encoding": "<encoding>",
    "fid_column": "<fid column name or "">",
    "geometry_name": "<geometry column name or "">",
    "geometry_type": "<geometry type>",
    "features": <feature count or -1>,
    "total_bounds": <tuple with total bounds or None>,
    "driver": "<driver>",
    "capabilities": "<dict of driver capabilities>"
    "dataset_metadata": "<dict of dataset metadata or None>"
    "layer_metadata": "<dict of layer metadata or None>"
}

pyogrio.set_gdal_config_options(options)

设置GDAL配置选项。

选项列在此处：https://trac.osgeo.org/gdal/wiki/ConfigOptions

如果提供无效的选项名称，不会引发错误。

这些选项适用于整个会话，而不是单个功能。

参数:

options迪克特: 如果存在，则提供GDAL配置选项的选项名称/值对的映射。 True / False 归一化为 'ON' / 'OFF' .的值 None 配置选项可用于清除之前设置的值。

Geopandas集成

pyogrio.read_dataframe(path_or_buffer, /, layer=None, encoding=None, columns=None, read_geometry=True, force_2d=False, skip_features=0, max_features=None, where=None, bbox=None, mask=None, fids=None, sql=None, sql_dialect=None, fid_as_index=False, use_arrow=None, on_invalid='raise', arrow_to_pandas_kwargs=None, **kwargs)

从OGR数据源读取到GePandas GeoDataFrame或Pandas DataFrame。如果数据源没有几何列或 read_geometry 为假，将返回DataFrame。

需要 geopandas >= 0.8。

参数:

path_or_bufferpathlib。路径或字符串，或字节缓冲区

数据集路径或URI或原始缓冲区。

layerint或char，可选（默认：第一层）

如果提供了一个整数，则它对应于具有数据源的层的索引。如果提供了字符串，则它必须与数据源中的层的名称匹配。复制到数据源中的第一层。

encoding字符串，可选（默认：无）

如果存在，将用作从数据源读取字符串值的编码。默认情况下，将自动尝试检测本地编码并解码以 UTF-8 。

columns类似列表，可选（默认：所有列）

要从数据源导入的列名列表。列名必须与数据源中的名称完全匹配，并将按照它们在数据源中出现的顺序返回。为了避免读取任何列，请传递类似于空列表的列表。如果结合 where 参数，必须包括 where 表达或数据可能无法正确读取;数据源可能返回空结果或引发异常（行为因驱动程序而异）。

read_geometry布尔，可选（默认：True）

如果为True，则会将几何图形读取到地理系列中。如果为假，则返回Pandas DataFrame。

force_2d布尔，可选（默认：False）

如果几何具有Z值，则将其设置为True将导致忽略这些值并返回2D几何

skip_featuresint，可选（默认：0）

在返回功能之前从文件开头跳过的功能数。如果超过可用功能数量，将返回空的数据框架。如果驱动程序不支持随机寻找特定功能的能力，使用此参数可能会产生巨大的负担，因为它需要重写所有先前的功能。

max_featuresint，可选（默认：无）

要从文件中读取的功能数量。

where字符串，可选（默认：无）

Where Clause用于按属性值过滤层中的要素。如果数据源原生支持SQL，则应使用其特定的SQL方言（例如SQLite和地理包： SQLITE 、PostgreSQL）。如果没有， OGRSQL WHERE 应该使用语法。请注意，不可能否决SQL方言，只有当您使用 sql 参数.例子： "ISO_A3 = 'CAN'" ， "POP_EST > 10000000 AND POP_EST < 100000000"

bbox（xmin，ymin，xmax，ymax）的多元组（默认：无）

如果存在，将用于过滤其几何图形与此框相交的记录。这必须与数据集位于同一个CRS中。如果GEOS存在并由GDAL使用，则仅返回与此bbox相交的几何图形;如果GEOS不可用或GDAL未使用，则将返回具有与此bbox相交的边界框的所有几何图形。将无法享受 mask 关键字。

mask形状几何，可选（默认：无）

如果存在，将用于过滤其几何图形与该几何图形相交的记录。这必须与数据集位于同一个CRS中。如果GDAL存在并使用GEOS，则仅返回与该几何体相交的几何体;如果GDAL不可用或不使用GEOS，则将返回具有与该几何体边界框相交的边界框的所有几何体。要求Shapely >= 2.0。将无法享受 bbox 关键字。

fids类数组，可选（默认：无）

要选择的整元特征id（DID）值数组。不能与其他关键词组合选择子集 (skip_features ， max_features ， where ， bbox ， mask ，或 sql ).请注意，开始索引是驱动程序和文件特定的（例如，Shapetime通常为0，GeoPack通常为1，但仍然可以取决于特定的文件）。使用DID读取大量要素的性能也取决于驱动程序，并取决于 use_arrow .返回的行的顺序未定义。如果您想根据DID进行排序，请使用 fid_as_index=True 将返回的GeDataFrame的索引设置为读取的要素的DID。如果 use_arrow=True ，对于默认SQL方言为“OGRSQL”的驱动程序，DID数量限制为4997个。要读取更多数量的DID，请设置 user_arrow=False 。

sql字符串，可选（默认：无）

要执行的SQL声明。请查看SQL_dialong参数，了解有关用于查询的语法的更多信息。当与其他关键词（例如）结合时 columns ， skip_features ， max_features ， where ， bbox ，或 mask ，这些在SQL查询之后应用。请注意，这可能会对性能产生影响（例如，使用 bbox 或 mask 关键词不得使用空间索引）。不能与 layer 或 fids 关键字。

sql_dialect字符串，可选（默认：无）

编写SQL陈述所用的SQL方言。可能的值：

None ：如果数据源原生支持SQL，则默认使用其特定的SQL方言（例如SQLite和Geopackage： SQLITE 、PostgreSQL）。如果数据源本机不支持SQL，则 OGRSQL 方言是默认值。

“' OGRSQL '_'：可用于任何数据源。当在原生支持SQL的数据源上使用时，性能可能会受到影响。

“' SQLITE '_'：可用于任何数据源。所有 spatialite 可以使用功能。在原生支持SQL的数据源上，性能可能会受到影响，Geopackage和SQLite除外，因为这是它们的原生SQL方言。

fid_as_index布尔，可选（默认：False）

如果为True，将使用已读取的要素的DID作为GeoDataFrame的索引。根据驾驶员的不同，可以从0或1开始。

use_arrow布尔，可选（默认：False）

是否使用Arrow作为从GDAL到Python的读取数据的传输机制（要求GDAL >= 3.6且 pyarrow 待安装）。启用后，这将进一步加快速度。默认为False，但也可以通过设置 PYOGRIO_USE_ARROW=1 环境变量。

on_invalid字符串，可选（默认：“raise”）

raise ：如果WKB输入几何无效，将引发异常。
warn ：将发出警告，并返回无效的WKB几何形状， None 。
ignore ：无效的WKB几何将返回为 None 没有任何警告。

arrow_to_pandas_kwargsdict，可选（默认：无）

什么时候 use_arrow is True, these kwargs will be passed to the to_pandas 呼吁将箭头转换为Pandas。

**kwargs

其他特定于驱动程序的数据集打开选项传递给OGR。无效的选项将触发警告。

退货:

GeoDataFrame或DataFrame（如果不存在几何图形）

pyogrio.write_dataframe(df, path, layer=None, driver=None, encoding=None, geometry_type=None, promote_to_multi=None, nan_as_null=True, append=False, use_arrow=None, dataset_metadata=None, layer_metadata=None, metadata=None, dataset_options=None, layer_options=None, **kwargs)

将GeoPandas GeoDataFrame写入OGR文件格式。

参数:

df地理数据框架或数据框架

要写的数据。对于“对象”dype的属性列，所有值都将转换为字符串以写入输出文件，但无和np.nan除外，它们将在输出文件中设置为空。

path字符串或io。字节IO

可写文件系统或io.BytesIO对象上的输出文件路径，以允许写入内存注意：对写入内存的支持仅限于特定驱动程序。

layer字符串，可选（默认：无）

要创建的层名称。如果未提供写入内存和层名称，则层名称将设置为UID 4值。

driver字符串，可选（默认：无）

用于写入载体文件的OGR格式驱动程序。默认情况下，尝试从路径推断驱动程序。必须提供该功能才能写入内存。

encoding字符串，可选（默认：无）

如果存在，将用作将字符串值写入文件的编码。请谨慎使用，只有某些驱动程序支持UTF-8以外的编码。

geometry_type字符串，可选（默认：无）

默认情况下，应用promotion_to_multi逻辑后，将从数据推断出层的几何类型。如果数据仅包含单个几何类型（应用promotion_to_multi逻辑后），则该类型将用于该层。如果数据（仍然）包含混合几何类型，则输出层几何类型将设置为“未知”。

此参数不会修改几何图形，但会尝试将输出文件的层类型强制为此值。请谨慎使用此参数，因为使用非默认层几何类型可能会导致写入文件时出现错误、可能被驱动程序忽略或可能导致无效文件。可能的值包括：“Unknown”、“Point”、“LineString”、“Polygon”、“MultiPoint”、“MultiLineString”、“MultiPolygon”或“GeometryCollection”。

promote_to_multi布尔，可选（默认：无）

如果为True，则会将数据中的奇异几何类型转换为相应的多几何类型以进行写入。默认情况下，对于不支持混合奇异和多几何类型的驱动程序，将混合奇异和多几何类型转换为多几何类型。如果为False，则不会升级几何类型，这可能会在尝试将混合的奇异和多重几何类型写入不支持此类组合的驱动程序时导致错误或无效文件。

nan_as_null布尔，默认为True

对于浮点列（float 32/float 64），NaN值是否被写入“空”（缺失值）。默认为True，因为在大Pandas中，NaN通常被用作缺失值。请注意，当设置为False时，行为是特定于格式的：某些格式默认不支持NaN（例如，GeojSON将跳过此属性）或者可能无论如何都将它们视为空（例如，GeoPack）。

append布尔，可选（默认：False）

如果为True，则路径指定的数据源已存在，并且驱动程序支持附加到现有数据源，将导致数据附加到数据源中的现有记录。不支持写入内存文件。注：附加支持仅限于特定驱动程序和GDAL版本。

use_arrow布尔，可选（默认：False）

是否使用Arrow作为从Python写入GDAL的数据传输机制（要求GDAL >= 3.8和 pyarrow 待安装）。启用后，这将进一步加快速度。默认为False，但也可以通过设置 PYOGRIO_USE_ARROW=1 环境变量。使用Arrow不支持编写具有混合类型的对象数据类型列。

dataset_metadatadict，可选（默认：无）

元数据将存储在输出文件中的数据集级别;仅限于支持写入元数据的驱动程序（例如GPKG），否则将被悄然忽略。键和值必须是字符串。

layer_metadatadict，可选（默认：无）

元数据将存储在输出文件中的层级;仅限于支持写入元数据的驱动程序（例如GPGK），否则将被悄然忽略。键和值必须是字符串。

metadatadict，可选（默认：无）

Layer_metals的别名

dataset_options法令，可选

数据集创建选项（特定格式）传递给OGR。指定为key-Value字典。

layer_options法令，可选

层创建选项（特定格式）传递给OGR。指定为key-Value字典。

**kwargs

将其他特定于驱动器的数据集或层创建选项传递给OGR。pyogrio将尝试根据特定驱动程序的已知选项自动将这些关键字作为数据集或作为层创建选项传递。或者，您可以使用显式的 dataset_options 或 layer_options 手动执行此操作的关键字（例如，如果选项同时作为数据集和层选项存在）。

箭头集成

pyogrio.read_arrow(path_or_buffer, /, layer=None, encoding=None, columns=None, read_geometry=True, force_2d=False, skip_features=0, max_features=None, where=None, bbox=None, mask=None, fids=None, sql=None, sql_dialect=None, return_fids=False, **kwargs)

将OGR数据源读取到pyarrow表中。

请参阅文档字符串 read 用于参数。

退货:

(dict、pyarrow.表）

返回有关dict中数据源的Meta信息的多元组，以及包含数据的pyarrow Table。

Meta是：{: “crs”：“<crs>”，“fields”：<ndarray of field names>，“encoding”：“<encoding>”，“geography_style”：“<geometry_type>”，“geography_list”：“<name of geometry column in arrow table>”，

}

pyogrio.open_arrow(path_or_buffer, /, layer=None, encoding=None, columns=None, read_geometry=True, force_2d=False, skip_features=0, max_features=None, where=None, bbox=None, mask=None, fids=None, sql=None, sql_dialect=None, return_fids=False, batch_size=65536, use_pyarrow=False, **kwargs)

将OGR数据源打开为Arrow记录批次流。

请参阅文档字符串 read 用于参数。

返回的对象正在从OGR提供的流中读取，并且在OGR数据集关闭后（即在上下文管理器关闭后）不得访问该对象。

默认情况下，此函数返回实现 Arrow PyCapsule Protocol (i.e.具有 __arrow_c_stream__ 方法）。然后，您选择的支持此协议的Arrow实现可以使用此对象。或者，您可以指定 use_pyarrow=True 直接获取流作为 pyarrow.RecordBatchReader 。

退货:

(dict、pyarrow.RecordBatchReader或ArrowStream）

返回有关dict中数据源的Meta信息的多元组和数据流对象（通用ArrowStream对象，或pyarrow RecordBatchReader，如果 use_pyarrow 设置为True）。

Meta是：{: “crs”：“<crs>”，“fields”：<ndarray of field names>，“encoding”：“<encoding>”，“geography_style”：“<geometry_type>”，“geography_list”：“<name of geometry column in arrow table>”，

}

其他参数:

batch_sizeint（默认：65_536）: 批量检索的最大要素数。
use_pyarrow布尔（默认：假）: 如果为True，则返回pyarrow RecordBatchReader，而不是通用ArrowStream对象。在默认情况下，此流对象需要传递到另一个支持Arrow PyCapsule协议的库才能消费数据流。

实例

>>> from pyogrio.raw import open_arrow
>>> import pyarrow as pa
>>> import shapely
>>>
>>> with open_arrow(path) as source:
>>>     meta, stream = source
>>>     # wrap the arrow stream object in a pyarrow RecordBatchReader
>>>     reader = pa.RecordBatchReader.from_stream(stream)
>>>     for batch in reader:
>>>         geometries = shapely.from_wkb(batch[meta["geometry_name"] or "wkb_geometry"])

归来的人 stream 对象需要由实现Arrow PyCapsule协议的库消费。在上面的示例中，pyarrow通过其RecordBatchReader使用。对于这种情况，您还可以指定 use_pyarrow=True 直接获得此结果作为捷径：

>>> with open_arrow(path, use_pyarrow=True) as source:
>>>     meta, reader = source
>>>     for batch in reader:
>>>         geometries = shapely.from_wkb(batch[meta["geometry_name"] or "wkb_geometry"])

pyogrio.write_arrow(arrow_obj, path, layer=None, driver=None, geometry_name=None, geometry_type=None, crs=None, encoding=None, append=False, dataset_metadata=None, layer_metadata=None, metadata=None, dataset_options=None, layer_options=None, **kwargs)

将Arrow兼容的数据源写入OGR文件格式。

参数:

arrow_obj

要写入的箭头数据。这可以是实现 Arrow PyCapsule Protocol (i.e.具有 __arrow_c_stream__ 方法），例如pyarrow Table或RecordBatchReader。

path字符串或io。字节IO

可写文件系统或io.BytesIO对象上的输出文件路径，以允许写入内存注意：对写入内存的支持仅限于特定驱动程序。

layer字符串，可选（默认：无）

要创建的层名称。如果未提供写入内存和层名称，则层名称将设置为UID 4值。

driver字符串，可选（默认：无）

用于写入载体文件的OGR格式驱动程序。默认情况下，尝试从路径推断驱动程序。必须提供该功能才能写入内存。

geometry_name字符串，可选（默认：无）

输入数据中将写入几何字段的列的名称。如果几何列注释为“gearrow.wKB”或“ogc.wKB”扩展类型，则将从输入数据中推断出来。否则需要显式指定。

geometry_type应力

写入层的几何类型。目前，在创建具有几何图形的新层时需要明确指定这一点。可能的值包括：“Unknown”、“Point”、“LineString”、“Polygon”、“MultiPoint”、“MultiLineString”、“MultiPolygon”或“GeometryCollection”。

此参数不会修改几何图形，但会尝试将输出文件的层类型强制为此值。请谨慎使用此参数，因为使用错误的层几何类型可能会导致写入文件时出现错误、可能被驱动程序忽略或可能导致无效文件。

encoding字符串，可选（默认：无）

仅用于ESRI Shapefiles的.dbf文件。如果未指定，则使用默认区域设置。

append布尔，可选（默认：False）

如果为True，则路径指定的数据源已存在，并且驱动程序支持附加到现有数据源，将导致数据附加到数据源中的现有记录。不支持写入内存文件。注：附加支持仅限于特定驱动程序和GDAL版本。

dataset_metadatadict，可选（默认：无）

元数据将存储在输出文件中的数据集级别;仅限于支持写入元数据的驱动程序（例如GPKG），否则将被悄然忽略。键和值必须是字符串。

layer_metadatadict，可选（默认：无）

元数据将存储在输出文件中的层级;仅限于支持写入元数据的驱动程序（例如GPGK），否则将被悄然忽略。键和值必须是字符串。

metadatadict，可选（默认：无）

Layer_metals的别名

dataset_options法令，可选

数据集创建选项（特定格式）传递给OGR。指定为key-Value字典。

layer_options法令，可选

层创建选项（特定格式）传递给OGR。指定为key-Value字典。

**kwargs

将其他特定于驱动器的数据集或层创建选项传递给OGR。pyogrio将尝试根据特定驱动程序的已知选项自动将这些关键字作为数据集或作为层创建选项传递。或者，您可以使用显式的 dataset_options 或 layer_options 手动执行此操作的关键字（例如，如果选项同时作为数据集和层选项存在）。