API Reference#

The shelmet package.

A shell power-up for working with the file system and running subprocess commands.

Exceptions:

`ArchiveError`	General archive error.
`UnsafeArchiveError`	Unsafe archive exception raised when an untrusted archive would extract contents outside of the destination directory.

Classes:

`Command`	A system command that can be executed multiple times and used to create piped commands.
`Ls`	Directory listing iterable that iterates over its contents and returns them as `Path` objects.

Functions:

`archive`	Create an archive from the given source paths.
`atomicdir`	Context-manager that is used to atomically create a directory and its contents.
`atomicfile`	Context-manager similar to `open()` that is used to perform an atomic file write operation by first writing to a temporary location in the same directory as the destination and then renaming the file to the destination after all write operations are finished.
`backup`	Create a backup of a file or directory as either a direct copy or an archive file.
`cd`	Context manager that changes the working directory on enter and restores it on exit.
`chmod`	Change file or directory permissions using numeric or symbolic modes.
`chown`	Change ownership of file or directory to user and/or group.
`cmd`	Factory that returns an instance of `Command` initialized with the given arguments.
`cp`	Copy file or directory to destination.
`cwd`	Return current working directory as `Path` object.
`dirsync`	Force sync on directory.
`environ`	Context manager that updates environment variables with env on enter and restores the original environment on exit.
`fsync`	Force write of file to disk.
`getdirsize`	Return total size of directory's contents.
`homedir`	Return current user's home directory as `Path` object.
`ls`	Return iterable that lists directory contents as `Path` objects.
`lsarchive`	Return list of member paths contained in archive file.
`lsdirs`	Return iterable that only lists directories in directory as `Path` objects.
`lsfiles`	Return iterable that only lists files in directory as `Path` objects.
`mkdir`	Recursively create directories in paths along with any parent directories that don't already exists.
`mv`	Move source file or directory to destination.
`read`	Return contents of file.
`readbytes`	Return binary contents of file.
`readchunks`	Yield contents of file as chunks.
`readlines`	Yield each line of a file.
`readtext`	Return text contents of file.
`reljoin`	Like `os.path.join` except that all paths are treated as relative to the previous one so that an absolute path in the middle will extend the existing path instead of becoming the new root path.
`rm`	Delete files and directories.
`rmdir`	Delete directories.
`rmfile`	Delete files.
`run`	Convenience function-wrapper around `Command.run()`.
`touch`	Touch files.
`umask`	Context manager that sets the umask to mask and restores it on exit.
`unarchive`	Extract an archive to the given destination path.
`walk`	Return iterable that recursively lists all directory contents as `Path` objects.
`walkdirs`	Return iterable that recursively lists only directories in directory as `Path` objects.
`walkfiles`	Return iterable that recursively lists only files in directory as `Path` objects.
`write`	Write contents to file.
`writebytes`	Write binary contents to file.
`writelines`	Write lines to file.
`writetext`	Write text contents to file.

exception shelmet.ArchiveError(*args, orig_exc=None)[source]#: General archive error.

class shelmet.Command(*args, stdin=None, input=None, stdout=-1, stderr=-1, capture_output=True, combine_output=False, cwd=None, timeout=None, check=True, encoding=None, errors=None, text=True, env=None, replace_env=False, parent=None, **popen_kwargs)[source]#

A system command that can be executed multiple times and used to create piped commands.

Executing the command is done using run() which is a wrapper around subprocess.run. However, the default arguments for a Command enable different default behavior than subprocess.run:

Output is captured
Text-mode is enabled
Environment variables extend os.environ instead of replacing them.
Exceptions are raised by default when the completed process returns a non-zero exit code.
System command arguments can be passed as a var-args instead of just a list.

To disable output capture completely, use capture_output=False. To disable output capture for just one of them, set stdout or stderr to None.

To disable os.environ extension, use replace_env=True.

To disable exception raising, use check=False.

Therefore, to use the default behavior of subprocess.run, set the following keyword arguments:

ls = Command(["ls", "-la"], capture_output=False, text=False, check=False, replace_env=True)
ls.run()

Parameters:

*args (Union[str, bytes, None, Iterable[Union[str, bytes, None]]]) – System command arguments to execute. If None is given as an argument value, it will be discarded.
stdin (Union[int, IO[Any], None]) – Specify the executed command’s standard input.
input (Union[str, bytes, None]) – If given it will be passed to the underlying process as stdin. When used, stdin will be set to PIPE automatically and cannot be used. The value will be encoded or decoded automatically if it does not match the expected type based on whether text-mode is enabled or not.
stdout (Union[int, IO[Any], None]) – Specify the executed command’s standard output.
stderr (Union[int, IO[Any], None]) – Specify the executed command’s standard error.
capture_output (bool) – Whether to capture stdout and stderr and include in the returned completed process result.
combine_output (bool) – Whether to combine stdout and stderr. Equilvalent to setting stderr=subprocess.STDOUT.
cwd (Union[str, Path, None]) – Set the current working directory when executing the command.
timeout (Union[float, int, None]) – If the timeout expires, the child process will be killed and waited for.
check (bool) – Whether to check return code and raise if it is non-zero.
encoding (Optional[str]) – Set encoding to use for text-mode.
errors (Optional[str]) – Specify how encoding and decoding errors should be handled. Must be one of “strict”, “ignore”, “replace”, “backslashreplace”, “xmlcharrefreplace”, “namereplace”
text (bool) – Set text-mode.
env (Optional[dict]) – Environment variables for the new process. Unlike in subprocess.run, the default behavior is to extend the existing environment. Use replace_env=True to replace the environment variables instead.
replace_env (bool) – Whether to replace the current environment when env given.

Keyword Arguments:

them (All other keyword arguments are passed to subprocess.run which subsequently passes) –
subprocess.Popen. (to) –

Methods:

`after`	Return a new command that will be executed after this command regardless of this command's return code.
`and_`	Return a new command that will be AND'd with this command.
`or_`	Return a new command that will be OR'd with this command.
`pipe`	Return a new command whose input will be piped from the output of this command.
`run`	Wrapper around `subprocess.run` that uses this class' arguments as defaults.

Attributes:

`parents`	Return list of parent `Command` objects that pipe output into this command.
`shell_cmd`	Return string version of command that would be used when executing from a shell.

after(*args, stdin=None, input=None, stdout=-1, stderr=-1, capture_output=True, combine_output=False, cwd=None, timeout=None, check=True, encoding=None, errors=None, text=True, env=None, replace_env=False, **popen_kwargs)[source]#

Return a new command that will be executed after this command regardless of this command’s return code.

This is like running “<this-command> ; <next-command>”.

Return type:: Command

and_(*args, stdin=None, input=None, stdout=-1, stderr=-1, capture_output=True, combine_output=False, cwd=None, timeout=None, check=True, encoding=None, errors=None, text=True, env=None, replace_env=False, **popen_kwargs)[source]#

Return a new command that will be AND’d with this command.

This is like running “<this-command> && <next-command>”.

Return type:: Command

or_(*args, stdin=None, input=None, stdout=-1, stderr=-1, capture_output=True, combine_output=False, cwd=None, timeout=None, check=True, encoding=None, errors=None, text=True, env=None, replace_env=False, **popen_kwargs)[source]#

Return a new command that will be OR’d with this command.

This is like running “<this-command> || <next-command>”.

Return type:: Command

property parents: List[ChainCommand]#: Return list of parent Command objects that pipe output into this command.

pipe(*args, stdin=None, input=None, stdout=-1, stderr=-1, capture_output=True, combine_output=False, cwd=None, timeout=None, check=True, encoding=None, errors=None, text=True, env=None, replace_env=False, **popen_kwargs)[source]#

Return a new command whose input will be piped from the output of this command.

This is like running “<this-command> | <next-command>”.

Return type:: Command

run(*extra_args, **override_kwargs)[source]#

Wrapper around subprocess.run that uses this class’ arguments as defaults.

To add additional command args to args, pass them as var-args.

To override default keyword arguments, pass them as keyword-args.

If parent is set (e.g. if this command was created with pipe(), after(), and_(), or or_()), then the parent command will be called first and then chained with this command.

Parameters:

*extra_args (Union[str, bytes, None, Iterable[Union[str, bytes, None]]]) – Extend args with extra command arguments.
**override_kwargs (Any) – Override this command’s keyword arguments.

Return type:

CompletedProcess

property shell_cmd: str#: Return string version of command that would be used when executing from a shell.

class shelmet.Ls(path='.', *, recursive=False, only_files=False, only_dirs=False, include=None, exclude=None)[source]#

Directory listing iterable that iterates over its contents and returns them as Path objects.

Parameters:

path (Union[str, Path]) – Directory to list.
recursive (bool) – Whether to recurse into subdirectories. Defaults to False.
only_files (bool) – Limit results to files only. Mutually exclusive with only_dirs.
only_dirs (bool) – Limit results to directories only. Mutually exclusive with only_files.
include (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Include paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is included if any of the filters return True and path matches only_files or only_dirs (if set). If path is a directory and is not included, its contents are still eligible for inclusion if they match one of the include filters.
exclude (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Exclude paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is not yielded if any of the filters return True. If the path is a directory and is excluded, then all of its contents will be excluded.

exception shelmet.UnsafeArchiveError(*args, orig_exc=None)[source]#: Unsafe archive exception raised when an untrusted archive would extract contents outside of the destination directory.

shelmet.archive(file, *paths, root=None, repath=None, ext='')[source]#

Create an archive from the given source paths.

The source paths can be relative or absolute but the path names inside the archive will always be relative. By default, the paths within the archive will be determined by taking the common path of all the sources and removing it from each source path so that the archive paths are all relative to the shared parent path of all sources. If root is given, it will be used in place of the dynamic common path determination, but it must be a parent path common to all sources.

The archive member names of the source paths can be customized using the repath argument. The repath argument is a mapping of source paths to their custom archive name. If a source path is given as relative, then its repath key must also be relative. If a source path is given as absolute, then its repath key must also be absolute. The repath keys/values should be either strings or Path objects but they don’t have to match the corresponding source path. Both the keys and values will have their path separators normalized.

Archives can be created in either the tar or zip format. A tar archive can use the same compressions that are available from tarfile which are gzipped, bzip2, and lzma. A zip archive will use deflate compression if the zlib library is available. Otherwise, it will fallback to being uncompressed.

The archive format is interfered from the file extension of file by default, but can be overridden using the ext argument (e.g. ext=".tgz" for a gzipped tarball).

The supported tar-based extensions are:

.tar
.tar.gz, .tgz, .taz
.tar.bz2, .tb2, .tbz, .tbz2, .tz2
.tar.xz, .txz

The supported zip-based extensions are:

.zip,
.egg, .jar
.docx, pptx, xlsx
.odg, .odp, .ods, .odt

Parameters:

file (Union[str, Path]) – Archive file path to create.
*paths (Union[str, Path, Ls]) – Source paths (files and/or directories) to archive. Directories will be recursively added.
root (Union[str, Path, None]) – Archive member paths will be relative to this root directory. The root path must be a parent directory of all source paths, otherwise, an exception will be raised.
repath (Union[str, Mapping[Union[str, Path], Union[str, Path]], None]) – A mapping of source paths to archive names that will rename the source path to the mapped value within the archive. A string representing the archive member name can only be used when a single source path is being added to the archive.
ext (str) – Specify the archive format to use by referencing the corresponding file extension (starting with a leading “.”) instead of interfering the format from the file extension.

Return type:

None

shelmet.atomicdir(dir, *, skip_sync=False, overwrite=True)[source]#

Context-manager that is used to atomically create a directory and its contents.

This context-manager will create a temporary directory in the same directory as the destination and yield the temporary directory as a pathblib.Path object. All atomic file system updates to the directory should then be done within the context-manager. Once the context-manager exits, the temporary directory will be passed to dirsync() (unless skip_sync=True) and then moved to the destination followed by dirsync() on the parent directory. If the destination directory exists, it will be overwritten unless overwrite=False.

Parameters:

dir (Union[str, Path]) – Directory path to create.
skip_sync (bool) – Whether to skip calling dirsync() on the directory. Skipping this can help with performance at the cost of durability.
overwrite (bool) – Whether to raise an exception if the destination exists once the directory is to be moved to its destination.

Return type:

Iterator[Path]

shelmet.atomicfile(file, mode='w', *, skip_sync=False, overwrite=True, **open_kwargs)[source]#

Context-manager similar to open() that is used to perform an atomic file write operation by first writing to a temporary location in the same directory as the destination and then renaming the file to the destination after all write operations are finished.

This context-manager will open a temporary file for writing in the same directory as the destination and yield a file object just like open() does. All file operations while the context-manager is opened will be performed on the temporary file. Once the context-manager exits, the temporary file will flushed and fsync’d (unless skip_sync=True). If the destination file exists, it will be overwritten unless overwrite=False.

Parameters:

file (Union[str, Path]) – File path to write to.
mode (str) – File open mode.
skip_sync (bool) – Whether to skip calling fsync on file. Skipping this can help with performance at the cost of durability.
overwrite (bool) – Whether to raise an exception if the destination file exists once the file is to be written to its destination.
**open_kwargs (Any) – Additional keyword arguments to open() when creating the temporary write file.

Return type:

Iterator[IO]

shelmet.backup(src, *, timestamp='%Y-%m-%dT%H:%M:%S.%f%z', utc=False, epoch=False, prefix='', suffix='~', ext=None, hidden=False, overwrite=False, dir=None, namer=None)[source]#

Create a backup of a file or directory as either a direct copy or an archive file.

The format of the backup name is {prefix}{src}.{timestamp}{suffix|ext}.

By default, the backup will be created in the same parent directory as the source and be named like "src.YYYY-MM-DDThh:mm:ss.ffffff~", where the timestamp is the current local time.

If utc is True, then the timestamp will be in the UTC timezone.

If epoch is True, then the timestamp will be the Unix time as returned by time.time() instead of the strftime format.

If ext is given, the backup created will be an archive file. The extension must be one that archive() supports. The suffix value will be ignored and ext used in its place.

If hidden is True, then a "." will be prepended to the prefix. It won’t be added if prefix already starts with a ".".

If dir is given, it will be used as the parent directory of the backup instead of the source’s parent directory.

If overwrite is True and the backup location already exists, then it will be overwritten.

If namer is given, it will be called with namer(src) and it should return the full destination path of the backup. All other arguments to this function will be ignored except for overwrite.

Parameters:

src (Union[str, Path]) – Source file or directory to backup.
timestamp (Optional[str]) – Timestamp strftime-format string or None to exclude timestamp from backup name. Defaults to ISO-8601 format.
utc (bool) – Whether to use UTC time instead of local time for the timestamp.
epoch (bool) – Whether to use the Unix time for the timestamp instead of the strftime format in timestamp.
prefix (str) – Name prefix to prepend to the backup.
suffix (str) – Name suffix to append to the backup.
ext (Optional[str]) – Create an archive of src as the backup instead of a direct copy using the given archive extension. The extension must be supported by archive() or an exception will be raised. When given the suffix value is ignored and ext will be used in its place.
hidden (bool) – Whether to ensure that the backup location is a hidden file or directory.
overwrite (bool) – Whether to overwrite an existing file or directory when backing up.
dir (Union[str, Path, None]) – Set the parent directory of the backup. Defaults to None which will use the parent directory of the src.
namer (Optional[Callable[[Path], Union[str, Path]]]) – Naming function that can be used to return the full path of the backup location. It will be passed the src value as a pathlib.Path object as a positional argument. It should return the destination path of the backup as a str or pathlib.Path.

Return type:

Path

Returns:

Backup location.

shelmet.cd(path)[source]#

Context manager that changes the working directory on enter and restores it on exit.

Parameters:: path (Union[str, Path]) – Directory to change to.
Return type:: Iterator[None]

shelmet.chmod(path, mode, *, follow_symlinks=True, recursive=False)[source]#

Change file or directory permissions using numeric or symbolic modes.

The mode can either be an integer, an octal number (e.g. 0o600), an octal string (e.g. "600"), or a symbolic permissions string (e.g. "u+rw,g=r,o-rwx").

The symbolic permissions string format is similar to what is accepted by the UNIX command chmod:

Symbolic format: [ugoa...][-+=][rwxstugo...][,...]
[ugoa...]: Optional zero or more characters that set the user class parameter.
- u: user
- g: group
- o: other
- a: all
- Defaults to a when none given
[-+=]: Required operation that modifies the permissions.
- -: removes the given permissions
- +: adds the given permissions
- =: sets the given permissions to what was specified
- If = is used without permissions, then the user class will have all of its permissions removed
[rwxstugo...]: Permissions to modify for the given user classes.
- r: Read
- w: Write
- x: Execute
- s: User or Group ID bit
- t: Sticky bit
- u: User permission bits of the original path mode
- g: Group permission bits of the original path mode
- o: Other permission bits of the original path mode
Multiple permission clauses are separated with ,.

Examples:

# Set permissions to 600 using octal number.
chmod(path, 0o600)

# Set permissions to 600 using octal string.
chmod(path, "600")

# Set user to read-write, group to read, and remove read-write-execute from other
chmod(path, "u=rw,g=r,o-rwx")

# Set user, group, and other to read-write
chmod(path, "a=rw")

# Add execute permission for user, group, and other
chmod(path, "+x")

# Add user id bit, group id bit, and set sticky bit
chmod(path, "u+s,g+s,+t")

# Set group permission to same as user
chmod(path, "g=u")

Parameters:

path (Union[str, Path, int]) – File, directory, or file-descriptor.
mode (Union[str, int]) – Permission mode to set.
follow_symlinks (bool) – Whether to follow symlinks.
recursive (bool) – Whether to recursively apply permissions to subdirectories and their files.

Return type:

None

shelmet.chown(path, user=None, group=None, *, follow_symlinks=True, recursive=False)[source]#

Change ownership of file or directory to user and/or group.

User and group can be a string name or a numeric id. Leave as None to not change the respective user or group ownership.

Parameters:

path (Union[str, Path, int]) – File, directory, or file-descriptor.
user (Union[str, int, None]) – User name or uid to set as owner. Use None or -1 to not change.
group (Union[str, int, None]) – Group name or gid to set as owner. Use None or -1 to not change.
follow_symlinks (bool) – Whether to follow symlinks.
recursive (bool) – Whether to recursively apply ownership to subdirectories and their files.

Return type:

None

shelmet.cmd(*args, stdin=None, input=None, stdout=-1, stderr=-1, capture_output=True, combine_output=False, cwd=None, timeout=None, check=True, encoding=None, errors=None, text=True, env=None, replace_env=False, **popen_kwargs)[source]#: Factory that returns an instance of Command initialized with the given arguments. :rtype: Command

See also

Command for description of arguments.

shelmet.cp(src, dst, *, follow_symlinks=True)[source]#

Copy file or directory to destination.

Files are copied atomically by first copying to a temporary file in the same target directory and then renaming the temporary file to its actual filename.

Parameters:

src (Union[str, Path]) – Source file or directory to copy from.
dst (Union[str, Path]) – Destination file or directory to copy to.
follow_symlinks (bool) – When true (the default), symlinks in the source will be dereferenced into the destination. When false, symlinks in the source will be preserved as symlinks in the destination.

Return type:

None

shelmet.cwd()[source]#

Return current working directory as Path object.

Return type:: Path

shelmet.dirsync(path)[source]#

Force sync on directory.

Parameters:: path (Union[str, Path]) – Directory to sync.
Return type:: None

shelmet.environ(env=None, *, replace=False)[source]#

Context manager that updates environment variables with env on enter and restores the original environment on exit.

Parameters:

env (Optional[Dict[str, str]]) – Environment variables to set.
replace (bool) – Whether to clear existing environment variables before setting new ones. This fully replaces the existing environment variables so that only env are set.

Yields:

The current environment variables.

Return type:

Iterator[Dict[str, str]]

shelmet.fsync(fd)[source]#

Force write of file to disk.

The file descriptor will have os.fsync() (or fcntl.fcntl() with fcntl.F_FULLFSYNC if available) called on it. If a file object is passed it, then it will first be flushed before synced.

Parameters:: fd (Union[IO, int]) – Either file descriptor integer or file object.
Return type:: None

shelmet.getdirsize(path, pattern='**/*')[source]#

Return total size of directory’s contents.

Parameters:

path (Union[str, Path]) – Directory to calculate total size of.
pattern (str) – Only count files if they match this glob-pattern.

Return type:

int

Returns:

Total size of directory in bytes.

shelmet.homedir()[source]#: Return current user’s home directory as Path object.

shelmet.ls(path='.', *, recursive=False, only_files=False, only_dirs=False, include=None, exclude=None)[source]#

Return iterable that lists directory contents as Path objects.

Parameters:

path (Union[str, Path]) – Directory to list.
recursive (bool) – Whether to recurse into subdirectories. Defaults to False.
only_files (bool) – Limit results to files only. Mutually exclusive with only_dirs.
only_dirs (bool) – Limit results to directories only. Mutually exclusive with only_files.
include (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Include paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is included if any of the filters return True and path matches only_files or only_dirs (if set). If path is a directory and is not included, its contents are still eligible for inclusion if they match one of the include filters.
exclude (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Exclude paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is not yielded if any of the filters return True. If the path is a directory and is excluded, then all of its contents will be excluded.

Return type:

Ls

shelmet.lsarchive(file, ext='')[source]#

Return list of member paths contained in archive file.

Parameters:

file (Union[str, Path]) – Archive file to list.
ext (str) – Specify the archive format to use by referencing the corresponding file extension (starting with a leading “.”) instead of interfering the format from the file extension.

Return type:

List[PurePath]

shelmet.lsdirs(path='.', *, include=None, exclude=None)[source]#

Return iterable that only lists directories in directory as Path objects.

See also

This function is not recursive and will only yield the top-level contents of a directory. Use walkdirs() to recursively yield all directories from a directory.

Parameters:

path (Union[str, Path]) – Directory to list.
include (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Include paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is included if any of the filters return True. If path is a directory and is not included, its contents are still eligible for inclusion if they match one of the include filters.
exclude (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Exclude paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is not yielded if any of the filters return True. If the path is a directory and is excluded, then all of its contents will be excluded.

Return type:

Ls

shelmet.lsfiles(path='.', *, include=None, exclude=None)[source]#

Return iterable that only lists files in directory as Path objects.

See also

This function is not recursive and will only yield the top-level contents of a directory. Use walkfiles() to recursively yield all files from a directory.

Parameters:

path (Union[str, Path]) – Directory to list.
include (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Include paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is included if any of the filters return True. If path is a directory and is not included, its contents are still eligible for inclusion if they match one of the include filters.
exclude (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Exclude paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is not yielded if any of the filters return True. If the path is a directory and is excluded, then all of its contents will be excluded.

Return type:

Ls

shelmet.mkdir(*paths, mode=511, exist_ok=True)[source]#

Recursively create directories in paths along with any parent directories that don’t already exists.

This is like the Unix command mkdir -p <path1> <path2> ....

Parameters:

*paths (Union[str, Path]) – Directories to create.
mode (int) – Access mode for directories.
exist_ok (bool) – Whether it’s ok or not if the path already exists. When True, a FileExistsError will be raised.

Return type:

None

shelmet.mv(src, dst)[source]#

Move source file or directory to destination.

The move semantics are as follows:

If src and dst are files, then src will be renamed to dst and overwrite dst if it exists.
If src is a file and dst is a directory, then src will be moved under dst.
If src is a directory and dst does not exist, then src will be renamed to dst and any parent directories that don’t exist in the dst path will be created.
If src is a directory and dst is a directory and the src’s basename does not exist under dst or if it is an empty directory, then src will be moved under dst.
If src is directory and dst is a directory and the src’s basename is a non-empty directory under dst, then an OSError will be raised.
If src and dst reference two difference file-systems, then src will be copied to dst using cp() and then deleted at src.

Parameters:

src (Union[str, Path]) – Source file or directory to move.
dst (Union[str, Path]) – Destination file or directory to move source to.

Return type:

None

shelmet.read(file, mode='r', **open_kwargs)[source]#

Return contents of file.

Parameters:

file (Union[str, Path]) – File to read.
mode (str) – File open mode.
**open_kwargs (Any) – Additional keyword arguments to pass to open.

Return type:

Union[str, bytes]

shelmet.readbytes(file, **open_kwargs)[source]#

Return binary contents of file.

Equivalent to calling read() with mode="rb".

Parameters:

file (Union[str, Path]) – File to read.
**open_kwargs (Any) – Additional keyword arguments to pass to open.

Return type:

bytes

shelmet.readchunks(file, mode='r', *, size=8192, sep=None, **open_kwargs)[source]#

Yield contents of file as chunks.

If separator, sep, is not given, chunks will be yielded by size.

If separator, sep, is given, chunks will be yielded from as if from contents.split(sep). The size argument will still be used for each file read operation, but the contents will be buffered until a separator is encountered.

Parameters:

file (Union[str, Path]) – File to read.
mode (str) – File open mode.
size (int) – Size of chunks to read from file at a time and chunk size to yield when sep not given.
sep (Union[str, bytes, None]) – Separator to split chunks by in lieu of splitting by size.
**open_kwargs (Any) – Additional keyword arguments to pass to open.

Return type:

Generator[Union[str, bytes], None, None]

shelmet.readlines(file, mode='r', *, limit=-1, **open_kwargs)[source]#

Yield each line of a file.

Note

Line-endings are included in the yielded values.

Parameters:

file (Union[str, Path]) – File to read.
mode (str) – File open mode.
limit (int) – Maximum length of each line to yield. For example, limit=10 will yield the first 10 characters of each line.
**open_kwargs (Any) – Additional keyword arguments to pass to open.

Return type:

Generator[Union[str, bytes], None, None]

shelmet.readtext(file, **open_kwargs)[source]#

Return text contents of file.

Equivalent to calling read() with mode="r" (the default behavior of read()).

Parameters:

file (Union[str, Path]) – File to read.
**open_kwargs (Any) – Additional keyword arguments to pass to open.

Return type:

str

shelmet.reljoin(*paths)[source]#

Like os.path.join except that all paths are treated as relative to the previous one so that an absolute path in the middle will extend the existing path instead of becoming the new root path.

Parameters:: *paths (Union[str, Path]) – Paths to join together.
Return type:: str

shelmet.rm(*paths)[source]#

Delete files and directories.

Note

Deleting non-existent files or directories does not raise an error.

Warning

This function is like $ rm -rf so be careful. To limit the scope of the removal to just files or just directories, use rmfile() or rmdir() respectively.

Parameters:: *paths (Union[str, Path]) – Files and/or directories to delete.
Return type:: None

shelmet.rmdir(*dirs)[source]#

Delete directories.

Note

Deleting non-existent directories does not raise an error.

Warning

This function is like calling $ rm -rf on a directory. To limit the scope of the removal to just files, use rmfile().

Parameters:: *dirs (Union[str, Path]) – Directories to delete.
Raises:: NotADirectoryError – When given path is not a directory.
Return type:: None

shelmet.rmfile(*files)[source]#

Delete files.

Note

Deleting non-existent files does not raise an error.

Parameters:: *files (Union[str, Path]) – Files to delete.
Raises:: IsADirectoryError – When given path is a directory.
Return type:: None

shelmet.run(*args, stdin=None, input=None, stdout=-1, stderr=-1, capture_output=True, combine_output=False, cwd=None, timeout=None, check=True, encoding=None, errors=None, text=True, env=None, replace_env=False, **popen_kwargs)[source]#

Convenience function-wrapper around Command.run().

Using this function is equivalent to:

result = sh.cmd(*args, **kwargs).run()

Return type:: CompletedProcess

See also

Command for description of arguments.

shelmet.touch(*paths)[source]#

Touch files.

Parameters:: *paths (Union[str, Path]) – File paths to create.
Return type:: None

shelmet.umask(mask=0)[source]#

Context manager that sets the umask to mask and restores it on exit.

Parameters:: mask (int) – Numeric umask to set.
Yields:: None
Return type:: Iterator[None]

shelmet.unarchive(file, dst='.', *, ext='', trusted=False)[source]#

Extract an archive to the given destination path.

If the archive contains any paths that would be extracted outside the destination path, an ArchiveError will be raised to prevent untrusted archives from extracting contents to locations that may pose a security risk. To allow a trusted archive to extract contents outside the destination, use the argument trusted=True.

Archives can be extracted from either zip or tar formats with compression. The tar compressions available are the same as what is supported by tarfile which are gzipped, bzip2, and lzma.

The archive format is interfered from the file extension of file by default, but can be overridden using the ext argument (e.g. ext=".tgz" for a gzipped tarball).

The supported tar extensions are:

.tar
.tar.gz, .tgz, .taz
.tar.bz2, .tb2, .tbz, .tbz2, .tz2
.tar.xz, .txz
.zip,
.egg, .jar
.docx, pptx, xlsx
.odg, .odp, .ods, .odt

Parameters:

file (Union[str, Path]) – Archive file to unarchive.
dst (Union[str, Path]) – Destination directory to unarchive contents to.
ext (str) – Specify the archive format to use by referencing the corresponding file extension (starting with a leading “.”) instead of interfering the format from the file extension.
trusted (bool) – Whether the archive is safe and can be trusted to allow it to extract contents outside of the destination path. Only enable this for archives that have been verified as originating from a trusted source.

Return type:

None

shelmet.walk(path='.', *, only_files=False, only_dirs=False, include=None, exclude=None)[source]#

Return iterable that recursively lists all directory contents as Path objects.

See also

This function is recursive and will list all contents of a directory. Use ls() to list only the top-level contents of a directory.

Parameters:

path (Union[str, Path]) – Directory to walk.
only_files (bool) – Limit results to files only. Mutually exclusive with only_dirs.
only_dirs (bool) – Limit results to directories only. Mutually exclusive with only_files.
include (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Include paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is included if any of the filters return True and path matches only_files or only_dirs (if set). If path is a directory and is not included, its contents are still eligible for inclusion if they match one of the include filters.
exclude (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Exclude paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is not yielded if any of the filters return True. If the path is a directory and is excluded, then all of its contents will be excluded.

Return type:

Ls

shelmet.walkdirs(path='.', *, include=None, exclude=None)[source]#

Return iterable that recursively lists only directories in directory as Path objects.

See also

This function is recursive and will list all directories in a directory. Use lsfiles() to list only the top-level directories in a directory.

Parameters:

path (Union[str, Path]) – Directory to walk.
include (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Include paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is included if any of the filters return True. If path is a directory and is not included, its contents are still eligible for inclusion if they match one of the include filters.
exclude (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Exclude paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is not yielded if any of the filters return True. If the path is a directory and is excluded, then all of its contents will be excluded.

Return type:

Ls

shelmet.walkfiles(path='.', *, include=None, exclude=None)[source]#

Return iterable that recursively lists only files in directory as Path objects.

See also

This function is recursive and will list all files in a directory. Use lsfiles() to list only the top-level files in a directory.

Parameters:

path (Union[str, Path]) – Directory to walk.
include (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Include paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is included if any of the filters return True. If path is a directory and is not included, its contents are still eligible for inclusion if they match one of the include filters.
exclude (Union[str, Pattern, Callable[[Path], bool], Iterable[Union[str, Pattern, Callable[[Path], bool]]], None]) – Exclude paths by filtering on a glob-pattern string, compiled regex, callable, or iterable containing any of those types. Path is not yielded if any of the filters return True. If the path is a directory and is excluded, then all of its contents will be excluded.

Return type:

Ls

shelmet.write(file, contents, mode='w', *, atomic=False, **open_kwargs)[source]#

Write contents to file.

Parameters:

file (Union[str, Path]) – File to write.
contents (Union[str, bytes]) – Contents to write.
mode (str) – File open mode.
atomic (bool) – Whether to write the file to a temporary location in the same directory before moving it to the destination.
**open_kwargs (Any) – Additional keyword arguments to pass to open.

Return type:

None

shelmet.writebytes(file, contents, mode='wb', *, atomic=False, **open_kwargs)[source]#

Write binary contents to file.

Parameters:

file (Union[str, Path]) – File to write.
contents (bytes) – Contents to write.
mode (str) – File open mode.
atomic (bool) – Whether to write the file to a temporary location in the same directory before moving it to the destination.
**open_kwargs (Any) – Additional keyword arguments to pass to open.

Return type:

None

shelmet.writelines(file, items, mode='w', *, ending=None, atomic=False, **open_kwargs)[source]#

Write lines to file.

Parameters:

file (Union[str, Path]) – File to write.
items (Union[Iterable[str], Iterable[bytes]]) – Items to write.
mode (str) – File open mode.
ending (Union[str, bytes, None]) – Line ending to use. Defaults to newline.
atomic (bool) – Whether to write the file to a temporary location in the same directory before moving it to the destination.
**open_kwargs (Any) – Additional keyword arguments to pass to open.

Return type:

None

shelmet.writetext(file, contents, mode='w', *, atomic=False, **open_kwargs)[source]#

Write text contents to file.

Parameters:

file (Union[str, Path]) – File to write.
contents (str) – Contents to write.
mode (str) – File open mode.
atomic (bool) – Whether to write the file to a temporary location in the same directory before moving it to the destination.
**open_kwargs (Any) – Additional keyword arguments to pass to open.

Return type:

None