摘要
可创建一个 AIO 对象以采用适用于 Python 的统一方式处理本地文件、云文件和数据存储。
使用此对象,您可以执行多种任务,例如在两个位置之间复制文件、重命名或删除文件夹以及包括读取和写入在内的与内容归档相关的操作。 通过指定 .acs 文件的路径作为输入,可将 AIO 对象用于云存储。 对于本地数据存储,可以通过指定本地文件夹路径(后续将用作当前工作目录)来创建 AIO 对象,也可以不指定任何参数值。
说明
AIO 对象支持不考虑文件系统的文件操作。 该对象当前支持 Windows、Linux 和主要的云存储实现。
除了本地文件系统和 UNC 路径之外,AIO 对象还支持以下虚拟云 URI 用于类初始化:
- ACS 连接文件 (.acs) - 以二进制持久化加密格式存储连接信息。 有关详细信息,请参阅创建云存储连接文件工具。
- /cloudStores json - 以适用于 ArcGIS Enterprise 的 JSON 格式存储连接信息。
- /vsi paths - 在不考虑文件系统的文件操作中,GDAL 为首选 URI。 有关详细信息,请参阅 GDAL 虚拟文件系统。
- http[s] paths - 资源的云提供商 URL,有时包含连接信息,如 Microsoft Azure SAS。
- 一个特定于云提供商的 URI 模式前缀,例如 s3:// 或 abfs://。
注:
还可以通过 IAM/RBAC、GDAL 环境选项和 .aws、.azure 或 bin/gdalrc 文件夹中的提供商特定的 CLI 配置文件来使用连接信息。
所有特定于云的方法均可以使用 cloud 属性访问。
在处理云操作时,类方法支持当前工作目录的相对路径 (aio.getcwd)。 如果使用绝对路径,则仅支持 vsi 路径。 这些类型的操作默认会返回 vsi 路径。 该输出路径类型可以通过提供 CloudPathType 枚举来覆盖。
这些方法遵循与 Python 原生文件系统方法相同的约定和行为。
语法
AIO ({path})
参数 | 说明 | 数据类型 |
path | To construct an AIO object to handle a cloud store, use the .acs file path. To construct an AIO object to handle a local file store, this parameter can be a local folder path or it can be left empty. If a local folder path is provided, it will be used as the current working directory. | String |
属性
属性 | 说明 | 数据类型 |
cloud (只读) | 具有特定于云的方法的类实例。 创建 AIO 对象时,用于检索所使用的云存储的详细信息。 返回 CloudOp 对象。
| Object |
方法概述
方法 | 说明 |
chdir (path) | 相对于当前工作目录执行工作目录更改。 |
close (handle) | 关闭打开的文件句柄。 |
copy (src, dst, {options}) | 将文件从源复制到目标。 对于基于云的 AIO 对象:
对于本地 AIO 对象:
|
copytree (src, dst, {options}) | 将内容从一个目录复制到另一个目录。 对于基于云的 AIO 对象:
对于本地 AIO 对象:
|
exists (path) | 验证路径是否存在。 |
getatime (path) | 获取文件的访问时间。 |
getctime (path) | 获取文件的创建时间。 |
getcwd ({type}) |
获取当前工作目录。 |
getmtime (path) |
获取文件的修改时间。 |
getpath (path, {type}) |
构建 URI 路径。 |
getsize (path) | 获取以字节为单位的文件大小。 |
isdir (path) | 验证路径是否为目录。 |
isfile (path) | 验证路径是否为文件。 |
listdir ({path}, {type}) |
以非递归方式列出目录的内容。 |
makedirs (path) | 以递归方式创建目录。 |
mkdir (path) | 创建目录。 |
open (path, {mode}, {encoding}, {mime}) | 打开文件句柄。 该句柄必须显式关闭。 |
remove (path) | 删除文件。 |
removefiles (path) | 删除多个文件。 |
rename (src, dst) | 重命名或移动文件或目录。 重命名云文件的运算量较大,因为复制和删除在服务器端执行。 对于基于云的 AIO 对象:
对于本地 AIO 对象:
|
rmtree (path) | 以递归方式移除目录及其内容。 |
scandir (path, {depth}, {type}) |
返回目录中条目的可迭代对象。 |
方法
chdir (path)
参数 | 说明 | 数据类型 |
path | A relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.chdir(r"aio") # relative path
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.chdir(r"/vsis3/u-agu/arcio") # absolute VSI path
local_io = AIO(r"C:\data")
local_io.chdir(r"aio")
close (handle)
参数 | 说明 | 数据类型 |
handle | An open file handle. The data type is AIOFile. 注:An instance of this class is returned by the AIO object's open method. | Object |
cloud_io = AIO(r"C:\data\datacloud.acs")
rcsfile = cloud_io.open(r'testfile.txt', 'r')
rcsfile.read(size=4)
cloud_io.close(rcsfile)
copy (src, dst, {options})
参数 | 说明 | 数据类型 |
src | The source path of the file. | String |
dst | The target path of the file. | String |
options | Specifies the options that will be used.
Syntax—RECURSIVE=[YES|NO], SYNC_STRATEGY=[TIMESTAMP|ETAG|OVERWRITE], NUM_THREADS=(integer) CHUNK_SIZE=(integer) [x-amz-*|x-goog-*|x-ms-*=(value)] Example—{'RECURSIVE':'YES', 'SYNC_STRATEGY':'OVERWRITE', 'NUM_THREADS':'10', 'CHUNK_SIZE':'8'} (默认值为 None) | Dictionary |
数据类型 | 说明 |
String | 目标路径。 |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.copy(r'/vsis3/data/list/utf8_test.json',
r'/vsis3/data/list/new_dir_new/utf8_test.json')
local_io = AIO(r"C:\data")
local_io.copy(r"C:\data\datatest.json", r"C:\data_temp\datatest.json")
copytree (src, dst, {options})
参数 | 说明 | 数据类型 |
src | The source path of the file. | String |
dst | The target path of the file. | String |
options | Specifies the options that will be used.
Syntax—RECURSIVE=[YES|NO], SYNC_STRATEGY=[TIMESTAMP|ETAG|OVERWRITE], NUM_THREADS=(integer) CHUNK_SIZE=(integer) [x-amz-*|x-goog-*|x-ms-*=(value)] Example— {'RECURSIVE':'YES', 'SYNC_STRATEGY':'OVERWRITE', 'NUM_THREADS':'10', 'CHUNK_SIZE':'8'} (默认值为 None) | Dictionary |
数据类型 | 说明 |
String | 目标路径。 |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.copytree(r'/vsis3/data/list', r'/vsis3/data/data_new_dir')
local_io = AIO(r"C:\data")
local_io.copytree(r"C:\data\list", r"C:\data\data_new_dir")
exists (path)
参数 | 说明 | 数据类型 |
path | A relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
数据类型 | 说明 |
Boolean | 如果目录或文件存在,则为 True,否则为 False。 |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.exists(r"C:\data\datacloud.acs\data")
getatime (path)
参数 | 说明 | 数据类型 |
path | The path for which the access time will be obtained. The value can be a relative path from the current working directory or an absolute path. | String |
数据类型 | 说明 |
Double | 自新纪元以来的访问时间(以秒数表示)。 |
此方法不适用于云存储。
local_io = AIO(r"C:\data")
local_io.getatime(r"data.json")
getctime (path)
参数 | 说明 | 数据类型 |
path | The path for which the creation time will be obtained. The value can be a relative path from the current working directory or an absolute path. | String |
数据类型 | 说明 |
Double | 自新纪元以来的创建时间(以秒数表示)。 |
此方法不适用于云存储。
local_io = AIO(r"C:\data")
local_io.getctime(r"data.json")
getcwd ({type})
参数 | 说明 | 数据类型 |
type | Specifies the path style for the returned URI (for cloud only). The data type is CloudPathType. Available options are CloudPathType.VSI, CloudPathType.ACS, CloudPathType.HTTP, and CloudPathType.CLOUDSTORES. (默认值为 CloudPathType.VSI) | Object |
数据类型 | 说明 |
String | 当前工作目录。 |
local_io = AIO()
local_io.getcwd()
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.getcwd()
getmtime (path)
参数 | 说明 | 数据类型 |
path |
The relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
数据类型 | 说明 |
Double | 自新纪元以来的文件修改时间(以秒数表示)。 |
local_io = AIO(r"C:\data")
local_io.getmtime(r"data.json")
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.getmtime(r"data.json")
getpath (path, {type})
参数 | 说明 | 数据类型 |
path | The relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
type | Specifies the path style for the returned URI (for cloud only). The data type is CloudPathType. Available options are CloudPathType.VSI, CloudPathType.ACS, CloudPathType.HTTP, and CloudPathType.CLOUDSTORES. (默认值为 CloudPathType.VSI) | Object |
数据类型 | 说明 |
String | 构建的 URI 路径。 |
from arcpy import CloudPathType
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.getpath('cog.tif', CloudPathType.HTTP)
getsize (path)
参数 | 说明 | 数据类型 |
path | The relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
数据类型 | 说明 |
Integer | 以字节为单位的文件大小。 |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.getsize(r'cog.tif')
isdir (path)
参数 | 说明 | 数据类型 |
path | A relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
数据类型 | 说明 |
Boolean | 如果目录存在,则为 True,否则为 False。 |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.isdir(r'cog')
isfile (path)
参数 | 说明 | 数据类型 |
path | A relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
数据类型 | 说明 |
Boolean | 如果文件存在,则为 True,否则为 False。 |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.isfile(r'cog')
listdir ({path}, {type})
参数 | 说明 | 数据类型 |
path | The relative path from the current working directory or an absolute path (absolute vsi path for cloud). (默认值为 None) | String |
type | Specifies the path style for the returned URI (for cloud only). The data type is CloudPathType. Available options are CloudPathType.VSI, CloudPathType.ACS, CloudPathType.HTTP, and CloudPathType.CLOUDSTORES. (默认值为 CloudPathType.VSI) | Object |
数据类型 | 说明 |
String | 文件夹中文件名的列表。 |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.listdir('data_folder')
from arcpy import CloudPathType
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.listdir('data_folder', CloudPathType.ACS)
local_io = AIO(r"C:\data")
local_io.listdir()
makedirs (path)
参数 | 说明 | 数据类型 |
path | A relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.makedirs(r"datasensor\datatest\data")
mkdir (path)
参数 | 说明 | 数据类型 |
path | A relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.mkdir(r'cog')
open (path, {mode}, {encoding}, {mime})
参数 | 说明 | 数据类型 |
path | A relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
mode | Specifies the mode that will be used for opening a file.
注:Only read mode honors the encoding parameter. (默认值为 None) | String |
encoding | The type of encoding that will be used to open a file.
(默认值为 utf-8) | String |
mime | The Multipurpose Internet Mail Extensions (MIME) headers. It is recommended that you set MIME headers when creating the file for faster creation and setting of metadata. (默认值为 None) | Dictionary |
数据类型 | 说明 |
File | 返回 AIOFile 对象。 |
from arcpy import AIO
local_io = AIO(r"C:\data")
rcsfile = local_io.open(r'testfile.txt', 'r')
rcsfile.write("This is a test file.")
rcsfile.close()
from arcpy import AIO
cloud_io = AIO(r"C:\data\datacloud.acs")
rcsfile = cloud_io.open(r"C:\data\info\datafile.txt", 'w', mime={'Content-Type': 'text/plain'})
rcsfile.write("This is a test file.")
rcsfile.close()
# Using with statement (context manager to close the opened file)
cloud_io = AIO(r"C:\data\datacloud.acs")
with cloud_io.open(r"C:\data\info\datafile.txt", 'w', mime={'Content-Type': 'text/plain'}) as rcsfile:
rcsfile.write("This is a test file.")
remove (path)
参数 | 说明 | 数据类型 |
path | A relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.remove(r'rcsfile.txt')
local_io = AIO(r"c:\data")
local_io.remove(r'rcsfile.txt')
removefiles (path)
参数 | 说明 | 数据类型 |
path [path,...] | The relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
数据类型 | 说明 |
List | 在失败时返回未移除路径的列表。 |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.removefiles(['/vsis3/data/list/to_be_deleted/datatest.json','/vsis3/u-agu/list/to_be_deleted/data_new.json'])
local_io = AIO(r"c:\data")
local_io.removefiles([r'C:\data\datatest.json',r'C:\data\data_new.json'])
rename (src, dst)
参数 | 说明 | 数据类型 |
src | The source path of the file. | String |
dst | The target path of the file. | String |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.rename(r'to_be_renamed/cog.tif',r'to_be_renamed/cognew.tif')
local_io = AIO(r"C:\data")
local_io.rename(r'test.json',r'new_test.json')
rmtree (path)
参数 | 说明 | 数据类型 |
path | The relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.rmtree(r"aio") # Relative path
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.rmtree(r"/vsis3/data/arcio") # Absolute VSI path
local_io = AIO(r"C:\data")
local_io.rmtree(r"aio")
scandir (path, {depth}, {type})
参数 | 说明 | 数据类型 |
path | The relative path from the current working directory or an absolute path (absolute vsi path for cloud). | String |
depth | The recursion depth.
(默认值为 0) | Integer |
type | Specifies the path style for the returned URI (for cloud only). The data type is CloudPathType. Available options are CloudPathType.VSI, CloudPathType.ACS, CloudPathType.HTTP, and CloudPathType.CLOUDSTORES. (默认值为 CloudPathType.VSI) | Object |
数据类型 | 说明 |
Iterable | AIODirEntry 对象的可迭代对象。 |
cloud_io = AIO(r"C:\data\datacloud.acs")
# Depth = 0, performs cur dir scanning only
from arcpy import CloudPathType
for item in cloud_io.scandir(r'list', depth=0, type=CloudPathType.HTTP):
print(item.path)
print(item.is_dir())
print(item.is_file())
ob = item.stat()
print(ob.st_mode)
# Cloud specific operations through cloud property
print(item.cloud.getvsipath())
print(item.cloud.getpath(CloudPathType.ACS))
local_io = AIO(r"c:\data")
# Depth = -1, performs recursive scanning
for item in local_io.scandir(r'aio', -1):
print(item.name)
print(item.path)
print(item.is_dir())
print(item.is_file())
ob = item.stat()
print(ob.st_mode)
代码示例
# To create an AIO object based on cloud store
cloud_io = AIO(r"C:\data\datacloud.acs")
cloud_io.getcwd()
cloud_io.listdir(r'aio')
# aio is a virtual folder in the cloud store referred in datacloud.acs
# To create an AIO object based on local file system
local_io = AIO()
local_io.getcwd() # Returns the current working directory
# To create an AIO object based on local file system with path parameter
local_io = AIO(r"C:\data") # Set the current working directory as C:\data
local_io.getcwd() # Return the current working directory that is C:\data