Shortcuts

LocalBackend

class mmengine.fileio.LocalBackend[source]

Raw local storage backend.

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[str | 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 (str | 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)