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.
    """
    return self._get_item(endpoint=f"/issue/{issue_id}", type_=Issue)

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.
    """
    return self._get_item(endpoint=f"/publisher/{publisher_id}", type_=Publisher)

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.
    """
    return self._get_item(endpoint=f"/series/{series_id}", type_=Series)

def list_issues(
    self,
    series_name: str,
    issue_number: int,
    year: int | None = None,
    max_results: int | None = 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: If given, return at most this many results.

    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.
    """
    if year is None:
        return self._get_list(
            endpoint=f"/series/name/{series_name}/issue/{issue_number}",
            type_=BasicIssue,
            max_results=max_results,
        )
    return self._get_list(
        endpoint=f"/series/name/{series_name}/issue/{issue_number}/year/{year}",
        type_=BasicIssue,
        max_results=max_results,
    )

def list_onsale_weekly_issues(
    self, year: int, week: int, max_results: int | None = 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: If given, return at most this many results.

    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.
    """
    return self._get_list(
        endpoint=f"/issue/on_sale_weekly/{year}/week/{week}",
        type_=BasicIssue,
        max_results=max_results,
    )

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

    Args:
        max_results: If given, return at most this many results.

    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.
    """
    return self._get_list(endpoint="/publisher", type_=Publisher, max_results=max_results)

def list_series(
    self, name: str | None = None, year: int | None = None, max_results: int | None = 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: If given, return at most this many results.

    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.
    """
    if name is None:
        return self._get_list(endpoint="/series", type_=Series, max_results=max_results)
    if year is None:
        return self._get_list(
            endpoint=f"/series/name/{name}", type_=Series, max_results=max_results
        )
    return self._get_list(
        endpoint=f"/series/name/{name}/year/{year}", type_=Series, max_results=max_results
    )