files9781%python.module
fault.system

Filesystem interfaces and data structures.

Current working directory related interfaces are provided in process.

Sequence
import

Iterable
import

Optional
import

TypeAlias0
import

os0
import

sys0
import

contextlib0
import

collections0
import

stat0
import

itertools0
import

functools0
import

shutil0
import

tempfile0
import

cachedcalls0
import

Selector
import

Segment0
import

type_codes0
data

Single character representations for file types. Primarily used by Path.fs_require.

type_codes = {
	'*': None,
	'/': 'directory',
	'.': 'data',
	'#': 'device',
	'@': 'socket',
	'|': 'pipe',
	'&': 'link',
	'!': 'void',
	'?': 'unknown',
}

RequirementViolation0
class

Exception

Exception raised by Path.fs_require when requirements are not met.

RequirementViolationProperties

r_violation

The subtype declaring the kind of violation that occurred.

'void'

File did not exist.

'inaccessible'

Path traversed through a non-directory file, or had insufficient permissions on the leading path.

'type'

The r_type did not match the fs_type.

'directory'

The file identified by the path is a directory.

'prohibited'

The required permissions stated in r_properties were not available to the process.

r_type

The required type issued to Path.fs_require.

r_properties

The required properties issued to Path.fs_require.

fs_type

The type of the file identified by fs_path.

fs_path

The path to the subject file.

RequirementViolation__init__0
method

__init__(self, subject, type, violation, rtype, properties)

RequirementViolation__str__192%
method

__str__(self)

Status0
class

tuple

File status interface providing symbolic names for the data packed in the system's status record, system.

StatusEngineering

Experimental. Helps isolate delayed imports. Likely undesired noise if a stat-cache is employed by Path.

Status__slots__0
data

__slots__ = ()

Status_fs_type_map0
data

_fs_type_map = {
	stat.S_IFIFO: 'pipe',
	stat.S_IFLNK: 'link',
	stat.S_IFREG: 'data',
	stat.S_IFDIR: 'directory',
	stat.S_IFSOCK: 'socket',
	stat.S_IFBLK: 'device',
	stat.S_IFCHR: 'device',
}

Status_fs_subtype_map0
data

_fs_subtype_map = {
	stat.S_IFBLK: 'block',
	stat.S_IFCHR: 'character',
}
	@property

Status_interpret_time0
property

Status_read_user30%
property

Status_read_group30%
property

Statusfrom_route10%
classmethod

from_route(Class, route)

Statussystem0
property

The status record produced by the system (os.path.stat).

Statusfilename233%
property
str

The name of the file.

Status__add__10%
method

__add__(self, operand)

Statussize233%
property
int

Number of bytes contained by the file.

Statustype0
property
str

'void'

A broken link or nonexistent file.

'directory'

A file containing other files.

'data'

A regular file containing bytes.

'pipe'

A named pipe; also known as a FIFO.

'socket'

A unix domain socket.

'device'

A character or block device file.

'link'

Status record of a link to a file.

Statussubtype250%
property
Optional[str]

For POSIX-type systems, designates the kind of device: block or character.

None for status instances whose type is not device.

Statuscreated20%
property

Time of creation; UTC. Not available on all systems.

Statuslast_modified0
property

Time of last modification; UTC.

Statuslast_accessed20%
property

Time of last access; UTC.

Statusmeta_last_modified20%
property

Time of last status change; UTC.

Statusowner10%
property

Statusgroup10%
property

Statussetuid10%
property

Statussetgid10%
property

Statussticky10%
property

Statusexecutable0
property
bool

Whether the data file is considered executable by anyone.

Extended attributes are not checked.

Statussearchable433%
property
bool

Whether the directory file is considered searchable by anyone.

Extended attributes are not checked.

path_string_cache0
function

path_string_cache(path)

Path0
class

Selector[str]

Path implementation providing file system controls. files.root is provided for convenience, and process.fs_pwd is available for getting the working directory of the process.

Path__slots__0
data

__slots__ = ('context', 'points',)

PathViolation0
data

Violation = RequirementViolation

Path_root_path0
data

_root_path = _path_separator = os.path.sep

Path_fs_access0
data

_fs_access = staticmethod(functools.partial(
	os.access,
	effective_ids=(os.access in os.supports_effective_ids)
))

Path_fs_access_map0
data

_fs_access_map = {
	'r': os.R_OK,
	'w': os.W_OK,
	'x': os.X_OK,
	'/': 0,
	'!': 0,
}

Pathfs_require196%
method

fs_require(self)

Pathfrom_path0
classmethod

from_path(Class, path)

Construct a Path instance from the given absolute or relative path provided for string; if a relative path is specified, it will be relative to the current working directory as identified by os.path.getcwd.

This is usually the most appropriate way to instantiate a Path route from user input. The exception being cases where the current working directory is not the relevant context.

Pathfrom_relative0
classmethod

from_relative(Class, context, path)

Return a new Route pointing to the file referenced by path; where path is a path relative to the context Path instance.

This function does not refer to the current working directory returned by os.path.getcwd; if this is desired, from_path is the appropriate constructor to use.

Pathfrom_absolute0
classmethod

from_absolute(Class, path)

Pathfrom_absolute_parts0
classmethod

from_absolute_parts(Class, start, *paths)

Path_partition_string0
staticmethod
Iterable[Sequence[str]]

_partition_string(path)

Pathfrom_partitioned_string0
classmethod

from_partitioned_string(Class, path)

Construct an absolute path while interpreting consecutive separators as distinct partitions.

Path__matmul__0
method

__matmul__(self, path)

Pathfs_tmpdir277%
classmethod

fs_tmpdir(Class)

Create a temporary directory at a new route using a context manager.

A Path to the temporary directory is returned on entrance, and that same path is destroyed on exit.

Pathfs_tmpdirEngineering

The use of specific temporary files is avoided as they have inconsistent behavior on some platforms.

Path__repr__180%
method

__repr__(self)

Path__str__0
method

__str__(self)

Pathfullpath0
property
str

Returns the full filesystem path designated by the route.

Pathbytespath0
property
bytes

Returns the full filesystem path designated by the route as a bytes object returned by encoding the fullpath in sys.getfilesystemencoding with 'surrogateescape' as the error mode.

Pathjoin190%
method
str

join(self, *parts)

Construct a string path using self as the prefix and appending the path fragments from parts.

Segment instances should be given with an asterisk applied to the argument.

Pathfilename0
property

Filesystem specific alias for identifier.

Pathextension0
property

Return the last dot-extension of the filename. None if the filename has no . characters at all.

Pathsuffix_filename0
method

suffix_filename(self, appended_suffix)

Modify the name of the file adding the given suffix.

Returns a new Path Route.

Pathsuffix0
data

suffix = suffix_filename

Pathprefix_filename0
method

prefix_filename(self, prefix_string)

Modify the name of the file adding the given prefix.

Returns a new Path Route.

Pathprefix0
data

prefix = prefix_filename

Path__pos__0
method

__pos__(self)

Pathfs_path_string0
method
str

fs_path_string(self)

Construct a normalized string representing the path to the file.

Relative resolution must still be explicitly performed, but empty path entries delimiting partitions are eliminated.

Path__fspath__0
data

__fspath__ = fs_path_string

Pathfs_status0
method
Status

fs_status(self)

Pathfs_type0
method
str

fs_type(self)

The type of file the route points to. Transforms the result of an os.path.stat call into a string describing the st_mode field.

Pathfs_typeReturns

  • 'directory'

  • 'data'

  • 'pipe'

  • 'socket'

  • 'device'

  • 'void'

If no file is present at the path or a broken link is present, 'void' will be returned.

Pathfs_executable350%
method
bool

fs_executable(self)

Whether the file at the route is considered to be an executable.

Pathfs_iterfiles193%
method

fs_iterfiles()

Generate Path instances identifying the files held by the directory, self. By default, all file types are included, but if the type parameter is given, only files of that type are returned.

If self is not a directory or cannot be searched, an empty iterator is returned.

Pathfs_list0
method

fs_list(self)

Retrieve the list of files contained by the directory referred to by self. Returns a pair, the sequence of directories and the sequence of data files.

Sockets, pipes, devices, and other non-data files are not retained in the list.

Pathfs_index0
method

fs_index(self)

Generate pairs of directories associated with their files.

Sockets, pipes, devices, broken links, and other non-data files are not retained in the lists.

Pathfs_snapshot1372%
method

fs_snapshot()

Pathfs_since0
method
Iterable[tuple[int, Selector]]

fs_since(self, since)

Identify the set of files that have been modified since the given point in time.

The resulting iterable does not include directories.

Pathfs_sinceParameters

self

Undocumented.

since

The point in time after which files and directories will be identified as being modified and returned inside the result set.

traversed

Undocumented.

Pathfs_real175%
method

fs_real(self)

Pathexists233%
method
bool

exists(self)

Query the filesystem and return whether or not the file exists.

A Route to a symbolic link will return False if the target does not exist.

Pathfs_modified0
method

fs_modified(self)

Update the modification time of the file identified by self.

Pathfs_size0
method
int

fs_size(self)

Return the size of the file as depicted by os.path.stat.

Pathget_last_modified0
method
int

get_last_modified(self)

Return the modification time of the file.

Pathset_last_modified0
method

set_last_modified(self, time)

Set the modification time of the file identified by the Route.

Pathget_text_content0
method
str

get_text_content(self)

Retrieve the entire contents of the file as a str.

Pathset_text_content0
method
None

set_text_content(self, string)

Modify the regular file identified by self to contain the given string.

Pathmeta30%
method

meta(self)

Return file specific meta data.

WARNING

Preliminary API.

Pathfs_void370%
method

fs_void(self)

Pathfs_replace0
method

fs_replace(self, replacement)

Pathfs_linear156%
method

fs_linear(self)

Pathfs_reduce827%
method

fs_reduce(self, discarded)

Pathfs_init0
method

fs_init(self)

Create and initialize a data file at the route using the given data.

If data is None, no write operation will occur for pre-existing files. If data is not None, the bytes will be written regardless.

Returns the route instance, self. Leading directories will be created as needed.

Pathfs_alloc0
method

fs_alloc(self)

Pathfs_mkdir0
method

fs_mkdir(self)

Pathfs_open362%
method

fs_open(self, *args, **kw)

Open the file pointed to by the route.

If the file doesn't exist, create it; if the directories leading up to the file don't exist, create the directories too.

Pathfs_load0
method
bytes

fs_load(self)

Pathfs_store0
method

fs_store(self, data)

root0
data

The Path to the root directory of the operating system.

root = Path(None, ())

null0
data

The Path to the file that has no content and will discard writes.

null = root/'dev'/'null'

empty0
data

The Path to the directory that contains no files.

empty = (root/'var'/'empty').delimit()