Package {pyrt}

pyrt: Runtime Support for Converted 'Python' Packages

Description

Provides the 'Python' runtime semantics required by 'R' packages generated with 'pyport', including reference-semantics containers, class and method-resolution-order dispatch, exception hierarchies, iteration and slicing helpers, arbitrary-precision integer arithmetic, and bit-exact random number generation.

Author(s)

Maintainer: pyport authors maintainer@example.com (PLACEHOLDER: replace with the real maintainer before release)

Retrieve a Python built-in function or exception constructor by name

Description

Looks up a Python built-in function (len, range, enumerate, zip, reversed, iter, next, int, float, bool, str, repr, ascii, abs, divmod, pow, min, max, sum, all, any, sorted, list, tuple, dict, set, map, filter, isinstance, issubclass, getattr, setattr, hasattr, delattr, super, property, staticmethod, classmethod, ord, chr, hex, oct, bin, round, print, callable) or built-in exception constructor (ValueError, TypeError, KeyError, IndexError, StopIteration, RuntimeError, ZeroDivisionError, AttributeError, LookupError, AssertionError, NotImplementedError, OSError, Exception, BaseException).

Usage

py_builtin(name)

py_builtin_names()

Arguments

Value

A callable R function or pyrt_class representing the built-in.

Examples

py_builtin("len")(py_list(list(1L, 2L, 3L)))
py_builtin("sum")(py_range(5L))

Python class system: C3 MRO, super(), descriptors, and with context managers

Description

py_class() defines a Python class with C3 method-resolution order (matching Python's multiple-inheritance rules), dunder hooks (⁠__init__⁠, ⁠__call__⁠, ⁠__repr__⁠, ⁠__str__⁠, ⁠__eq__⁠, ⁠__lt__⁠, ⁠__len__⁠, ⁠__getitem__⁠, ⁠__iter__⁠, ⁠__enter__⁠, ⁠__exit__⁠, etc.), and descriptors (py_property(), py_staticmethod(), py_classmethod()). Calling a pyrt_class (or via ⁠$new(...)⁠) constructs an instance (pyrt_instance) with reference semantics. py_super(cls, self) returns a proxy that resolves attributes starting after cls in self's MRO. py_with(mgr, body) implements Python's with statement (⁠__enter__⁠ / ⁠__exit__⁠, including exception suppression when ⁠__exit__⁠ returns a truthy value).

Usage

py_class(name, bases = list(), dict = list())

py_class(name, bases = list(), dict = list())

py_property(fget = NULL, fset = NULL, fdel = NULL)

py_staticmethod(fn)

py_classmethod(fn)

py_getattr(obj, attr, default = missing_sentinel)

py_setattr(obj, attr, value)

py_delattr(obj, attr)

py_hasattr(obj, attr)

py_super(cls, self)

py_isinstance(obj, classinfo)

py_issubclass(cls, classinfo)

py_call(obj, args = list(), kwargs = list())

py_with(mgr, body)

Arguments

Value

py_class() returns a callable pyrt_class; instantiating it returns a pyrt_instance.

Examples

Counter <- py_class("Counter", dict = list(
  `__init__` = function(self, start = 0L) {
    py_setattr(self, "n", start)
  },
  inc = function(self, step = 1L) {
    py_setattr(self, "n", py_getattr(self, "n") + step)
    py_getattr(self, "n")
  }
))
c1 <- Counter(10L)
c1$inc(5L)

Python comparison, identity, and membership operators

Description

py_eq(), py_ne(), py_lt(), py_le(), py_gt(), py_ge() implement Python's value equality and ordering rules (including ⁠1 == 1.0 == True⁠, gmp::bigz comparisons, structural equality on py_list / py_tuple / py_dict / py_set, and dunder hooks ⁠__eq__⁠, ⁠__lt__⁠, etc.). py_is() tests object identity (for reference-semantics objects, whether two bindings point to the same underlying environment). py_in() tests membership (⁠x in container⁠), dispatching to ⁠__contains__⁠ when present.

Usage

py_eq(x, y)

py_ne(x, y)

py_lt(x, y)

py_le(x, y)

py_gt(x, y)

py_ge(x, y)

py_is(x, y)

py_in(x, y)

Arguments

Value

A single logical (TRUE or FALSE), or a pyrt_ndarray for array comparisons.

Examples

py_eq(1L, TRUE)
py_eq(py_list(list(1L, 2L)), py_list(list(1.0, 2.0)))

Construct, raise, and catch Python exceptions

Description

py_exception() creates an R condition object whose S3 classes follow Python's built-in exception hierarchy (KeyError inherits from LookupError, Exception, BaseException, etc.). py_raise() signals the exception (optionally chaining ⁠__cause__⁠ via ⁠from =⁠). py_isinstance_exc() tests whether an exception matches a class name (or list/tuple of class names). py_try() implements Python's full ⁠try / except / else / finally⁠ semantics (where ⁠else⁠ runs only when expr finishes without raising, and finally always runs).

Usage

py_exception(type = "Exception", ..., value = NULL)

py_raise(exc = NULL, ..., cause = NULL)

py_isinstance_exc(exc, classes)

py_try(expr, handlers = list(), orelse = NULL, finalbody = NULL)

Arguments

Value

py_exception() returns a condition of class "pyrt_exception"; py_isinstance_exc() returns a single logical; py_try() returns the value of expr, the matched handler, or orelse().

Examples

e <- py_exception("KeyError", "missing")
py_isinstance_exc(e, "LookupError")
py_try(
  py_raise("IndexError", "out of range"),
  handlers = list(LookupError = function(err) err$type)
)

Python int() constructor and exact integer / operator semantics

Description

py_int() converts numbers, booleans, or strings (in base 0 or 2..36, with optional ⁠_⁠ separators) to a Python integer (integer when in 32-bit signed range, gmp::bigz when larger). py_floordiv(), py_mod(), py_divmod(), py_pow(), py_bitand(), py_bitor(), py_bitxor(), py_invert(), py_lshift(), and py_rshift() implement Python's exact numeric and two's-complement bitwise semantics (including floor division and modulo toward -Inf, and raises ZeroDivisionError on division by zero).

Usage

py_int(x = 0L, base = NULL)

py_add(x, y)

py_sub(x, y)

py_mul(x, y)

py_truediv(x, y)

py_floordiv(x, y)

py_mod(x, y)

py_divmod(x, y)

py_pow(x, y, mod = NULL)

py_bitand(x, y)

py_bitor(x, y)

py_bitxor(x, y)

py_invert(x)

py_lshift(x, y)

py_rshift(x, y)

py_neg(x)

py_pos(x)

py_abs(x)

py_matmul(x, y)

Arguments

Value

An R integer, gmp::bigz, double, complex, or dunder result.

Examples

py_floordiv(-7L, 2L)
py_mod(-7L, 2L)
py_bitand(-5L, 3L)
py_rshift(-8L, 2L)

Python iteration protocol (iter, next), generators, and range

Description

py_iter() returns a stateful pyrt_iterator over any Python container, string, py_range(), generator, R vector/list, or custom class implementing ⁠__iter__⁠ (or ⁠__getitem__⁠). py_next() advances an iterator by one step, returning default if supplied or raising StopIteration when exhausted. py_generator() wraps a step function (function(yield_val) ...) into a stateful generator supporting next(), ⁠$send()⁠, and ⁠$close()⁠. py_for() executes a loop body for each item of an iterable and runs orelse() if the loop finished without break.

Usage

py_iter(x)

py_next(x, default = missing_sentinel)

py_collect(x)

py_iter_step(x)

py_bounce(thunk)

py_yield(value = NULL, cont = NULL)

py_stop_iteration(value = NULL)

py_generator(step_fn)

py_break_signal()

py_for(x, body, orelse = NULL)

py_range(start, stop = NULL, step = 1L)

py_range_seq(start, stop = NULL, step = 1L)

py_enumerate(x, start = 0L)

py_zip(...)

py_reversed(x)

Arguments

Value

py_iter() and py_generator() return pyrt_iterator objects; py_next() returns the next element; py_collect() returns an R list of all remaining elements.

Examples

it <- py_iter(py_range(1L, 6L, 2L))
py_next(it)
py_collect(it)

Python len() and container constructors (list, tuple, dict, set)

Description

Reference-semantics containers that mirror Python's built-in list, tuple, dict, and set types (with 0-based indexing, negative indices, slices, and Python methods such as ⁠$append()⁠, ⁠$extend()⁠, ⁠$pop()⁠, ⁠$sort()⁠, ⁠$get()⁠, ⁠$setdefault()⁠, ⁠$update()⁠, ⁠$items()⁠, ⁠$union()⁠, ⁠$intersection()⁠, etc.). Mutating a py_list, py_dict, or py_set updates it in place across all variables referencing it.

Usage

py_len(x)

py_tuple(x = NULL)

py_list(x = NULL)

py_dict(x = NULL, ...)

py_set(x = NULL)

Arguments

Value

A container object (pyrt_list, pyrt_tuple, pyrt_dict, or pyrt_set), or an integer length from py_len().

Examples

xs <- py_list(list(10L, 20L, 30L))
alias <- xs
xs$append(40L)
py_len(alias)
py_getitem(alias, -1L)

Create a Python-compatible ndarray backed by an R vector/matrix/array

Description

Wraps an R atomic vector, matrix, or array in a reference-semantics pyrt_ndarray object with 0-based indexing, .shape tuple, .ndim, .size, .dtype, .T transpose, .reshape(), .flatten(), .tolist(), .sum(), .mean(), .std(), .var(), .min(), .max(), .argmin(), .argmax(), .cumsum(), .dot(), and elementwise arithmetic/comparison operators with NumPy broadcasting semantics.

Usage

py_ndarray(data, dtype = NULL)

Arguments

Value

A pyrt_ndarray environment.

Examples

np <- py_stdlib("numpy")
a <- np$array(list(list(1, 2, 3), list(4, 5, 6)))
a$shape
a$sum(axis = 0L)

Python None, Ellipsis, and truthiness helpers

Description

Foundational singletons and truthiness rules used by R code generated with pyport. Phase 1 expands pyrt with reference-semantics containers (py_list, py_dict, py_set, py_tuple), the Python class/MRO system, exceptions, iteration, slicing, and bit-exact random.

Usage

py_none()

is_py_none(x)

py_ellipsis()

is_py_ellipsis(x)

py_bool(x)

Arguments

Value

py_none() and py_ellipsis() return singleton objects; is_py_none(), is_py_ellipsis(), and py_bool() return a single logical (TRUE or FALSE).

Examples

is_py_none(py_none())
py_bool(0L)
py_bool("non-empty")

Bit-exact CPython random.Random generator and module-level py_random

Description

py_random_generator(seed) creates an independent random.Random instance whose Mersenne Twister (MT19937) state, version = 2 seeding (for int, gmp::bigz, bool, str, and bytes), random(), getrandbits(), ⁠_randbelow()⁠, randrange(), randint(), choice(), shuffle(), sample(), choices(), uniform(), triangular(), gauss(), normalvariate(), expovariate(), lognormvariate(), getstate(), and setstate() match CPython's random module bit-for-bit. R's own RNG is never touched. py_random is a pre-instantiated module-like object exposing the same functions at top level (py_random$seed(42L), py_random$random(), etc.).

Usage

py_random_generator(a = NULL)

py_random

Arguments

Format

An object of class pyrt_Random (inherits from pyrt_container) of length 20.

Value

py_random_generator() returns a pyrt_Random environment; py_random is the default module-level generator.

Examples

rng <- py_random_generator(12345L)
rng$random()
rng$randint(1L, 100L)
rng$getrandbits(100L)

Python slice() and 0-based subscript helpers

Description

py_slice(start, stop, step) constructs a Python slice object (including its ⁠$indices(length)⁠ method). py_getitem(), py_setitem(), and py_delitem() implement 0-based indexing, negative indices, slices with arbitrary positive or negative steps (including extended slice assignment and deletion on py_list), dictionary key lookup, string slicing, and ⁠__getitem__⁠ / ⁠__setitem__⁠ / ⁠__delitem__⁠ dunder dispatch on custom classes. py_unpack() implements Python's sequence and starred unpacking (⁠a, *b, c = seq⁠), raising ValueError when the item count does not match.

Usage

py_slice(start = NULL, stop = NULL, step = NULL)

py_getitem(x, key)

py_setitem(x, key, value)

py_delitem(x, key)

py_unpack(x, n_before, n_after = 0L, has_star = FALSE)

Arguments

Value

py_slice() returns a pyrt_slice object; py_getitem() returns the indexed element or sliced sub-container; py_setitem() and py_delitem() mutate reference containers in place and return the modified object invisibly; py_unpack() returns a flat R list of unpacked values.

Examples

xs <- py_list(list("a", "b", "c", "d", "e"))
py_getitem(xs, -1L)
py_getitem(xs, py_slice(1L, 4L, 2L))
py_setitem(xs, py_slice(1L, 3L), list("B", "C", "CC"))
xs

Runtime helpers for transpiled ⁠*args⁠/⁠**kwargs⁠, assert, and signals

Description

py_split_varargs() partitions an R list(...) into a py_tuple of extra positional arguments (⁠$args⁠) and a py_dict of extra keyword arguments (⁠$kwargs⁠), raising TypeError when unexpected positional or keyword arguments are passed. py_return_signal(), py_continue_signal(), is_py_return(), is_py_continue(), and is_py_break() propagate return/break/continue out of py_try() and py_with() closures. py_assert() raises AssertionError when test is falsy under py_bool().

Usage

py_split_varargs(dots, vararg = TRUE, kwarg = TRUE)

py_return_signal(value = py_none())

is_py_return(x)

py_continue_signal()

is_py_continue(x)

is_py_break(x)

py_assert(test, msg = NULL)

Arguments

Value

py_split_varargs() returns list(args = py_tuple, kwargs = py_dict).

Retrieve a Python standard-library module implemented in pyrt

Description

Returns an environment implementing the requested Python standard-library module (math, itertools, functools, operator, collections, re, json, copy, bisect, heapq, string, datetime, dataclasses, enum, random, sys).

Usage

py_stdlib(name)

py_stdlib_names()

Arguments

Value

A pyrt_module environment.

Examples

m <- py_stdlib("math")
m$gcd(48L, 18L)
it <- py_stdlib("itertools")
py_collect(it$islice(it$count(10L, 2L), 4L))

Python str(), repr(), ascii(), format(), and str methods

Description

py_str(), py_repr(), and py_ascii() format values using Python's string and representation rules (dispatching to ⁠__str__⁠ / ⁠__repr__⁠ on custom instances). py_format(value, spec) implements Python's Format Specification Mini-Language (⁠[[fill]align][sign][#][0][width][grouping_option][.precision][type]⁠, used by f-strings and format()). py_fstring(...) evaluates an f-string's parts. py_str_method(s, method) dispatches Python str methods (split, rsplit, splitlines, join, strip, lstrip, rstrip, replace, find, rfind, index, rindex, count, startswith, endswith, upper, lower, capitalize, title, swapcase, zfill, center, ljust, rjust, partition, rpartition, removeprefix, removesuffix, isdigit, isalpha, isalnum, isspace, isupper, islower, format).

Usage

py_str(x = "")

py_repr(x)

py_ascii(x)

py_format(value, spec = "", conversion = -1L)

py_fstring(...)

py_str_method(s, method)

Arguments

Value

A character string (or container / logical / integer for str methods that return lists, tuples, booleans, or indices).

Examples

py_format(3.14159, ">+10.2f")
py_format(255L, "#06x")
py_format(1234567L, ",d")
py_str_method("  hello, world  ", "strip")()