DataClasses

Validations()

A base class for data validation in dataclasses.

This class provides initialization and post-initialization hooks for validating dataclass fields.

Initialize the Validations class.

This constructor sets up the initial state for the Validations class, preparing it for use in data validation.

Functions

__post_init__() -> None

Run validation methods if declared.

The validation method can be a simple check that raises ValueError or a transformation to the field value. The validation is performed by calling a function named: validate_<field_name>(self, value, field) -> field.type.

PARAMETER	DESCRIPTION
self	The instance of the Validations class. TYPE: Validations

RETURNS	DESCRIPTION
None	None

Example

Python

validations = Validations()
validations.__post_init__()

PageType

Defines constants for different types of pages.

This class provides a set of predefined page types for categorizing pages in a publication.

ImageMetadata

Bases: TypedDict

Defines the structure of ImageMetadata using TypedDict.

This class represents the metadata associated with an image.

Price(amount: Decimal, currency: str = 'USD') dataclass

Bases: Validations

A data class representing a price with validations.

ATTRIBUTE	DESCRIPTION
amount	The amount associated with the price. TYPE: Decimal
currency	The ISO 4217 currency code, defaults to "USD". TYPE: str

Functions

validate_currency(value: str, **_: object) -> str staticmethod

Validate an ISO 4217 currency code.

If the value is None, it returns the default currency code "USD". Otherwise, it strips any leading or trailing whitespace and uppercases the value. If the value is empty after stripping, it raises a ValueError. The currency code is validated against pycountry's ISO 4217 currency database.

PARAMETER	DESCRIPTION
value	The currency code to validate. TYPE: str
**_	Additional keyword arguments (ignored). TYPE: any DEFAULT: {}

RETURNS	DESCRIPTION
str	The validated ISO 4217 currency code. TYPE: str

RAISES	DESCRIPTION
ValueError	Raised when the currency code is invalid or no value is given.

Basic(name: str, id_: int | str | None = None) dataclass

A data class representing basic information.

ATTRIBUTE	DESCRIPTION
name	The name associated with the basic information. TYPE: str
id_	The ID associated with the basic information, defaults to None. TYPE: int | None

Universe(name: str, id_: int | str | None = None, designation: str | None = None) dataclass

Bases: Basic

A data class representing a universe.

ATTRIBUTE	DESCRIPTION
name	The name associated with the basic information. TYPE: str
id_	The ID associated with the basic information, defaults to None. TYPE: int | None
designation	The designation of the universe, defaults to None. TYPE: str | None

Role(name: str, id_: int | str | None = None, primary: bool = False) dataclass

Bases: Basic

A data class representing a role.

ATTRIBUTE	DESCRIPTION
name	The name associated with the basic information. TYPE: str
id_	The ID associated with the basic information, defaults to None. TYPE: int | None
primary	Indicates if the role is primary, defaults to False. TYPE: bool

Series(name: str, id_: int | str | None = None, sort_name: str | None = None, volume: int | None = None, format: str | None = None, start_year: int | None = None, issue_count: int | None = None, volume_count: int | None = None, alternative_names: list[AlternativeNames] = list(), language: str | None = None) dataclass

Bases: Basic, Validations

A data class representing a series with basic information and validations.

ATTRIBUTE	DESCRIPTION
name	The name associated with the basic information. TYPE: str
id_	The ID associated with the basic information, defaults to None. TYPE: int | None
sort_name	The sort name of the series, defaults to None. TYPE: str | None
volume	The volume of the series, defaults to None. TYPE: int | None
format	The format of the series, defaults to None. TYPE: str | None
start_year	The year that the series started in. A 4 digit value. TYPE: int | None
issue_count	The count of issues. TYPE: Optional[int]
volume_count	The count of volumes. TYPE: int | None
alternative_names	list[AlternativeNames]: A list of alternative names for series. TYPE: list[AlternativeNames]
language	The 2-letter ISO code of the language, defaults to None. TYPE: str | None

Static Methods

validate_language(value: str, **_: any) -> str | None: Validates a language value.

Functions

validate_language(value: str, **_: any) -> str | None staticmethod

Validate a language value.

If the value is empty, it returns None. Otherwise, it strips any leading or trailing whitespace from the value. If the length of the value is 2, it tries to find the language object using the alpha-2 code. Otherwise, it tries to look up the language object using the value. If the language object is not found, it raises a ValueError.

PARAMETER	DESCRIPTION
value	The language value to validate. TYPE: str
**_	Additional keyword arguments (ignored). TYPE: any DEFAULT: {}

RETURNS	DESCRIPTION
str | None	Optional[str]: The validated language code, or None if the value is empty.

RAISES	DESCRIPTION
ValueError	Raised when the language object cannot be found.

validate_start_year(value: int, **_: any) -> int | None staticmethod

Validate a start year value.

This method checks if the provided value is a valid four-digit year. If the value is not present, it returns None. If the value is not exactly four digits, it raises a ValueError.

PARAMETER	DESCRIPTION
value	The year value to validate. TYPE: int
**_	Additional keyword arguments (ignored). TYPE: any DEFAULT: {}

RETURNS	DESCRIPTION
int | None	Optional[int]: The validated year value, or None if the value is not present.

RAISES	DESCRIPTION
ValueError	Raised when the year is not exactly four digits.

Arc(name: str, id_: int | str | None = None, number: int | None = None) dataclass

Bases: Basic

A data class representing an arc with basic information.

ATTRIBUTE	DESCRIPTION
name	The name associated with the basic information. TYPE: str
id_	The ID associated with the basic information, defaults to None. TYPE: int | None
number	The number of the arc, defaults to None. TYPE: int | None

Credit(person: str, role: list[Role], id_: int | None = None) dataclass

A data class representing a creator credit.

ATTRIBUTE	DESCRIPTION
person	The name of the person associated with the credit. TYPE: str
role	The list of roles associated with the credit. TYPE: list[Role]
id_	The ID associated with the credit, defaults to None. TYPE: int | None

GTIN(upc: int | None = None, isbn: int | None = None) dataclass

Bases: Validations

A data class representing a GTIN (Global Trade Item Number) with validations.

ATTRIBUTE	DESCRIPTION
upc	The UPC (Universal Product Code) associated with the GTIN, defaults to None. TYPE: int | None
isbn	The ISBN (International Standard Book Number) associated with the GTIN, defaults to None. TYPE: int | None

Static Methods

validate_upc(value: int, _: any) -> int | None: Validates a UPC (Universal Product Code) value. validate_isbn(value: int, _: any) -> int | None: Validates an ISBN (International Standard Book Number) value.

Functions

validate_isbn(value: int, **_: any) -> int | None staticmethod

Validate an ISBN (International Standard Book Number) value.

If the value is None or not an instance of int, it returns None. Otherwise, it checks if the length of the ISBN value is greater than the maximum allowed length. If it is, it raises a ValueError.

PARAMETER	DESCRIPTION
value	The ISBN value to validate. TYPE: int
**_	Additional keyword arguments (ignored). TYPE: any DEFAULT: {}

RETURNS	DESCRIPTION
int | None	Optional[int]: The validated ISBN value, or None if the value is None or not an instance of int.

validate_upc(value: int, **_: any) -> int | None staticmethod

Validate a UPC (Universal Product Code) value.

If the value is None or not an instance of int, it returns None. Otherwise, it checks if the length of the UPC value is greater than the maximum allowed length. If it is, it raises a ValueError.

PARAMETER	DESCRIPTION
value	The UPC value to validate. TYPE: int
**_	Additional keyword arguments (ignored). TYPE: any DEFAULT: {}

RETURNS	DESCRIPTION
int | None	Optional[int]: The validated UPC value, or None if the value is None or not an instance of int.

Metadata(is_empty: bool = True, info_source: list[InfoSources] | None = None, series: Series | None = None, issue: str | None = None, collection_title: str | None = None, stories: list[Basic] = list(), publisher: Publisher | None = None, cover_date: date | None = None, store_date: date | None = None, prices: list[Price] = list(), gtin: GTIN | None = None, genres: list[Basic] = list(), comments: str | None = None, community_rating: Decimal | None = None, main_character_or_team: str | None = None, review: str | None = None, alternate_series: str | None = None, alternate_number: str | None = None, alternate_count: int | None = None, notes: Notes | None = None, web_link: list[Links] | None = None, manga: str | None = None, black_and_white: bool | None = None, page_count: int | None = None, age_rating: AgeRatings | None = None, story_arcs: list[Arc] = list(), series_group: str | None = None, scan_info: str | None = None, characters: list[Basic] = list(), teams: list[Basic] = list(), locations: list[Basic] = list(), universes: list[Universe] = list(), credits: list[Credit] = list(), reprints: list[Basic] = list(), tags: list[Basic] = list(), pages: list[ImageMetadata] = list(), modified: datetime | None = None) dataclass

Represents metadata for a comic.

ATTRIBUTE	DESCRIPTION
is_empty	Indicates if the metadata is empty. TYPE: bool
info_source	The information source. TYPE: Optional[list[InfoSources]]
series	The series information. TYPE: Optional[Series]
issue	The issue number. TYPE: Optional[str]
collection_title	The title of the collection. TYPE: Optional[str]
stories	The list of stories. TYPE: list[Basic]
publisher	The publisher information. TYPE: Optional[Publisher]
cover_date	The cover date. TYPE: Optional[date]
store_date	The store date. TYPE: Optional[date]
prices	The list of prices. TYPE: list[Price]
gtin	The GTIN (Global Trade Item Number). TYPE: Optional[GTIN]
genres	The list of genres. TYPE: list[Basic]
comments	The comments. TYPE: Optional[str]
community_rating	The community rating (0-5, up to 2 decimal places). TYPE: Optional[Decimal]
alternate_series	The alternate series. TYPE: Optional[str]
alternate_number	The alternate number. TYPE: Optional[str]
alternate_count	The count of alternates. TYPE: Optional[int]
notes	The notes. TYPE: Optional[Notes]
web_link	The web link. TYPE: Optional[list[Links]]
manga	The manga information. TYPE: Optional[str]
black_and_white	Indicates if the comic is black and white. TYPE: Optional[bool]
page_count	The count of pages. TYPE: Optional[int]
age_rating	The age rating. TYPE: Optional[AgeRatings]
story_arcs	The list of story arcs. TYPE: list[Arc]
series_group	The series group. TYPE: Optional[str]
scan_info	The scan information. TYPE: Optional[str]
characters	The list of characters. TYPE: list[Basic]
teams	The list of teams. TYPE: list[Basic]
locations	The list of locations. TYPE: list[Basic]
credits	The list of credits. TYPE: list[Credit]
reprints	The list of reprints. TYPE: list[Basic]
tags	The list of tags. TYPE: list[Basic]
pages	The list of pages. TYPE: list[ImageMetadata]

METHOD	DESCRIPTION
__post_init__	Initializes the metadata object.
overlay	Overlays a metadata object on this one.
overlay_credits	Overlays the credits from a new metadata object.
set_default_page_list	Sets a default page list.
get_archive_page_index	Gets the archive page index for a given displayed page number.
get_cover_page_index_list	Gets a list of archive page indices of cover pages.
_existing_credit	Checks if a credit with the given creator already exists.
_role_exists	Checks if a role already exists in the old roles list.
add_credit	Adds a new credit to the metadata.
__str__	Returns a string representation of the metadata.

Example

Python

metadata = Metadata(is_empty=True)
metadata.overlay(new_md)
print(metadata)

Functions

__post_init__() -> None

Execute the post-initialization process for a Metadata instance.

The method iterates over the attributes of the Metadata object and checks if any attribute has a non-empty value, excluding the "is_empty" attribute. If a non-empty value is found, the "is_empty" attribute is set to False and the iteration is stopped.

PARAMETER	DESCRIPTION
self	The Metadata instance. TYPE: Metadata

RETURNS	DESCRIPTION
None	None

Example

Python

metadata = Metadata()
metadata.__post_init__()
print(metadata.is_empty)  # Output: False

__str__() -> str

Returns a formatted string representation of the Metadata object.

This improved version provides a more readable and organized display of the metadata, grouping related fields and handling different data types appropriately.

add_credit(new_credit: Credit) -> None

Add a new credit to the Metadata.

If a credit with the same person already exists, the roles from the new credit are added to the existing credit. If the person is new, the new credit is appended to the list of credits.

PARAMETER	DESCRIPTION
new_credit	The new credit to add to the Metadata. TYPE: Credit

RETURNS	DESCRIPTION
None	None

get_archive_page_index(pagenum: int) -> int

Convert the displayed page number to the page index of the file in the archive.

The method takes a displayed page number and returns the corresponding page index in the archive. If the displayed page number is within the range of the available pages, the "Image" attribute of the corresponding page in the "pages" attribute of the Metadata object is returned as an integer. If the displayed page number is out of range, 0 is returned.

PARAMETER	DESCRIPTION
self	The Metadata object. TYPE: Metadata
pagenum	The displayed page number. TYPE: int

RETURNS	DESCRIPTION
int	The page index in the archive. TYPE: int

Example

Python

metadata = Metadata()
metadata.pages = [ImageMetadata(Image=0), ImageMetadata(Image=1), ImageMetadata(Image=2)]
index = metadata.get_archive_page_index(1)
print(index)  # Output: 1

get_cover_page_index_list() -> list[int]

Return a list of archive page indices of cover pages.

The method iterates over the pages in the Metadata object and checks if a page is marked as a front cover by having a "Type" attribute equal to PageType.FrontCover. If a front cover page is found, its "Image" attribute is added to the coverlist. If no front cover pages are found, the coverlist is initialized with a single element of 0.

RETURNS	DESCRIPTION
list[int]	list[int]: The list of archive page indices of cover pages.

Example

Python

metadata = Metadata()
metadata.pages = [ImageMetadata(Image=0, Type=PageType.FrontCover),ImageMetadata(Image=1), ImageMetadata(Image=2)]
cover_indices = metadata.get_cover_page_index_list()
print(cover_indices)  # Output: [0]

overlay(new_md: Metadata) -> None

Overlays a metadata object on this one.

The method assigns non-None values from the new metadata object to the corresponding attributes of the current metadata object. If a value is an empty string, it is assigned as None. The "is_empty" attribute of the current metadata object is set to False if the new metadata object is not empty.

PARAMETER	DESCRIPTION
self	The current metadata object. TYPE: Metadata
new_md	The new metadata object to overlay. TYPE: Metadata

RETURNS	DESCRIPTION
None	None

Example

Python

metadata = Metadata()
new_metadata = Metadata(series="Series 1", issue="Issue 1")
metadata.overlay(new_metadata)
print(metadata.series)  # Output: "Series 1"
print(metadata.issue)  # Output: "Issue 1"

overlay_credits(new_credits: list[Credit]) -> None

Overlays the credits from a new metadata object on the current metadata object.

The method iterates over the new credits and removes any credit role if the person is blank. If the person is not blank, the "primary" attribute of the credit is set based on the presence of the "primary" key in the credit dictionary. The credit is then added to the current metadata object using the "add_credit" method.

PARAMETER	DESCRIPTION
self	The current metadata object. TYPE: Metadata
new_credits	The list of new credits to overlay. TYPE: list[Credit]

RETURNS	DESCRIPTION
None	None

Example

Python

metadata = Metadata()
new_credits = [Credit(person="John Doe", role="Writer")]
metadata.overlay_credits(new_credits)
print(metadata.credits)  # Output: [Credit(person="John Doe", role="Writer")]

set_default_page_list(count: int) -> None

Generate a default page list for the Metadata object.

The method creates a default page list with the specified count. Each page is represented by an ImageMetadata object with the "Image" attribute set to the corresponding index. The first page is marked as the front cover by setting the "Type" attribute to PageType.FrontCover. The generated page list is appended to the "pages" attribute of the Metadata object.

PARAMETER	DESCRIPTION
self	The Metadata object. TYPE: Metadata
count	The count of pages to generate. TYPE: int

RETURNS	DESCRIPTION
None	None

Example

Python

metadata = Metadata()
metadata.set_default_page_list(5)
print(metadata.pages)
# Output: [ImageMetadata(Image=0, Type=PageType.FrontCover),
# ImageMetadata(Image=1), ImageMetadata(Image=2), ImageMetadata(Image=3),
# ImageMetadata(Image=4)]

validate_community_rating(value: Decimal | None) -> Decimal | None staticmethod

Validate and normalise a community rating value.

Checks that the value is in the range 0-5 (inclusive) and rounds it to 2 decimal places, matching the Rating type defined in ComicInfo v2.

PARAMETER	DESCRIPTION
value	The rating value to validate, or None. TYPE: Decimal | None

RETURNS	DESCRIPTION
Decimal | None	The validated value quantised to 2 decimal places, or None.

RAISES	DESCRIPTION
ValueError	If the value is outside the range 0-5.