Manage files and directories

pshell.remove(path: str | Path, *, recursive: bool = False, force: bool = True, ignore_readonly: bool = False, rename_on_fail: bool = False) → None

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 exist

  • OSError –

    • if rename_on_fail==False and path can’t be deleted

    • if 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: Callable | None = 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 raise FileExistsError because bar 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: Literal['copy', 'move'] = 'copy') → str | None
pshell.backup(path: Path, *, suffix: str | None = None, force: bool = False, action: Literal['copy', 'move'] = '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 a Path.

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.

pshell.mkdir(path: str | Path, *, parents: bool = True, force: bool = True) → None

Create target directory.

This function is safe for use in concurrent environments, where multiple actors try to simultaneously create the same directory.

Parameters:

  • path – directory to be created

  • parents (bool) – if True, also create parent directories if necessary.

  • force (bool) – if True, do nothing if <path> already exists.

pshell.owner(fname: str | Path) → str

Return the username of the user owning a file.

This function is not available on Windows.