Rust Ffi

Rust FFI Instructions

FFI approach: pyo3_ffi, not pyo3

The low-level pyo3_ffi module is used, not pyo3 directly. This avoids overhead, complex abstractions, and gives full control over generated code. The src/py/ module provides safe wrappers. Key types:

Key helpers in src/py/:

• raise_value_err(), raise_type_err(), raise_key_err() — raise Python exceptions
• warn_with_class(cls, msg, stacklevel) — emit a Python warning. Takes PyObj, not a raw pointer
• handle_kwargs(fname, kwargs, handler) — iterate kwargs with interned string matching
• handle_no_args(fname, args) — reject positional arguments
• handle_one_arg(fname, args) — extract exactly one positional arg, or raise TypeError
• handle_opt_arg(fname, args) — extract zero or one positional arg
• handle_one_kwarg(fname, key, kwargs) — extract a single optional kwarg by key
• raise_mixed_args(fname), raise_unexpected_kwarg(fname, key) — keep common argument errors consistent in class-specific parsers
• obj.expect_int(name) — accept a Python int or subclass and raise TypeError: {name} must be an integer otherwise
• find_interned(value, &[(string, value), ...]) — match a PyObj against an interned-string/value table, returning Option
• match_interned_str(name, value, &[(string, value), ...]) — like find_interned but raises on no match
• find_interned_with(value, handler) — compose multiple interned-string matchers while retaining one global pointer-equality pass before Unicode comparison
• find_interned_by(value, choices, eq) — match one table using the equality function supplied by find_interned_with
• match_type!(obj, type => |value| {...}, _ => {...}) — match an extension object against differently typed PyClass<T> values; prefix an arm with ref for non-Copy types
• CompareOp::from_ffi(op).apply(a, b) — apply a CPython rich-comparison operation to ordered Rust values
• generic_alloc(cls, data) — allocate a Python object with the given payload
• PyAsciiStrBuilder::format() — build a Python string without intermediate Rust String
• PyTuple::with_len() / unsafe .init_item_unchecked() — allocate and initialize tuple slots
• .to_py() via the ToPy trait — convert Rust values to Python objects
• .to_tuple() — convert a Python sequence to a tuple (prefer over seq_len+seq_getitem)
• import(module_name) — import a Python module (don't call PyImport_ImportModule directly)

Module State pattern

State (in src/pymodule/def.rs) is a large struct stored on the Python module. It holds:

• HeapType<T> for each class (date_type, time_delta_type, etc.)
• Exception classes (exc_repeated, exc_skipped, etc.)
• Warning classes (warn_deprecation, warn_days_not_always_24h, etc.)
• Interned strings (str_years, str_hour, str_units, etc.)
• Unpickling functions

Access it via cls.state() from any PyClass<T>.

Method registration

Methods are registered in a static mut METHODS: &[PyMethodDef] array using macros:

• method0! — no args
• method1! — one positional arg
• method_vararg! — variable positional args
• method_kwargs! — positional args + keyword args
• classmethod1!, classmethod_kwargs! — class methods

The function signatures must match the macro used. For method_kwargs!:

fn my_method(cls: PyClass<MyType>, slf: MyType, args: &[PyObj], kwargs: &mut IterKwargs) -> PyReturn

Performance philosophy

• Avoid unnecessary allocations. Use helpers to build Python objects directly (e.g., PyAsciiStrBuilder instead of format!() → to_py())
• Prefer i32/i64 over i128 when possible
• Use tuples (not lists) for immutable Python sequences
• For known strings, check pointer equality before falling back to direct Unicode comparison

Common patterns

Positional argument handling:

// No positional args:
handle_no_args("method_name", args)?;
// Exactly one required arg:
let arg = handle_one_arg("method_name", args)?;
// Zero or one optional arg:
let maybe_arg = handle_opt_arg("method_name", args)?;

Kwarg handling:

handle_kwargs("method_name", kwargs, |key, value, eq| {
    if eq(key, str_some_kwarg) {
        // parse value
    } else {
        return Ok(false); // unrecognized kwarg
    }
    Ok(true)
})

Single optional kwarg shortcut:

let relative_to = handle_one_kwarg("total", state.str_relative_to, kwargs)?;

Building deltas from kwargs (shift/add/subtract methods): Use common::shift_args::parse_datetime_shift_kwargs() for full datetime units or parse_calendar_shift_kwargs() for calendar-only units. They return a typed DateTimeShift or CalendarShift; the datetime parser's callback retains class-specific kwargs such as disambiguate and warning suppression. For a positional delta, use parse_datetime_shift_arg() or parse_calendar_shift_arg(); these raise the method-specific type error if the argument is not a supported delta.

Instant-like arguments: Use common::instant::extract_instant() when a non-Instant operand should fall through to another operation, and parse_instant_arg() for a required Instant, OffsetDateTime, or ZonedDateTime argument. Both normalize to the domain Instant.

Interned string matching with custom errors: Use find_interned + manual error message when you need a specific error format. Use match_interned_str when the default error format is acceptable. For composed subsets, use find_interned_with(value, |v, eq| ...), call find_interned_by(v, choices, eq) for table-shaped subsets, and use eq(v, expected) for individual strings. Do not call top-level find_interned separately for each subset: that would perform Unicode comparison before later subsets have had their pointer-equality pass.

Error handling:

• raise_value_err("msg")? for ValueError
• .ok_or_value_err("msg")? on Options — for domain errors with specific messages
• .ok_or_range_err()? on Options — for generic out-of-range errors (preferred)
• PyErrMarker() (with parens) as the sentinel in PyResult<T>