GitHub

platform_error

API reference for platform_error.

Errors of platform services (Effect's PlatformError).

FileSystem, Stdio, Terminal and the other platform services fail with one error class, PlatformError, whose reason says what went wrong: a BadArgument the service rejected before doing anything, or a SystemError the operating system reported. Each of Effect's system error tags ("NotFound", "PermissionDenied", ...) is a subclass of SystemError, so catch_reason matches them by class::

fs.read_file_string(path).pipe(
    fx.catch_reason(PlatformError, platform_error.NotFound, lambda _r, _e: fx.succeed(""))
)

reason.tag is Effect's _tag string. An OSError maps to a tag by its errno, as Node's code does in Effect's Node file system.

Types

TypeDefinitionDescription
SystemErrorTagtype SystemErrorTag = Literal['AlreadyExists', 'BadResource', 'Busy', 'InvalidData', 'NotFound', 'PermissionDenied', 'TimedOut', 'UnexpectedEof', 'Unknown', 'WouldBlock', 'WriteZero']

Classes

Functions

system_error

system_error(tag, *, module, method, description=None, syscall=None, path_or_descriptor=None, cause=None) -> PlatformError

A PlatformError whose reason is the SystemError subclass named by tag.

ParameterTypeDescription
tagSystemErrorTag
modulestr
methodstr
descriptionstr | None = None
syscallstr | None = None
path_or_descriptorstr | int | None = None
causeobject = None

Returns PlatformError

def system_error(
    tag: SystemErrorTag,
    *,
    module: str,
    method: str,
    description: str | None = None,
    syscall: str | None = None,
    path_or_descriptor: str | int | None = None,
    cause: object = None,
) -> PlatformError:
    """A ``PlatformError`` whose reason is the ``SystemError`` subclass
    named by ``tag``."""
    reason = _BY_TAG[tag](
        module=module,
        method=method,
        description=description,
        syscall=syscall,
        path_or_descriptor=path_or_descriptor,
        cause=cause,
    )
    return PlatformError(reason)

bad_argument

bad_argument(*, module, method, description=None, cause=None) -> PlatformError

A PlatformError whose reason is a BadArgument.

ParameterTypeDescription
modulestr
methodstr
descriptionstr | None = None
causeobject = None

Returns PlatformError

def bad_argument(
    *, module: str, method: str, description: str | None = None, cause: object = None
) -> PlatformError:
    """A ``PlatformError`` whose reason is a ``BadArgument``."""
    return PlatformError(
        BadArgument(module=module, method=method, description=description, cause=cause)
    )

tag_of

tag_of(error) -> SystemErrorTag

The tag Effect's Node platform gives the same errno (Unknown for any other).

ParameterTypeDescription
errorOSError

Returns SystemErrorTag

def tag_of(error: OSError) -> SystemErrorTag:
    """The tag Effect's Node platform gives the same ``errno`` (``Unknown``
    for any other)."""
    return "Unknown" if error.errno is None else _TAGS_BY_ERRNO.get(error.errno, "Unknown")

from_exception

from_exception(error, *, module, method, path_or_descriptor=None) -> PlatformError

An OSError as a SystemError tagged by its errno; any other exception (a ValueError for a path with a NUL byte, say) as a BadArgument, as Effect's Node platform reports invalid arguments.

ParameterTypeDescription
errorException
modulestr
methodstr
path_or_descriptorstr | int | None = None

Returns PlatformError

def from_exception(
    error: Exception, *, module: str, method: str, path_or_descriptor: str | int | None = None
) -> PlatformError:
    """An ``OSError`` as a ``SystemError`` tagged by its ``errno``; any other
    exception (a ``ValueError`` for a path with a NUL byte, say) as a
    ``BadArgument``, as Effect's Node platform reports invalid arguments."""
    if isinstance(error, OSError):
        return system_error(
            tag_of(error),
            module=module,
            method=method,
            path_or_descriptor=path_or_descriptor,
            description=error.strerror,
            cause=error,
        )
    return bad_argument(module=module, method=method, description=str(error), cause=error)