Manage files and directories

pshell.remove(path, *, recursive=False, force=True, rename_on_fail=False)

Remove file or directory

Parameters:
  • path (str) – Target file or directory
  • recursive (bool) – If True, recursively delete tree starting at file
  • force (bool) – If True, don’t raise OSError if path doesn’t exist
  • 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)

Move the present-working directory (pwd) into the target directory.

pshell.pushd(path)

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 mydir
pshell.move(src, dst)

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, dst, *, ignore=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, *, suffix=None, force=False, action='copy')

Recursively copy or move a file of directory from <path> to <path>.<suffix>.

Parameters:
  • 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 target path does not exist and force = False
Returns:

output file name, or None if no backup was performed

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 wether src and dst are 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)

Wrapper around os.path.exists(), with automated resolution of environment variables and logging.

pshell.lexists(path)

Wrapper around os.path.lexists(), with automated resolution of environment variables and logging.

pshell.mkdir(path, *, parents=True, force=True)

Create target directory.

Parameters:
  • path (str) – 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)

Return the username of the user owning a file.

This function is not available on Windows.