Codebeamer Python API
=====================

This section describes the end-user facing Codebeamer API for LOBSTER.

API
---

::

   from lobster.tools.codebeamer.codebeamer import lobster_codebeamer
   lobster_codebeamer(config: Config, out_file: str)

First, prepare a configuration:

Configuration Parameters
------------------------

Attributes accepted by ``AuthenticationConfig`` and ``Config`` when used in Python.

AuthenticationConfig
~~~~~~~~~~~~~~~~~~~~

::

   from lobster.tools.codebeamer.codebeamer import AuthenticationConfig

   auth = AuthenticationConfig(token="<TOKEN>", root="https://codebeamer.example")

- ``token`` (str | None): Bearer token for Codebeamer. Preferred over user/password.
- ``user`` (str | None): Username (used only if ``token`` is not provided).
- ``password`` (str | None): Password (paired with ``user``); may be auto-populated via ``~/.netrc``.
- ``root`` (str): Base HTTPS URL of the Codebeamer instance (must start with ``https://``).

Config
~~~~~~

::

   from lobster.tools.codebeamer.codebeamer import AuthenticationConfig, Config

   auth = AuthenticationConfig(token="<TOKEN>", root="https://codebeamer.example")
   conf = Config(
         references=[],
         import_tagged=None,
         import_query=1234,  # report ID or cbQL query string
         verify_ssl=True,
         page_size=100,
         schema="requirement",  # or "implementation" / "activity"
         timeout=30,
         out=None,
         num_request_retry=5,
         retry_error_codes=[500, 502, 503, 504],
         cb_auth_conf=auth,
   )

- ``references`` (List[str]): Names of Codebeamer fields whose referenced items should be traced (converted to ``req`` tags).
- ``import_tagged`` (str | None): Path to an existing LOBSTER artifact whose unresolved ``req`` references define item IDs to import.
- ``import_query`` (int | str | None): Report ID (int) or cbQL query string used to fetch items directly.
- ``verify_ssl`` (bool): Whether to verify TLS certificates; set ``True`` in production for security.
- ``page_size`` (int): Pagination size for REST queries; a trade-off between round trips and response size (default typically 100).
- ``schema`` (str): Target schema type (``requirement``, ``implementation``, ``activity``) controlling class/namespace mapping.
- ``timeout`` (int): Per-request timeout in seconds for HTTP calls.
- ``out`` (str | None): Output ``.lobster`` filename; if ``None`` you supply one to ``lobster_codebeamer``.
- ``num_request_retry`` (int): Number of retry attempts on transient failures (must be > 0).
- ``retry_error_codes`` (List[int]): HTTP status codes that trigger retry logic (e.g. [500, 502, 503, 504]).
- ``cb_auth_conf`` (AuthenticationConfig): Authentication + root endpoint.

Stable API Function
-------------------

``lobster_codebeamer(config: Config, out_file: str) -> None``
  Loads items (via query or tagged import) and writes them to a LOBSTER interchange file.

Example (Using Query with Custom Settings)
-------------------------------------------

::

   from lobster.tools.codebeamer.codebeamer import AuthenticationConfig, Config, lobster_codebeamer

   auth = AuthenticationConfig(
      token="my_secret_token_123",
      root="https://codebeamer.example.com"
   )

   conf = Config(
      references=["Depends On", "Related To"],
      import_tagged=None,
      import_query=5678,
      verify_ssl=True,
      page_size=200,
      schema="implementation",
      timeout=60,
      out=None,
      num_request_retry=3,
      retry_error_codes=[500, 502, 503, 504],
      cb_auth_conf=auth,
   )

   lobster_codebeamer(conf, "codebeamer_items.lobster")

Core Goals
----------
- Fetch items using a query or report ID by setting ``import_query``.
- Fetch items referenced in an existing LOBSTER file by setting ``import_tagged``.
- Choose the item type (requirement, implementation, or activity) using ``schema``.
- Make network calls more reliable by configuring ``num_request_retry`` and ``verify_ssl``.
- Improve performance by adjusting ``page_size`` and ``timeout``.
- Trace additional relationships by listing custom field names in ``references``.

Behavioral Notes
----------------
- ``import_tagged`` overrides ``import_query`` if both provided.
- ``schema`` maps to namespace class: requirement→``req`` / implementation→``imp`` / activity→``act``.
- Exponential backoff is implicit (1s, 2s, 4s...) based on ``num_request_retry``.
- Missing ``token`` triggers user/password or ``~/.netrc`` resolution.

Error Conditions
----------------
- Missing/invalid ``root`` (non-HTTPS) → ``KeyError``.
- Absent both ``import_query`` & ``import_tagged`` → ``KeyError``.
- ``num_request_retry <= 0`` → ``ValueError``.
- Unrecognised ``schema`` → ``KeyError``.