megfile.fs module

megfile.fs.is_fs(path: Union[PathLike, int]) → bool[source]

Test if a path is fs path

Parameters: path – Path to be tested
Returns: True of a path is fs path, else False

class megfile.fs.StatResult[source]

Bases: megfile.pathlike.StatResult

is_dir() → bool[source]

is_file() → bool[source]

is_symlink() → bool[source]

property st_atime: Time of most recent access expressed in seconds. Only support fs.

property st_atime_ns: Time of most recent access expressed in nanoseconds as an integer. Only support fs.

property st_ctime: Platform dependent:

the time of most recent metadata change on Unix, the time of creation on Windows, expressed in seconds, the time of file created on oss; if is dir, return the latest ctime of the files in dir.

property st_ctime_ns

Platform dependent:

the time of most recent metadata change on Unix, the time of creation on Windows, expressed in nanoseconds as an integer.

Only support fs.

property st_dev: Identifier of the device on which this file resides.

property st_gid: Group identifier of the file owner. Only support fs.

property st_ino

Platform dependent, but if non-zero, uniquely identifies the file for a given value of st_dev. Typically:

the inode number on Unix, the file index on Windows, the decimal of etag on oss.

property st_mode: File mode: file type and file mode bits (permissions). Only support fs.

property st_mtime: Time of most recent content modification expressed in seconds.

property st_mtime_ns: Time of most recent content modification expressed in nanoseconds as an integer. Only support fs.

property st_nlink: Number of hard links. Only support fs.

property st_size: Size of the file in bytes.

property st_uid: User identifier of the file owner. Only support fs.

megfile.fs.fs_path_join(path: Union[str, os.PathLike], *other_paths: Union[str, os.PathLike]) → str[source]

megfile.fs.fs_readlink(path) → str[source]: Return a string representing the path to which the symbolic link points. :returns: Return a string representing the path to which the symbolic link points.

megfile.fs.fs_cwd() → str[source]

Return current working directory

returns: Current working directory

megfile.fs.fs_home()[source]

Return the home directory

returns: Home directory path

megfile.fs.fs_iglob(path: Union[str, os.PathLike], recursive: bool = True, missing_ok: bool = True) → Iterator[str][source]

Return path iterator in ascending alphabetical order, in which path matches glob pattern

If doesn’t match any path, return empty list
Notice: glob.glob in standard library returns [‘a/’] instead of empty list when pathname is like a/**, recursive is True and directory ‘a’ doesn’t exist. fs_glob behaves like glob.glob in standard library under such circumstance.
No guarantee that each path in result is different, which means:
Assume there exists a path /a/b/c/b/d.txt use path pattern like /**/b/**/*.txt to glob, the path above will be returned twice
** will match any matched file, directory, symlink and ‘’ by default, when recursive is True
fs_glob returns same as glob.glob(pathname, recursive=True) in acsending alphabetical order.
Hidden files (filename stars with ‘.’) will not be found in the result

Parameters

recursive – If False, ** will not search directory recursively
missing_ok – If False and target path doesn’t match any file, raise FileNotFoundError

Returns

An iterator contains paths match pathname

megfile.fs.fs_glob(path: Union[str, os.PathLike], recursive: bool = True, missing_ok: bool = True) → List[str][source]

Return path list in ascending alphabetical order, in which path matches glob pattern

If doesn’t match any path, return empty list
Notice: glob.glob in standard library returns [‘a/’] instead of empty list when pathname is like a/**, recursive is True and directory ‘a’ doesn’t exist. fs_glob behaves like glob.glob in standard library under such circumstance.
No guarantee that each path in result is different, which means:
Assume there exists a path /a/b/c/b/d.txt use path pattern like /**/b/**/*.txt to glob, the path above will be returned twice
** will match any matched file, directory, symlink and ‘’ by default, when recursive is True
fs_glob returns same as glob.glob(pathname, recursive=True) in acsending alphabetical order.
Hidden files (filename stars with ‘.’) will not be found in the result

Parameters

recursive – If False, ** will not search directory recursively
missing_ok – If False and target path doesn’t match any file, raise FileNotFoundError

Returns

A list contains paths match pathname

megfile.fs.fs_glob_stat(path: Union[str, os.PathLike], recursive: bool = True, missing_ok: bool = True) → Iterator[megfile.pathlike.FileEntry][source]

Return a list contains tuples of path and file stat, in ascending alphabetical order, in which path matches glob pattern

If doesn’t match any path, return empty list
Notice: glob.glob in standard library returns [‘a/’] instead of empty list when pathname is like a/**, recursive is True and directory ‘a’ doesn’t exist. fs_glob behaves like glob.glob in standard library under such circumstance.
No guarantee that each path in result is different, which means:
Assume there exists a path /a/b/c/b/d.txt use path pattern like /**/b/**/*.txt to glob, the path above will be returned twice
** will match any matched file, directory, symlink and ‘’ by default, when recursive is True
fs_glob returns same as glob.glob(pathname, recursive=True) in acsending alphabetical order.
Hidden files (filename stars with ‘.’) will not be found in the result

Parameters

recursive – If False, ** will not search directory recursively
missing_ok – If False and target path doesn’t match any file, raise FileNotFoundError

Returns

A list contains tuples of path and file stat, in which paths match pathname

megfile.fs.fs_rename(src_path: Union[str, os.PathLike], dst_path: Union[str, os.PathLike]) → None[source]

rename file on fs

Parameters

src_path – Given path
dst_path – Given destination path

megfile.fs.fs_resolve(path: Union[str, os.PathLike]) → str[source]

Equal to fs_realpath, return the real path of given path

Parameters: path – Given path
Returns: Real path of given path

megfile.fs.fs_move(src_path: Union[str, os.PathLike], dst_path: Union[str, os.PathLike]) → None[source]

rename file on fs

Parameters

src_path – Given path
dst_path – Given destination path

megfile.fs.fs_makedirs(path: Union[str, os.PathLike], exist_ok: bool = False)[source]

make a directory on fs, including parent directory

If there exists a file on the path, raise FileExistsError

Parameters

path – Given path
exist_ok – If False and target directory exists, raise FileExistsError

Raises

FileExistsError

megfile.fs.fs_isabs(path: Union[str, os.PathLike]) → bool[source]

Test whether a path is absolute

Parameters: path – Given path
Returns: True if a path is absolute, else False

megfile.fs.fs_abspath(path: Union[str, os.PathLike]) → str[source]

Return the absolute path of given path

Parameters: path – Given path
Returns: Absolute path of given path

megfile.fs.fs_access(path: Union[str, os.PathLike], mode: megfile.pathlike.Access = <Access.READ: 1>) → bool[source]

Test if path has access permission described by mode Using os.access

Parameters

path – Given path
mode – access mode

Returns

Access: Enum, the read/write access that path has.

megfile.fs.fs_exists(path: Union[str, os.PathLike], followlinks: bool = False) → bool[source]

Test if the path exists

Note

The difference between this function and os.path.exists is that this function regard symlink as file. In other words, this function is equal to os.path.lexists

Parameters

path – Given path
followlinks – False if regard symlink as file, else True

Returns

True if the path exists, else False

megfile.fs.fs_getmtime(path: Union[str, os.PathLike], follow_symlinks: bool = False) → float[source]

Get last-modified time of the file on the given path (in Unix timestamp format). If the path is an existent directory, return the latest modified time of all file in it.

Parameters: path – Given path
Returns: last-modified time

megfile.fs.fs_getsize(path: Union[str, os.PathLike], follow_symlinks: bool = False) → int[source]

Get file size on the given file path (in bytes). If the path in a directory, return the sum of all file size in it, including file in subdirectories (if exist). The result excludes the size of directory itself. In other words, return 0 Byte on an empty directory path.

Parameters: path – Given path
Returns: File size

megfile.fs.fs_expanduser(path: Union[str, os.PathLike])[source]: Expand ~ and ~user constructions. If user or $HOME is unknown, do nothing.

megfile.fs.fs_isdir(path: Union[str, os.PathLike], followlinks: bool = False) → bool[source]

Test if a path is directory

Note

The difference between this function and os.path.isdir is that this function regard symlink as file

Parameters

path – Given path
followlinks – False if regard symlink as file, else True

Returns

True if the path is a directory, else False

megfile.fs.fs_isfile(path: Union[str, os.PathLike], followlinks: bool = False) → bool[source]

Test if a path is file

Note

The difference between this function and os.path.isfile is that this function regard symlink as file

Parameters

path – Given path
followlinks – False if regard symlink as file, else True

Returns

True if the path is a file, else False

megfile.fs.fs_listdir(path: Union[str, os.PathLike]) → List[str][source]

Get all contents of given fs path. The result is in acsending alphabetical order.

Parameters: path – Given path
Returns: All contents have in the path in acsending alphabetical order

megfile.fs.fs_load_from(path: Union[str, os.PathLike]) → BinaryIO[source]

Read all content on specified path and write into memory

User should close the BinaryIO manually

Parameters: path – Given path
Returns: Binary stream

megfile.fs.fs_realpath(path: Union[str, os.PathLike]) → str[source]

Return the real path of given path

Parameters: path – Given path
Returns: Real path of given path

megfile.fs.fs_relpath(path: Union[str, os.PathLike], start: Optional[str] = None) → str[source]

Return the relative path of given path

Parameters

path – Given path
start – Given start directory

Returns

Relative path from start

megfile.fs.fs_remove(path: Union[str, os.PathLike], missing_ok: bool = False) → None[source]

Remove the file or directory on fs

Parameters

path – Given path
missing_ok – if False and target file/directory not exists, raise FileNotFoundError

megfile.fs.fs_scan(path: Union[str, os.PathLike], missing_ok: bool = True, followlinks: bool = False) → Iterator[str][source]

Iteratively traverse only files in given directory, in alphabetical order. Every iteration on generator yields a path string.

If path is a file path, yields the file only If path is a non-existent path, return an empty generator If path is a bucket path, return all file paths in the bucket

Parameters

path – Given path
missing_ok – If False and there’s no file in the directory, raise FileNotFoundError

Returns

A file path generator

megfile.fs.fs_scan_stat(path: Union[str, os.PathLike], missing_ok: bool = True, followlinks: bool = False) → Iterator[megfile.pathlike.FileEntry][source]

Iteratively traverse only files in given directory, in alphabetical order. Every iteration on generator yields a tuple of path string and file stat

Parameters

path – Given path
missing_ok – If False and there’s no file in the directory, raise FileNotFoundError

Returns

A file path generator

megfile.fs.fs_scandir(path: Union[str, os.PathLike]) → Iterator[megfile.pathlike.FileEntry][source]

Get all content of given file path.

Parameters: path – Given path
Returns: An iterator contains all contents have prefix path

megfile.fs.fs_stat(path: Union[str, os.PathLike], follow_symlinks=True) → megfile.pathlike.StatResult[source]

Get StatResult of file on fs, including file size and mtime, referring to fs_getsize and fs_getmtime

Parameters: path – Given path
Returns: StatResult

megfile.fs.fs_lstat(path: Union[str, os.PathLike]) → megfile.pathlike.StatResult[source]

Like Path.stat() but, if the path points to a symbolic link, return the symbolic link’s information rather than its target’s.

Parameters: path – Given path
Returns: StatResult

megfile.fs.fs_unlink(path: Union[str, os.PathLike], missing_ok: bool = False) → None[source]

Remove the file on fs

Parameters

path – Given path
missing_ok – if False and target file not exists, raise FileNotFoundError

megfile.fs.fs_walk(path: Union[str, os.PathLike], followlinks: bool = False) → Iterator[Tuple[str, List[str], List[str]]][source]

Generate the file names in a directory tree by walking the tree top-down. For each directory in the tree rooted at directory path (including path itself), it yields a 3-tuple (root, dirs, files).

root: a string of current path dirs: name list of subdirectories (excluding ‘.’ and ‘..’ if they exist) in ‘root’. The list is sorted by ascending alphabetical order files: name list of non-directory files (link is regarded as file) in ‘root’. The list is sorted by ascending alphabetical order

If path not exists, or path is a file (link is regarded as file), return an empty generator

Note

Be aware that setting followlinks to True can lead to infinite recursion if a link points to a parent directory of itself. fs_walk() does not keep track of the directories it visited already.

Parameters

path – Given path
followlinks – False if regard symlink as file, else True

Returns

A 3-tuple generator

megfile.fs.fs_getmd5(path: Union[str, os.PathLike], recalculate: bool = False, followlinks: bool = True)[source]

Calculate the md5 value of the file

Parameters

path – Given path
recalculate – Ignore this parameter, just for compatibility
followlinks – Ignore this parameter, just for compatibility

returns: md5 of file

megfile.fs.fs_copy(src_path: Union[str, os.PathLike], dst_path: Union[str, os.PathLike], callback: Optional[Callable[int, None]] = None, followlinks: bool = False)[source]

File copy on file system Copy content (excluding meta date) of file on src_path to dst_path. dst_path must be a complete file name

Note

The differences between this function and shutil.copyfile are:

If parent directory of dst_path doesn’t exist, create it

Allow callback function, None by default. callback: Optional[Callable[[int], None]],

the int data is means the size (in bytes) of the written data that is passed periodically

This function is thread-unsafe

Parameters

src_path – Given path
dst_path – Target file path
callback – Called periodically during copy, and the input parameter is the data size (in bytes) of copy since the last call
followlinks – False if regard symlink as file, else True

megfile.fs.fs_sync(src_path: Union[str, os.PathLike], dst_path: Union[str, os.PathLike], followlinks: bool = False, force: bool = False) → None[source]

Force write of everything to disk.

Parameters

src_path – Given path
dst_path – Target file path
followlinks – False if regard symlink as file, else True
force – Sync file forcely, do not ignore same files

megfile.fs.fs_symlink(src_path: Union[str, os.PathLike], dst_path: Union[str, os.PathLike]) → None[source]

Create a symbolic link pointing to src_path named dst_path.

Parameters

src_path – Given path
dst_path – Desination path

megfile.fs.fs_islink(path: Union[str, os.PathLike]) → bool[source]

Test whether a path is a symbolic link

Parameters: path – Given path
Returns: If path is a symbolic link return True, else False
Return type: bool

megfile.fs.fs_ismount(path: Union[str, os.PathLike]) → bool[source]

Test whether a path is a mount point

Parameters: path – Given path
Returns: True if a path is a mount point, else False

megfile.fs.fs_save_as(file_object: BinaryIO, path: Union[str, os.PathLike])[source]

Write the opened binary stream to path If parent directory of path doesn’t exist, it will be created.

Parameters

path – Given path
file_object – stream to be read