encrustable

Introduction

encrustable is a small project that aims to bring the very basic benefits of the Rust's type system to Python. With the introduction of pattern matching in Python 3.12 and all the benefits associated with relevant type checking this paradigm becomes more and more usable.

Currently the main focus of encrustable is to port over Option and Result types, the very basic building blocks of Rust's type safety.

Using encrustable

Installation

python -m pip install encrustable

Basic usage of Option

Run the example with python -m encrustable.examples.option:

from typing import NewType

from encrustable import Nothing, Option, Some

# we use the newtype pattern to squeeze the most ouf of our type checker
Username = NewType("Username", str)
PasswdFileLine = NewType("PasswdFileLine", str)
ParsedPasswdEntry = NewType("ParsedPasswdEntry", list[str])
ShellPath = NewType("ShellPath", str)


# we assume the passwd file exists, is readable and consists of valid lines, so we have
# a function that can fail in exactly one way (the user is not in the passwd file)
# we encode this scenario as an Option
def get_user_entry(username: Username) -> Option[PasswdFileLine]:
    with open("/etc/passwd", "r") as passwd_file:
        for line in passwd_file:
            parts: list[str] = line.split(":")
            if parts[0] == username:
                return Some(PasswdFileLine(line.strip()))
        return Nothing()


# we have a regular function that cannot fail
# assuming it receives a valid passwd file line
def parse_user_entry(entry: PasswdFileLine) -> ParsedPasswdEntry:
    return ParsedPasswdEntry(entry.split(":"))


# we have another regular function that cannot fail
# assuming it receives a valid parsed passwd entry
def get_shell_name(parsed_entry: ParsedPasswdEntry) -> ShellPath:
    return ShellPath(parsed_entry[6])


# now we can combine them and we can skip any error checking midway
# we will only check the result at the end using pattern matching
def print_user_shell(username: Username) -> None:
    match get_user_entry(username) | parse_user_entry | get_shell_name:
        # the result is of the type `Option[ShellPath]`
        case Some(s):
            print(f"- user '{username}' has shell set to '{s}'")
        case Nothing():
            print(f"- user '{username}' not found in the '/etc/passwd' file")


# execute the example for two users, "root" and "anchovies"
if __name__ == "__main__":
    print_user_shell(Username("root"))
    print_user_shell(Username("anchovies"))

- user 'root' has shell set to '/bin/bash'
- user 'anchovies' not found in the '/etc/passwd' file

Basic usage of Result

Run the example with python -m encrustable.examples.result:

import tempfile
from dataclasses import dataclass, field
from pathlib import Path

from encrustable import Err, Ok, Result


@dataclass(frozen=True, eq=True)
class FileReadError(Exception):
    file_name: Path
    original_error: Exception | None = field(default=None, kw_only=True, repr=False)


class FileNotFound(FileReadError):
    pass


class FileNotReadable(FileReadError):
    pass


class FileEmpty(FileReadError):
    pass


# this function can fail in many different ways:
#   - file does not exist
#   - file is not readable (because of permissions)
#   - file is empty (so no first line)
#   - we can even have a catch-all generic exception handler if we want to
# we encode this scenario as a Result
def read_first_line_from_file(file_name: Path) -> Result[str, FileReadError]:
    try:
        with file_name.open("r") as file:
            if (line := file.readline().strip()) == "":
                return Err(FileEmpty(file_name))
            return Ok(line)
    except FileNotFoundError as e:
        return Err(FileNotFound(file_name, original_error=e))
    except PermissionError as e:
        return Err(FileNotReadable(file_name, original_error=e))
    except Exception as e:
        return Err(FileReadError(file_name, original_error=e))


# we have a regular function that cannot fail
# given a valid string it will give us up to 20 characters from the beginning
def trim_str_above_20_len(line: str) -> str:
    return line.strip()[:20]


# now we can combine them and we can skip any error checking midway
# we will only check the result at the end using pattern matching
def print_first_line_from_file(file_name: Path) -> None:
    match read_first_line_from_file(file_name) | trim_str_above_20_len:
        case Ok(line):
            print(f"- First line (up to 20 chars) from '{file_name}': {line}")
        case Err(err):
            print(
                f"- Could not read first line from '{str(file_name)[:20]}'\n"
                f"  error: {repr(err)}\n"
                f"  original error: {repr(err.original_error)}"
            )


# execute the example for a couple of filenames
if __name__ == "__main__":
    print_first_line_from_file(Path("/etc/passwd"))
    print_first_line_from_file(Path("/does-not-exist.yaml"))
    print_first_line_from_file(Path("/root/file.yaml"))
    with tempfile.NamedTemporaryFile("w") as f:
        print_first_line_from_file(Path(f.name))

- First line (up to 20 chars) from '/etc/passwd': root:x:0:0:root:/roo
- Could not read first line from '/does-not-exist.yaml'
  error: FileNotFound(file_name=PosixPath('/does-not-exist.yaml'))
  original error: [Errno 2] No such file or directory: '/does-not-exist.yaml'
- Could not read first line from '/root/file.yaml'
  error: FileNotReadable(file_name=PosixPath('/root/file.yaml'))
  original error: [Errno 13] Permission denied: '/root/file.yaml'
- Could not read first line from '/tmp/tmp1jbyntjo'
  error: FileEmpty(file_name=PosixPath('/tmp/tmp1jbyntjo'))
  original error: None

The Panic boundary

The boundary between Options/Results and regular Python code can be force-crossed by using the unwrap* or expect* methods, which immediately extracts the contained value. This can however raise a Panic if used when the object state is not the one that's expected, so pattern matching should be the preferred way of extracting values.

Panics are normal Python Exceptions and can be caught at the boundary.

Run the example with python -m encrustable.examples.panic:

from encrustable import Err, Nothing, Ok, Option, Panic, Result, Some


def get_some(v: int) -> Option[int]:
    return Some(v)


def get_nothing() -> Option[int]:
    return Nothing()


def get_ok(v: int) -> Result[int, Exception]:
    return Ok(v)


def get_err(e: Exception) -> Result[int, Exception]:
    return Err(e)


def try_unwrap[T, E: Exception](v: Option[T] | Result[T, E]) -> None:
    try:
        unwrapped = v.unwrap()
        print(f"- {repr(v)} unwrap: {repr(unwrapped)}")
    except Panic as p:
        print(f"- {repr(v)} unwrap: {str(p)}\n  cause: {repr(p.__cause__)}")


def try_expect[T, E: Exception](v: Option[T] | Result[T, E]) -> None:
    try:
        unwrapped = v.expect("no valid value")
        print(f"- {repr(v)} expect: {repr(unwrapped)}")
    except Panic as p:
        print(f"- {repr(v)} expect: {str(p)}\n  cause: {repr(p.__cause__)}")


if __name__ == "__main__":
    try_unwrap(get_some(1))
    try_expect(get_some(1))

    try_unwrap(get_nothing())
    try_expect(get_nothing())

    try_unwrap(get_ok(1))
    try_expect(get_ok(1))

    try_unwrap(get_err(Exception()))
    try_expect(get_err(Exception()))

- Some(v=1) unwrap: 1
- Some(v=1) expect: 1
- Nothing() unwrap: panic!
  cause: None
- Nothing() expect: no valid value
  cause: None
- Ok(v=1) unwrap: 1
- Ok(v=1) expect: 1
- Err(e=Exception()) unwrap: panic!
  cause: Exception()
- Err(e=Exception()) expect: no valid value
  cause: Exception()