megfile.fs_path module

class megfile.fs_path.FSPath(path: Union[PathLike, int], *other_paths: Union[str, os.PathLike])

Bases: megfile.pathlike.URIPath

file protocol e.g. file:///data/test/ or /data/test

absolute() → megfile.fs_path.FSPath

Make the path absolute, without normalization or resolving symlinks. Returns a new path object

abspath() → str

Return the absolute path of given path

Returns

Absolute path of given path

access(mode: megfile.pathlike.Access = <Access.READ: 1>) → bool

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

Parameters

mode – access mode

Returns

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

anchor

chmod(mode: int, *, follow_symlinks: bool = True)

Change the file mode and permissions, like os.chmod().

This method normally follows symlinks. Some Unix flavours support changing permissions on the symlink itself; on these platforms you may add the argument follow_symlinks=False, or use lchmod().

copy(dst_path: Union[str, os.PathLike], callback: Optional[Callable[int, None]] = None, followlinks: bool = False)

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:

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

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

3. This function is thread-unsafe

Parameters

• 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

cwd() → megfile.fs_path.FSPath

Return current working directory

returns: Current working directory

drive

exists(followlinks: bool = False) → bool

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

followlinks – False if regard symlink as file, else True

Returns

True if the path exists, else False

expanduser()

Expand ~ and ~user constructions. If user or $HOME is unknown, do nothing.

classmethod from_uri(path: str) → megfile.fs_path.FSPath

getmtime(follow_symlinks: bool = False) → float

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.

Returns

last-modified time

getsize(follow_symlinks: bool = False) → int

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.

Returns

File size

glob(pattern, recursive: bool = True, missing_ok: bool = True) → List[megfile.fs_path.FSPath]

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

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

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

3. ** will match any matched file, directory, symlink and ‘’ by default, when recursive is True

4. fs_glob returns same as glob.glob(pathname, recursive=True) in acsending alphabetical order.

5. Hidden files (filename stars with ‘.’) will not be found in the result

Parameters

• pattern – Glob the given relative pattern in the directory represented by this path

• 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

glob_stat(pattern, recursive: bool = True, missing_ok: bool = True) → Iterator[megfile.pathlike.FileEntry]

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

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

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

3. ** will match any matched file, directory, symlink and ‘’ by default, when recursive is True

4. fs_glob returns same as glob.glob(pathname, recursive=True) in acsending alphabetical order.

5. Hidden files (filename stars with ‘.’) will not be found in the result

Parameters

• pattern – Glob the given relative pattern in the directory represented by this path

• 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

group() → str

Return the name of the group owning the file. KeyError is raised if the file’s gid isn’t found in the system database.

hardlink_to(target)

Make this path a hard link to the same file as target.

home()

Return the home directory

returns: Home directory path

iglob(pattern, recursive: bool = True, missing_ok: bool = True) → Iterator[megfile.fs_path.FSPath]

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

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

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

3. ** will match any matched file, directory, symlink and ‘’ by default, when recursive is True

4. fs_glob returns same as glob.glob(pathname, recursive=True) in acsending alphabetical order.

5. Hidden files (filename stars with ‘.’) will not be found in the result

Parameters

• pattern – Glob the given relative pattern in the directory represented by this path

• 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

is_absolute() → bool

Test whether a path is absolute

Returns

True if a path is absolute, else False

is_block_device() → bool

Return True if the path points to a block device (or a symbolic link pointing to a block device), False if it points to another kind of file.

False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

is_char_device() → bool

Return True if the path points to a character device (or a symbolic link pointing to a character device), False if it points to another kind of file.

False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

is_dir(followlinks: bool = False) → bool

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

followlinks – False if regard symlink as file, else True

Returns

True if the path is a directory, else False

is_fifo() → bool

Return True if the path points to a FIFO (or a symbolic link pointing to a FIFO), False if it points to another kind of file.

False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

is_file(followlinks: bool = False) → bool

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

followlinks – False if regard symlink as file, else True

Returns

True if the path is a file, else False

is_mount() → bool

Test whether a path is a mount point

Returns

True if a path is a mount point, else False

is_socket() → bool

Return True if the path points to a Unix socket (or a symbolic link pointing to a Unix socket), False if it points to another kind of file.

False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

is_symlink() → bool

Test whether a path is a symbolic link

Returns

If path is a symbolic link return True, else False

Return type

bool

iterdir() → Iterator[megfile.fs_path.FSPath]

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

Returns

All contents have in the path in acsending alphabetical order

joinpath(*other_paths: Union[str, os.PathLike]) → megfile.fs_path.FSPath

Calling this method is equivalent to combining the path with each of the other arguments in turn

listdir() → List[str]

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

Returns

All contents have in the path in acsending alphabetical order

load() → BinaryIO

Read all content on specified path and write into memory

User should close the BinaryIO manually

Returns

Binary stream

lstat() → megfile.pathlike.StatResult

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

Returns

StatResult

md5(recalculate: bool = False, followlinks: bool = True)

Calculate the md5 value of the file

Parameters

• recalculate – Ignore this parameter, just for compatibility

• followlinks – Ignore this parameter, just for compatibility

returns: md5 of file

mkdir(mode=511, parents: bool = False, exist_ok: bool = False)

make a directory on fs, including parent directory

If there exists a file on the path, raise FileExistsError

Parameters

• mode – If mode is given, it is combined with the process’ umask value to determine the file mode and access flags.

• parents – If parents is true, any missing parents of this path are created as needed;

If parents is false (the default), a missing parent raises FileNotFoundError. :param exist_ok: If False and target directory exists, raise FileExistsError :raises: FileExistsError

open(mode: str = 'r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, **kwargs) → IO[AnyStr]

Open the file with mode.

owner() → str

Return the name of the user owning the file. KeyError is raised if the file’s uid isn’t found in the system database.

parts

A tuple giving access to the path’s various components

property path_with_protocol

Return path with protocol, like file:///root, s3://bucket/key

protocol = 'file'

readlink() → megfile.fs_path.FSPath

Return a FSPath instance representing the path to which the symbolic link points. :returns: Return a FSPath instance representing the path to which the symbolic link points.

realpath() → str

Return the real path of given path

Returns

Real path of given path

relpath(start: Optional[str] = None) → str

Return the relative path of given path

Parameters

start – Given start directory

Returns

Relative path from start

remove(missing_ok: bool = False) → None

Remove the file or directory on fs

Parameters

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

rename(dst_path: Union[str, os.PathLike]) → megfile.fs_path.FSPath

rename file on fs

Parameters

dst_path – Given destination path

replace(dst_path: Union[str, os.PathLike]) → megfile.fs_path.FSPath

move file on fs

Parameters

dst_path – Given destination path

resolve(strict=False) → megfile.fs_path.FSPath

Equal to fs_realpath

Returns

Return the canonical path of the specified filename, eliminating any symbolic links encountered in the path.

Return type

FSPath

rmdir()

Remove this directory. The directory must be empty.

root

save(file_object: BinaryIO)

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

Parameters

file_object – stream to be read

scan(missing_ok: bool = True, followlinks: bool = False) → Iterator[str]

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

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

Returns

A file path generator

scan_stat(missing_ok: bool = True, followlinks: bool = False) → Iterator[megfile.pathlike.FileEntry]

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

Parameters

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

Returns

A file path generator

scandir() → Iterator[megfile.pathlike.FileEntry]

Get all content of given file path.

Returns

An iterator contains all contents have prefix path

stat(follow_symlinks=True) → megfile.pathlike.StatResult

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

Returns

StatResult

symlink(dst_path: Union[str, os.PathLike]) → None

Create a symbolic link pointing to src_path named dst_path.

Parameters

dst_path – Desination path

sync(dst_path: Union[str, os.PathLike], followlinks: bool = False, force: bool = False) → None

Force write of everything to disk.

Parameters

• dst_path – Target file path

• followlinks – False if regard symlink as file, else True

• force – Sync file forcely, do not ignore same files

unlink(missing_ok: bool = False) → None

Remove the file on fs

Parameters

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

utime(atime: Union[float, int], mtime: Union[float, int])

Set the access and modified times of the file specified by path.

Parameters

• atime – a float or int representing the access time to be set. If it is set to None, the access time is set to the current time.

• mtime – a float or int representing the modified time to be set. If it is set to None, the modified time is set to the current time.

Returns

None

walk(followlinks: bool = False) → Iterator[Tuple[str, List[str], List[str]]]

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

followlinks – False if regard symlink as file, else True

Returns

A 3-tuple generator