AIO

摘要

可创建一个 AIO 对象以采用适用于 Python 的统一方式处理本地文件、云文件和数据存储。

使用此对象,您可以执行多种任务,例如在两个位置之间复制文件、重命名或删除文件夹以及包括读取和写入在内的与内容归档相关的操作。 通过指定 .acs 文件的路径作为输入,可将 AIO 对象用于云存储。 对于本地数据存储,可以通过指定本地文件夹路径(后续将用作当前工作目录)来创建 AIO 对象,也可以不指定任何参数值。

说明

AIO 对象支持不考虑文件系统的文件操作。 该对象当前支持 WindowsLinux 和主要的云存储实现。

除了本地文件系统和 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.azurebin/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)

相对于当前工作目录执行工作目录更改。

close (handle)

关闭打开的文件句柄。

copy (src, dst, {options})

将文件从源复制到目标。

对于基于云的 AIO 对象:

  • 如果 srcdst 值是本地路径,请使用绝对本地路径。
  • 如果 srcdst 值是云路径,请使用当前工作目录中的相对路径或绝对 vsi 云路径。
  • 如果 srcdst 值是云路径,请使用绝对 vsi 云路径。

对于本地 AIO 对象:

  • srcdst 值可以是当前工作目录中的相对路径,也可以是绝对路径。
copytree (src, dst, {options})

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

对于基于云的 AIO 对象:

  • 如果 srcdst 值是本地路径,请使用绝对本地路径。
  • 如果 srcdst 值是云路径,请使用当前工作目录中的相对路径或绝对 vsi 云路径。
  • 如果 srcdst 值是云路径,请使用绝对 vsi 云路径。

对于本地 AIO 对象:

  • srcdst 值可以是当前工作目录中的相对路径,也可以是绝对路径。
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 对象:

  • 如果 srcdst 值是本地路径,请使用绝对本地路径。
  • 如果 srcdst 值是云路径,请使用当前工作目录中的相对路径或绝对 vsi 云路径。
  • 如果 srcdst 值是云路径,请使用绝对 vsi 云路径。

对于本地 AIO 对象:

  • srcdst 值可以是当前工作目录中的相对路径,也可以是绝对路径。
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.

  • 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})
参数说明数据类型
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)
参数说明数据类型
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.

  • 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,...]

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.

  • 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
返回值
数据类型说明
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