Comicvine

def get_character(self, character_id: int) -> Character:
    """Request a Character using its id.

    Args:
        character_id: The Character id.

    Returns:
        A Character object or None if not found.

    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(resource=ComicvineResource.CHARACTER, id_=character_id)

def get_concept(self, concept_id: int) -> Concept:
    """Request a Concept using its id.

    Args:
        concept_id: The Concept id.

    Returns:
        A Concept object or None if not found.

    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(resource=ComicvineResource.CONCEPT, id_=concept_id)

def get_creator(self, creator_id: int) -> Creator:
    """Request a Creator using its id.

    Args:
        creator_id: The Creator id.

    Returns:
        A Creator object or None if not found.

    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(resource=ComicvineResource.CREATOR, id_=creator_id)

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

    Args:
        issue_id: The Issue id.

    Returns:
        A Issue object or None if not found.

    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(resource=ComicvineResource.ISSUE, id_=issue_id)

def get_item(self, item_id: int) -> Item:
    """Request an Item using its id.

    Args:
        item_id: The Item id.

    Returns:
        An Item object or None if not found.

    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(resource=ComicvineResource.ITEM, id_=item_id)

def get_location(self, location_id: int) -> Location:
    """Request a Location using its id.

    Args:
        location_id: The Location id.

    Returns:
        A Location object or None if not found.

    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(resource=ComicvineResource.LOCATION, id_=location_id)

def get_origin(self, origin_id: int) -> Origin:
    """Request an Origin using its id.

    Args:
        origin_id: The Origin id.

    Returns:
        An Origin object or None if not found.

    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(resource=ComicvineResource.ORIGIN, id_=origin_id)

def get_power(self, power_id: int) -> Power:
    """Request a Power using its id.

    Args:
        power_id: The Power id.

    Returns:
        A Power object or None if not found.

    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(resource=ComicvineResource.POWER, id_=power_id)

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

    Args:
        publisher_id: The Publisher id.

    Returns:
        A Publisher object or None if not found.

    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(resource=ComicvineResource.PUBLISHER, id_=publisher_id)

def get_story_arc(self, story_arc_id: int) -> StoryArc:
    """Request a Story Arc using its id.

    Args:
        story_arc_id: The StoryArc id.

    Returns:
        A StoryArc object or None if not found.

    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(resource=ComicvineResource.STORY_ARC, id_=story_arc_id)

def get_team(self, team_id: int) -> Team:
    """Request a Team using its id.

    Args:
        team_id: The Team id.

    Returns:
        A Team object or None if not found.

    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(resource=ComicvineResource.TEAM, id_=team_id)

def get_volume(self, volume_id: int) -> Volume:
    """Request a Volume using its id.

    Args:
        volume_id: The Volume id.

    Returns:
        A Volume object or None if not found.

    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(resource=ComicvineResource.VOLUME, id_=volume_id)

def list_characters(
    self, params: dict[str, Any] | None = None, max_results: int | None = 500
) -> list[BasicCharacter]:
    """Request a list of Characters.

    Args:
        params: Parameters to add to the request.
        max_results: If given, return at most this many results.

    Returns:
        A list of Character 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(
        resource=ComicvineResource.CHARACTER, params=params, max_results=max_results
    )

def list_concepts(
    self, params: dict[str, Any] | None = None, max_results: int | None = 500
) -> list[BasicConcept]:
    """Request a list of Concepts.

    Args:
        params: Parameters to add to the request.
        max_results: If given, return at most this many results.

    Returns:
        A list of Concept 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(
        resource=ComicvineResource.CONCEPT, params=params, max_results=max_results
    )

def list_creators(
    self, params: dict[str, Any] | None = None, max_results: int | None = 500
) -> list[BasicCreator]:
    """Request a list of Creators.

    Args:
        params: Parameters to add to the request.
        max_results: If given, return at most this many results.

    Returns:
        A list of Creator 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(
        resource=ComicvineResource.CREATOR, params=params, max_results=max_results
    )

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

    Args:
        params: Parameters to add to the request.
        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.
    """
    return self._get_list(
        resource=ComicvineResource.ISSUE, params=params, max_results=max_results
    )

def list_items(
    self, params: dict[str, Any] | None = None, max_results: int | None = 500
) -> list[BasicItem]:
    """Request a list of Items.

    Args:
        params: Parameters to add to the request.
        max_results: If given, return at most this many results.

    Returns:
        A list of Item 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(
        resource=ComicvineResource.ITEM, params=params, max_results=max_results
    )

def list_locations(
    self, params: dict[str, Any] | None = None, max_results: int | None = 500
) -> list[BasicLocation]:
    """Request a list of Locations.

    Args:
        params: Parameters to add to the request.
        max_results: If given, return at most this many results.

    Returns:
        A list of Location 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(
        resource=ComicvineResource.LOCATION, params=params, max_results=max_results
    )

def list_origins(
    self, params: dict[str, Any] | None = None, max_results: int | None = 500
) -> list[BasicOrigin]:
    """Request a list of Origins.

    Args:
        params: Parameters to add to the request.
        max_results: If given, return at most this many results.

    Returns:
        A list of Origin 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(
        resource=ComicvineResource.ORIGIN, params=params, max_results=max_results
    )

def list_powers(
    self, params: dict[str, Any] | None = None, max_results: int | None = 500
) -> list[BasicPower]:
    """Request a list of Powers.

    Args:
        params: Parameters to add to the request.
        max_results: If given, return at most this many results.

    Returns:
        A list of Power 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(
        resource=ComicvineResource.POWER, params=params, max_results=max_results
    )

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

    Args:
        params: Parameters to add to the request.
        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(
        resource=ComicvineResource.PUBLISHER, params=params, max_results=max_results
    )

def list_story_arcs(
    self, params: dict[str, Any] | None = None, max_results: int | None = 500
) -> list[BasicStoryArc]:
    """Request a list of Story Arcs.

    Args:
        params: Parameters to add to the request.
        max_results: If given, return at most this many results.

    Returns:
        A list of StoryArc 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(
        resource=ComicvineResource.STORY_ARC, params=params, max_results=max_results
    )

def list_teams(
    self, params: dict[str, Any] | None = None, max_results: int | None = 500
) -> list[BasicTeam]:
    """Request a list of Teams.

    Args:
        params: Parameters to add to the request.
        max_results: If given, return at most this many results.

    Returns:
        A list of Team 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(
        resource=ComicvineResource.TEAM, params=params, max_results=max_results
    )

def list_volumes(
    self, params: dict[str, Any] | None = None, max_results: int | None = 500
) -> list[BasicVolume]:
    """Request a list of Volumes.

    Args:
        params: Parameters to add to the request.
        max_results: If given, return at most this many results.

    Returns:
        A list of Volume 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(
        resource=ComicvineResource.VOLUME, params=params, max_results=max_results
    )

@deprecated("Use the resource specific search functions instead.")
def search(
    self, resource: ComicvineResource, query: str, max_results: int | None = 500
) -> (
    list[BasicPublisher]
    | list[BasicVolume]
    | list[BasicIssue]
    | list[BasicStoryArc]
    | list[BasicCreator]
    | list[BasicCharacter]
    | list[BasicTeam]
    | list[BasicLocation]
    | list[BasicConcept]
    | list[BasicPower]
    | list[BasicOrigin]
    | list[BasicItem]
):
    """Request a list of search results filtered by the provided resource.

    **Deprecated:** Use the resource specific search functions instead.

    Args:
        resource: Filter which type of resource to return.
        query: Search query string.
        max_results: If given, return at most this many results.

    Returns:
        A list of results, mapped to the given resource.

    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._search(resource=resource, query=query, max_results=max_results)

def search_characters(self, query: str, max_results: int | None = 500) -> list[BasicCharacter]:
    """Request a list of search results.

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

    Returns:
        A list of character results.

    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._search(
        resource=ComicvineResource.CHARACTER, query=query, max_results=max_results
    )

def search_concepts(self, query: str, max_results: int | None = 500) -> list[BasicConcept]:
    """Request a list of search results.

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

    Returns:
        A list of concept results.

    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._search(
        resource=ComicvineResource.CONCEPT, query=query, max_results=max_results
    )

def search_creators(self, query: str, max_results: int | None = 500) -> list[BasicCreator]:
    """Request a list of search results.

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

    Returns:
        A list of creator results.

    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._search(
        resource=ComicvineResource.CREATOR, query=query, max_results=max_results
    )

def search_issues(self, query: str, max_results: int | None = 500) -> list[BasicIssue]:
    """Request a list of search results.

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

    Returns:
        A list of issue results.

    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._search(resource=ComicvineResource.ISSUE, query=query, max_results=max_results)

def search_items(self, query: str, max_results: int | None = 500) -> list[BasicItem]:
    """Request a list of search results.

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

    Returns:
        A list of item results.

    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._search(resource=ComicvineResource.ITEM, query=query, max_results=max_results)

def search_locations(self, query: str, max_results: int | None = 500) -> list[BasicLocation]:
    """Request a list of search results.

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

    Returns:
        A list of location results.

    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._search(
        resource=ComicvineResource.LOCATION, query=query, max_results=max_results
    )

def search_origins(self, query: str, max_results: int | None = 500) -> list[BasicOrigin]:
    """Request a list of search results.

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

    Returns:
        A list of origin results.

    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._search(resource=ComicvineResource.ORIGIN, query=query, max_results=max_results)

def search_powers(self, query: str, max_results: int | None = 500) -> list[BasicPower]:
    """Request a list of search results.

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

    Returns:
        A list of power results.

    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._search(resource=ComicvineResource.POWER, query=query, max_results=max_results)

def search_publishers(self, query: str, max_results: int | None = 500) -> list[BasicPublisher]:
    """Request a list of search results.

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

    Returns:
        A list of publisher results.

    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._search(
        resource=ComicvineResource.PUBLISHER, query=query, max_results=max_results
    )

def search_story_arcs(self, query: str, max_results: int | None = 500) -> list[BasicStoryArc]:
    """Request a list of search results.

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

    Returns:
        A list of story arc results.

    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._search(
        resource=ComicvineResource.STORY_ARC, query=query, max_results=max_results
    )

def search_teams(self, query: str, max_results: int | None = 500) -> list[BasicTeam]:
    """Request a list of search results.

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

    Returns:
        A list of team results.

    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._search(resource=ComicvineResource.TEAM, query=query, max_results=max_results)

def search_volumes(self, query: str, max_results: int | None = 500) -> list[BasicVolume]:
    """Request a list of search results.

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

    Returns:
        A list of volume results.

    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._search(resource=ComicvineResource.VOLUME, query=query, max_results=max_results)