LocalBackend

class mmengine.fileio.LocalBackend

Raw local storage backend.

copy_if_symlink_fails(src, dst)

Create a symbolic link pointing to src named dst.

If failed to create a symbolic link pointing to src, directly copy src to dst instead.

参数:

• src (str or Path) – Create a symbolic link pointing to src.

• dst (str or Path) – Create a symbolic link named dst.

返回:

Return True if successfully create a symbolic link pointing to src. Otherwise, return False.

返回类型:

bool

示例

>>> backend = LocalBackend()
>>> src = '/path/of/file'
>>> dst = '/path1/of/file1'
>>> backend.copy_if_symlink_fails(src, dst)
True
>>> src = '/path/of/dir'
>>> dst = '/path1/of/dir1'
>>> backend.copy_if_symlink_fails(src, dst)
True

copyfile(src, dst)

Copy a file src to dst and return the destination file.

src and dst should have the same prefix. If dst specifies a directory, the file will be copied into dst using the base filename from src. If dst specifies a file that already exists, it will be replaced.

参数:

• src (str or Path) – A file to be copied.

• dst (str or Path) – Copy file to dst.

返回:

The destination file.

返回类型:

str

抛出:

SameFileError – If src and dst are the same file, a SameFileError will be raised.

示例

>>> backend = LocalBackend()
>>> # dst is a file
>>> src = '/path/of/file'
>>> dst = '/path1/of/file1'
>>> # src will be copied to '/path1/of/file1'
>>> backend.copyfile(src, dst)
'/path1/of/file1'

>>> # dst is a directory
>>> dst = '/path1/of/dir'
>>> # src will be copied to '/path1/of/dir/file'
>>> backend.copyfile(src, dst)
'/path1/of/dir/file'

copyfile_from_local(src, dst)

Copy a local file src to dst and return the destination file. Same as copyfile().

参数:

• src (str or Path) – A local file to be copied.

• dst (str or Path) – Copy file to dst.

返回:

If dst specifies a directory, the file will be copied into dst using the base filename from src.

返回类型:

str

抛出:

SameFileError – If src and dst are the same file, a SameFileError will be raised.

示例

>>> backend = LocalBackend()
>>> # dst is a file
>>> src = '/path/of/file'
>>> dst = '/path1/of/file1'
>>> # src will be copied to '/path1/of/file1'
>>> backend.copyfile_from_local(src, dst)
'/path1/of/file1'

>>> # dst is a directory
>>> dst = '/path1/of/dir'
>>> # src will be copied to
>>> backend.copyfile_from_local(src, dst)
'/path1/of/dir/file'

copyfile_to_local(src, dst)

Copy the file src to local dst and return the destination file. Same as copyfile().

If dst specifies a directory, the file will be copied into dst using the base filename from src. If dst specifies a file that already exists, it will be replaced.

参数:

• src (str or Path) – A file to be copied.

• dst (str or Path) – Copy file to to local dst.

返回:

If dst specifies a directory, the file will be copied into dst using the base filename from src.

返回类型:

str

示例

>>> backend = LocalBackend()
>>> # dst is a file
>>> src = '/path/of/file'
>>> dst = '/path1/of/file1'
>>> # src will be copied to '/path1/of/file1'
>>> backend.copyfile_to_local(src, dst)
'/path1/of/file1'

>>> # dst is a directory
>>> dst = '/path1/of/dir'
>>> # src will be copied to
>>> backend.copyfile_to_local(src, dst)
'/path1/of/dir/file'

copytree(src, dst)

Recursively copy an entire directory tree rooted at src to a directory named dst and return the destination directory.

src and dst should have the same prefix and dst must not already exist.

TODO: Whether to support dirs_exist_ok parameter.

参数:

• src (str or Path) – A directory to be copied.

• dst (str or Path) – Copy directory to dst.

返回:

The destination directory.

返回类型:

str

抛出:

FileExistsError – If dst had already existed, a FileExistsError will be raised.

示例

>>> backend = LocalBackend()
>>> src = '/path/of/dir1'
>>> dst = '/path/of/dir2'
>>> backend.copytree(src, dst)
'/path/of/dir2'

copytree_from_local(src, dst)

Recursively copy an entire directory tree rooted at src to a directory named dst and return the destination directory. Same as copytree().

参数:

• src (str or Path) – A local directory to be copied.

• dst (str or Path) – Copy directory to dst.

返回:

The destination directory.

返回类型:

str

示例

>>> backend = LocalBackend()
>>> src = '/path/of/dir1'
>>> dst = '/path/of/dir2'
>>> backend.copytree_from_local(src, dst)
'/path/of/dir2'

copytree_to_local(src, dst)

Recursively copy an entire directory tree rooted at src to a local directory named dst and return the destination directory.

参数:

• src (str or Path) – A directory to be copied.

• dst (str or Path) – Copy directory to local dst.

• backend_args (dict, optional) – Arguments to instantiate the prefix of uri corresponding backend. Defaults to None.

返回:

The destination directory.

返回类型:

str

示例

>>> backend = LocalBackend()
>>> src = '/path/of/dir1'
>>> dst = '/path/of/dir2'
>>> backend.copytree_from_local(src, dst)
'/path/of/dir2'

exists(filepath)

Check whether a file path exists.

参数:

filepath (str or Path) – Path to be checked whether exists.

返回:

Return True if filepath exists, False otherwise.

返回类型:

bool

示例

>>> backend = LocalBackend()
>>> filepath = '/path/of/file'
>>> backend.exists(filepath)
True

get(filepath)

Read bytes from a given filepath with ‘rb’ mode.

参数:

filepath (str or Path) – Path to read data.

返回:

Expected bytes object.

返回类型:

bytes

示例

>>> backend = LocalBackend()
>>> filepath = '/path/of/file'
>>> backend.get(filepath)
b'hello world'

get_local_path(filepath)

Only for unified API and do nothing.

参数:

• filepath (str or Path) – Path to be read data.

• backend_args (dict, optional) – Arguments to instantiate the corresponding backend. Defaults to None.

返回类型:

Generator[str | Path, None, None]

示例

>>> backend = LocalBackend()
>>> with backend.get_local_path('s3://bucket/abc.jpg') as path:
...     # do something here

get_text(filepath, encoding='utf-8')

Read text from a given filepath with ‘r’ mode.

参数:

• filepath (str or Path) – Path to read data.

• encoding (str) – The encoding format used to open the filepath. Defaults to ‘utf-8’.

返回:

Expected text reading from filepath.

返回类型:

str

示例

>>> backend = LocalBackend()
>>> filepath = '/path/of/file'
>>> backend.get_text(filepath)
'hello world'

isdir(filepath)

Check whether a file path is a directory.

参数:

filepath (str or Path) – Path to be checked whether it is a directory.

返回:

Return True if filepath points to a directory, False otherwise.

返回类型:

bool

示例

>>> backend = LocalBackend()
>>> filepath = '/path/of/dir'
>>> backend.isdir(filepath)
True

isfile(filepath)

Check whether a file path is a file.

参数:

filepath (str or Path) – Path to be checked whether it is a file.

返回:

Return True if filepath points to a file, False otherwise.

返回类型:

bool

示例

>>> backend = LocalBackend()
>>> filepath = '/path/of/file'
>>> backend.isfile(filepath)
True

join_path(filepath, *filepaths)

Concatenate all file paths.

Join one or more filepath components intelligently. The return value is the concatenation of filepath and any members of *filepaths.

参数:

• filepath (str or Path) – Path to be concatenated.

• filepaths (str | Path) –

返回:

The result of concatenation.

返回类型:

str

示例

>>> backend = LocalBackend()
>>> filepath1 = '/path/of/dir1'
>>> filepath2 = 'dir2'
>>> filepath3 = 'path/of/file'
>>> backend.join_path(filepath1, filepath2, filepath3)
'/path/of/dir/dir2/path/of/file'

list_dir_or_file(dir_path, list_dir=True, list_file=True, suffix=None, recursive=False)

Scan a directory to find the interested directories or files in arbitrary order.

备注

list_dir_or_file() returns the path relative to dir_path.

参数:

• dir_path (str or Path) – Path of the directory.

• list_dir (bool) – List the directories. Defaults to True.

• list_file (bool) – List the path of files. Defaults to True.

• suffix (str or tuple[str], optional) – File suffix that we are interested in. Defaults to None.

• recursive (bool) – If set to True, recursively scan the directory. Defaults to False.

生成器:

Iterable[str] – A relative path to dir_path.

返回类型:

Iterator[str]

示例

>>> backend = LocalBackend()
>>> dir_path = '/path/of/dir'
>>> # list those files and directories in current directory
>>> for file_path in backend.list_dir_or_file(dir_path):
...     print(file_path)
>>> # only list files
>>> for file_path in backend.list_dir_or_file(dir_path, list_dir=False):
...     print(file_path)
>>> # only list directories
>>> for file_path in backend.list_dir_or_file(dir_path, list_file=False):
...     print(file_path)
>>> # only list files ending with specified suffixes
>>> for file_path in backend.list_dir_or_file(dir_path, suffix='.txt'):
...     print(file_path)
>>> # list all files and directory recursively
>>> for file_path in backend.list_dir_or_file(dir_path, recursive=True):
...     print(file_path)

put(obj, filepath)

Write bytes to a given filepath with ‘wb’ mode.

备注

put will create a directory if the directory of filepath does not exist.

参数:

• obj (bytes) – Data to be written.

• filepath (str or Path) – Path to write data.

返回类型:

None

示例

>>> backend = LocalBackend()
>>> filepath = '/path/of/file'
>>> backend.put(b'hello world', filepath)

put_text(obj, filepath, encoding='utf-8')

Write text to a given filepath with ‘w’ mode.

备注

put_text will create a directory if the directory of filepath does not exist.

参数:

• obj (str) – Data to be written.

• filepath (str or Path) – Path to write data.

• encoding (str) – The encoding format used to open the filepath. Defaults to ‘utf-8’.

返回类型:

None

示例

>>> backend = LocalBackend()
>>> filepath = '/path/of/file'
>>> backend.put_text('hello world', filepath)

remove(filepath)

Remove a file.

参数:

filepath (str or Path) – Path to be removed.

抛出:

• IsADirectoryError – If filepath is a directory, an IsADirectoryError will be raised.

• FileNotFoundError – If filepath does not exist, an FileNotFoundError will be raised.

返回类型:

None

示例

>>> backend = LocalBackend()
>>> filepath = '/path/of/file'
>>> backend.remove(filepath)

rmtree(dir_path)

Recursively delete a directory tree.

参数:

dir_path (str or Path) – A directory to be removed.

返回类型:

None

示例

>>> dir_path = '/path/of/dir'
>>> backend.rmtree(dir_path)