Rust Ffi
Developmentrust-ffiRust Ffi is an Agent Skill for development published in the ariebovenberg/whenever repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Instructions for using whenever's internal Rust FFI abstractions
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/ariebovenberg/whenever/blob/HEAD/.agents/skills/rust-ffi/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/rust-ffi, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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:
| Type | Purpose |
|---|---|
PyObj | Core wrapper around *mut PyObject. Has .extract() (Copy types), .extract_ref() (ref types), .type_(), .is_none() |
Owned<T> | RAII refcount wrapper. Use Owned::new() to take ownership, .borrow() for non-owning access |
HeapType<T> | A Python heap type that carries module state via .state() → &State |
PyType | A Python type object. .same_module() checks if two types belong to the same module |
PyReturn | Alias for PyResult<Owned<PyObj>> — the return type of Python-visible functions |
PyErrMarker | Sentinel indicating the Python error indicator is set |
ContextVarBool | Copy wrapper for a context variable. Has .get() -> PyResult<bool> |
Key helpers in src/py/:
raise_value_err(),raise_type_err(),raise_key_err()— raise Python exceptionswarn_with_class(cls, msg, stacklevel)— emit a Python warning. TakesPyObj, not a raw pointerhandle_kwargs(fname, kwargs, handler)— iterate kwargs with interned string matchinghandle_one_arg(fname, args)— extract exactly one positional arg, or raise TypeErrorhandle_opt_arg(fname, args)— extract zero or one positional arghandle_one_kwarg(fname, key, kwargs)— extract a single optional kwarg by keyfind_interned(value, handler)— match a PyObj against interned strings, returnsOptionmatch_interned_str(name, value, handler)— likefind_internedbut raises on no matchgeneric_alloc(type_, data)— allocate a Python object with given dataPyAsciiStrBuilder::format()— build a Python string without intermediate RustStringPyTuple::with_len()/.init_item()— safe tuple construction.to_py()via theToPytrait — convert Rust values to Python objects.to_tuple()— convert a Python sequence to a tuple (prefer overseq_len+seq_getitem)import(module_name)— import a Python module (don't callPyImport_ImportModuledirectly)
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.) ContextVarBools for suppressing warnings- Interned strings (
str_years,str_hour,str_units, etc.) - Unpickling functions
Access it via cls.state() from any HeapType<T>. Unpack needed fields at the top
of the function to avoid repeated state. access:
let &State {
date_type,
str_disambiguate,
exc_skipped,
time_delta_type,
..
} = cls.state();
When adding new fields to State, update three places: the struct definition,
the initialization in init_module, and Py_CLEAR in the traverse/clear functions.
Method registration
Methods are registered in a static mut METHODS: &[PyMethodDef] array using macros:
method0!— no argsmethod1!— one positional argmethod_vararg!— variable positional argsmethod_kwargs!— positional args + keyword argsclassmethod1!,classmethod_kwargs!— class methods
The function signatures must match the macro used. For method_kwargs!:
fn my_method(cls: HeapType<MyType>, slf: MyType, args: &[PyObj], kwargs: &mut IterKwargs) -> PyReturn
Performance philosophy
- Avoid unnecessary allocations. Use helpers to build Python objects directly
(e.g.,
PyAsciiStrBuilderinstead offormat!()→to_py()) - Prefer
i32/i64overi128when possible - Use
u8::eq_ignore_ascii_case()instead of manual case checks - Use tuples (not lists) for immutable Python sequences
- Check pointer equality before falling back to
py_eqfor comparisons
Common patterns
Positional argument handling:
// 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 handle_delta_unit_kwargs() for full datetime units, or
handle_date_delta_unit_kwargs() for calendar-only units. These build typed
DeltaMonths/DeltaDays/TimeDelta directly from kwargs.
Structured since/until kwarg parsing:
let SinceUntilKwargs { units, round_mode, round_increment } =
SinceUntilKwargs::parse(fname, state, kwargs)?;
Unit sets: Use the appropriate bitfield type:
CalUnitSet— calendar units only (years, months, weeks, days)ExactUnitSet— exact units only (weeks through nanoseconds)DeltaUnitSet— all delta units (calendar + exact)
Each has from_py() for parsing from Python, .iter(), .smallest(), .contains().
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.
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 inPyResult<T>
Type-specific gotchas
- ZonedDateTime doesn't implement
Ordin Rust. Compare via.instant()for ordering. Non-Copy (containsArc<TimeZone>). UsesArc::ptr_eq+ content equality for timezone comparison. DST-aware operations needambiguity_for_local()resolution. - OffsetDateTime compares by instant (
InstanthasOrd). Offset is anOffsetscalar. - PlainDateTime (
DateTimein Rust) compares by local date+time. HasOrd. - TimeDelta stores
secs: DeltaSeconds+subsec: SubSecNanos. Use.total_nanos() -> i128. Has.in_single_unit()and.in_exact_units()for unit decomposition. - ItemizedDelta/ItemizedDateDelta use
DeltaField<T>withi32::MAXas the UNSET sentinel.DeltaFieldhas customDebugshowing<unset>for sentinel values.
Development philosophy
- Avoid new macros when the logic isn't complex enough to warrant them. Slightly repetitive code is preferred over macro abstractions that obscure intent.
- Move logic into domain types: put computation methods on the data type itself rather than in free functions. This keeps FFI glue thin.
- Use
.ok_or_range_err()for out-of-range errors instead of custom messages. - Use
// SAFETY:comments forunsafeblocks per the Rust convention (exact casing matters). - Don't downcast integer types without an explicit check or comment explaining why it's safe.
pub(crate)notpubfor internal visibility.- Leverage the type system for safety: use distinct types to make invalid states unrepresentable. Prefer validated newtypes over raw primitives for constrained values.