# Adding symbols

The routine task: the app needs an OCCT class this binding does not expose yet.
Read [design.md](design.md) first if you are touching the machinery instead.

## 1. Find what is missing

```bash
python tools/inventory.py --emit    # re-scan the app for OCP usage
python tools/inventory.py --check   # what the installed wheel lacks, by module
```

`--check` groups gaps by module, which is how increments are scoped. Note it
only sees symbols reached through an import (`TopExp.MapShapes_s`), not methods
called on instances (`shape.IsSame(...)`) — a green `--check` is necessary, not
sufficient. Running the app's own tests in the parity venv is what catches the
rest, loudly, as an `AttributeError`.

## 2. Write the module

One file per OCP module: `src/modules/mod_<Name>.cpp`.

```cpp
#include "../common/occt_module.h"     // brings in the handle caster and "_a"
#include "../common/occt_policies.h"   // OCP_RETURN_COPY, OCP_NOGIL

#include <Some_Class.hxx>

void register_Some(nb::module_ &root) {
    nb::module_ m = ocp_submodule(root, "Some");

    nb::class_<Some_Class>(m, "Some_Class")
        .def(nb::init<>())
        .def("Value", &Some_Class::Value, "index"_a, OCP_RETURN_COPY)
        .def("Build", &Some_Class::Build, OCP_NOGIL);
}
```

Declare and call `register_Some` in `src/core.cpp`. Registration order matters
only in that a base class must precede its derived classes.

## 3. The checklist

- **Shape-returning API** → `OCP_RETURN_COPY`. Explorers, iterators, map
  lookups, `Generated`/`Modified` lists — anything handing out a reference into
  storage the caller does not own.
- **Static method** → `OCP_DEF_S(cls, "Name", ...)`, which appends `_s`. Every
  static, without exception.
- **Transient (handle-managed) class** → derive from `Standard_Transient` in the
  `nb::class_` declaration and bind constructors with `ocp_new<T, Args...>()`.
  Never `nb::init<>` — see design.md.
- **Long kernel call** → `OCP_NOGIL`, but only if it cannot re-enter Python.
- **Executing constructor** → do not bind it. Bind the default constructor plus
  the `SetX`/`Build` sequence.
- **Enum** → `nb::is_arithmetic()` and `.export_values()`.
- **`Message_ProgressRange` parameters** → omit them. The app never passes one
  (no `OCP.Message` import anywhere), and leaving them out keeps signatures
  small. Add the module if `--check` ever reports it.
- **Out-parameters** stay out-parameters. `BRep_Tool.Triangulation_s(F, L)`
  writes through `L` because the app calls it that way; returning a tuple would
  be tidier and wrong.

When in doubt about a signature, ask the stock wheel rather than guessing:

```bash
cd ../app && .venv/bin/python -c "from OCP.BRep import BRep_Tool; print(BRep_Tool.Triangulation_s.__doc__)"
```

## 4. New toolkits

If the linker cannot find a symbol, the class lives in a toolkit not yet listed
in `CMakeLists.txt` (`target_link_libraries(_OCP PRIVATE ...)`). Add it there;
`auditwheel` bundles whatever the linker records, so nothing else changes.

## 5. Verify and ship

```bash
make dev        # compile + tests
make test-asan  # if you touched ownership or added transients
make wheel      # bump the .devN in pyproject.toml first
make publish
tools/parity_venv.sh && python tools/inventory.py --check
```

Then run the slice of the app's suite the increment claims — Inc 1 is gated on
`backend/tests/test_geom_memo.py`, Inc 2 on the tessellation tests plus
`pytest -m perf`, Inc 4 on `test_cad_pool.py` and `test_derive.py`, and the
cutover on the full suite plus `backend/tools/rebuild_sweep.py --diff` over the
project store.

## Adding to `n3xd_ocp` instead

Anything that is not a faithful mirror of an upstream symbol belongs in
`src/ext/` under the `n3xd_ocp` namespace: bulk array APIs, batched measurement,
anything GIL-free that upstream does not offer. `OCP.*` staying a
symbol-for-symbol drop-in is what makes parity testing meaningful, so keep
additive work out of it. Register leaf modules with
`ocp_named_module("n3xd_ocp.<name>")` and re-export them in
`python/n3xd_ocp/__init__.py`.