Developing UMAAPy
=================

Contributor Environment
-----------------------

Use an editable install so tests and local commands resolve the workspace ``src/`` tree:

.. code-block:: bash

   python -m pip install --upgrade pip
   pip install -e .[tests,cyclone]

Verify import resolution points to this checkout (not a stale site-packages install):

.. code-block:: bash

   UMAAPY_AUTO_INIT=0 python -c "import umaapy,inspect; print(umaapy.__file__)"

Expected output ends with ``src/umaapy/__init__.py`` from your local repository path.

Type Generation
---------------

Cyclone DDS nightly Python bindings are required for Python 3.13 and type generation:

.. code-block:: bash

   pip install cyclonedds-nightly==2025.11.25

Generate types from all IDL files under ``specs/idls/``:

.. code-block:: bash

   make generate-types-clean

Equivalent direct script invocation:

.. code-block:: bash

   python scripts/generate_types.py --clean --verbose

This writes generated code under ``src/umaapy/UMAA/`` (package tree, not a single file).

CI validates generated output drift in a dedicated Windows job by regenerating types and checking for tracked/untracked changes in
``src/umaapy/UMAA/``. If CI fails this check, regenerate locally and commit the updated generated files.

Troubleshooting:

- With ``cyclonedds-nightly==2025.11.25``, run generation on Windows; current Linux nightly ``idlc`` can segfault.
- If ``idlc`` is not on ``PATH``, set ``IDLC_PATH=/path/to/idlc`` before running generation.
- Use ``--verbose`` to print per-file generation progress and failures.

Testing Workflow
----------------

UMAAPy tests are classified with explicit pytest markers:

- ``unit``: Fast isolated tests with no live DDS middleware requirements.
- ``component``: Multi-module tests without live vendor middleware requirements.
- ``integration_vendor``: Tests that require a live DDS runtime (Cyclone-first lane; marker name retained for compatibility).

Default test runs use the fast path and exclude vendor integration tests:

.. code-block:: bash

   pytest

This is equivalent to:

.. code-block:: bash

   pytest -m "not integration_vendor"

Run only middleware integration tests:

.. code-block:: bash

   pytest -m integration_vendor

Useful collection checks:

.. code-block:: bash

   pytest --collect-only
   pytest -m "not integration_vendor" --collect-only
   pytest -m integration_vendor --collect-only