FileSystem¶

Usage

use FileSystem;

or

import FileSystem;

A file utilities library

The FileSystem module focuses on file and directory properties and operations. It does not cover every interaction involving a file— for instance, path-specific operations live in the Path module, while routines for opening, writing to, or reading from a file live in the IO module. Rather, it covers cases where the user would prefer a file or directory to be handled wholesale and/or with minimal interaction. For example, this module contains File/Directory Manipulations and functions for determining the File/Directory Properties. Also included are operations relating to the current process’s file system state, which are performed on a specified locale (Locale State Functionality). The module also contains iterators for traversing the file system (File System Traversal Iterators).

Note

Functions in this module can use and return escaped strings on systems where UTF-8 file names are not enforced.

File/Directory Manipulations¶

copy copyFile copyTree mkdir moveDir remove rmTree symlink chmod chown copyMode rename

File/Directory Properties¶

getGID getMode getFileSize getUID exists isDir isFile isLink isMount sameFile

Locale State Functionality¶

locale.chdir locale.cwd locale.umask

File System Traversal Iterators¶

glob listdir walkdirs findfiles

Constant and Function Definitions¶

const S_IRUSR: int¶

S_IRUSR and the following constants are values of the form S_I[R | W | X][USR | GRP | OTH], S_IRWX[U | G | O], S_ISUID, S_ISGID, or S_ISVTX, where R corresponds to readable, W corresponds to writable, X corresponds to executable, USR and U correspond to user, GRP and G correspond to group, OTH and O correspond to other, directly tied to the C idea of these constants as visible at GNU Permissions. They are intended for use when dealing with the permissions of files or directories, such as with chmod, getMode, mkdir, or umask

S_IRUSR refers to the user’s read permission

const S_IWUSR: int¶: Refers to the user’s write permission, see S_IRUSR

const S_IXUSR: int¶: Refers to the user’s executable permission, see S_IRUSR

const S_IRWXU: int¶: Refers to all the user’s permissions - read, write, and execute. See S_IRUSR

const S_IRGRP: int¶: Refers to the group’s read permission, see S_IRUSR

const S_IWGRP: int¶: Refers to the group’s write permission, see S_IRUSR

const S_IXGRP: int¶: Refers to the group’s executable permission, see S_IRUSR

const S_IRWXG: int¶: Refers to all the permissions - read, write, and execute - of those in this group, see S_IRUSR

const S_IROTH: int¶: Refers to everyone else’s read permission, see S_IRUSR

const S_IWOTH: int¶: Refers to everyone else’s write permission, see S_IRUSR

const S_IXOTH: int¶: Refers to everyone else’s executable permission, see S_IRUSR

const S_IRWXO: int¶: Refers to all the permissions - read, write, and execute - of everyone else, see S_IRUSR

const S_ISUID: int¶: Use of this would cause the user id to be set on execution. See GNU Permissions for what that generally means, and S_IRUSR for intended uses, etc.

const S_ISGID: int¶: Use of this would cause the group id to be set on execution. See GNU Permissions for what that generally means, and S_IRUSR for intended uses, etc.

const S_ISVTX: int¶: This is the sticky bit. See GNU Permissions for what that generally means, and S_IRUSR for intended uses, etc.

proc locale.chdir(name: string) throws¶

Change the current working directory of the locale in question to the specified path name.

Warning

This is not safe within a parallel context. A chdir call in one task will affect the current working directory of all tasks for that locale.

Arguments: name : string – The intended current working directory
Throws: SystemError – Thrown to describe an error if one occurs.

proc chmod(name: string, mode: int) throws¶

Set the permissions of the file or directory specified by the argument name to that indicated by the argument mode.

Arguments

name : string – The name of the file or directory whose permissions should be altered.
mode : int – The permissions desired for the file or directory in question. See description of S_IRUSR, for instance, for potential values.

Throws

FileNotFoundError – Thrown when the name specified does not correspond to a file or directory that exists.
PermissionError – Thrown when the current user does not have permission to change the permissions

proc chown(name: string, uid: int, gid: int) throws¶

Change one or both of the owner and group id of the named file or directory to the specified values. If uid or gid are -1, the value in question will remain unchanged.

Arguments

name : string – The name of the file to be changed.
uid : int – The intended new owner(user) id, or -1 if it should remain the same.
gid : int – The intended new group owner(id), or -1 if it should remain the same.

Throws

SystemError – Thrown to describe an error if one occurs.

proc copy(src: string, dest: string, metadata: bool = false) throws¶

Copies the contents and permissions of the file indicated by src into the file or directory dest. If metadata is set to true, will also copy the metadata (uid, gid, time of last access and time of modification) of the file to be copied. A partially copied file or directory may be present in dest if there is an error in copying.

Note

In the future, when the Path module has been expanded further, this function will be able to support directories for the dest argument.

Arguments

src : string – The source file whose contents and permissions are to be copied
dest : string – The name of the destination file for the contents and permissions. May or may not exist previously, but will be overwritten if it did exist
metadata : bool – This argument indicates whether to copy metadata associated with the source file. It is set to false by default.

Throws

IsADirectoryError – when dest is directory.
SystemError – thrown to describe another error if it occurs.

proc copyFile(src: string, dest: string) throws¶

Copies the contents of the file indicated by src into the file indicated by dest, replacing dest’s contents if it already exists (and is a different file than src, i.e. not a symbolic link to src). Does not copy metadata.

Arguments

src : string – The source file whose contents are to be copied.
dest : string – The intended destination of the contents.

Throws

FileNotFoundError – when src does not exist.
IsADirectoryError – when src or dest is a directory.
SystemError – when src and dest refer to the same file, when dest is not writable, or to describe another error if it occurs.

proc copyMode(src: string, dest: string) throws¶

Copies the permissions of the file indicated by src to the file indicated by dest, leaving contents, owner and group unaffected.

Arguments

src : string – The source file whose permissions are to be copied.
dest : string – The intended destination of the permissions.

Throws

FileNotFoundError – Thrown when the name specified does not correspond to a file or directory that exists.
PermissionError – Thrown when the current user does not have permission to change the permissions

proc copyTree(src: string, dest: string, copySymbolically: bool = false) throws¶

Will recursively copy the tree which lives under src into dst, including all contents and permissions. Metadata such as file creation and modification times, uid, and gid will not be preserved. dst must not previously exist, this function assumes it can create it and any missing parent directories. If copySymbolically is true, symlinks will be copied as symlinks, otherwise their contents and metadata will be copied instead.

Arguments

src : string – The root of the source tree to be copied.
dest : string – The root of the destination directory under which the contents of src are to be copied (must not exist prior to this function call).
copySymbolically : bool – This argument is used to indicate how to handle symlinks in the source directory. It is set to false by default

Throws

FileExistsError – when the dest already exists.
NotADirectoryError – when src is not a directory.
SystemError – thrown to describe another error if it occurs.

proc locale.cwd(): string throws¶

Obtains and returns the current working directory for this locale.

Warning

Another task on this locale can change the current working directory from underneath this task, so use caution when making use of this method in a parallel environment.

Returns: The current working directory for the locale in question.
Return type: string
Throws: SystemError – Thrown to describe an error if one occurs.

proc exists(name: string): bool throws¶

Determines if the file or directory indicated by name exists and returns the result of this check.

Arguments: name : string – The file or directory whose existence is in question.
Returns: true if the provided argument corresponds to an existing file or directory, false otherwise. Also returns false for broken symbolic links.
Return type: bool
Throws: SystemError – Thrown to describe an error if one occurs.

iter findfiles(startdir: string = ".", recursive: bool = false, hidden: bool = false): string¶

Finds files from a given start directory and yields their names, similar to simple invocations of the command-line find utility. May be invoked in serial or non-zippered parallel contexts.

Arguments

startdir : string – The root directory from which to start the search (defaults to ".")
recursive : bool – Indicates whether or not to descend recursively into subdirectories (defaults to false)
hidden : bool – Indicates whether or not to descend into hidden subdirectories and yield hidden files (defaults to false)

Yields

The paths to any files found, relative to startdir, as strings

proc getGID(name: string): int throws¶

Obtains and returns the group id associated with the file or directory specified by name.

Arguments: name : string – The file or directory whose group id is desired
Returns: The group id of the file or directory in question
Return type: int
Throws: SystemError – Thrown to describe an error if one occurs.

proc getMode(name: string): int throws¶

Obtains and returns the current permissions of the file or directory specified by name.

Arguments: name : string – The file or directory whose permissions are desired.
Returns: The permissions of the specified file or directory See description of S_IRUSR, for instance, for potential values.
Return type: int
Throws: SystemError – Thrown to describe an error if one occurs.

proc getFileSize(name: string): int throws¶

Obtains and returns the size (in bytes) of the file specified by name.

Arguments: name : string – The file whose size is desired
Returns: The size in bytes of the file in question
Return type: int
Throws: SystemError – Thrown to describe an error if one occurs.

proc getUID(name: string): int throws¶

Obtains and returns the user id associated with the file or directory specified by name.

Arguments: name : string – The file or directory whose user id is desired
Returns: The user id of the specified file or directory
Return type: int
Throws: SystemError – Thrown to describe an error if one occurs.

iter glob(pattern: string = "*"): string¶

Yields filenames that match a given glob pattern. May be invoked in serial or parallel contexts (zippered or non-).

Arguments: pattern : string – The glob pattern to match against (defaults to "*")
Yields: The matching filenames as strings

proc isDir(name: string): bool throws¶

Determine if the provided path name corresponds to a directory and return the result

Arguments: name : string – A path that could refer to a directory.
Returns: true if the path is a directory, false if it is not
Return type: bool
Throws: SystemError – Thrown to describe an error if one occurs, including the case where the path does not refer to a valid file or directory.

proc isFile(name: string): bool throws¶

Determine if the provided path name corresponds to a file and return the result

Arguments: name : string – A path that could refer to a file.
Returns: true if the path is a file, false if it is not
Return type: bool
Throws: SystemError – Thrown to describe an error if one occurs, including the case where the path does not refer to a valid file or directory.

proc isLink(name: string): bool throws¶

Determine if the provided path name corresponds to a link and return the result. If symbolic links are not supported, will return false.

Arguments: name : string – A path that could refer to a symbolic link.
Returns: true if the path is a symbolic link, false if it is not or if symbolic links are not supported.
Return type: bool
Throws: SystemError – Thrown to describe an error if one occurs, including the case where the path does not refer to a valid file or directory.

proc isMount(name: string): bool throws¶

Determine if the provided path name corresponds to a mount point and return the result.

Arguments: name : string – A path that could refer to a mount point.
Returns: true if the path is a mount point, false if it is not.
Return type: bool
Throws: SystemError – Thrown to describe an error if one occurs, including the case where the path does not refer to a valid file or directory.

iter listdir(path: string = ".", hidden: bool = false, dirs: bool = true, files: bool = true, listlinks: bool = true): string¶

Lists the contents of a directory. May be invoked in serial contexts only.

Arguments

path : string – The directory whose contents should be listed (defaults to ".")
hidden : bool – Indicates whether hidden files/directory should be listed (defaults to false)
dirs : bool – Indicates whether directories should be listed (defaults to true)
files : bool – Indicates whether files should be listed (defaults to true)
listlinks : bool – Indicates whether symbolic links should be listed (defaults to true)

Yields

The names of the specified directory’s contents, as strings

proc mkdir(name: string, mode: int = 511, parents: bool = false) throws¶

Attempt to create a directory with the given path, name. If parents is true, will attempt to create any directory in the path that did not previously exist.

Warning

In the case where parents is true, there is a potential security vulnerability. Checking whether parent directories exist and creating them are separate events. This is called a Time of Check, Time of Use vulnerability (TOCTOU), and in the case of files or directories that did not previously exist, there is no known guard against it. So even if parents == true and a parent directory didn’t exist before this function was called but does exist afterward, it’s not necessarily true that this function created that parent. Some other concurrent operation could have done so, either intentionally or unintentionally, maliciously or ignorantly. This option is provided as a convenience only, and any attempt to perform the same functionality will run a similar risk.

Arguments

name : string – The name of the directory to be created, fully specified.
mode : int – The permissions desired for the directory to create. Takes the current umask into account. See description of S_IRUSR, for instance, for potential values.
parents : bool – Indicates whether parent directories should be created. If set to false, any nonexistent parent will cause an error to occur.

Throws

SystemError – Thrown to describe an error if one occurs.

proc moveDir(src: string, dest: string) throws¶

Recursively moves the directory indicated by src and its contents to the destination denoted by dest. If dest is a directory, src is moved inside of it.

Note

We do not currently support the case where the dest argument already exists and is a directory. When the Path module has been expanded further, this support can be enabled.

Arguments

src : string – the location of the directory to be moved
dest : string – the location to move it to.

Throws

IsADirectoryError – when dest exists and is a directory.
NotADirectoryError – when dest exists and is not a directory.
IllegalArgumentError – when src and dest is the same directory.
SystemError – thrown to describe another error if it occurs.

proc rename(oldname: string, newname: string) throws¶

Renames the file specified by oldname to newname. The file is not opened during this operation.

Arguments

oldname : string – Current name of the file
newname : string – Name which should be used to refer to the file in the future.

Throws

SystemError – Thrown to describe an error if one occurs.

proc remove(name: string) throws¶

Removes the file or directory specified by name

Arguments: name : string – The file/directory to remove
Throws: SystemError – Thrown to describe an error if one occurs.

proc rmTree(root: string) throws¶

Delete the entire directory tree specified by root.

Arguments

root : string – path name representing a directory that should be deleted along with its entire contents.

Throws

FileNotFoundError – when root does not exist.
NotADirectoryError – when root is not a directory.
SystemError – thrown to describe another error if it occurs.

proc sameFile(file1: string, file2: string): bool throws¶

Determines if both pathnames refer to the same file or directory (utilizing operating system operations rather than string ones, due to the possibility of symbolic links, curDir, or parentDir appearing in the path) and returns the result of that check

Arguments

file1 : string – The first path to be compared.
file2 : string – The second path to be compared.

Returns

true if the two paths refer to the same file or directory, false otherwise.

Return type

bool

Throws

SystemError – Thrown to describe an error if one occurs.

proc sameFile(file1: file, file2: file): bool throws

Determines if both file records refer to the same file (utilizing operating system operations rather than string ones, due to the possibility of symbolic links, curDir, or parentDir appearing in the path) and returns the result of that check

Arguments

file1 : file – The first file to be compared.
file2 : file – The second file to be compared.

Returns

true if the two records refer to the same file, false otherwise.

Return type

bool

Throws

SystemError – Thrown to describe an error if one occurs.

proc symlink(oldName: string, newName: string) throws¶

Create a symbolic link pointing to oldName with the path newName.

Arguments

oldName : string – The source file to be linked
newName : string – The location where the symbolic link should live

Throws

SystemError – Thrown to describe an error if one occurs.

proc locale.umask(mask: int): int¶

Sets the file creation mask of the current locale to mask, and returns the previous value of the file creation mask for that locale. See description of S_IRUSR, for instance, for potential values.

Warning

This is not safe within a parallel context. A umask call in one task will affect the umask of all tasks for that locale.

Arguments: mask : int – The file creation mask to use now.
Returns: The previous file creation mask
Return type: int

iter walkdirs(path: string = ".", topdown: bool = true, depth: int = max(int), hidden: bool = false, followlinks: bool = false, sort: bool = false): string¶

Recursively walk a directory structure, yielding directory names. May be invoked in serial or non-zippered parallel contexts.

Note

The current parallel version is not very adaptive/dynamic in its application of parallelism to the list of subdirectories at any given level of the traversal, and could be improved in this regard.

Arguments

path : string – The directory from which to start the walk (defaults to ".")
topdown : bool – Indicates whether to yield a directory before or after descending into its children (defaults to true)
depth : int – Indicates the maximum recursion depth to use (defaults to max(int))
hidden : bool – Indicates whether to descend into hidden directories (defaults to false)
followlinks : bool – Indicates whether to follow symbolic links (defaults to false)
sort : bool – Indicates whether or not to consider subdirectories in sorted order (defaults to false). Note that requesting sorting has no effect in parallel invocations.

Yields

The directory names encountered, relative to path, as strings