GitHub

SecureRandomService

API reference for SecureRandomService.

Secure random values drawn from one source of bytes; build it with make.

Attributes

AttributeTypeDescription
ulidEffect[str]

A ULID: the Clock's time in milliseconds, then 80 random bits; strictly increasing per service.

Functions

__init__

__init__(random_bytes) -> None
ParameterTypeDescription
random_bytesCallable[[int], bytes]
def __init__(self, random_bytes: Callable[[int], bytes]) -> None:
    self._random_bytes = random_bytes
    self._uuid_v7 = _ids.make_v7_monotonic()
    self._ulid = _ids.make_ulid_monotonic()

random_bytes

random_bytes(size) -> Effect[bytes]

size random bytes; a size that is not a non-negative safe integer is a defect.

ParameterTypeDescription
sizeint

Returns Effect[bytes]

def random_bytes(self, size: int) -> Effect[bytes]:
    """``size`` random bytes; a size that is not a non-negative safe
    integer is a defect."""

    def go() -> bytes:
        _check_size(size)
        return bytes(self._random_bytes(size))

    return sync(go)

int_between

int_between(low, high, *, half_open=False) -> Effect[int]

A uniformly random integer from ceil(low) to floor(high), inclusive unless half_open. An empty range, or bounds that are not finite or safe integers, is a defect.

ParameterTypeDescription
lowfloat
highfloat
half_openbool = False

Returns Effect[int]

def int_between(self, low: float, high: float, *, half_open: bool = False) -> Effect[int]:
    """A uniformly random integer from ``ceil(low)`` to ``floor(high)``,
    inclusive unless ``half_open``. An empty range, or bounds that are not
    finite or safe integers, is a defect."""
    return sync(lambda: int_between_unsafe(low, high, half_open, self._draw))

shuffle

shuffle[A](elements) -> Effect[list[A]]

A uniformly shuffled copy of elements.

ParameterTypeDescription
elementsIterable[A]

Returns Effect[list[A]]

def shuffle[A](self, elements: Iterable[A]) -> Effect[list[A]]:
    """A uniformly shuffled copy of ``elements``."""

    def go() -> list[A]:
        buffer = list(elements)
        for i in range(len(buffer) - 1, 0, -1):
            index = int_between_unsafe(0, i, False, self._draw)
            buffer[i], buffer[index] = buffer[index], buffer[i]
        return buffer

    return sync(go)

uuid_v4

uuid_v4(*, format: Literal['string'] = 'string') -> Effect[str]
uuid_v4(*, format: Literal['bytes']) -> Effect[bytes]

A UUIDv4: the lowercase hyphenated text, or its 16 bytes.

ParameterTypeDescription
format= 'string'
@overload
def uuid_v4(self, *, format: Literal["string"] = "string") -> Effect[str]: ...
@overload
def uuid_v4(self, *, format: Literal["bytes"]) -> Effect[bytes]: ...
def uuid_v4(self, *, format: UuidFormat = "string") -> Effect[str] | Effect[bytes]:
    """A UUIDv4: the lowercase hyphenated text, or its 16 bytes."""
    return sync(lambda: _formatted(_ids.v4_bytes(self._random_bytes(16)), format))  # pyright: ignore[reportReturnType]

uuid_v7

uuid_v7(*, format: Literal['string'] = 'string') -> Effect[str]
uuid_v7(*, format: Literal['bytes']) -> Effect[bytes]

A UUIDv7 holding the Clock's time in milliseconds; strictly increasing per service.

ParameterTypeDescription
format= 'string'
@overload
def uuid_v7(self, *, format: Literal["string"] = "string") -> Effect[str]: ...
@overload
def uuid_v7(self, *, format: Literal["bytes"]) -> Effect[bytes]: ...
def uuid_v7(self, *, format: UuidFormat = "string") -> Effect[str] | Effect[bytes]:
    """A UUIDv7 holding the ``Clock``'s time in milliseconds; strictly
    increasing per service."""
    return clock_with(  # pyright: ignore[reportReturnType]
        lambda clock: sync(
            lambda: _formatted(
                self._uuid_v7(now_millis_unsafe(clock), self._random_bytes(16)),
                format,
            )
        )
    )