Files and directories (Effect's FileSystem). Paths are strings;
every operation fails with a PlatformError.
An implementation defines the abstract operations; exists, glob,
read_file_string, write_file_string, stream and sink are
built from them.
Functions#
access#
access(path, *, readable=False, writable=False) -> Effect[None, PlatformError]Succeed when path exists (and is readable / writable).
| Parameter | Type | Description |
|---|---|---|
path | str | |
readable | bool = False | |
writable | bool = False |
Returns Effect[None, PlatformError]
@abstractmethod
def access(
self, path: str, *, readable: bool = False, writable: bool = False
) -> Effect[None, PlatformError]:
"""Succeed when ``path`` exists (and is readable / writable)."""copy#
copy(from_path, to_path, *, overwrite=False, preserve_timestamps=False) -> Effect[None, PlatformError]Copy a file or a directory tree. Without overwrite, files
that exist at the destination are kept.
| Parameter | Type | Description |
|---|---|---|
from_path | str | |
to_path | str | |
overwrite | bool = False | |
preserve_timestamps | bool = False |
Returns Effect[None, PlatformError]
@abstractmethod
def copy(
self,
from_path: str,
to_path: str,
*,
overwrite: bool = False,
preserve_timestamps: bool = False,
) -> Effect[None, PlatformError]:
"""Copy a file or a directory tree. Without ``overwrite``, files
that exist at the destination are kept."""copy_file#
copy_file(from_path, to_path) -> Effect[None, PlatformError]Copy the file from_path (its contents and permissions) to
to_path, replacing a file there.
| Parameter | Type | Description |
|---|---|---|
from_path | str | |
to_path | str |
Returns Effect[None, PlatformError]
@abstractmethod
def copy_file(self, from_path: str, to_path: str) -> Effect[None, PlatformError]:
"""Copy the file ``from_path`` (its contents and permissions) to
``to_path``, replacing a file there."""chmod#
chmod(path, mode) -> Effect[None, PlatformError]Set the permissions of path to mode (0o644, say).
| Parameter | Type | Description |
|---|---|---|
path | str | |
mode | int |
Returns Effect[None, PlatformError]
@abstractmethod
def chmod(self, path: str, mode: int) -> Effect[None, PlatformError]:
"""Set the permissions of ``path`` to ``mode`` (``0o644``, say)."""chown#
chown(path, uid, gid) -> Effect[None, PlatformError]Set the owner of path to user uid and group gid.
| Parameter | Type | Description |
|---|---|---|
path | str | |
uid | int | |
gid | int |
Returns Effect[None, PlatformError]
@abstractmethod
def chown(self, path: str, uid: int, gid: int) -> Effect[None, PlatformError]:
"""Set the owner of ``path`` to user ``uid`` and group ``gid``."""link#
link(from_path, to_path) -> Effect[None, PlatformError]Make to_path a hard link to from_path.
| Parameter | Type | Description |
|---|---|---|
from_path | str | |
to_path | str |
Returns Effect[None, PlatformError]
@abstractmethod
def link(self, from_path: str, to_path: str) -> Effect[None, PlatformError]:
"""Make ``to_path`` a hard link to ``from_path``."""lstat#
lstat(path) -> Effect[FileInfo, PlatformError]stat of a symbolic link itself.
| Parameter | Type | Description |
|---|---|---|
path | str |
Returns Effect[FileInfo, PlatformError]
@abstractmethod
def lstat(self, path: str) -> Effect[FileInfo, PlatformError]:
"""``stat`` of a symbolic link itself."""make_directory#
make_directory(path, *, recursive=False, mode=511) -> Effect[None, PlatformError]Make a directory; with recursive, its missing parents too, and
an existing directory is no error.
| Parameter | Type | Description |
|---|---|---|
path | str | |
recursive | bool = False | |
mode | int = 511 |
Returns Effect[None, PlatformError]
@abstractmethod
def make_directory(
self, path: str, *, recursive: bool = False, mode: int = 0o777
) -> Effect[None, PlatformError]:
"""Make a directory; with ``recursive``, its missing parents too, and
an existing directory is no error."""make_temp_directory#
make_temp_directory(*, directory=None, prefix='') -> Effect[str, PlatformError]Make a new directory named with prefix in directory (the
system's temporary directory by default) and give its path. Nothing
removes it; make_temp_directory_scoped does.
| Parameter | Type | Description |
|---|---|---|
directory | str | None = None | |
prefix | str = '' |
Returns Effect[str, PlatformError]
@abstractmethod
def make_temp_directory(
self, *, directory: str | None = None, prefix: str = ""
) -> Effect[str, PlatformError]:
"""Make a new directory named with ``prefix`` in ``directory`` (the
system's temporary directory by default) and give its path. Nothing
removes it; ``make_temp_directory_scoped`` does."""make_temp_directory_scoped#
make_temp_directory_scoped(*, directory=None, prefix='') -> Effect[str, PlatformError, Scope]A temporary directory, removed with its contents when the scope closes.
| Parameter | Type | Description |
|---|---|---|
directory | str | None = None | |
prefix | str = '' |
Returns Effect[str, PlatformError, Scope]
@abstractmethod
def make_temp_directory_scoped(
self, *, directory: str | None = None, prefix: str = ""
) -> Effect[str, PlatformError, Scope]:
"""A temporary directory, removed with its contents when the scope
closes."""make_temp_file#
make_temp_file(*, directory=None, prefix='', suffix='') -> Effect[str, PlatformError]An empty file in a new temporary directory named with
prefix.
| Parameter | Type | Description |
|---|---|---|
directory | str | None = None | |
prefix | str = '' | |
suffix | str = '' |
Returns Effect[str, PlatformError]
@abstractmethod
def make_temp_file(
self, *, directory: str | None = None, prefix: str = "", suffix: str = ""
) -> Effect[str, PlatformError]:
"""An empty file in a new temporary directory named with
``prefix``."""make_temp_file_scoped#
make_temp_file_scoped(*, directory=None, prefix='', suffix='') -> Effect[str, PlatformError, Scope]A temporary file, removed with its directory when the scope closes.
| Parameter | Type | Description |
|---|---|---|
directory | str | None = None | |
prefix | str = '' | |
suffix | str = '' |
Returns Effect[str, PlatformError, Scope]
@abstractmethod
def make_temp_file_scoped(
self, *, directory: str | None = None, prefix: str = "", suffix: str = ""
) -> Effect[str, PlatformError, Scope]:
"""A temporary file, removed with its directory when the scope
closes."""open#
open(path, *, flag='r', mode=438, no_follow=False) -> Effect[File, PlatformError, Scope]Open a file until the scope closes. no_follow refuses a
symbolic link (BadResource), or fails with BadArgument
where the platform cannot tell.
| Parameter | Type | Description |
|---|---|---|
path | str | |
flag | OpenFlag = 'r' | |
mode | int = 438 | |
no_follow | bool = False |
Returns Effect[File, PlatformError, Scope]
@abstractmethod
def open(
self, path: str, *, flag: OpenFlag = "r", mode: int = 0o666, no_follow: bool = False
) -> Effect[File, PlatformError, Scope]:
"""Open a file until the scope closes. ``no_follow`` refuses a
symbolic link (``BadResource``), or fails with ``BadArgument``
where the platform cannot tell."""read_directory#
read_directory(path, *, recursive=False) -> Effect[list[str], PlatformError]The names in a directory; with recursive, every path below
it, relative to it.
| Parameter | Type | Description |
|---|---|---|
path | str | |
recursive | bool = False |
Returns Effect[list[str], PlatformError]
@abstractmethod
def read_directory(
self, path: str, *, recursive: bool = False
) -> Effect[list[str], PlatformError]:
"""The names in a directory; with ``recursive``, every path below
it, relative to it."""read_directory_entries#
read_directory_entries(path) -> Effect[tuple[DirectoryEntry, ...], PlatformError]The names in a directory (as read_directory, in no particular
order) with the type of each entry itself, not of a link's target;
"Unknown" where the listing cannot tell, and glob then asks
stat. A wrapper that changes read_directory (prefixing
paths, say) must change this the same way for glob to list the
right directory.
| Parameter | Type | Description |
|---|---|---|
path | str |
Returns Effect[tuple[DirectoryEntry, ...], PlatformError]
@abstractmethod
def read_directory_entries(
self, path: str
) -> Effect[tuple[DirectoryEntry, ...], PlatformError]:
"""The names in a directory (as ``read_directory``, in no particular
order) with the type of each entry itself, not of a link's target;
``"Unknown"`` where the listing cannot tell, and ``glob`` then asks
``stat``. A wrapper that changes ``read_directory`` (prefixing
paths, say) must change this the same way for ``glob`` to list the
right directory."""read_file#
read_file(path) -> Effect[bytes, PlatformError]The contents of the file path.
| Parameter | Type | Description |
|---|---|---|
path | str |
Returns Effect[bytes, PlatformError]
@abstractmethod
def read_file(self, path: str) -> Effect[bytes, PlatformError]:
"""The contents of the file ``path``."""read_link#
read_link(path) -> Effect[str, PlatformError]Where the symbolic link path points, as written in the
link.
| Parameter | Type | Description |
|---|---|---|
path | str |
Returns Effect[str, PlatformError]
@abstractmethod
def read_link(self, path: str) -> Effect[str, PlatformError]:
"""Where the symbolic link ``path`` points, as written in the
link."""real_path#
real_path(path) -> Effect[str, PlatformError]The canonical path, every symbolic link resolved.
| Parameter | Type | Description |
|---|---|---|
path | str |
Returns Effect[str, PlatformError]
@abstractmethod
def real_path(self, path: str) -> Effect[str, PlatformError]:
"""The canonical path, every symbolic link resolved."""remove#
remove(path, *, recursive=False, force=False) -> Effect[None, PlatformError]Remove a file, or a directory with recursive. With force
a missing path is no error.
| Parameter | Type | Description |
|---|---|---|
path | str | |
recursive | bool = False | |
force | bool = False |
Returns Effect[None, PlatformError]
@abstractmethod
def remove(
self, path: str, *, recursive: bool = False, force: bool = False
) -> Effect[None, PlatformError]:
"""Remove a file, or a directory with ``recursive``. With ``force``
a missing path is no error."""rename#
rename(old_path, new_path) -> Effect[None, PlatformError]Move the file or directory old_path to new_path.
| Parameter | Type | Description |
|---|---|---|
old_path | str | |
new_path | str |
Returns Effect[None, PlatformError]
@abstractmethod
def rename(self, old_path: str, new_path: str) -> Effect[None, PlatformError]:
"""Move the file or directory ``old_path`` to ``new_path``."""stat#
stat(path) -> Effect[FileInfo, PlatformError]What is known about path (a symbolic link is followed; see
lstat).
| Parameter | Type | Description |
|---|---|---|
path | str |
Returns Effect[FileInfo, PlatformError]
@abstractmethod
def stat(self, path: str) -> Effect[FileInfo, PlatformError]:
"""What is known about ``path`` (a symbolic link is followed; see
``lstat``)."""symlink#
symlink(from_path, to_path) -> Effect[None, PlatformError]Make to_path a symbolic link pointing at from_path.
| Parameter | Type | Description |
|---|---|---|
from_path | str | |
to_path | str |
Returns Effect[None, PlatformError]
@abstractmethod
def symlink(self, from_path: str, to_path: str) -> Effect[None, PlatformError]:
"""Make ``to_path`` a symbolic link pointing at ``from_path``."""truncate#
truncate(path, length=0) -> Effect[None, PlatformError]Cut the file path to length bytes (empty by default),
or extend it with zero bytes.
| Parameter | Type | Description |
|---|---|---|
path | str | |
length | int = 0 |
Returns Effect[None, PlatformError]
@abstractmethod
def truncate(self, path: str, length: int = 0) -> Effect[None, PlatformError]:
"""Cut the file ``path`` to ``length`` bytes (empty by default),
or extend it with zero bytes."""utimes#
utimes(path, atime, mtime) -> Effect[None, PlatformError]Set the access and modification times (a datetime, or
seconds since the epoch).
| Parameter | Type | Description |
|---|---|---|
path | str | |
atime | datetime | float | |
mtime | datetime | float |
Returns Effect[None, PlatformError]
@abstractmethod
def utimes(
self, path: str, atime: datetime | float, mtime: datetime | float
) -> Effect[None, PlatformError]:
"""Set the access and modification times (a ``datetime``, or
seconds since the epoch)."""watch#
watch(path, *, recursive=False, on_ready=None) -> Stream[WatchEvent, PlatformError]The changes under path (a directory, or one file), as they
happen. on_ready runs once changes are being watched.
| Parameter | Type | Description |
|---|---|---|
path | str | |
recursive | bool = False | |
on_ready | Callable[[], None] | None = None |
Returns Stream[WatchEvent, PlatformError]
@abstractmethod
def watch(
self, path: str, *, recursive: bool = False, on_ready: Callable[[], None] | None = None
) -> Stream[WatchEvent, PlatformError]:
"""The changes under ``path`` (a directory, or one file), as they
happen. ``on_ready`` runs once changes are being watched."""write_file#
write_file(path, data, *, flag='w', mode=438) -> Effect[None, PlatformError]Write data to the file path, opened with flag (made
or truncated by default; "a" appends). A file it makes gets
mode (less the umask).
| Parameter | Type | Description |
|---|---|---|
path | str | |
data | bytes | |
flag | OpenFlag = 'w' | |
mode | int = 438 |
Returns Effect[None, PlatformError]
@abstractmethod
def write_file(
self, path: str, data: bytes, *, flag: OpenFlag = "w", mode: int = 0o666
) -> Effect[None, PlatformError]:
"""Write ``data`` to the file ``path``, opened with ``flag`` (made
or truncated by default; ``"a"`` appends). A file it makes gets
``mode`` (less the umask)."""glob#
glob(pattern, *, root=None, exclude=(), dot=False) -> Effect[list[str], PlatformError]The paths below root (the working directory) matching the
pyfect.glob pattern and none of exclude: /-separated,
relative to root (absolute for an absolute pattern), depth
first with each directory's entries sorted by name. Wildcards skip
names that start with . unless the segment does or dot is
set, and dir/** includes dir. ** does not follow
symbolic links to directories; a link named by another segment is
followed. Excluded directories are not read; an entry whose type
cannot be told (a broken link) counts as a file.
Failing to read the root or a leading literal directory fails;
missing paths give nothing, and unreadable directories reached
through wildcards are skipped. Wildcards are case-sensitive; leading
literal segments use stat, so they follow the file system's case
rules and results keep the pattern's spelling. Built from
read_directory_entries, stat and read_link.
| Parameter | Type | Description |
|---|---|---|
pattern | str | |
root | str | None = None | |
exclude | tuple[str, ...] = () | |
dot | bool = False |
Returns Effect[list[str], PlatformError]
def glob(
self,
pattern: str,
*,
root: str | None = None,
exclude: tuple[str, ...] = (),
dot: bool = False,
) -> Effect[list[str], PlatformError]:
"""The paths below ``root`` (the working directory) matching the
``pyfect.glob`` pattern and none of ``exclude``: ``/``-separated,
relative to ``root`` (absolute for an absolute pattern), depth
first with each directory's entries sorted by name. Wildcards skip
names that start with ``.`` unless the segment does or ``dot`` is
set, and ``dir/**`` includes ``dir``. ``**`` does not follow
symbolic links to directories; a link named by another segment is
followed. Excluded directories are not read; an entry whose type
cannot be told (a broken link) counts as a file.
Failing to read the root or a leading literal directory fails;
missing paths give nothing, and unreadable directories reached
through wildcards are skipped. Wildcards are case-sensitive; leading
literal segments use ``stat``, so they follow the file system's case
rules and results keep the pattern's spelling. Built from
``read_directory_entries``, ``stat`` and ``read_link``."""
return glob_walk(self, pattern, root=root, exclude=exclude, dot=dot)exists#
exists(path) -> Effect[bool, PlatformError]Whether path exists; errors other than NotFound fail.
| Parameter | Type | Description |
|---|---|---|
path | str |
Returns Effect[bool, PlatformError]
def exists(self, path: str) -> Effect[bool, PlatformError]:
"""Whether ``path`` exists; errors other than ``NotFound`` fail."""
return self.access(path).map(lambda _: True).catch_all(_false_if_not_found)read_file_string#
read_file_string(path, encoding='utf-8') -> Effect[str, PlatformError]The file decoded as encoding; undecodable bytes become
U+FFFD and a leading byte order mark is dropped, as JavaScript's
TextDecoder does. An unknown encoding is a BadArgument.
| Parameter | Type | Description |
|---|---|---|
path | str | |
encoding | str = 'utf-8' |
Returns Effect[str, PlatformError]
def read_file_string(self, path: str, encoding: str = "utf-8") -> Effect[str, PlatformError]:
"""The file decoded as ``encoding``; undecodable bytes become
U+FFFD and a leading byte order mark is dropped, as JavaScript's
``TextDecoder`` does. An unknown encoding is a ``BadArgument``."""
return self.read_file(path).flat_map(lambda data: _decode(data, encoding))write_file_string#
write_file_string(path, data, *, flag='w', mode=438) -> Effect[None, PlatformError]data as UTF-8 (a lone surrogate becomes U+FFFD).
| Parameter | Type | Description |
|---|---|---|
path | str | |
data | str | |
flag | OpenFlag = 'w' | |
mode | int = 438 |
Returns Effect[None, PlatformError]
def write_file_string(
self, path: str, data: str, *, flag: OpenFlag = "w", mode: int = 0o666
) -> Effect[None, PlatformError]:
"""``data`` as UTF-8 (a lone surrogate becomes U+FFFD)."""
return self.write_file(path, text_encode(data), flag=flag, mode=mode)stream#
stream(path, *, offset=0, bytes_to_read=None, chunk_size=DEFAULT_CHUNK_SIZE) -> Stream[bytes, PlatformError]The file's bytes from offset, chunk_size at a time, up to
bytes_to_read of them. The file opens when the stream starts and
closes when it ends.
| Parameter | Type | Description |
|---|---|---|
path | str | |
offset | int = 0 | |
bytes_to_read | int | None = None | |
chunk_size | int = DEFAULT_CHUNK_SIZE |
Returns Stream[bytes, PlatformError]
def stream(
self,
path: str,
*,
offset: int = 0,
bytes_to_read: int | None = None,
chunk_size: int = DEFAULT_CHUNK_SIZE,
) -> Stream[bytes, PlatformError]:
"""The file's bytes from ``offset``, ``chunk_size`` at a time, up to
``bytes_to_read`` of them. The file opens when the stream starts and
closes when it ends."""
def make() -> Generator[
Effect[Any, PlatformError, Scope], Any, Stream[bytes, PlatformError]
]:
file = yield from self.open(path, flag="r")
if offset:
yield from file.seek(offset, "start")
return stream_.from_pull(succeed(_reader(file, bytes_to_read, chunk_size)))
return stream_.unwrap(gen(make))sink#
sink(path, *, flag='w', mode=438) -> Sink[None, bytes, Never, PlatformError]A sink writing each chunk it reads to the file, opened (truncated by default) when the sink starts.
| Parameter | Type | Description |
|---|---|---|
path | str | |
flag | OpenFlag = 'w' | |
mode | int = 438 |
Returns Sink[None, bytes, Never, PlatformError]
def sink(
self, path: str, *, flag: OpenFlag = "w", mode: int = 0o666
) -> Sink[None, bytes, Never, PlatformError]:
"""A sink writing each chunk it reads to the file, opened (truncated
by default) when the sink starts."""
return unwrap_sink(
self.open(path, flag=flag, mode=mode).map(lambda file: for_each(file.write_all))
)On This Page
Functionsaccesscopycopy_filechmodchownlinklstatmake_directorymake_temp_directorymake_temp_directory_scopedmake_temp_filemake_temp_file_scopedopenread_directoryread_directory_entriesread_fileread_linkreal_pathremoverenamestatsymlinktruncateutimeswatchwrite_fileglobexistsread_file_stringwrite_file_stringstreamsink