Cryptographically secure random values as a service (Effect's
effect/crypto/SecureRandom)::
random = yield from SecureRandom()
token = yield from random.random_bytes(32)
roll = yield from random.int_between(1, 6)
uuid = yield from random.uuid_v7()make(random_bytes) builds the service from a source of random bytes;
every other value is drawn from it. int_between rejects draws that
would bias the result. uuid_v7 and ulid read the Clock and
strictly increase per service, even when the clock moves back.
layer_web_crypto draws from the WebCrypto reference. Bad sizes and
empty or non-finite ranges are defects, as in Effect.
Values#
| Attribute | Type | Description |
|---|---|---|
layer_web_crypto | Layer[SecureRandom] | Random bytes from the |
Types#
| Type | Definition | Description |
|---|---|---|
UuidFormat | type UuidFormat = Literal['string', 'bytes'] |
Classes#
Functions#
int_between_unsafe#
int_between_unsafe(low, high, half_open, draw) -> intAn integer from ceil(low) to floor(high) (exclusive when
half_open), by rejection sampling over 53-bit draws (54-bit for
ranges wider than 2^53), so every integer is equally likely.
| Parameter | Type | Description |
|---|---|---|
low | float | |
high | float | |
half_open | bool | |
draw | Callable[[], bytes] |
Returns int
def int_between_unsafe(low: float, high: float, half_open: bool, draw: Callable[[], bytes]) -> int:
"""An integer from ``ceil(low)`` to ``floor(high)`` (exclusive when
``half_open``), by rejection sampling over 53-bit draws (54-bit for
ranges wider than 2^53), so every integer is equally likely."""
low_int = _to_safe_int(low, math.ceil)
high_int = _to_safe_int(high, math.floor)
count = high_int - low_int + (0 if half_open else 1)
if count <= 0:
raise ValueError("range must contain at least one integer")
if high_int - low_int < _MAX_SAFE:
if count == 1:
return low_int
bucket = (2**53 - 2**53 % count) // count
limit = bucket * count
while True:
value = _read_uint53(draw())
if value < limit:
return low_int + value // bucket
wide = count > 2**53
bucket = (2**54 if wide else 2**53) // count
limit = bucket * count
while True:
data = draw()
value = _read_uint53(data) + (2**53 if wide and data[0] & 0x20 else 0)
if value < limit:
return low_int + value // bucketmake#
make(random_bytes) -> SecureRandomServiceA SecureRandom drawing every value from random_bytes(size).
| Parameter | Type | Description |
|---|---|---|
random_bytes | Callable[[int], bytes] |
Returns SecureRandomService
def make(random_bytes: Callable[[int], bytes]) -> SecureRandomService:
"""A ``SecureRandom`` drawing every value from ``random_bytes(size)``."""
return SecureRandomService(random_bytes)fill_random#
fill_random(crypto, size) -> bytessize bytes from crypto.get_random_values, 64 KiB at a time
(Web Crypto refuses more per call).
| Parameter | Type | Description |
|---|---|---|
crypto | Crypto | |
size | int |
Returns bytes
def fill_random(crypto: Crypto, size: int) -> bytes:
"""``size`` bytes from ``crypto.get_random_values``, 64 KiB at a time
(Web Crypto refuses more per call)."""
buffer = bytearray(size)
with memoryview(buffer) as view:
for offset in range(0, size, 65_536):
with view[offset : offset + 65_536] as chunk:
crypto.get_random_values(chunk)
return bytes(buffer)random_bytes_unsafe#
random_bytes_unsafe(size) -> bytessize random bytes from the host, outside any effect.
| Parameter | Type | Description |
|---|---|---|
size | int |
Returns bytes
def random_bytes_unsafe(size: int) -> bytes:
"""``size`` random bytes from the host, outside any effect."""
_check_size(size)
return os.urandom(size)uuid_v4_unsafe#
uuid_v4_unsafe(*, format: Literal['string'] = 'string') -> str
uuid_v4_unsafe(*, format: Literal['bytes']) -> bytesA UUIDv4 from the host's random bytes.
| Parameter | Type | Description |
|---|---|---|
format | = 'string' |
@overload
def uuid_v4_unsafe(*, format: Literal["string"] = "string") -> str: ...
@overload
def uuid_v4_unsafe(*, format: Literal["bytes"]) -> bytes: ...
def uuid_v4_unsafe(*, format: UuidFormat = "string") -> str | bytes:
"""A UUIDv4 from the host's random bytes."""
return _formatted(_ids.v4_bytes(os.urandom(16)), format)uuid_v7_unsafe#
uuid_v7_unsafe(*, format: Literal['string'] = 'string') -> str
uuid_v7_unsafe(*, format: Literal['bytes']) -> bytesA UUIDv7 from the system time and the host's random bytes; strictly
increasing across every *_unsafe call in the process.
| Parameter | Type | Description |
|---|---|---|
format | = 'string' |
@overload
def uuid_v7_unsafe(*, format: Literal["string"] = "string") -> str: ...
@overload
def uuid_v7_unsafe(*, format: Literal["bytes"]) -> bytes: ...
def uuid_v7_unsafe(*, format: UuidFormat = "string") -> str | bytes:
"""A UUIDv7 from the system time and the host's random bytes; strictly
increasing across every ``*_unsafe`` call in the process."""
return _formatted(_ids.v7_monotonic(time.time() * 1000, os.urandom(16)), format)ulid_unsafe#
ulid_unsafe() -> strA ULID from the system time and the host's random bytes; strictly increasing across the process.
Returns str
def ulid_unsafe() -> str:
"""A ULID from the system time and the host's random bytes; strictly
increasing across the process."""
return _ids.ulid_monotonic(time.time() * 1000, lambda: os.urandom(10))