tpy-lang 0.3.0.dev0__py3-none-any.whl

tpyc/_data/runtime/cpp/include/tpy/set_ops.hpp

@@ -0,0 +1,265 @@
+/**
+ * TurboPython Runtime - Set Operations
+ *
+ * Set-specific helpers: remove (panicking), pop, set algebra operations,
+ * constructors from iterables, and SetPrinter.
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <iostream>
+#include <ranges>
+#include <sstream>
+
+#include "core.hpp"
+#include "next_iter.hpp"
+#include "ordered_set.hpp"
+#include "printing.hpp"
+
+namespace tpy {
+
+// -- Constructors -----------------------------------------------------------
+
+// set(native_iterable) -- construct from range
+template<typename T, std::ranges::input_range R>
+ordered_set<T> set_from_range(R&& range) {
+    ordered_set<T> result;
+    for (auto&& elem : range) {
+        result.insert(elem);
+    }
+    return result;
+}
+
+// set(iterator) -- construct from user-defined iterator
+template<typename T, typename Iter>
+ordered_set<T> set_collect(Iter&& iter) {
+    ordered_set<T> result;
+    for (;;) {
+        auto __r = iter.__next__();
+        if (!__r.has_value()) break;
+        result.insert(unwrap_ref(*__r));
+    }
+    return result;
+}
+
+// set_construct -- unified set construction from any iterable.
+// Uses begin/end for std::ranges::input_range, __next__() otherwise.
+template<typename T, typename Arg>
+ordered_set<T> set_construct(Arg&& arg) {
+    if constexpr (std::ranges::input_range<std::remove_cvref_t<Arg>>) {
+        return set_from_range<T>(std::forward<Arg>(arg));
+    } else {
+        return set_collect<T>(std::forward<Arg>(arg));
+    }
+}
+
+// -- Copy -------------------------------------------------------------------
+
+template<typename T>
+ordered_set<T> set_copy(const ordered_set<T>& s) {
+    return ordered_set<T>(s);
+}
+
+// -- Methods ----------------------------------------------------------------
+
+// s.remove(value) -- throws KeyError if not present
+template<typename T>
+void set_remove(ordered_set<T>& s, const T& value) {
+    if (!s.erase(value)) {
+        raise_key_error("KeyError");
+    }
+}
+
+// s.pop() -- remove and return first element (insertion order); throws KeyError if empty
+template<typename T>
+T set_pop(ordered_set<T>& s) {
+    if (s.empty()) {
+        raise_key_error("pop from an empty set");
+    }
+    T result = s.front();
+    s.pop_front();
+    return result;
+}
+
+// -- Set algebra ------------------------------------------------------------
+
+template<typename T>
+ordered_set<T> set_union(const ordered_set<T>& a, const ordered_set<T>& b) {
+    ordered_set<T> result(a);
+    for (auto& v : b) {
+        result.insert(v);
+    }
+    return result;
+}
+
+template<typename T>
+ordered_set<T> set_intersection(const ordered_set<T>& a, const ordered_set<T>& b) {
+    ordered_set<T> result;
+    for (auto& v : a) {
+        if (b.contains(v)) result.insert(v);
+    }
+    return result;
+}
+
+template<typename T>
+ordered_set<T> set_difference(const ordered_set<T>& a, const ordered_set<T>& b) {
+    ordered_set<T> result;
+    for (auto& v : a) {
+        if (!b.contains(v)) result.insert(v);
+    }
+    return result;
+}
+
+template<typename T>
+ordered_set<T> set_symmetric_difference(const ordered_set<T>& a, const ordered_set<T>& b) {
+    ordered_set<T> result;
+    for (auto& v : a) {
+        if (!b.contains(v)) result.insert(v);
+    }
+    for (auto& v : b) {
+        if (!a.contains(v)) result.insert(v);
+    }
+    return result;
+}
+
+template<typename T>
+bool set_issubset(const ordered_set<T>& a, const ordered_set<T>& b) {
+    if (a.size() > b.size()) return false;
+    for (auto& v : a) {
+        if (!b.contains(v)) return false;
+    }
+    return true;
+}
+
+template<typename T>
+bool set_issuperset(const ordered_set<T>& a, const ordered_set<T>& b) {
+    return set_issubset(b, a);
+}
+
+template<typename T>
+bool set_strict_subset(const ordered_set<T>& a, const ordered_set<T>& b) {
+    return a.size() < b.size() && set_issubset(a, b);
+}
+
+template<typename T>
+bool set_strict_superset(const ordered_set<T>& a, const ordered_set<T>& b) {
+    return a.size() > b.size() && set_issubset(b, a);
+}
+
+template<typename T>
+bool set_isdisjoint(const ordered_set<T>& a, const ordered_set<T>& b) {
+    const auto& smaller = (a.size() <= b.size()) ? a : b;
+    const auto& larger = (a.size() <= b.size()) ? b : a;
+    for (auto& v : smaller) {
+        if (larger.contains(v)) return false;
+    }
+    return true;
+}
+
+// -- In-place updates -------------------------------------------------------
+
+template<typename T>
+void set_update(ordered_set<T>& s, const ordered_set<T>& other) {
+    for (auto& v : other) {
+        s.insert(v);
+    }
+}
+
+template<typename T>
+void set_intersection_update(ordered_set<T>& s, const ordered_set<T>& other) {
+    ordered_set<T> result;
+    for (auto& v : s) {
+        if (other.contains(v)) result.insert(v);
+    }
+    s = std::move(result);
+}
+
+template<typename T>
+void set_difference_update(ordered_set<T>& s, const ordered_set<T>& other) {
+    if (&s == &other) { s.clear(); return; }
+    for (auto& v : other) {
+        s.erase(v);
+    }
+}
+
+template<typename T>
+void set_symmetric_difference_update(ordered_set<T>& s, const ordered_set<T>& other) {
+    if (&s == &other) { s.clear(); return; }
+    for (auto& v : other) {
+        if (!s.erase(v)) {
+            s.insert(v);
+        }
+    }
+}
+
+// -- ordered_set::__iter__() definition (deferred -- needs native_iterator) -
+
+template<typename T>
+auto ordered_set<T>::__iter__() const {
+    return native_iterator<const_iterator, T>{begin(), end()};
+}
+
+// -- Dunder overloads -------------------------------------------------------
+
+template<typename T>
+int32_t __len__(const ordered_set<T>& s) {
+    return s.size();
+}
+
+template<typename T>
+bool __bool__(const ordered_set<T>& s) {
+    return !s.empty();
+}
+
+// -- Printing ---------------------------------------------------------------
+
+namespace detail {
+// Forward declaration -- defined in printing.hpp
+template <typename T> void print_element(std::ostream& os, const T& elem);
+}  // namespace detail
+
+template<typename T>
+struct SetPrinter {
+    const ordered_set<T>& value;
+    explicit SetPrinter(const ordered_set<T>& v) : value(v) {}
+};
+
+template<typename T>
+std::ostream& operator<<(std::ostream& os, const SetPrinter<T>& p) {
+    if (p.value.empty()) {
+        return os << "set()";
+    }
+    os << '{';
+    bool first = true;
+    for (auto& v : p.value) {
+        if (!first) os << ", ";
+        first = false;
+        detail::print_element(os, v);
+    }
+    os << '}';
+    return os;
+}
+
+template<typename T>
+std::string set_to_str(const ordered_set<T>& s) {
+    std::ostringstream oss;
+    oss << SetPrinter<T>(s);
+    return oss.str();
+}
+
+// Nested container support
+namespace detail {
+template<typename T>
+void print_element(std::ostream& os, const ordered_set<T>& elem) {
+    os << SetPrinter<T>(elem);
+}
+}  // namespace detail
+
+// ValuePrinter specialization so sets inside generic containers print correctly
+template<typename T>
+std::ostream& operator<<(std::ostream& os, const ValuePrinter<ordered_set<T>>& p) {
+    return os << SetPrinter<T>(p.value);
+}
+
+}  // namespace tpy

tpyc/_data/runtime/cpp/include/tpy/slice.hpp

@@ -0,0 +1,47 @@
+// tpy::BasicSlice / tpy::Slice -- built-in slice types for subscript ranges.
+// BasicSlice has start/stop only (for a[1:3] syntax).
+// Slice adds step (for a[1:3:2] syntax).
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <ostream>
+
+namespace tpy {
+
+struct BasicSlice {
+    std::optional<int32_t> start;
+    std::optional<int32_t> stop;
+};
+
+struct Slice {
+    std::optional<int32_t> start;
+    std::optional<int32_t> stop;
+    std::optional<int32_t> step;
+
+    Slice() = default;
+    Slice(std::optional<int32_t> s, std::optional<int32_t> e, std::optional<int32_t> st)
+        : start(s), stop(e), step(st) {}
+    // Implicit conversion from BasicSlice (basic_slice coerces to slice)
+    Slice(const BasicSlice& bs) : start(bs.start), stop(bs.stop), step(std::nullopt) {}
+};
+
+inline std::ostream& operator<<(std::ostream& os, const BasicSlice& s) {
+    os << "basic_slice(";
+    if (s.start) os << *s.start; else os << "None";
+    os << ", ";
+    if (s.stop) os << *s.stop; else os << "None";
+    return os << ")";
+}
+
+inline std::ostream& operator<<(std::ostream& os, const Slice& s) {
+    os << "slice(";
+    if (s.start) os << *s.start; else os << "None";
+    os << ", ";
+    if (s.stop) os << *s.stop; else os << "None";
+    os << ", ";
+    if (s.step) os << *s.step; else os << "None";
+    return os << ")";
+}
+
+} // namespace tpy

tpyc/_data/runtime/cpp/include/tpy/span_iter.hpp

@@ -0,0 +1,42 @@
+/**
+ * TurboPython Runtime - SpanIter
+ *
+ * Lightweight iterator over a contiguous span. Wraps std::span<T> and exposes
+ * both C++ range (begin/end) and Iterator (__next__/__iter__) interfaces.
+ *
+ * SpanIter<T> holds span<T> and yields T& (mutable elements).
+ * SpanIter<const T> holds span<const T> and yields const T& (readonly elements).
+ * Use SpanIter<const T> when iterating from a const/readonly context.
+ */
+
+#pragma once
+
+#include "core.hpp"
+
+#include <expected>
+#include <span>
+#include <type_traits>
+
+namespace tpy {
+
+template<typename T>
+struct SpanIter {
+    std::span<T> span_;
+    size_t index_ = 0;
+
+    explicit SpanIter(std::span<T> s) : span_(s) {}
+
+    // NativeIterable: zero-cost iteration via begin/end.
+    auto begin() const { return span_.begin() + static_cast<std::ptrdiff_t>(index_); }
+    auto end() const { return span_.end(); }
+
+    // Iterator protocol
+    std::expected<std::remove_const_t<T>, StopIteration> __next__() {
+        if (index_ >= span_.size()) return tpy::make_unexpected(StopIteration{});
+        return span_[index_++];
+    }
+
+    SpanIter& __iter__() { return *this; }
+};
+
+} // namespace tpy

tpyc/_data/runtime/cpp/include/tpy/stdlib/math.hpp

@@ -0,0 +1,41 @@
+#pragma once
+
+#include <cmath>
+#include <cstdint>
+#include <limits>
+#include <tuple>
+
+namespace tpy::stdlib::math {
+
+inline std::tuple<double, double> modf(double x) {
+    double int_part;
+    double frac = std::modf(x, &int_part);
+    return {frac, int_part};
+}
+
+// Exponent template parameter. For IEEE 754 double, std::frexp normalizes
+// |m| to [0.5, 1), so exp is in [-1073, 1024] (the lower bound comes from
+// subnormals: smallest positive denormal is 2^-1074 -> m=0.5, exp=-1073;
+// upper bound from max finite double just under 2^1024). Safely fits in
+// any 16+ bit signed int. Caller picks the int type (defaults to
+// DefaultInt on the Python side); `T(exp)` uses the target's constructor
+// so BigInt also works.
+template<typename T>
+inline std::tuple<double, T> frexp(double x) {
+    int exp;
+    double m = std::frexp(x, &exp);
+    return {m, T(exp)};
+}
+
+// Unit in the Last Place: distance to the next representable double > |x|.
+// Matches CPython math.ulp: ulp(nan)=nan, ulp(+-inf)=inf, ulp(0)=smallest
+// subnormal, else nextafter(|x|, inf) - |x|.
+inline double ulp(double x) {
+    if (std::isnan(x)) return x;
+    if (std::isinf(x)) return std::numeric_limits<double>::infinity();
+    if (x == 0.0) return std::numeric_limits<double>::denorm_min();
+    double ax = std::fabs(x);
+    return std::nextafter(ax, std::numeric_limits<double>::infinity()) - ax;
+}
+
+}  // namespace tpy::stdlib::math

tpyc/_data/runtime/cpp/include/tpy/stdlib/pcre2_h.hpp

@@ -0,0 +1,96 @@
+#pragma once
+// Hand-written PCRE2 facade for TPy bindings.
+//
+// We deliberately do NOT `#include <pcre2.h>` here. PCRE2's header
+// `#define`s a large set of `PCRE2_*` macros that would collide with
+// TPy module-level constants of the same name (the preprocessor expands
+// the macro at every TPy `inline constexpr uint32_t PCRE2_CASELESS = ...;`
+// declaration site, producing a syntax error). By instead manually
+// mirroring the symbols and types we need, pcre2.h never enters any
+// TPy-generated translation unit -- its macros never get a chance to fire.
+//
+// All names match upstream pcre2.h exactly and live at global scope (same
+// as the real header), so generated TPy code that references e.g.
+// `pcre2_code_8*` or `PCRE2_SPTR8` resolves directly without any namespace
+// qualification.
+//
+// PCRE2's ABI is stable, so this mirror is low-maintenance. Bumping the
+// vendored PCRE2 version doesn't require touching this file unless the
+// upstream API surface we use changes shape.
+//
+// Linker connects our extern "C" declarations to the symbols defined by
+// the vendored PCRE2 .c files (compiled separately into their own .o
+// files; their TUs include the real pcre2.h).
+
+#include <cstddef>
+#include <cstdint>
+
+// ---- Type aliases (8-bit code unit) ----
+// Upstream pcre2.h has `typedef size_t PCRE2_SIZE`. We use `std::uint64_t`
+// instead because the TPy bindings (lib/tpy/_bindings/pcre2.py) type the
+// matching pointer params as `Ptr[UInt64]` -- on Linux x86_64 `size_t` and
+// `uint64_t` are both `unsigned long`, but on macOS `size_t` is
+// `unsigned long` while `uint64_t` is `unsigned long long`, so the pointer
+// types don't implicitly convert. Both are 8-byte unsigned on every 64-bit
+// Unix target we support, so this matches PCRE2's actual ABI byte-for-byte;
+// the linker only resolves the `extern "C"` symbol name, not param types.
+using PCRE2_SIZE   = std::uint64_t;
+using PCRE2_SPTR8  = const std::uint8_t*;
+using PCRE2_UCHAR8 = std::uint8_t;
+
+// ---- Opaque handle types ----
+// Forward declarations only -- we only ever pass pointers around, never
+// dereference or sizeof the underlying structs in TPy-generated code.
+struct pcre2_real_code_8;
+struct pcre2_real_match_data_8;
+struct pcre2_real_match_context_8;
+struct pcre2_real_general_context_8;
+struct pcre2_real_compile_context_8;
+
+using pcre2_code_8            = pcre2_real_code_8;
+using pcre2_match_data_8      = pcre2_real_match_data_8;
+using pcre2_match_context_8   = pcre2_real_match_context_8;
+using pcre2_general_context_8 = pcre2_real_general_context_8;
+using pcre2_compile_context_8 = pcre2_real_compile_context_8;
+
+// ---- Function declarations ----
+extern "C" {
+
+pcre2_code_8* pcre2_compile_8(PCRE2_SPTR8 pattern, PCRE2_SIZE length,
+                              std::uint32_t options, int* errorcode,
+                              PCRE2_SIZE* erroffset,
+                              pcre2_compile_context_8* ccontext);
+
+void pcre2_code_free_8(pcre2_code_8* code);
+
+int pcre2_jit_compile_8(pcre2_code_8* code, std::uint32_t options);
+
+int pcre2_get_error_message_8(int errorcode, PCRE2_UCHAR8* buffer,
+                              PCRE2_SIZE bufflen);
+
+pcre2_match_context_8* pcre2_match_context_create_8(
+    pcre2_general_context_8* gcontext);
+void pcre2_match_context_free_8(pcre2_match_context_8* mcontext);
+
+pcre2_match_data_8* pcre2_match_data_create_from_pattern_8(
+    const pcre2_code_8* code, pcre2_general_context_8* gcontext);
+void pcre2_match_data_free_8(pcre2_match_data_8* md);
+
+int pcre2_match_8(const pcre2_code_8* code, PCRE2_SPTR8 subject,
+                  PCRE2_SIZE length, PCRE2_SIZE startoffset,
+                  std::uint32_t options, pcre2_match_data_8* match_data,
+                  pcre2_match_context_8* mcontext);
+
+PCRE2_SIZE* pcre2_get_ovector_pointer_8(pcre2_match_data_8* md);
+
+int pcre2_pattern_info_8(const pcre2_code_8* code, std::uint32_t what,
+                         void* where);
+
+int pcre2_substitute_8(const pcre2_code_8* code, PCRE2_SPTR8 subject,
+                       PCRE2_SIZE length, PCRE2_SIZE startoffset,
+                       std::uint32_t options, pcre2_match_data_8* match_data,
+                       pcre2_match_context_8* mcontext,
+                       PCRE2_SPTR8 replacement, PCRE2_SIZE rlength,
+                       PCRE2_UCHAR8* outputbuffer, PCRE2_SIZE* outlengthptr);
+
+}  // extern "C"

tpyc/_data/runtime/cpp/include/tpy/stdlib/random.hpp

@@ -0,0 +1,25 @@
+#pragma once
+
+#include <cstdint>
+#include <random>
+
+namespace tpy::stdlib::random {
+
+// Returns a uint32 sourced from the OS entropy pool. Backed by
+// std::random_device, which uses /dev/urandom on Linux, getentropy /
+// arc4random on BSD/macOS, and BCryptGenRandom on Windows. Each call
+// returns fresh entropy; instance is held in a function-local static
+// since opening the entropy source can be expensive on some platforms.
+//
+// Thread safety: C++11 guarantees the static initialization is
+// thread-safe. Concurrent rd() calls are thread-safe in practice on
+// libstdc++ / libc++ / MSVC (all read from OS primitives) but the
+// language standard does not contract this. When TPy gains threading,
+// callers needing multi-thread safety should serialize or construct
+// per-thread Random instances.
+inline uint32_t os_entropy_uint32() {
+    static std::random_device rd;
+    return rd();
+}
+
+} // namespace tpy::stdlib::random

tpyc/_data/runtime/cpp/include/tpy/stdlib/socket_h.hpp

@@ -0,0 +1,145 @@
+#pragma once
+// Hand-written POSIX-sockets facade for TPy bindings.
+//
+// We deliberately do NOT `#include <sys/socket.h>`, `<netinet/in.h>`,
+// `<netdb.h>`, etc. here. Those headers `#define` a large set of macros
+// (`AF_INET`, `SOCK_STREAM`, `SO_REUSEADDR`, ...) that would collide with
+// TPy module-level constants of the same name: the preprocessor would
+// expand `AF_INET` inside a generated `inline constexpr int32_t AF_INET
+// = 2;` declaration, producing a syntax error. By manually mirroring the
+// libc symbols + the one struct we need, the system headers never enter
+// any TPy-generated translation unit.
+//
+// All names match upstream POSIX exactly and live at global scope (same
+// as the real headers), so generated TPy code that references
+// `sockaddr_in` or calls `::socket` resolves directly.
+//
+// sockaddr_in's layout is POSIX-stable (16 bytes, defined field order)
+// across Linux, *BSD, macOS; safe to mirror. struct addrinfo is NOT
+// stable (ai_addr and ai_canonname are swapped on BSD/macOS), which is
+// why we provide `tpy_resolve_ipv4` below -- the helper hides addrinfo
+// entirely behind a flat C signature.
+//
+// Linker connects our extern "C" declarations to the actual libc
+// implementations; no vendoring, no third-party lib.
+
+#include <cstddef>
+#include <cstdint>
+
+// On macOS, libc's `<sys/_endian.h>` is pulled in transitively by libc++'s
+// base headers (`<cstdint>`, `<string>`, ...) and `#define`s the byte-order
+// helpers as preprocessor macros expanding to inline asm. The macros then
+// fire inside our `extern "C"` decls below and inside any generated code
+// that names them (`::htons(x)` becomes `::((uint16_t)(...))`, a syntax
+// error). Real linker symbols for these helpers exist on every supported
+// platform (Linux glibc/musl, macOS libSystem), so undef'ing the macros
+// here lets us keep the upstream names end-to-end and bind directly.
+#undef htons
+#undef ntohs
+#undef htonl
+#undef ntohl
+
+extern "C" {
+
+// ---- sockaddr_in (POSIX-stable 16-byte layout) ----
+// Field widths chosen to match struct sockaddr_in on any POSIX system:
+//   sa_family_t is 16-bit unsigned;
+//   in_port_t is 16-bit unsigned (network order);
+//   in_addr.s_addr is 32-bit unsigned (network order);
+//   sin_zero is 8 bytes of padding (required for cast-compat with sockaddr).
+struct sockaddr_in {
+    std::uint16_t sin_family;
+    std::uint16_t sin_port;
+    std::uint32_t sin_addr;
+    std::uint8_t  sin_zero[8];
+};
+
+}  // extern "C" (close for static_asserts, reopen below)
+
+// We `reinterpret_cast<sockaddr*>(&our_sockaddr_in)` at every kernel-boundary
+// call, so the layout must match the system's struct exactly. Any toolchain
+// that inserts padding or reorders fields must fail at compile time, not at
+// runtime where it would silently corrupt addresses.
+static_assert(sizeof(sockaddr_in) == 16,
+              "sockaddr_in must be exactly 16 bytes to match POSIX layout");
+static_assert(offsetof(sockaddr_in, sin_family) == 0,
+              "sin_family must be at offset 0");
+static_assert(offsetof(sockaddr_in, sin_port) == 2,
+              "sin_port must be at offset 2");
+static_assert(offsetof(sockaddr_in, sin_addr) == 4,
+              "sin_addr must be at offset 4");
+static_assert(offsetof(sockaddr_in, sin_zero) == 8,
+              "sin_zero must be at offset 8");
+
+extern "C" {
+
+// ---- Raw libc bindings ----
+// sockaddr arguments are declared `void*` to avoid forward-declaring
+// `struct sockaddr` (unused name in TPy land). Pointer ABI is identical.
+// `socklen_t` is `unsigned int` on Linux (glibc + musl), FreeBSD, and
+// macOS -- stable enough to hardcode. `ssize_t` is `long` on every 64-bit
+// *nix target TPy runs on.
+
+int socket(int domain, int type, int protocol);
+int bind(int sockfd, const void* addr, unsigned int addrlen);
+int connect(int sockfd, const void* addr, unsigned int addrlen);
+int listen(int sockfd, int backlog);
+int accept(int sockfd, void* addr, unsigned int* addrlen);
+int close(int fd);
+int shutdown(int sockfd, int how);
+
+long send(int sockfd, const void* buf, unsigned long len, int flags);
+long recv(int sockfd, void* buf, unsigned long len, int flags);
+
+int setsockopt(int sockfd, int level, int optname,
+               const void* optval, unsigned int optlen);
+int getsockname(int sockfd, void* addr, unsigned int* addrlen);
+int getpeername(int sockfd, void* addr, unsigned int* addrlen);
+int socketpair(int domain, int type, int protocol, int sv[2]);
+
+std::uint16_t htons(std::uint16_t hostshort);
+std::uint16_t ntohs(std::uint16_t netshort);
+// `inet_pton` and `inet_ntop` -- we use uint8_t* instead of char* for the
+// IP-text buffers so TPy bindings can use Ptr[UInt8] naturally (matches
+// the re module's convention for string-like byte buffers). uint8_t* and
+// char* have identical ABI; libc's real decls use char*, linker resolves.
+int            inet_pton(int af, const std::uint8_t* src, void* dst);
+std::uint8_t* inet_ntop(int af, const void* src, std::uint8_t* dst,
+                         unsigned int size);
+
+// strerror is intentionally NOT declared here: libc's `char* strerror(int)`
+// is transitively pulled in via `<cstring>` (from tpy.hpp's PCH chain),
+// and declaring a different const-qualification here conflicts. TPy
+// binding references `strerror` directly against the libc decl.
+
+// ---- Runtime helpers (implemented in runtime/cpp/src/stdlib/socket_impl.cpp) ----
+
+// Resolve a hostname to a single IPv4 address via getaddrinfo().
+// `host` + `host_len` are a non-null-terminated byte span (matches TPy's
+// str = std::string_view convention); the helper copies into a local
+// std::string before calling getaddrinfo. Writes 4 bytes of the first
+// A-record address to `out` in network byte order on success. Returns
+// 0 on success, -1 on failure (caller checks tpy_last_resolve_error()
+// for a human-readable message).
+//
+// Rationale for not exposing getaddrinfo directly: struct addrinfo's
+// field order differs between Linux (ai_addr before ai_canonname) and
+// BSD/macOS (swapped), so we cannot declare it portably at @native level.
+// This helper keeps the struct walking on the C++ side where <netdb.h>
+// is available.
+int tpy_resolve_ipv4(const std::uint8_t* host, std::uint64_t host_len,
+                     std::uint8_t out[4]);
+
+// Returns `errno` at the point of call. Indirection needed because the
+// errno symbol resolves differently per platform (__errno_location on
+// Linux glibc, __error on macOS); the TPy binding shouldn't care.
+int tpy_errno();
+
+// Returns a human-readable description of the most recent failure from
+// tpy_resolve_ipv4. Pointer is valid until the next tpy_resolve_ipv4
+// call on the same thread. Used by TPy-side error reporting to turn
+// getaddrinfo errors (EAI_*) into messages via gai_strerror without
+// exposing the error-code namespace.
+const char* tpy_last_resolve_error();
+
+}  // extern "C"