存储管理器

类 StorageManager()​

StorageManager 是一个用于下载和上传文件到支持的远程存储的辅助接口 支持的远程服务器：http(s)/S3/GS/Azure/文件系统文件夹 默认情况下，所有下载的远程URL/文件都启用了缓存

StorageManager.download_file​

classmethod download_file(remote_url, local_folder=None, overwrite=False, skip_zero_size_check=False, silence_errors=False)

将远程文件下载到本地机器，保持远程存储中的子文件夹结构。

• 参数

  • remote_url (str ) – 源远程存储位置，remote_url的路径将在目标local_folder下创建。支持S3/GS/Azure和共享文件系统。 示例：'s3://bucket/data/'

  • overwrite (bool ) – 如果为False，并且目标文件存在，则不下载。 如果为True，则始终下载远程文件。默认为False。

  • skip_zero_size_check (bool ) – 如果为True，则不会对大小为0字节的文件抛出错误。

  • silence_errors (bool ) – 如果为True，则在尝试下载远程存储的文件时静默可能出现的错误。默认为False

  • local_folder (可选 [ str ] ) –

• 返回类型

  Optional[str]

• 返回

  下载文件的路径或出错时为None

StorageManager.download_folder​

classmethod download_folder(remote_url, local_folder=None, match_wildcard=None, overwrite=False, skip_zero_size_check=False, silence_errors=False, max_workers=None)

递归下载远程文件夹到本地机器，保持远程存储中的子文件夹结构。

• 参数

  • remote_url (str ) – 源远程存储位置，remote_url的树结构将在目标local_folder下创建。支持S3/GS/Azure和共享文件系统。 示例：'s3://bucket/data/'

  • local_folder (str ) – 从remote_url创建完整树的本地目标文件夹。 如果为None，则使用缓存文件夹。（默认：使用缓存文件夹）

  • match_wildcard (Optional[str]) – 如果指定，则仅下载与 match_wildcard 匹配的文件 示例: *.json

  • overwrite (bool ) – 如果为False，并且目标文件存在，则不下载。 如果为True，则始终下载远程文件。默认为False。

  • skip_zero_size_check (bool ) – 如果为True，则不会对大小为0字节的文件抛出错误。

  • silence_errors (bool ) – 如果为True，则在尝试下载远程存储的文件时静默可能出现的错误。默认为False

  • max_workers (int ) – 如果值设置为一个数字， 它将生成指定数量的工作线程 以并行下载文件夹的内容。否则，如果设置为 None，它将 内部使用与系统中逻辑 CPU 核心数量相同的线程 （这是 Python 的默认行为）。默认值为 None

• 返回类型

  Optional[str]

• 返回

  目标本地文件夹

StorageManager.exists_file​

classmethod exists_file(remote_url)

检查远程文件是否存在。请注意，此函数将返回 False 对于目录。

• 参数

  remote_url (str ) – 文件存储的URL。 例如：‘s3://bucket/some_file.txt’, ‘file://local/file’

• 返回类型

  bool

• 返回

  如果 remote_url 存储了一个文件则为 True，否则为 False

StorageManager.get_file_size_bytes​

classmethod get_file_size_bytes(remote_url, silence_errors=False)

获取远程文件的大小，单位为字节。

• 参数

  • remote_url (str ) – 文件存储的URL。 例如：‘s3://bucket/some_file.txt’, ‘file://local/file’

  • silence_errors (bool ) – 在获取文件大小时，静默可能发生的错误。默认值：False

• 返回类型

  [int, None]

• 返回

  文件的大小，以字节为单位。 如果找不到文件或发生错误，则为None。

StorageManager.get_local_copy​

classmethod get_local_copy(remote_url, cache_context=None, extract_archive=True, name=None, force_download=False)

获取远程文件的本地副本。如果远程URL是直接文件访问，返回的链接是相同的，否则返回指向URL文件本地副本的链接。默认情况下启用缓存，缓存受每个缓存上下文存储的文件数量限制。当缓存满时，最早访问的文件将被删除。还可以使用此函数来防止已缓存文件的删除，因为相应的文件将刷新其时间戳。

• 参数

  • remote_url (str ) – 远程链接地址 (字符串)

  • cache_context (str ) – 可选的缓存上下文标识符（字符串），默认上下文为‘global’

  • extract_archive (bool ) – 如果为True，返回的路径将是一个包含存档内容的缓存文件夹， 目前仅支持zip文件。

  • name (str ) – 目标文件的名称

  • force_download (bool ) – 即使本地缓存中存在文件，也从远程下载文件

• 返回类型

  [str, None]

• 返回

  请求的URL的本地副本的完整路径。出错时返回None。

StorageManager.get_metadata​

classmethod get_metadata(remote_url, return_full_path=False)

获取远程对象的元数据。 元数据是一个包含以下键的字典：名称、大小。

• 参数

  • remote_url (str ) – 源远程存储位置，remote_url的树结构将在目标local_folder下创建。支持S3/GS/Azure、共享文件系统和http(s)。 示例：'s3://bucket/data/'

  • return_full_path (bool) – 如果为True，则返回完整路径（包含基础URL）

• 返回类型

  Optional[dict]

• 返回

  包含远程对象元数据的字典。如果发生错误，则返回 None

StorageManager.list​

classmethod list(remote_url, return_full_path=False, with_metadata=False)

返回基本路径内的对象名称列表或包含相应对象元数据的字典（如果with_metadata为True）

• 参数

  • remote_url (str ) – 基本路径。 对于Google Storage、Azure和S3，它是路径的存储桶，对于本地文件，它是根目录。 例如：AWS S3: s3://bucket/folder_ 将列出你在 s3://bucket-name/folder_*/* 中的所有文件。Google Storage 也有相同的行为：gs://bucket/folder_, Azure blob 存储：azure://bucket/folder_ 以及文件系统列表：/mnt/share/folder_

  • return_full_path (bool ) – 如果为True，返回完整对象路径的列表，否则返回相对对象路径的列表（默认为False）。

  • with_metadata (bool) – 不仅返回对象的名称，还返回包含远程文件名称和元数据的字典列表。因此，每个字典将包含以下键：name, size。 return_full_path 将修改每个字典条目的名称为完整路径。

• 返回类型

  Optional[List[Union[str, dict]]]

• 返回

  所有对象的路径，存储基础路径下的前缀或包含对象元数据的字典，相对于基础路径。如果列表操作不受支持（例如http和https协议），则为None。

StorageManager.set_cache_file_limit​

classmethod set_cache_file_limit(cache_file_limit, cache_context=None)

设置缓存上下文文件限制。文件限制是特定缓存上下文持有的最大文件数量。 请注意，这些文件的大小没有限制，只有缓存文件的总数有限制。

• 参数

  • cache_file_limit (int ) – 新的缓存文件最大数量

  • cache_context (str ) – 可选的缓存上下文标识符，默认为全局上下文

• 返回类型

  int

• 返回

  新的缓存上下文文件限制。

StorageManager.set_report_download_chunk_size​

classmethod set_report_download_chunk_size(chunk_size_mb)

设置下载进度报告的块大小（以MB为单位）。块大小决定了进度报告的记录频率： 每次下载的数据块大小超过chunk_size_mb时，记录报告。 此函数会覆盖sdk.storage.log.report_download_chunk_size_mb配置项

• 参数

  chunk_size_mb (int ) – 块大小，以兆字节为单位

• 返回类型

  ()

StorageManager.set_report_upload_chunk_size​

classmethod set_report_upload_chunk_size(chunk_size_mb)

设置上传进度报告的块大小（以MB为单位）。块大小决定了进度报告的记录频率：每次上传的数据块大小超过chunk_size_mb时，记录报告。此函数会覆盖sdk.storage.log.report_upload_chunk_size_mb配置项。

• 参数

  chunk_size_mb (int ) – 块大小，以兆字节为单位

• 返回类型

  ()

StorageManager.upload_file​

classmethod upload_file(local_file, remote_url, wait_for_upload=True, retries=None)

将本地文件上传到远程位置。远程URL是上传文件的最终目的地。

示例：

upload_file('/tmp/artifact.yaml', 'http://localhost:8081/manual_artifacts/my_artifact.yaml')
upload_file('/tmp/artifact.yaml', 's3://a_bucket/artifacts/my_artifact.yaml')
upload_file('/tmp/artifact.yaml', '/mnt/share/folder/artifacts/my_artifact.yaml')

• 参数

  • local_file (str ) – 要上传的本地文件的完整路径

  • remote_url (str ) – 上传的完整路径或远程URL（包括文件名）

  • wait_for_upload (bool ) – 如果为False，立即返回并在后台上传。默认为True。

  • retries (int ) – 上传文件失败前的重试次数。

• 返回类型

  str

• 返回

  新上传的远程URL。

StorageManager.upload_folder​

classmethod upload_folder(local_folder, remote_url, match_wildcard=None, retries=None)

将本地文件夹递归上传到远程存储，保持远程存储中的子文件夹结构。

• 参数

  • local_folder (str ) – 要递归上传的本地文件夹

  • remote_url (str ) – 目标远程存储位置，本地文件夹的树结构将在目标remote_url下创建。支持Http/S3/GS/Azure和共享文件系统。 示例：'s3://bucket/data/'

  • match_wildcard (str ) – 如果指定，则仅上传与 match_wildcard 匹配的文件 示例: *.json 注意：不检查目标文件的大小/日期。默认为 True，始终上传。 注意：如果上传到 http，我们将始终覆盖目标。

  • retries (int ) – 在上传文件夹中的文件失败之前重试的次数。

• 返回类型

  Optional[str]

• 返回

  新上传的远程URL或出错时为None。