Functions · Setu

vec_norm2(v: Vec) -> int#

The squared length of v (a Vec, or a subclass).

Example

>>> vec_norm2(Vec(3, 4))
25
>>> vec_norm2((3, 4))
TypeError: vec_norm2() argument 'v' must be `Vec`

vec_scale(v: Vec, k: int) -> None#

Multiplies the coordinates of v by k, in place.

Example #1

>>> v = Vec(1, 2)
>>> vec_scale(v, 3)
>>> v
Vec(3, 6)

Example #2

# a second block: a new namespace, so no `v`
>>> w = Vec(1, -2)
>>> vec_scale(w, -1)
>>> w
Vec(-1, 2)

vec_self(v: Vec) -> Vec#

v itself: the object back from its instance data (VecType.object).

Type

return Vec

Example

>>> v = Vec()
>>> vec_self(v) is v
True

label_of(v: Labeled | None = None) -> object#

The label of v, or None without one (v is None or not given).

Type

return object

Example

>>> label_of(Labeled('a'))
'a'
>>> label_of(None)

buffer_sum(data: Buffer) -> int#

The sum of the bytes of data (any bytes-like object).

Example

>>> buffer_sum(b'abc')
294
>>> buffer_sum(memoryview(b'abc')[1:])
197

buffer_len(data: Buffer | None = None) -> int | None#

The length of data, or None without one.

Example

>>> buffer_len(bytearray(5))
5
>>> buffer_len(None)

buffer_fill(buf: Buffer, value: int) -> int#

Sets every byte of buf (a writable bytes-like object) to value; returns how many.

Example

>>> b = bytearray(3)
>>> buffer_fill(b, 7)
3
>>> b
bytearray(b'\x07\x07\x07')

read(fd: int, buf: Buffer, n: int | None = None, *, offset: int) -> int#

Reads up to n bytes (default: all of buf) from fd into buf at offset; returns how many.

Example

>>> import os
>>> fd = os.open('a.txt', os.O_RDWR | os.O_CREAT)
>>> os.write(fd, b'hello world')
11
>>> b = bytearray(8)
>>> read(fd, b, 4, offset=6)
4
>>> b
bytearray(b'worl\x00\x00\x00\x00')
>>> os.close(fd)

seq_sum(values: Sequence[int]) -> int#

The sum of values (a list, tuple, range, ... of u32s).

Example

>>> seq_sum([1, 2, 3])
6
>>> seq_sum(range(4))
6

seq_join(parts: Sequence[bytes]) -> bytes#

parts joined: b''.join(parts).

Type

return bytes

Example

>>> seq_join([b'ab', b'c'])
b'abc'

seq_norm2(vs: Sequence[Vec]) -> int#

The squared lengths of vs (Vecs), added up.

Example

>>> seq_norm2([Vec(3, 4), Vec(1, 0)])
26

seq_buffer_len(bufs: Sequence[Buffer] | None = None) -> int | None#

The total length of bufs (bytes-like objects), or None without them.

Example

>>> seq_buffer_len([b'ab', bytearray(3)])
5

hold(buf: Buffer | None = None, data: Buffer | None = None, bufs: Sequence[Buffer] | None = None) -> None#

Releases what the last call kept, then keeps buf, data and bufs (take): locked until the next call. hold() only releases.

Example

>>> b = bytearray(3)
>>> hold(b)
>>> b.append(1)
BufferError: Existing exports of data: object cannot be re-sized
>>> hold()
>>> b.append(1)

own(buf: Buffer | None = None, data: Buffer | None = None, drop: bool | None = None) -> None#

Releases what the last call kept, then keeps buf and data as they come (py.OwnedWritableBuffer / py.OwnedBuffer, no second view): locked until the next call. own() only releases; with drop=True the function releases them itself before returning.

Example

>>> b = bytearray(3)
>>> own(b)
>>> b.append(1)
BufferError: Existing exports of data: object cannot be re-sized
>>> own()
>>> b.append(1)

owned_sum(data: Buffer) -> int#

The sum of the bytes of data, kept by the call (py.OwnedBuffer) and released by it.

Example

>>> owned_sum(b'abc')
294

bench_nop(v: Vec) -> None#

v converted, nothing else: the cheapest call for tool/bench.py (Liburing's io_uring_prep_nop(sqe)).

Example

>>> bench_nop(Vec())

bench_recv(v: Vec, fd: int, buf: Buffer | None = None, flags: int | None = None) -> int#

The arguments of Liburing's io_uring_prep_recv(sqe, sockfd, buf, flags) (https://man7.org/linux/man-pages/man3/io_uring_prep_recv.3.html), converted and released after the call (tool/bench.py); returns fd.

Example

>>> bench_recv(Vec(), -1, bytearray(4), 0)
-1

Flags

K_ONE the first K_ constant, linked like ANSWER
K_TWO (default)
0 none, see https://man7.org/linux/man-pages/man2/recv.2.html.

bench_recv_take(v: Vec, fd: int, buf: Buffer | None = None, flags: int | None = None) -> int#

bench_recv, keeping buf until the next call with a second view (take); buf=None only releases (tool/bench.py).

Example

>>> bench_recv_take(Vec(), -1, bytearray(4))
-1

bench_recv_owned(v: Vec, fd: int, buf: Buffer | None = None, flags: int | None = None) -> int#

bench_recv, keeping buf until the next call as it comes (py.OwnedWritableBuffer); buf=None only releases (tool/bench.py).

Example

>>> bench_recv_owned(Vec(), -1, bytearray(4))
-1

bench_send(v: Vec, fd: int, buf: Buffer | None = None, flags: int | None = None) -> int#

The arguments of Liburing's io_uring_prep_send(sqe, sockfd, buf, flags), converted and released after the call (tool/bench.py); returns fd.

Example

>>> bench_send(Vec(), -1, b'abc')
-1

make_secret(value: int) -> Any#

A Secret (a hidden class) holding value.

Example

>>> type(make_secret(3)).__name__
'Secret'

secret_value(s: Any) -> int#

The value of s (a Secret, Any in the stub).

Example

>>> secret_value(make_secret(3))
3

check_errno(res: int) -> int#

res itself when it is >= 0, else OSError for the errno -res (py.checkErrno).

Example

>>> check_errno(3)
3
>>> check_errno(-2)
FileNotFoundError: [Errno 2] No such file or directory

raise_os_error(errno: int) -> None#

Raises OSError(errno, msg) with a message of Setu's (py.raiseOSError): CPython picks the subclass.

Example

>>> raise_os_error(17)
FileExistsError: [Errno 17] errno 17 from Setu

not_implemented(what: str) -> None#

Raises NotImplementedError naming what (py.raiseNotImplementedError).

Example

>>> not_implemented('spin')
NotImplementedError: `spin` is not implemented

is_int(obj: object) -> bool#

Is obj an int (bool too, a subclass): True / False from py.trueObj() / py.falseObj().

Type

`obj`	`object`
`return`	`bool`

Example

>>> is_int(3)
True
>>> is_int(True)
True
>>> is_int(3.0)
False

path_bytes(path: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> bytes#

path encoded like os.fsencode (py.Path).

Type

return bytes

Example

>>> path_bytes('/tmp/x')
b'/tmp/x'
>>> path_bytes(b'/tmp')
b'/tmp'
>>> path_bytes(3)
TypeError: expected str, bytes or os.PathLike object, not int

paths_len(paths: Sequence[str | bytes | os.PathLike[str] | os.PathLike[bytes]]) -> int#

The total length of paths, each encoded like os.fsencode (py.Sequence(py.Path)).

Example

>>> paths_len(['/a', b'/bc'])
5

keep_path(path: str | bytes | os.PathLike[str] | os.PathLike[bytes] | None = None) -> None#

Releases the path the last call kept, then keeps path (Path.take). keep_path() only releases.

Example

>>> keep_path('/tmp/x')
>>> keep_path()

small_sum(obj: int | Sequence[int]) -> int#

obj converted by hand: a u8 (py.fromPython), or the sum of a sequence of them (py.Sequence(u8).from), as an i8 (py.narrow).

Type

obj int | Sequence[int]

Example

>>> small_sum(5)
5
>>> small_sum([100, 27])
127
>>> small_sum([100, 28])
OverflowError: `small_sum(obj)` = 128 is out of range -128..127
>>> small_sum(300)
OverflowError: 300 is out of range 0..255

raise_long(text: str) -> None#

Raises ValueError(text) through py.raise (a formatted message): a text longer than 511 bytes is cut to the first 511.

Example

>>> raise_long('x' * 3)
ValueError: xxx

no_memory(zig_error: bool) -> None#

Fails like a Zig allocation: MemoryError, from py.raiseNoMemory(), or with zig_error from returning error.OutOfMemory.

Example

>>> no_memory(False)
MemoryError
>>> no_memory(True)
MemoryError

int_pair(big: int, small: int) -> tuple[int, int]#

big and small back: an i64 takes the fast path, a larger u64 the one past it.

Example

>>> int_pair(2**64 - 1, -128)
(18446744073709551615, -128)
>>> int_pair(-1, 0)
OverflowError: `int_pair(big)` = -1 is out of range 0..18446744073709551615

text_list(bad: bool) -> list[str]#

['a', 'b', 'c']; with bad the middle text is not UTF-8, so making the list fails midway.

Example

>>> text_list(False)
['a', 'b', 'c']
>>> text_list(True)
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position 0: invalid start byte

text_tuple(first: object, text: bytes, last: object) -> tuple[object, str, object]#

(first, text, last), text decoded as UTF-8: invalid UTF-8 fails the tuple midway, which drops last (a new reference not yet in it).

Type

`first`	`object`
`last`	`object`
`return`	`tuple[object, str, object]`

Example

>>> text_tuple(1, b'x', 2)
(1, 'x', 2)
>>> text_tuple(1, b'\xff', 2)
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position 0: invalid start byte