Extend commands¶

These commands add behaviour to objects and modules that already exist in just-makeit.toml. Run them from the project root after scaffolding.

just-makeit method¶

just-makeit method <object> <method_name>
    [--module name]
    [--param name:type ...]
    --return-type TYPE
    [--variable-output] [--arg-type TYPE]
    [--multi-output TYPE ...]

Add a named execute method to an existing object.

jm method is additive and splice-free: it injects the method's declaration into <obj>_core.h and appends a fresh C stub to <obj>_core.c, then regenerates the glue (_ext.c, .pyi) with the new Python binding. Existing bodies in _core.c are never re-rendered — only the new stub is appended, ready for you to implement.

Arguments

Named parameters (--param)¶

Use --param name:type when the method takes multiple distinct typed scalar inputs. This generates named parameters in both the C stub and the Python wrapper.

just-makeit method nco configure --module dsp \
    --param freq:float \
    --param phase:float \
    --param mode:int32_t \
    --return-type void

Generated C stub:

void
nco_configure(nco_state_t *state, float freq, float phase, int32_t mode)
{
    (void)state; (void)freq; (void)phase; (void)mode;
}

Python call:

nco.configure(0.1, 0.0, 2)

All scalar types in _CTYPE_META are supported as --param types (float, double, int, int32_t, uint32_t, size_t, float _Complex, etc.).

Array parameters (--param name:type[]) generate a numpy array input. The C stub receives (const elem_t *name, size_t name_len) and the Python wrapper performs PyArray_FROM_OTF automatically:

just-makeit method resamp execute_ctrl --module resample \
    --param ctrl:"float _Complex[]" \
    --return-type size_t

Generated C stub:

size_t
resamp_execute_ctrl(resamp_state_t *state,
                    const float _Complex *ctrl, size_t ctrl_len)
{
    (void)state; (void)ctrl; (void)ctrl_len;
    return (size_t)0;
}

Python call: resamp.execute_ctrl(np.zeros(64, dtype=np.complex64))

--param and --arg-type are mutually exclusive per method.

Varargs methods (--varargs)¶

Use --varargs when a method needs fully flexible Python argument parsing — for example, configure(rate=48000, mode="fast") where the parameter set is open-ended or includes types that fall outside the fixed _CTYPE_META table.

just-makeit method filter configure --varargs

What gets generated:

• native/src/<comp>/<comp>_<name>_core.c (sacred — never regenerated). A Python-aware C file compiled directly into the Python extension DSO (not the pure-C OBJECT library), so it may include <Python.h> freely. Contains a PyObject * function with an <<IMPLEMENT>> stub:

  PyObject *
  filter_configure(PyObject *self, PyObject *args, PyObject *kwargs)
  {
      (void)self; (void)args; (void)kwargs;
      Py_RETURN_NONE;
  }
  

• <comp>_ext.c (regenerated). An extern PyObject * declaration pulls the symbol in from the binding file, and the PyMethodDef entry uses METH_VARARGS | METH_KEYWORDS:

  extern PyObject *
  filter_configure(PyObject *, PyObject *, PyObject *);
  
  /* in PyMethodDef array: */
  {"configure", (PyCFunction)(void *)filter_configure,
   METH_VARARGS | METH_KEYWORDS, "configure(*args, **kwargs)."},
  

• native/src/<comp>/CMakeLists.txt (surgically updated). The binding .c file is spliced into the Python3_add_library(...) source list so cmake compiles it into the same DSO.

• .pyi stub (regenerated):

  def configure(self, *args: Any, **kwargs: Any) -> Any: ...
  

• just-makeit.toml: varargs = true is recorded under [[<comp>.methods]].

Accessing the C state inside the binding:

The self pointer is a <Comp>Object * (the Python object), not the raw state struct. Cast it to reach the handle:

typedef struct { PyObject_HEAD; filter_state_t *handle; } Obj;
filter_state_t *state = ((Obj *)self)->handle;

The comment at the top of the generated sacred file shows this cast verbatim.

Constraint: --varargs is mutually exclusive with --arg-type, --param, and --variable-output. Those flags all imply a specific typed C signature; --varargs bypasses the type system entirely and gives you raw Python argument access.

Output modes¶

Choosing the right output mode depends on whether the maximum output count is knowable at init time.

--batch — 1:1-rate array transform¶

Use --batch when output length equals input length and is unknown at init time. The generated C stub receives (state, const in_t *in, size_t n, out_t *out) and the Python wrapper allocates and returns an output array of length n per call.

just-makeit method nco steps_u32 --module source \
    --arg-type void --return-type uint32_t --batch

just-makeit method nco steps_ctrl --module source \
    --arg-type float --return-type float --batch

Generated C stubs:

void nco_steps_u32(nco_state_t *state, size_t n, uint32_t *out);
void nco_steps_ctrl(nco_state_t *state, const float *in, size_t n, float *out);

Python calls:

ph  = nco.steps_u32(1024)    # returns uint32 ndarray of length 1024
out = nco.steps_ctrl(ctrl)   # ctrl is float32 ndarray; returns float32 ndarray

--variable-output — self-sizing output¶

Use --variable-output when the method's output count is not simply the input count — decimators, FIFOs, detectors, anything that returns "however many it produced". The generated binding allocates a NumPy-owned array of max(<method>_max_out(state), n) per call, lets the kernel write straight into it, and returns it trimmed to the count the kernel reported.

Each result is independent: it owns its memory, survives destroy(), and never aliases another call's result. See Array memory ownership for the policy and the measurements.

just-makeit method hbdecim execute --module resample \
    --arg-type "float _Complex" --return-type "float _Complex" \
    --variable-output

Generated C stubs:

/* Return maximum output samples possible given current state. */
size_t hbdecim_execute_max_out(hbdecim_state_t *state);

/* Process n_in samples; write up to _max_out results; return actual count. */
size_t hbdecim_execute(hbdecim_state_t *state,
                       const float _Complex *in, size_t n_in,
                       float _Complex *out);

Python call:

out = decim.execute(block)   # a fresh NumPy-owned array, trimmed to n_out

max_out() returning 0 is legal and means "unknown" — the binding then sizes the allocation from the call itself. It is a sizing contract, not a guarantee: the real bound is n_out <= max(max_out(state), n_requested), because a generator's steps(count) writes exactly count. If your kernel must know the capacity it was actually given, add pass_capacity = true — which also lets the binding size the allocation from max_out() alone, but only once max_out() takes the count and can answer for this call. See Array memory ownership for the exact rule.

Naming the synthesized count¶

A --variable-output method with --arg-type void and no --param is the generator shape: there is no input to size the output from, so jm synthesizes a leading count argument. Its default value is --count-default; its name is --count-name, and defaults to count.

just-makeit method delay ptr \
    --arg-type void --return-type "double _Complex" \
    --variable-output --count-default "state->n" --count-name n

delay.ptr(n=64)             # was `count=64`
delay.ptr_max_out(n=64)     # jm already derived this name from your C

Say it when your C API calls the quantity something else. The paired <comp>_<name>_max_out() already takes its parameter name from the C signature — deliberately, "rather than inventing a fourth name for the same concept" (gh-607) — so leaving the method's own kwarg hard-coded put the two halves of one generated pair at odds: ptr(count=…) beside ptr_max_out(n=…), for the same number (gh-1074).

Declaring the count as a real --param is not the same thing, even though it produces a byte-identical C prototype. It leaves the generator shape, and the default goes with it:

For a generator that is not a small loss: the zero-arg call's behaviour is its default. (Until gh-1079 the declared form also gave up the out= buffer; that shape has it back, so this table has one row fewer than it used to.)

The name reaches the binding's _kwlist, both .pyi generators, the runtime docstring and its worked call example — one accessor, so a project cannot end up with a stub advertising one name and a binding parsing another.

Two names are refused: anything that is not a Python identifier, and out — which is the other slot in the same _kwlist.

Accumulating results is safe. Every call returns an independent NumPy-owned array, so holding them in a list, concatenating them, or passing them on cannot be disturbed by a later call. This used to require a weakref liveness probe over a shared buffer (gh-437); that machinery is gone, and the guarantee is now structural rather than defended at runtime (gh-604).

Record shapes¶

When a method's output is records rather than plain samples, three shapes are available and --result-field names the fields in all three. What you get back depends on which of --single / --record-dtype you pass:

The two are mutually exclusive — the CLI rejects them together, because "one record" and "an array of records" are different results, not two spellings of one.

# an array of records: one row per telemetry entry, as a structured ndarray
just-makeit method tlm read --module link --arg-type void \
    --variable-output --record-dtype dp_tlm_rec_t \
    --result-field n:uint64_t --result-field flags:uint8_t

rows = tlm.read(64)
rows["n"]              # a column, no per-record Python objects
rows.dtype.itemsize    # C's itemsize, padding included

The dtype is built at runtime by the generated C, from offsetof and sizeof on the author's struct. That is not an optimisation — it is the only correct source. jm never sees the struct definition (it lives in the sacred header, which is yours), and numpy packs a field list where C pads it: a {uint8_t; uint64_t} struct is 16 bytes in C and 9 as a numpy dtype built from [(name, format), ...]. Deriving the layout from the field list would silently mis-read every row after the first.

--multi-output¶

Each --multi-output TYPE adds a parallel output array, producing a tuple return. Combine with --variable-output:

just-makeit method nco steps_u32_ovf --module resample \
    --arg-type void --return-type uint32_t \
    --variable-output --multi-output uint8_t

--nogil — release the GIL for thread-per-shard scaling¶

For a --variable-output execute method, --nogil wraps the pure-C kernel call in Py_BEGIN_ALLOW_THREADS / Py_END_ALLOW_THREADS:

just-makeit method ddc execute --module ddc \
    --param x:"float _Complex[]" --variable-output --pass-capacity --nogil

/* generated binding (abridged) */
const float _Complex *_ng0 = (const float _Complex *)PyArray_DATA(x_arr);
size_t _ng1 = (size_t)PyArray_SIZE(x_arr);
size_t n_out;
Py_BEGIN_ALLOW_THREADS
n_out = ddc_execute(self->handle, _ng0, _ng1, _d0, _cap);
Py_END_ALLOW_THREADS

Every numpy accessor is hoisted into a local before the block — including the output data pointer _d0 — so no Python C-API runs while the GIL is dropped; the allocation and any error-raising stay above it, under the GIL. A worker that gives each thread its own object then scales across cores instead of serialising on the GIL.

It is opt-in because releasing the GIL is sound only under that one-object-per-stream contract — jm cannot verify it, so you assert it by setting the flag. Generated, not hand-patched: the release is declarative and regenerates with the binding.

just-makeit property¶

just-makeit property <object> <prop_name>
    [--module name]
    --type TYPE
    [--writable] [--field] [--enum NAME]
    [--value-type TYPE] [--count-fn FN] [--key-fn FN] [--value-fn FN]

Add a read-only (or read-write) Python property to an existing object.

just-makeit property nco phase --module source --type uint32_t
just-makeit property nco phase_inc --module source --type uint32_t
just-makeit property buffer capacity --type size_t --writable
just-makeit property reader samples_read --module conv --type uint32_t --field
just-makeit property reader file_type --type int --field --enum ftype
just-makeit property reader stages --type list --value-type "const char *"
just-makeit property reader keywords --type dict --value-type object

Like jm method, a computed property is additive and splice-free: it injects a get_<prop>() declaration into <obj>_core.h and appends a fresh stub to <obj>_core.c (plus set_<prop>() if --writable) for you to implement, then regenerates the Python getter/setter glue in _ext.c. With --field no stub is generated — it injects one TYPE prop_name; member directly into the state struct and auto-implements the getter as return state->prop_name. Existing _core.c bodies are never re-rendered.

Arguments

Choosing a property kind — and what each costs your header¶

A property is backed one of five ways. The flags are not variations on a theme: they decide who writes the C and, crucially, whether your state struct has to be a complete type in the public header.

Omitting --field is not "unsupported" — it means "you implement the accessor". That is the computed kind, and it is the one to reach for when the struct is deliberately private: a file handle, a scratch buffer, a decoded header. jm declares

int rdr_get_fd(const rdr_state_t *state);

which takes a pointer to the state, so an incomplete type is fine — you can forward-declare typedef struct rdr_state rdr_state_t; in the header and keep the definition in your _core.c. The generated binding never touches a member.

The other three kinds read a member directly, so they need the definition. With an opaque struct a --field property fails at compile time:

rdr_ext.c:115:46: error: invalid use of incomplete typedef 'rdr_state_t'

If you see that, the property wants to be computed.

A computed property composes with everything else here, including --enum and its out-of-range check — the accessor's return value is decoded exactly as a field's would be:

just-makeit property rdr file_type --type int --enum ftype   # computed + enum

Enum-valued properties (--enum)¶

A property whose C value is an index into a [[enum]] table can present that value to Python as its string, exactly as a kind = "handle" module's getters have always done. C still stores the int; only the Python face changes.

[[enum]]
name = "ftype"
values = ["raw", "wav", "blue"]     # order IS the C int: raw=0, wav=1, blue=2

[[reader.properties]]
name = "file_type"
type = "int"
field = true
enum = "ftype"

>>> r.file_type
'blue'
>>> r.file_type = "wav"      # only when the property is --writable
>>> r.file_type
'wav'
>>> r.file_type = "nope"
ValueError: invalid file_type 'nope' (choices: raw, wav, blue)

The stub types it as Literal["raw", "wav", "blue"], so a typo is caught by mypy rather than at runtime.

Two things worth knowing:

• The value is range-checked. If the C side holds an index the table cannot contain — say a format code decoded from a file header that names a variant you do not support — reading the property raises ValueError: file_type holds out-of-range ftype value 99 (valid: 0..2) rather than reading past the table (gh-521).
• enum is not the same as string_enum:. enum = "name" references the shared [[enum]] SSOT and is what properties, handle getters, and --param name:enum:<ename> use. The inline string_enum:a,b,c form spells its choices in the type itself and applies to constructor init-params. Prefer the SSOT whenever the same choice set is used in more than one place — that is the whole reason it exists.

--enum cannot be combined with a buf_field property: an array of enum strings has no decoded form, and jm rejects it with a diagnostic rather than generating something misleading.

Container properties — dict, list and tuple¶

A property whose --type is dict, list or tuple is backed by a small iteration protocol your core implements. jm generates the loop, the container, the refcounting and every error path; you supply the accessors.

[[reader.properties]]
name       = "keywords"
type       = "dict"
count_fn   = "reader_num_keywords"    # size_t       (const state *)
key_fn     = "reader_keyword_tag"     # const char * (const state *, size_t)
value_fn   = "reader_keyword_value"   # <value_type> (const state *, size_t)
value_type = "object"

All three accessor names default from the object and property name (<obj>_num_<prop>, <obj>_<prop>_key, <obj>_<prop>_value), so the common declaration names none of them. key_fn applies to dict only — a list or tuple is keyed by position, and passing it there is an error rather than a silently ignored flag.

Container properties are read-only. jm builds the container fresh on every read, so a setter would mutate a copy the caller never sees; expose a method that mutates the core instead.

Choosing a value_type¶

This is the one real decision, and it is about who owns the conversion.

Prefer a C type. Your accessor returns an ordinary C value, jm converts it, and your core never includes Python.h:

const char *rc_stage_name(const rc_state_t *state, size_t i);   /* -> list[str] */

Reach for object when the value's Python type is data-dependent and so cannot be annotated statically. The motivating case is a BLUE extended header, where each keyword's type comes from a code stored in the file itself — one keyword yields a str, the next an int, the next a list[float]. There, value_fn returns a PyObject * directly:

PyObject *reader_keyword_value(const reader_state_t *state, size_t i);

It must return a new reference, or NULL with an exception set. Because it needs Python.h it cannot live in the pure-C core — put it in a hand-written <obj>_ext_extra.c (standalone) or <module>_ext_<obj>_extra.c (module), which jm wires in and never modifies. jm forward-declares it above the getter, so the #include order works out.

Stubs, and why this beats hand-writing it¶

The generated .pyi annotates as dict[str, T], list[T] or tuple[T, ...] — Any for the object escape hatch. That is half the point: a property hand-written into a sacred fragment never reaches the stub at all, so it stays invisible to a type checker even though the runtime is correct.

Errors you get for free¶

A key_fn or a pointer-valued value_fn that returns NULL raises a RuntimeError naming the property, the accessor and the index. Both are real guards, not decoration: PyUnicode_FromString(NULL) reaches strlen(NULL) and crashes, so the unchecked form segfaults rather than raising. A partially built container is released on every failure path.

Removing a method or property¶

just-makeit remove <kind> <name> --object <obj> [--module <mod>] [--force], where kind is method or property (also object, module, function, state, warning, or error for those respectively — --object/--module only apply where relevant; warning and error are addressed differently, see their own sections below):

just-makeit remove method configure --object nco --module dsp
just-makeit remove property phase --object nco --module dsp

This regenerates the glue (_ext.c, .pyi) without the entry, so the binding stops exposing it. It is splice-free, so it leaves the orphaned _core.c body (and the _core.h declaration, or the field-backed struct member) in place with a "delete by hand" note — your code is never silently rewritten. Remove the stub yourself once you're sure. (Removing state via just-makeit remove state <name> --object <obj> is structural and rebuilds the object via the regenerate path instead.)

just-makeit view¶

just-makeit view <object> <ViewClassName>
    --module name
    --create-fn fn
    [--init-param name:type[:default] ...]
    [--exclude-property name ...] [--exclude-method name ...]
    [--doc "text"]

Add a second Python class over the same generated C core (gh-504). The view shares the object's <obj>_state_t, its _core.c, and its step(); it differs only in the C constructor it calls, the constructor arguments it takes, and the Python surface it exposes. Use it when one algorithm has two front doors — a continuous mode and a burst mode, an empty accumulator and a pre-seeded one — and a second object would mean a second copy of the C.

just-makeit view acc SeededAcc --module bank \
    --create-fn acc_create_seeded \
    --init-param seed:double:0.0 \
    --exclude-method total

This records a [[<obj>.views]] entry, injects acc_state_t *acc_create_seeded(double seed); into <obj>_core.h, appends an <<IMPLEMENT>> stub for it to the sacred <obj>_core.c (so the module still compiles before you have written a line), and regenerates the module glue with the extra class registered. The view lands in its own binding fragment, <mod>_ext_<viewclass>.c, next to the parent's — no second core library and no second state struct.

Views are a module-object feature: the multi-type module machinery is what registers the extra class, so --module is required. --create-fn is also required and must differ from the parent's <obj>_create — a view exists precisely to build from a different constructor.

Arguments

Diverging, not only trimming¶

--exclude-property / --exclude-method take members away. To add a member the parent lacks, or override one it has, pass --view <ClassName> to jm property, jm method, or jm warning — reusing a parent member's name overrides it, a new name adds it:

# `runs` exists on SeededAcc only
just-makeit property acc runs --module bank --type size_t --field \
    --doc "reseed count" --view SeededAcc

# same name as the parent's property -> overrides its docstring on the view
just-makeit property acc depth --module bank --type size_t --field \
    --doc "seed depth" --view SeededAcc

These persist as [[<obj>.views.properties]], [[<obj>.views.methods]], and [[<obj>.views.warnings]] under the matching view, and are merged over the parent's when the glue is generated. See Configuration → Schema reference.

Excluding a method drops only the view's Python wrapper and its PyMethodDef entry — the shared C function stays in the core, so nothing dangles and the parent keeps working.

Overriding a parent method¶

A view method that reuses a parent method's name is an override, and there are two kinds. --fn decides which (gh-1012, gh-1011):

This is not a flag standing in for a second question. The parent's C symbol carries the parent's prototype, so a different signature is only callable through a different symbol — which is exactly what --fn supplies:

# doc-only: same signature, the view just words it differently
just-makeit method acc plain --module bank --view SeededAcc \
    --doc "seeded plain"
#   -> View 'SeededAcc' overrides the doc of 'plain' (shares acc_plain)

# signature override: its own arg_type, so its own C function
just-makeit method acc scaled --module bank --view SeededAcc \
    --fn acc_scaled_seeded --arg-type float --return-type double \
    --doc "seeded scale"
#   -> Implement acc_scaled_seeded() in acc_core.c

Both prototypes then stand side by side in the sacred header, and only the view's fragment calls the override:

double acc_scaled(acc_state_t *state, double x);         /* parent */
double acc_scaled_seeded(acc_state_t *state, float x);   /* the view's */

A differing signature without --fn is refused, rather than silently ignored as it was before 0.62.0 — the view would have called the parent's symbol, so the declaration could only ever have been dropped:

error: view 'SeededAcc' redeclares parent method 'scaled' with a different arg_type.
  Without --fn the view calls the parent's acc_scaled, which has the parent's
  signature, so this could only be ignored.
  Pass --fn <symbol> to bind its own C function (gh-1012), or drop the
  differing key(s) for a doc-only override.

Only the keys you actually state are compared, so a hand-written manifest entry carrying nothing but doc is a doc-only override and stays legal. And --fn naming the parent's own symbol is refused up front, rather than left for the C compiler to report as a conflicting redefinition:

error: view 'SeededAcc' overrides method 'scaled' with fn 'acc_scaled', which is
the symbol the parent already binds.
  A signature override needs its OWN C function — give --fn a different name, or
  drop it for a doc-only override.

Properties and warnings have no second kind: reusing a parent's name overrides how it reads, as in the depth example above.

Limitation: a view cannot yet sit over a parent whose init-params use per-array dtype-dispatch or optional-array forms (real_type, real_create_fn, create_fn, optional); those paths embed <obj>_create directly and would silently ignore the view's create_fn, so jm view rejects them with a diagnostic.

The Views example builds the whole thing end to end.

just-makeit warning¶

just-makeit warning <object>
    --condition FIELD
    --message TEXT
    [--module name] [--category NAME] [--stacklevel N]

Declare a warning that fires after construction when a boolean state field is set — a way to flag a degenerate-but-legal configuration without failing the constructor. The generated __init__ glue checks the field once the object is built and, if set, calls PyErr_WarnEx with your message and category.

just-makeit warning agc underpowered \
    --message "AGC gain floor reached; output may clip" \
    --category RuntimeWarning

This is declarative: the condition, message, and category live in just-makeit.toml as a [[<object>.warnings]] entry, and the check is regenerated into _ext.c — you write no C. --condition names a bool-ish field on the object's state struct (emitted as self->handle-><field>), so it must already exist as state (add it with just-makeit add if needed).

Arguments

An object may carry more than one warning — each just-makeit warning call on a distinct --condition adds another. Re-running with the same condition replaces that entry.

Remove one with just-makeit remove warning <condition> --object <obj> — a warning has no name of its own, so its condition is what identifies it.

just-makeit error¶

just-makeit error <object>
    --category NAME
    --message TEXT
    [--module name]
    [--view ClassName]

Translate a create() failure into a specific Python exception. By default a failed constructor raises a blanket MemoryError; this replaces that with an exception class and message of your choosing.

just-makeit error biquad \
    --category ValueError \
    --message "biquad coefficients unstable (|poles| >= 1)"

Also declarative: the choice is stored as create_error / create_error_message in just-makeit.toml and regenerated into the _ext.c failure path. There is one failure channel — a NULL from create() cannot say why it failed — so this applies to every create() failure, a genuine allocation failure included. Choose a category that reads sensibly for the most likely cause.

Arguments

Each object has a single failure translation, so re-running replaces it rather than accumulating. Remove it with just-makeit remove error <obj> --object <obj> — error takes no name because there is only ever one per object.

Views inherit their parent's translation¶

A view is a second Python class over the same C core, so declaring the error on the parent covers both front doors — you do not need to repeat it:

just-makeit error rateconv --module resample \
    --category ValueError \
    --message "RateConverter: invalid parameter (need rate > 0)"
# RateConverter(...)        -> ValueError
# MatchedRateConverter(...) -> ValueError, same message

This matters because a view exists precisely when the constructor takes different — usually more — parameters, so it is the constructor with the most ways to be handed something invalid.

Add --view when the view's extra parameters deserve their own wording:

just-makeit error rateconv --module resample --view MatchedRateConverter \
    --category ValueError \
    --message "MatchedRateConverter: invalid pulse/beta/span combination"

Only an explicit --view declaration is written to the manifest; an inherited translation keeps tracking the parent rather than being frozen into a copy. Note the contrast with just-makeit warning, where a view does not inherit: a warning describes a condition the view may not have, while an error describes the same object refusing to construct.

just-makeit function¶

just-makeit function <name> --module <mod>
    [--param name:type ...]
    [--return-type TYPE]
    [--doc "text"]

Add a stateless C function to an existing module — no struct, no lifecycle, no persistent state.

Writes a C stub to the function's own sacred source file native/src/<module>/<name>.c (never regenerated — your implementation is safe) and injects the declaration into native/inc/<module>/<module>_core.h. Each function thus owns one translation unit, which the module's CMakeLists compiles into the module's OBJECT library. Then regenerates <module>_ext.c to add a _bind_<name> Python wrapper and wire it into the PyMethodDef array.

With --inline the function instead lives entirely as a static inline body in <module>_core.h and gets no .c file.

The generated _bind_<name> wrapper is positional-or-keyword (METH_VARARGS | METH_KEYWORDS): callers may pass arguments positionally or by name (fn(input=x, n=8)). A no-parameter function stays METH_NOARGS. Keyword capability is ~free unless keywords are actually used — see Arguments: positional vs keyword.

Arguments

Example — no parameters:

just-makeit function fft_global_setup --module fft --doc "Initialize FFT tables."

native/src/fft/fft_global_setup.c (yours to implement):

/*
 * fft_global_setup.c — fft module-level function.
 */
#include "fft/fft_core.h"

/* <<IMPLEMENT: fft_global_setup>> */
void
fft_global_setup(void)
{
}

fft_core.h (declaration injected automatically):

void fft_global_setup(void);

Example — with parameters:

just-makeit function compute_window \
    --module fft \
    --param n:size_t \
    --param beta:float \
    --return-type float

native/src/fft/compute_window.c:

/*
 * compute_window.c — fft module-level function.
 */
#include "fft/fft_core.h"

/* <<IMPLEMENT: compute_window>> */
float
compute_window(size_t n, float beta)
{
    (void)n; (void)beta;
    return (float)0.0f; /* placeholder */
}

Python call:

from my_pkg import fft
w = fft.compute_window(512, 5.0)

Array parameters work identically to jm method: append [] to the type.

just-makeit function apply_window \
    --module fft \
    --param data:"float _Complex[]" \
    --return-type void

Path parameters (name:path) accept a str | os.PathLike from Python, coerce it to bytes via PyUnicode_FSConverter, and forward const char * to C — the same coercion used by the handle generator:

just-makeit function load_calibration \
    --module dsp \
    --param path:path \
    --return-type void

Python call:

from pathlib import Path
import my_pkg.dsp as dsp
dsp.load_calibration(Path("/data/cal.bin"))
dsp.load_calibration("/data/cal.bin")        # str also works

Enum parameters (name:enum:<ename>[=default]) accept a choice string, validate it against the [[enum]] SSOT in just-makeit.toml, and forward the int index to C. Requires a [[enum]] with the matching name to be declared in just-makeit.toml first.

# just-makeit.toml
[[enum]]
name = "color_space"
values = ["rgb", "hsv", "lab"]

just-makeit function convert_image \
    --module img \
    --param path:path \
    --param src_cs:enum:color_space=rgb \
    --param dst_cs:enum:color_space \
    --return-type int \
    --check-return

--check-return makes the generated binding treat a non-zero int return value as a failure: it captures the result, raises RuntimeError on a non-zero code, and returns None on success. Requires --return-type to be an integer type (int, size_t, …). It is the module-function analog of the handle generator's close_returns and composes naturally with path and enum args.

from my_pkg import img
img.convert_image("input.png", dst_cs="lab")   # → None, or raises RuntimeError

C stub (native/src/img/convert_image.c — yours to implement):

#include "img/img_core.h"

int
convert_image(const char *path, int src_cs, int dst_cs)
{
    /* <<IMPLEMENT: convert_image>> */
    return 0;
}