GitHub

FileSystemService

API reference for FileSystemService.

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).

ParameterTypeDescription
pathstr
readablebool = False
writablebool = 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.

ParameterTypeDescription
from_pathstr
to_pathstr
overwritebool = False
preserve_timestampsbool = 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.

ParameterTypeDescription
from_pathstr
to_pathstr

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).

ParameterTypeDescription
pathstr
modeint

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.

ParameterTypeDescription
pathstr
uidint
gidint

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(from_path, to_path) -> Effect[None, PlatformError]

Make to_path a hard link to from_path.

ParameterTypeDescription
from_pathstr
to_pathstr

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.

ParameterTypeDescription
pathstr

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.

ParameterTypeDescription
pathstr
recursivebool = False
modeint = 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.

ParameterTypeDescription
directorystr | None = None
prefixstr = ''

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.

ParameterTypeDescription
directorystr | None = None
prefixstr = ''

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.

ParameterTypeDescription
directorystr | None = None
prefixstr = ''
suffixstr = ''

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.

ParameterTypeDescription
directorystr | None = None
prefixstr = ''
suffixstr = ''

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.

ParameterTypeDescription
pathstr
flagOpenFlag = 'r'
modeint = 438
no_followbool = 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.

ParameterTypeDescription
pathstr
recursivebool = 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.

ParameterTypeDescription
pathstr

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.

ParameterTypeDescription
pathstr

Returns Effect[bytes, PlatformError]

@abstractmethod
def read_file(self, path: str) -> Effect[bytes, PlatformError]:
    """The contents of the file ``path``."""
read_link(path) -> Effect[str, PlatformError]

Where the symbolic link path points, as written in the link.

ParameterTypeDescription
pathstr

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.

ParameterTypeDescription
pathstr

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.

ParameterTypeDescription
pathstr
recursivebool = False
forcebool = 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.

ParameterTypeDescription
old_pathstr
new_pathstr

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).

ParameterTypeDescription
pathstr

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(from_path, to_path) -> Effect[None, PlatformError]

Make to_path a symbolic link pointing at from_path.

ParameterTypeDescription
from_pathstr
to_pathstr

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.

ParameterTypeDescription
pathstr
lengthint = 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).

ParameterTypeDescription
pathstr
atimedatetime | float
mtimedatetime | 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.

ParameterTypeDescription
pathstr
recursivebool = False
on_readyCallable[[], 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).

ParameterTypeDescription
pathstr
databytes
flagOpenFlag = 'w'
modeint = 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.

ParameterTypeDescription
patternstr
rootstr | None = None
excludetuple[str, ...] = ()
dotbool = 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.

ParameterTypeDescription
pathstr

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.

ParameterTypeDescription
pathstr
encodingstr = '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).

ParameterTypeDescription
pathstr
datastr
flagOpenFlag = 'w'
modeint = 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.

ParameterTypeDescription
pathstr
offsetint = 0
bytes_to_readint | None = None
chunk_sizeint = 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.

ParameterTypeDescription
pathstr
flagOpenFlag = 'w'
modeint = 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))
    )