autopkgtest for python-skbio
============================

The autopkgtest for python-skbio requires a specialized custom setup due to a
combination of complex package structural requirements:

1. Cython / C-Extensions:
   The package contains compiled Cython modules (like `_intersection`, `_cutils`,
   and `_c_nj`). During a native pytest run inside the source tree, Python's
   default import mechanism favors local directories, leading to 
   `ModuleNotFoundError` errors because the local source tree lacks the compiled 
   binary `.so` objects.

2. Implicit Namespace and Relative Imports:
   Simply renaming the local source directory breaks strict internal relative 
   package imports (e.g., `from .. import _intersection`), which then look for 
   non-existent module namespaces.

3. Module-Relative Test Data:
   Internal functions (like `get_data_path()`) evaluate `__file__` to look up 
   critical testing data files (e.g., `example2_Y`, `stockholm_missing_header`) 
   relative to the executing test suite path.

Solution Architecture:
----------------------
To resolve all three constraints simultaneously, the test environment uses a 
writable virtual overlay inside `debian/rules` during `PYBUILD_AUTOPKGTEST`:

- Maintenance Note: The `debian/pybuild.testfiles` manifest must contain a complete
  list of all test files and associated data resources. It can be fully re-generated 
  from the root of the source tree using the following command:

  find skbio -type f -path "*/tests/*" -printf '%p %p\n' | sort > debian/pybuild.testfiles

- In the testbed, a temporary `overlay/` directory copies the globally installed, 
  fully-compiled system package from `/usr/lib/python3/dist-packages/skbio`.
- The uncompiled testing structures and data files from the source tree are 
  mirrored directly over this writable system package copy.
- The original source directory is removed to prevent implicit module shadowing.
- Pytest runs inside the isolated `overlay/skbio` environment using 
  `--import-mode=importlib` to avoid naming collision conflicts on generic names 
  (like `test_util.py`).

This guarantees that the tests run cleanly against the true installed Debian 
package binaries while safely maintaining absolute relative paths for internal 
data lookup structures.

 -- Karsten Schöke <karsten.schoeke@geobasis-bb.de>  Sat, 15 Aug 2026 16:25:26 +0200

