gws.lib.osx

Operating system and shell utilities.

This package wraps common operating system tasks used throughout GWS:

  • running external commands (run, run_nowait),

  • file system operations (unlink, rename, copy, mkdir, rmdir, touch, chown),

  • file information (file_mtime, file_age, file_size, file_checksum),

  • searching directories (find_files, find_directories),

  • path manipulation (parse_path, abs_path, rel_path, abs_web_path),

  • processes and users (kill_pid, running_pids, process_rss_size, user_info).

Most file functions accept paths as str or bytes. Functions that query files return a sentinel value (-1 or an empty string) instead of raising when the file cannot be accessed.

Example:

import gws.lib.osx

out = gws.lib.osx.run(['gdalinfo', '--version'])
gws.lib.osx.mkdir('/tmp/gws/data')
for path in gws.lib.osx.find_files('/data/projects', ext='json'):
    print(path, gws.lib.osx.file_size(path))

Source code: gws.lib.osx

Package Contents

gws.lib.osx.abs_path(path: _Path, base: _Path) → str

Make a relative path absolute with respect to a base directory or file path.

If base is a file, its directory is used. An absolute path is only normalized.

Parameters:

  • path – A path.

  • base – Base directory or file path.

Returns:

The absolute path.

Raises:

ValueError – If path is relative and base is empty.

gws.lib.osx.abs_web_path(path: str, basedir: str) → str | None

Resolve a web path in a base directory.

The path components must consist of letters, digits, _ and -, the file name can also contain lowercase extensions. This prevents path traversal.

Parameters:

  • path – Slash-separated path, as received from a web request.

  • basedir – Path to the base directory.

Returns:

The path of an existing file in the base directory, or None if the path is invalid or the file does not exist.

gws.lib.osx.chown(path: _Path, user: int = None, group: int = None)

Change the owner and group of a path.

Parameters:

  • path – File path.

  • user – User ID, defaults to gws.c.UID.

  • group – Group ID, defaults to gws.c.GID.

gws.lib.osx.copy(src: _Path, dst: _Path, user: int = None, group: int = None)

Copy a file and set the owner of the copy.

Parameters:

  • src – Source path.

  • dst – Destination path.

  • user – User ID of the copy, defaults to gws.c.UID.

  • group – Group ID of the copy, defaults to gws.c.GID.

exception gws.lib.osx.Error

Bases: gws.Error

Generic error raised by OS utilities.

gws.lib.osx.file_age(path: _Path) → int

Return the number of seconds since a path was last modified.

Parameters:

path – File path.

Returns:

Age in seconds, or -1 if the path cannot be accessed.

gws.lib.osx.file_checksum(path: _Path) → str

Return the SHA-256 checksum of a file.

Parameters:

path – File path.

Returns:

Hex digest of the file content, or an empty string if the file cannot be read.

gws.lib.osx.file_mtime(path: _Path) → float

Return the modification time of a path.

Parameters:

path – File or directory path.

Returns:

Modification time in seconds since the epoch, or -1 if the path cannot be accessed.

gws.lib.osx.file_name(path: _Path) → str

Return the file name part of a path.

Parameters:

path – File path.

Returns:

The last component of the path.

gws.lib.osx.file_size(path: _Path) → int

Return the size of a file.

Parameters:

path – File path.

Returns:

Size in bytes, or -1 if the path cannot be accessed.

gws.lib.osx.find_directories(dirname: _Path, pattern=None, deep: bool = True)

Find directories in a directory, skipping hidden ones.

Parameters:

  • dirname – Path to a directory.

  • pattern – Regular expression to search for in the directory path.

  • deep – If true, also search subdirectories recursively.

Yields:

Paths of matching directories.

gws.lib.osx.find_entries(dirname: _Path, deep: bool = True)

Find entries in a directory, skipping hidden ones.

Parameters:

  • dirname – Path to a directory.

  • deep – If true, also search subdirectories recursively.

Yields:

os.DirEntry objects for files and directories whose names do not start with a dot.

gws.lib.osx.find_files(dirname: _Path, pattern=None, ext=None, deep: bool = True)

Find files in a directory, skipping hidden ones.

Parameters:

  • dirname – Path to a directory.

  • pattern – Regular expression to search for in the file path.

  • ext – Extension or a list of extensions to match. Used only if pattern is not given.

  • deep – If true, also search subdirectories recursively.

Yields:

Paths of matching files.

gws.lib.osx.getenv(key: str, default: str = None) → str | None

Return the value of an environment variable.

Parameters:

  • key – Variable name.

  • default – Value to return if the variable is not set.

Returns:

The variable value, or default if the variable is not set.

gws.lib.osx.is_abs_path(path: _Path) → bool

Check if a path is absolute.

Parameters:

path – File path.

Returns:

True if the path is absolute.

gws.lib.osx.kill_pid(pid: int, sig_name='TERM') → bool

Send a signal to a process.

Parameters:

  • pid – Process ID.

  • sig_name – Signal name, with or without the SIG prefix, e.g. TERM or SIGKILL.

Returns:

True if the signal was sent or the process does not exist, False if the signal could not be sent.

gws.lib.osx.mkdir(path: _Path, mode: int = 493, user: int = None, group: int = None)

Create a directory, including missing parent directories.

Does nothing if the directory already exists.

Parameters:

  • path – Path to a directory.

  • mode – Directory creation mode.

  • user – Directory user. Currently not used.

  • group – Directory group. Currently not used.

gws.lib.osx.parse_path(path: _Path) → ParsePathResult

Split a file path into its components.

The extension is everything after the first dot in the file name, so a.tar.gz has the stem a and the extension tar.gz. A file name starting with a dot has no extension.

Parameters:

path – File path.

Returns:

The path components.

class gws.lib.osx.ParsePathResult(*args, **kwargs)

Bases: gws.Data

Components of a file path, as returned by parse_path.

dirname: str

The directory part.

extension: str

The file name after the first dot, without the dot.

filename: str

The file name, including the extension.

path: str

The full path.

stem: str

The file name up to the first dot.

gws.lib.osx.process_rss_size(unit: str = 'm') → float

Return the Resident Set Size of the current process.

Parameters:

unit – k (kilobytes), m (megabytes) or g (gigabytes). Any other value returns bytes.

Returns:

The Resident Set Size in the given unit.

gws.lib.osx.rel_path(path: _Path, base: _Path) → str

Make a path relative to a base directory or file path.

If base is a file, its directory is used.

Parameters:

  • path – Path to make relative.

  • base – Base directory or file path.

Returns:

The relative path.

gws.lib.osx.rename(src: _Path, dst: _Path)

Move or rename a file or directory.

Parameters:

  • src – Source path.

  • dst – Destination path.

gws.lib.osx.rmdir(path: _Path) → bool

Remove a directory or a directory tree.

Parameters:

path – Path to a directory. Can be non-empty.

Returns:

True if the directory was removed, False if it does not exist or an OS error occurred.

gws.lib.osx.run(cmd: str | list, input: str = None, echo: bool = False, strict: bool = True, timeout: float = None, **kwargs) → str

Run an external command and wait for it to finish.

A string command is split into arguments with shlex.split. The command is not run in a shell, and stderr is merged into stdout.

Parameters:

  • cmd – Command to run, as a string or a list of arguments.

  • input – Data to send to the command’s stdin.

  • echo – Let the output go to the console instead of capturing it.

  • strict – Raise an error on a non-zero exit code.

  • timeout – Timeout in seconds.

  • kwargs – Arguments to pass to subprocess.Popen.

Returns:

The captured command output, or an empty string if the output was not captured.

Raises:

  • TimeoutError – If the command times out.

  • Error – If the command cannot be run, or exits with a non-zero code and strict is true.

gws.lib.osx.run_nowait(cmd: str | list, **kwargs) → subprocess.Popen

Start a process and return immediately, without waiting for it to finish.

By default, the process inherits stdin, stdout and stderr, and the command is not run in a shell.

Parameters:

  • cmd – Command to run, as a string or a list of arguments.

  • kwargs – Arguments to pass to subprocess.Popen.

Returns:

The subprocess.Popen object of the started process.

gws.lib.osx.running_pids() → dict[int, str]

Return all running processes.

Returns:

A dict mapping process IDs to process names.

exception gws.lib.osx.TimeoutError

Bases: Error

Raised when an external command times out.

gws.lib.osx.touch(path: _Path)

Set the access and modification times of a file to the current time.

If the file does not exist, it is created.

Parameters:

path – File path.

Delete a file.

Directories and non-existing paths are ignored.

Parameters:

path – File path.

Returns:

True on success or if there was nothing to delete, False if an OS error occurred.

gws.lib.osx.user_info(uid=None, gid=None) → dict

Return user and group information.

Parameters:

  • uid – User ID. Defaults to the user ID of the current process.

  • gid – Group ID. Defaults to the user’s primary group ID.

Returns:

A dict with the keys pw_name, pw_uid, pw_gid, pw_dir, pw_shell (from struct_passwd) and gr_name, gr_gid (from struct_group).