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

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

Returns

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

Return type

bool

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

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

Returns

The destination file.

Return type

str

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

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

Returns

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

Return type

str

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

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

Returns

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

Return type

str

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

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

Returns

The destination directory.

Return type

str

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

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

Returns

The destination directory.

Return type

str

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

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.

Returns

The destination directory.

Return type

str

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 if filepath exists, False otherwise.
Return type: bool

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: bytes

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

filepath (str or Path) – Path to be read data.
backend_args (dict, optional) – Arguments to instantiate the corresponding backend. Defaults to None.

Return type

Generator[Union[str, pathlib.Path], None, None]

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

filepath (str or Path) – Path to read data.
encoding (str) – The encoding format used to open the filepath. Defaults to ‘utf-8’.

Returns

Expected text reading from filepath.

Return type

str

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 if filepath points to a directory, False otherwise.
Return type: bool

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 if filepath points to a file, False otherwise.
Return type: bool

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

filepath (str or Path) – Path to be concatenated.
filepaths (Union[str, pathlib.Path]) –

Returns

The result of concatenation.

Return type

str

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 to dir_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

Iterator[str]

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 of filepath does not exist.

Parameters

obj (bytes) – Data to be written.
filepath (str or Path) – Path to write data.

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 of filepath does not exist.

Parameters

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’.

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)

rmtree(dir_path)[source]¶

Recursively delete a directory tree.

Parameters: dir_path (str or Path) – A directory to be removed.
Return type: None

Examples

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