megfile.fs_path module
- class megfile.fs_path.FSPath(path: str | BasePath | PathLike | int, *other_paths: str | BasePath | PathLike)[source]
Bases:
URIPath
file protocol e.g. file:///data/test/ or /data/test
- absolute() FSPath [source]
Make the path absolute, without normalization or resolving symlinks. Returns a new path object
- access(mode: Access = Access.READ) bool [source]
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.
- property anchor: str
str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.
- chmod(mode: int, *, follow_symlinks: bool = True)[source]
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: str | BasePath | PathLike, callback: Callable[[int], None] | None = None, followlinks: bool = False, overwrite: bool = True)[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:
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
overwrite – whether or not overwrite file when exists, default is True
- property drive: str
str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.
- exists(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 toos.path.lexists
- Parameters:
followlinks – False if regard symlink as file, else True
- Returns:
True if the path exists, else False
- getmtime(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.
- Returns:
last-modified time
- getsize(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.
- Returns:
File size
- glob(pattern, recursive: bool = True, missing_ok: bool = True) List[FSPath] [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 likeglob.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 ascending alphabetical order.
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[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 likeglob.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 ascending alphabetical order.
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 [source]
Return the name of the group owning the file. KeyError is raised if the file’s gid isn’t found in the system database.
- iglob(pattern, recursive: bool = True, missing_ok: bool = True) Iterator[FSPath] [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 likeglob.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 ascending alphabetical order.
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 [source]
Test whether a path is absolute
- Returns:
True if a path is absolute, else False
- is_block_device() bool [source]
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 [source]
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 [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:
followlinks – False if regard symlink as file, else True
- Returns:
True if the path is a directory, else False
- is_fifo() bool [source]
Return True if the path points to a FIFO (or a symbolic link pointing to a FIFO) Return 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 [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:
followlinks – False if regard symlink as file, else True
- Returns:
True if the path is a file, else False
- is_mount() bool [source]
Test whether a path is a mount point
- Returns:
True if a path is a mount point, else False
- is_socket() bool [source]
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 [source]
Test whether a path is a symbolic link
- Returns:
If path is a symbolic link return True, else False
- Return type:
bool
- iterdir() Iterator[FSPath] [source]
Get all contents of given fs path. The result is in ascending alphabetical order.
- Returns:
All contents have in the path in ascending alphabetical order
- joinpath(*other_paths: str | BasePath | PathLike) FSPath [source]
Calling this method is equivalent to combining the path with each of the other arguments in turn
- listdir() List[str] [source]
Get all contents of given fs path. The result is in ascending alphabetical order.
- Returns:
All contents have in the path in ascending alphabetical order
- load() BinaryIO [source]
Read all content on specified path and write into memory
User should close the BinaryIO manually
- Returns:
Binary stream
- md5(recalculate: bool = False, followlinks: bool = True)[source]
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)[source]
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.
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 [source]
Open the file with mode.
- owner() str [source]
Return the name of the user owning the file. KeyError is raised if the file’s uid isn’t found in the system database.
- property parts: Tuple[str, ...]
A tuple giving access to the path’s various components
- property path_with_protocol: str | int
Return path with protocol, like file:///root, s3://bucket/key
- protocol = 'file'
- readlink() FSPath [source]
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.
- relpath(start: str | None = None) str [source]
Return the relative path of given path
- Parameters:
start – Given start directory
- Returns:
Relative path from start
- remove(missing_ok: bool = False) None [source]
Remove the file or directory on fs
- Parameters:
missing_ok – if False and target file/directory not exists, raise FileNotFoundError
- rename(dst_path: str | BasePath | PathLike, overwrite: bool = True) FSPath [source]
rename file on fs
- Parameters:
dst_path – Given destination path
overwrite – whether or not overwrite file when exists
- replace(dst_path: str | BasePath | PathLike, overwrite: bool = True) FSPath [source]
move file on fs
- Parameters:
dst_path – Given destination path
overwrite – whether or not overwrite file when exists
- resolve(strict=False) FSPath [source]
Equal to fs_realpath
- Returns:
Return the canonical path of the specified filename, eliminating any symbolic links encountered in the path.
- Return type:
- property root: str
str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.
- save(file_object: BinaryIO)[source]
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] [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:
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[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:
missing_ok – If False and there’s no file in the directory, raise FileNotFoundError
- Returns:
A file path generator
- scandir() Iterator[FileEntry] [source]
Get all content of given file path.
- Returns:
An iterator contains all contents have prefix path
- stat(follow_symlinks=True) StatResult [source]
Get StatResult of file on fs, including file size and mtime, referring to fs_getsize and fs_getmtime
- Returns:
StatResult
- symlink(dst_path: str | BasePath | PathLike) None [source]
Create a symbolic link pointing to src_path named dst_path.
- Parameters:
dst_path – Destination path
- sync(dst_path: str | BasePath | PathLike, followlinks: bool = False, force: bool = False, overwrite: bool = True) None [source]
Force write of everything to disk.
- Parameters:
dst_path – Target file path
followlinks – False if regard symlink as file, else True
force – Sync file forcible, do not ignore same files, priority is higher than ‘overwrite’, default is False
overwrite – whether or not overwrite file when exists, default is True
- unlink(missing_ok: bool = False) None [source]
Remove the file on fs
- Parameters:
missing_ok – if False and target file not exists, raise FileNotFoundError
- utime(atime: float | int, mtime: float | int)[source]
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]]] [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:
followlinks – False if regard symlink as file, else True
- Returns:
A 3-tuple generator