metrics_evaluation/cvat_api/labels.py

"""CVAT API label methods."""

from typing import TYPE_CHECKING

from metrics_evaluation.schema.cvat import CvatApiLabelDefinition

from .retry import retry_with_backoff

# TYPE_CHECKING is False at runtime but True during static type checking.
# This allows us to import CvatApiClient for type hints without creating a circular
# import (client.py imports LabelsMethods, and we need CvatApiClient for type hints).
# Benefits:
# - Avoids circular import errors at runtime
# - Provides proper type checking during development
# - No performance overhead (import only happens during type checking, not at runtime)
# This is a recommended pattern in modern Python (PEP 484, PEP 563).
# -- Claude Code
if TYPE_CHECKING:
    from .client import CvatApiClient


class LabelsMethods:
    """Label management operations for CVAT API."""

    def __init__(self, client: "CvatApiClient"):
        """Initialize label methods with client reference.

        Args:
            client: Parent CvatApiClient instance
        """
        self.client = client

    @retry_with_backoff(max_retries=3, initial_delay=1.0)
    def get_label_details(
        self, label_id: int, token: str | None = None
    ) -> CvatApiLabelDefinition:
        """Fetch details for a specific label.

        Args:
            label_id: The ID of the label
            token: Authentication token (optional)

        Returns:
            Label definition object
        """
        headers = self.client._get_headers(token)
        url = f"{self.client.cvat_host}/api/labels/{label_id}"

        return self.client._make_request(
            method="GET",
            url=url,
            headers=headers,
            resource_name="label",
            resource_id=label_id,
            response_model=CvatApiLabelDefinition,
        )