LocalBackend¶
- class mmengine.fileio.LocalBackend[source]¶
Raw local storage backend.
- copy_if_symlink_fails(src, dst)[source]¶
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.
- Parameters:
- Returns:
Return True if successfully create a symbolic link pointing to src. Otherwise, return False.
- Return type:
Examples
>>> 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)[source]¶
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.
- Parameters:
- Returns:
The destination file.
- Return type:
- Raises:
SameFileError – If src and dst are the same file, a SameFileError will be raised.
Examples
>>> 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)[source]¶
Copy a local file src to dst and return the destination file. Same as
copyfile()
.- Parameters:
- Returns:
If dst specifies a directory, the file will be copied into dst using the base filename from src.
- Return type:
- Raises:
SameFileError – If src and dst are the same file, a SameFileError will be raised.
Examples
>>> 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)[source]¶
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.
- Parameters:
- Returns:
If dst specifies a directory, the file will be copied into dst using the base filename from src.
- Return type:
Examples
>>> 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)[source]¶
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.
- Parameters:
- Returns:
The destination directory.
- Return type:
- Raises:
FileExistsError – If dst had already existed, a FileExistsError will be raised.
Examples
>>> backend = LocalBackend() >>> src = '/path/of/dir1' >>> dst = '/path/of/dir2' >>> backend.copytree(src, dst) '/path/of/dir2'
- copytree_from_local(src, dst)[source]¶
Recursively copy an entire directory tree rooted at src to a directory named dst and return the destination directory. Same as
copytree()
.- Parameters:
- Returns:
The destination directory.
- Return type:
Examples
>>> backend = LocalBackend() >>> src = '/path/of/dir1' >>> dst = '/path/of/dir2' >>> backend.copytree_from_local(src, dst) '/path/of/dir2'
- copytree_to_local(src, dst)[source]¶
Recursively copy an entire directory tree rooted at src to a local directory named dst and return the destination directory.
- Parameters:
- Returns:
The destination directory.
- Return type:
Examples
>>> backend = LocalBackend() >>> src = '/path/of/dir1' >>> dst = '/path/of/dir2' >>> backend.copytree_from_local(src, dst) '/path/of/dir2'
- exists(filepath)[source]¶
Check whether a file path exists.
- Parameters:
filepath (str or Path) – Path to be checked whether exists.
- Returns:
Return
True
iffilepath
exists,False
otherwise.- Return type:
Examples
>>> backend = LocalBackend() >>> filepath = '/path/of/file' >>> backend.exists(filepath) True
- get(filepath)[source]¶
Read bytes from a given
filepath
with ‘rb’ mode.- Parameters:
filepath (str or Path) – Path to read data.
- Returns:
Expected bytes object.
- Return type:
Examples
>>> backend = LocalBackend() >>> filepath = '/path/of/file' >>> backend.get(filepath) b'hello world'
- get_local_path(filepath)[source]¶
Only for unified API and do nothing.
- Parameters:
- Return type:
Examples
>>> backend = LocalBackend() >>> with backend.get_local_path('s3://bucket/abc.jpg') as path: ... # do something here
- get_text(filepath, encoding='utf-8')[source]¶
Read text from a given
filepath
with ‘r’ mode.- Parameters:
- Returns:
Expected text reading from
filepath
.- Return type:
Examples
>>> backend = LocalBackend() >>> filepath = '/path/of/file' >>> backend.get_text(filepath) 'hello world'
- isdir(filepath)[source]¶
Check whether a file path is a directory.
- Parameters:
filepath (str or Path) – Path to be checked whether it is a directory.
- Returns:
Return
True
iffilepath
points to a directory,False
otherwise.- Return type:
Examples
>>> backend = LocalBackend() >>> filepath = '/path/of/dir' >>> backend.isdir(filepath) True
- isfile(filepath)[source]¶
Check whether a file path is a file.
- Parameters:
filepath (str or Path) – Path to be checked whether it is a file.
- Returns:
Return
True
iffilepath
points to a file,False
otherwise.- Return type:
Examples
>>> backend = LocalBackend() >>> filepath = '/path/of/file' >>> backend.isfile(filepath) True
- join_path(filepath, *filepaths)[source]¶
Concatenate all file paths.
Join one or more filepath components intelligently. The return value is the concatenation of filepath and any members of *filepaths.
- Parameters:
- Returns:
The result of concatenation.
- Return type:
Examples
>>> 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)[source]¶
Scan a directory to find the interested directories or files in arbitrary order.
Note
list_dir_or_file()
returns the path relative todir_path
.- Parameters:
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.
- Yields:
Iterable[str] – A relative path to
dir_path
.- Return type:
Examples
>>> 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)[source]¶
Write bytes to a given
filepath
with ‘wb’ mode.Note
put
will create a directory if the directory offilepath
does not exist.- Parameters:
- Return type:
None
Examples
>>> backend = LocalBackend() >>> filepath = '/path/of/file' >>> backend.put(b'hello world', filepath)
- put_text(obj, filepath, encoding='utf-8')[source]¶
Write text to a given
filepath
with ‘w’ mode.Note
put_text
will create a directory if the directory offilepath
does not exist.- Parameters:
- Return type:
None
Examples
>>> backend = LocalBackend() >>> filepath = '/path/of/file' >>> backend.put_text('hello world', filepath)
- remove(filepath)[source]¶
Remove a file.
- Parameters:
filepath (str or Path) – Path to be removed.
- Raises:
IsADirectoryError – If filepath is a directory, an IsADirectoryError will be raised.
FileNotFoundError – If filepath does not exist, an FileNotFoundError will be raised.
- Return type:
None
Examples
>>> backend = LocalBackend() >>> filepath = '/path/of/file' >>> backend.remove(filepath)