Manage files and directories¶
- pshell.remove(path: str | Path, *, recursive: bool = False, force: bool = True, ignore_readonly: bool = False, rename_on_fail: bool = False)¶
Remove file or directory
- Parameters
path – Target file or directory
recursive (bool) – If True, recursively delete tree starting at path
force (bool) – If True, don’t raise OSError if path doesn’t exist
ignore_readonly (bool) – If True, also delete files and directories with the read-only flag
rename_on_fail (bool) – If True, don’t raise OSError if deletion fails. This typically happens if the user does not have enough permissions to delete the file or directory, or in case of NFS locks. In this case, rename the file to <path>.DELETEME.<timestamp>. If the rename also fails, then raise OSError.
- Raises
FileNotFoundError – If
force==False
and path doesn’t existOSError –
if
rename_on_fail==False
and path can’t be deletedif
rename_on_fail==True
and path can be neither deleted nor renamed
- pshell.chdir(path: str | Path) → None¶
Move the present-working directory (pwd) into the target directory.
- pshell.pushd(path: str | Path) → Iterator[None]¶
Context manager that moves the pwd into target directory. When leaving the context, the pwd is changed back to what it originally was.
Usage:
with pushd("mydir"): ...
Is equivalent to the bash commands:
pushd mydir ... popd
- pshell.move(src: str | Path, dst: str | Path) → None¶
Recursively move a file or directory (src) to another location (dst). If the destination is a directory or a symlink to a directory, then src is moved inside that directory. The destination directory must not already exist. If the destination already exists but is not a directory, it may be overwritten depending on
os.rename()
semantics.
- pshell.copy(src: str | Path, dst: str | Path, *, ignore=None) → None¶
Recursively copy a file or directory. If src is a regular file and dst is a directory, a file with the same basename as src is created (or overwritten) in the directory specified. Permission bits and last modified dates are copied. Symlinks are preserved. Users and groups are discarded.
Note
This function behaves slightly differently from bash when src is a directory. bash alters its behaviour if dst exists or not, e.g.:
$ mkdir foo $ touch foo/hello.txt $ cp -r foo bar # First copy; bar does not exist $ cp -r foo bar # Identical command as before; # but it will behave differently! $ find ./bar ./bar/hello.txt ./bar/foo ./bar/foo/hello.txt ./foo ./foo/hello.txt
This function instead always requires the full destination path; the second invocation of
copy('foo', 'bar')
will raiseFileExistsError
becausebar
already exists.- Parameters
ignore – Only effective when copying a directory. See
shutil.copytree()
.
- pshell.backup(path: str, *, suffix: str | None = 'None', force: bool = 'False', action: str = "'copy'") → str | None¶
- pshell.backup(path: pathlib.Path, *, suffix: str | None = 'None', force: bool = 'False', action: str = "'copy'") → Path | None
Recursively copy or move a file of directory from <path> to <path>.<suffix>.
- Parameters
path – File or directory to back up. Can be a string or a
pathlib.Path
.suffix (str) – suffix for the backup file. Default: .YYYYMMDD-HHMMSS
force (bool) – if True, silently do nothing if file doesn’t exist.
action (str) – copy|move
- Raises
FileNotFoundError – if path does not exist and force=False
- Returns
renamed path, or None if no backup was performed. If path is a
Path
, then the return value is also aPath
.
- pshell.symlink(src: str | Path, dst: str | Path, *, force: bool = False, abspath: bool = False) → None¶
Create a symbolic link pointing to src named dst.
This exclusively works in Unix, on POSIX-compatible filesystems.
- Parameters
force (bool) – if True, remove previous dst if it exists and it’s a different symlink. If it’s the same symlink, do not replace it in order to prevent race conditions.
abspath (bool) – if False, build the shortest possible relative link. If True, generate a link using absolute paths. This is regardless of src and dst being absolute or relative paths, and regardless of the current working directory (cwd).
Examples:
>>> symlink('/common/foo', '/common/bar') /common/foo => bar >>> symlink('/common/foo', '/common/bar', abspath=True) /common/foo => /common/bar >>> chdir('/common') >>> symlink('foo', 'bar') /common/foo => bar >>> chdir('/common') >>> symlink('foo', 'bar', abspath=True) /common/foo => /common/bar
- pshell.exists(path: str | Path) → bool¶
Wrapper around
os.path.exists()
, with automated resolution of environment variables and logging.
- pshell.lexists(path: str | Path) → bool¶
Wrapper around
os.path.lexists()
, with automated resolution of environment variables and logging.