Grand Comics Database

def get_issue(self, issue_id: int) -> Issue:
    """Request an Issue using its id.

    Args:
        issue_id: The Issue id.

    Returns:
        A Issue object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/issue/{issue_id}")
        return TypeAdapter(Issue).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_publisher(self, publisher_id: int) -> Publisher:
    """Request a Publisher using its id.

    Args:
        publisher_id: The Publisher id.

    Returns:
        A Publisher object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/publisher/{publisher_id}")
        return TypeAdapter(Publisher).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_series(self, series_id: int) -> Series:
    """Request a Series using its id.

    Args:
        series_id: The Series id.

    Returns:
        A Series object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/series/{series_id}")
        return TypeAdapter(Series).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_issues(
    self, series_name: str, issue_number: int, year: int | None = None, max_results: int = 500
) -> list[BasicIssue]:
    """Request a list of Issues.

    Args:
        series_name: The name of the series to filter issues from.
        issue_number: The number to filter issues by.
        year: Filter the results using the issue year via its key_date.
        max_results: Maximum number of results to retrieve.

    Returns:
        A list of Issue objects.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        if year is None:
            results = self._fetch_list(
                endpoint=f"/series/name/{series_name}/issue/{issue_number}",
                max_results=max_results,
            )
        else:
            results = self._fetch_list(
                endpoint=f"/series/name/{series_name}/issue/{issue_number}/year/{year}",
                max_results=max_results,
            )
        return TypeAdapter(list[BasicIssue]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_onsale_weekly_issues(
    self, year: int, week: int, max_results: int = 500
) -> list[BasicIssue]:
    """Request a list of issues on sale in a given ISO week.

    Args:
        year: The ISO year (4-digit year).
        week: The ISO week number (1-53).
        max_results: Maximum number of results to retrieve.

    Returns:
        List of BasicIssue objects representing issues that went on sale during the given week.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        results = self._fetch_list(
            endpoint=f"/issue/on_sale_weekly/{year}/week/{week}", max_results=max_results
        )
        return TypeAdapter(list[BasicIssue]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_publishers(self, max_results: int = 500) -> list[Publisher]:
    """Request a list of Publishers.

    Args:
        max_results: Maximum number of results to retrieve.

    Returns:
        A list of Publisher objects.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        results = self._fetch_list(endpoint="/publisher", max_results=max_results)
        return TypeAdapter(list[Publisher]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_series(
    self, name: str | None = None, year: int | None = None, max_results: int = 500
) -> list[Series]:
    """Request a list of Series.

    Args:
        name: Filter the results using the series name.
        year: Filter the results using the series beginning year (Requires name to be passed).
        max_results: Maximum number of results to retrieve.

    Returns:
        A list of Series objects.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        if name is None:
            results = self._fetch_list(endpoint="/series", max_results=max_results)
        elif year is None:
            results = self._fetch_list(endpoint=f"/series/name/{name}", max_results=max_results)
        else:
            results = self._fetch_list(
                endpoint=f"/series/name/{name}/year/{year}", max_results=max_results
            )
        return TypeAdapter(list[Series]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err