AIO

汇总

可创建一个 ArcIO (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 对象。 cloud_io = AIO(r"C:\data\datacloud.acs") cloud_io.cloud.getprovidername()	Object

方法

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/data/aio")  # 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})

将文件从源复制到目标。

对于基于云的 AIO 对象：

• 如果 src 或 dst 值是本地路径，请使用绝对本地路径。

• 如果 src 或 dst 值是云路径，请使用当前工作目录中的相对路径或绝对 vsi 云路径。

• 如果 src 和 dst 值是云路径，请使用绝对 vsi 云路径。

对于本地 AIO 对象：

• src 和 dst 值可以是当前工作目录中的相对路径，也可以是绝对路径。

名称	说明	数据类型
src	The source path of the file.	String
dst	The target path of the file.	String
options （可选）	Specifies the options that will be used. RECURSIVE—Subdirectories and their contents will be recursively copied. This option is only applicable for folder operations. SYNC_STRATEGY—The criteria that will be used for overwriting if the target file exists. NUM_THREADS—The number of threads that will be used for parallel file copying. CHUNK_SIZE—The maximum chunk size (in bytes) that will be used to split large objects when uploading or downloading. 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})

将内容从一个目录复制到另一个目录。

对于基于云的 AIO 对象：

• 如果 src 或 dst 值是本地路径，请使用绝对本地路径。

• 如果 src 或 dst 值是云路径，请使用当前工作目录中的相对路径或绝对 vsi 云路径。

• 如果 src 和 dst 值是云路径，请使用绝对 vsi 云路径。

对于本地 AIO 对象：

• src 和 dst 值可以是当前工作目录中的相对路径，也可以是绝对路径。

名称	说明	数据类型
src	The source path of the file.	String
dst	The target path of the file.	String
options （可选）	Specifies the options that will be used. RECURSIVE—Subdirectories and their contents will be recursively copied. This option is only applicable for folder operations. SYNC_STRATEGY—The criteria that will be used for overwriting if the target file exists. NUM_THREADS—The number of threads that will be used for parallel file copying. CHUNK_SIZE—The maximum chunk size (in bytes) that will be used to split large objects when uploading or downloading. 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)

验证路径是否存在。

在调用 exists 方法之前使用 CloudFileOp 对象的 clearcache 方法，以便即使外部进程更新云存储，它也能生成正确的结果。

名称	说明	数据类型
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})

构建 URI 路径。

名称	说明	数据类型
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. r—The file will be opened in read mode. w—The file will be opened in write mode. rb—The file will be opened in binary format for reading. wb—The file will be opened in binary format for writing. 注: Only read mode honors the encoding parameter. (默认值为 None)	String
encoding （可选）	The type of encoding that will be used to open a file. utf-8—UTF-8 encoding will be used. This is the default. utf-16—UTF-16 encoding will be used. ascii—ASCII encoding will be used. (默认值为 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[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)

重命名或移动文件或目录。 重命名云文件的运算量较大，因为复制和删除在服务器端执行。

对于基于云的 AIO 对象：

• 如果 src 或 dst 值是本地路径，请使用绝对本地路径。

• 如果 src 或 dst 值是云路径，请使用当前工作目录中的相对路径或绝对 vsi 云路径。

• 如果 src 和 dst 值是云路径，请使用绝对 vsi 云路径。

对于本地 AIO 对象：

• 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}, {prefix})

返回目录中条目的可迭代对象。

名称	说明	数据类型
path	The relative path from the current working directory or an absolute path (absolute vsi path for cloud).	String
depth （可选）	The recursion depth. A value of -1 is for recursive scanning. A value of 0 is for scanning the current directory. A value greater than 0 (>0) is for an arbitrary level. (默认值为 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
prefix （可选）	A filter to select filenames that start with the specified prefix. This is optimized for the cloud, as the filtering is handled by the BLOB storage API. (默认值为 None)	String

返回值

数据类型	说明
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