Wheel Staging Area Internals
############################

Understanding the staging area helps when debugging import failures or building
custom wheels.

When CMake configures the project with ``ENABLE_PYTHON_FDB_INTERFACE=ON``, it
creates ``build/pyfdb-python-package-staging/`` with the following layout:

.. code-block:: text

   pyfdb-python-package-staging/
   ├── pyfdb/                   ← symlink → fdb/src/pyfdb/   (live source)
   ├── pyfdb_bindings/
   │   ├── __init__.py          ← copied at build time by CMake POST_BUILD
   │   └── pyfdb_bindings.cpython-<tag>.so   ← compiled extension
   ├── setup.py                 ← generated from cmake/pyfdb_setup.py.in
   ├── setup.cfg                ← generated from cmake/pyfdb_setup.cfg.in
   ├── README.md                ← copied at build time
   └── LICENSE                  ← copied at build time

Key points:

* The ``pyfdb/`` symlink means edits to the Python source in the repository
  take effect immediately after an editable install — no rebuild or reinstall
  needed.
* ``pyfdb_bindings/`` is a proper Python package (it has an ``__init__.py``),
  allowing ``from pyfdb_bindings import pyfdb_bindings`` to resolve the compiled
  extension as a submodule.  Without ``__init__.py`` the import would fall back
  to namespace-package semantics, which is fragile with tools like setuptools.
* The ``.so`` is regenerated by Ninja whenever ``bindings.cc`` or its
  dependencies change.  Re-running ``ninja`` is sufficient — no ``pip install``
  is required after a C++ rebuild.