darkseid package¶

Submodules¶

darkseid.comic module¶

A class to represent a single comic.

class darkseid.comic.Comic(path: str)¶

Bases: object

Comic implementation.

class ArchiveType¶

Bases: object

Types of archives supported. Currently .cbr and .cbz.

rar = 1¶

unknown = 2¶

zip = 0¶

apply_archive_info_to_metadata(metadata: Metadata, calc_page_sizes: bool = False) → None¶: Apply page information from the archive to the metadata.

export_as_zip(zipfilename: Path) → bool¶: Export CBR archives to CBZ format.

get_number_of_pages() → int¶: Returns the number of pages in an archive.

get_page(index: int) → bytes | None¶: Returns an image(page) from an archive.

get_page_name(index: int) → str | None¶: Returns the page name from an index.

get_page_name_list(sort_list: bool = True) → list[str]¶: Returns a list of page names from an archive.

has_metadata() → bool¶: Checks to see if the archive has metadata.

static is_image(name_path: Path) → bool¶

is_rar() → bool¶: Returns a boolean whether an archive is a rarfile.

is_writable() → bool¶: Returns a boolean whether an archive is writable.

is_zip() → bool¶: Returns a boolean whether an archive is a zipfile.

metadata_from_filename(parse_scan_info: bool = True) → Metadata¶: Attempts to get the metadata from the filename.

rar_test() → bool¶: Test whether an archive is a rar file.

read_metadata() → Metadata¶: Reads the metadata from an archive if present.

read_raw_metadata() → str | None¶

remove_metadata() → bool¶: Remove the metadata from the archive if present.

remove_pages(pages_index: list[int]) → bool¶: Remove page from the archive.

reset_cache() → None¶: Clears the cached data.

seems_to_be_a_comic_archive() → bool¶: Returns a boolean whether the file is a comic archive.

write_metadata(metadata: darkseid.metadata.Metadata | None) → bool¶: Write the metadata to the archive.

zip_test() → bool¶: Tests whether an archive is a zipfile.

darkseid.comicinfo module¶

A class to encapsulate ComicRack’s ComicInfo.xml data.

class darkseid.comicinfo.ComicInfo¶

Bases: object

ci_age_ratings: ClassVar[set[str]] = {'Adults Only 18+', 'Early Childhood', 'Everyone', 'Everyone 10+', 'G', 'Kids to Adults', 'M', 'MA15+', 'Mature 17+', 'PG', 'R18+', 'Rating Pending', 'Teen', 'Unknown', 'X18+'}¶

ci_manga: ClassVar[set[str]] = {'No', 'Unknown', 'Yes', 'YesAndRightToLeft'}¶

colorist_synonyms: ClassVar[set[str]] = {'color assists', 'color flats', 'colorer', 'colorist', 'colourer', 'colourist'}¶

convert_metadata_to_xml(md: Metadata, xml: bytes = b'') → ElementTree¶

convert_xml_to_metadata(tree: ElementTree) → Metadata¶

cover_synonyms: ClassVar[set[str]] = {'cover', 'cover artist', 'coverartist', 'covers'}¶

editor_synonyms: ClassVar[set[str]] = {'assistant editor', 'associate editor', 'consulting editor', 'editor', 'editor in chief', 'executive editor', 'group editor', 'senior editor', 'supervising editor'}¶

inker_synonyms: ClassVar[set[str]] = {'artist', 'embellisher', 'finishes', 'illustrator', 'ink assists', 'inker'}¶

letterer_synonyms: ClassVar[set[str]] = {'letterer'}¶

metadata_from_string(string: str) → Metadata¶

penciller_synonyms: ClassVar[set[str]] = {'artist', 'breakdowns', 'illustrator', 'layouts', 'penciler', 'penciller'}¶

read_from_external_file(filename: str) → Metadata¶

string_from_metadata(md: Metadata, xml: bytes = b'') → str¶

classmethod validate_age_rating(val: str | None = None) → str | None¶

classmethod validate_manga(val: str | None = None) → str | None¶

write_to_external_file(filename: str, md: Metadata, xml: bytes = b'') → None¶

writer_synonyms: ClassVar[set[str]] = {'plot', 'plotter', 'script', 'scripter', 'story', 'writer'}¶

darkseid.exceptions module¶

Exceptions module.

This module provides the following classes:

RarError

exception darkseid.exceptions.RarError¶

Bases: Exception

Class for a Rar error.

darkseid.filename module¶

Functions for parsing comic info from filename.

This should probably be re-written, but, well, it mostly works!

class darkseid.filename.FileNameParser¶

Bases: object

Class to get parse the filename to get information about the comic.

fix_spaces(string: str, remove_dashes: bool = True) → str¶: Returns a string with the spaces fixed.

get_issue_count(filename: str, issue_end: int) → str¶: Returns a string with the issue count.

get_issue_number(filename: str) → tuple[str, int, int]¶: Returns a tuple of issue number string, and start and end indexes in the filename (The indexes will be used to split the string up for further parsing).

get_remainder(filename: str, year: str, count: str, volume: str, issue_end: int) → str¶: Make a guess at where the non-interesting stuff begins.

get_series_name(filename: str, issue_start: int) → tuple[str, str]¶: Use the issue number string index to split the filename string.

static get_year(filename: str, issue_end: int) → str¶: Return the year from the filename.

parse_filename(comic: Path) → None¶: Method to parse the filename.

static repl(match: str) → str¶

darkseid.issue_string module¶

Support for mixed digit/string type Issue field.

Class for handling the odd permutations of an ‘issue number’ that the comics industry throws at us. e.g.: “12”, “12.1”, “0”, “-1”, “5AU”, “100-2”

class darkseid.issue_string.IssueString(text: str)¶

Bases: object

Class to handle various types of comic issue numbers.

Parameters: text (str) – The issue number.

as_float() → float | None¶

Return a float with no suffix.

example: “1½” is returned as “1.5”

Returns: String as a float.
Return type: float, optional

as_int() → int | None¶

Returns the integer version of the float.

Returns: String as an integer.
Return type: int, optional

as_string(pad: int = 0) → str¶

Returns a string with left-side zero padding.

Parameters: pad (int) – The number of left-side zeroes to pad with.
Returns: String with zero padding.
Return type: str

darkseid.metadata module¶

A class for internal metadata storage.

The goal of this class is to handle ALL the data that might come from various tagging schemes and databases, such as Metron, ComicVine or GCD. This makes conversion possible, however lossy it might be

class darkseid.metadata.Arc(name: str, id_: int | None = None, number: int | None = None)¶

Bases: Basic

number: int | None = None¶

class darkseid.metadata.Basic(name: str, id_: int | None = None)¶

Bases: object

id_: int | None = None¶

name: str¶

class darkseid.metadata.Credit(person: str, role: list[darkseid.metadata.Role], id_: int | None = None)¶

Bases: object

id_: int | None = None¶

person: str¶

role: list[darkseid.metadata.Role]¶

class darkseid.metadata.GTIN(upc: int | None = None, isbn: int | None = None)¶

Bases: Validations

isbn: int | None = None¶

upc: int | None = None¶

static validate_isbn(value: int, **_: any) → int | None¶

Validates 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.

Parameters

value (int) – The ISBN value to validate.
**_ (any) – Additional keyword arguments (ignored).

Returns

The validated ISBN value, or None if the value is None or not an instance of int.

Return type

Optional[int]

Raises

ValueError – Raised when the length of the ISBN value is greater than the maximum
allowed length. –

Example

`python isbn = 1234567890 validated_isbn = Validations.validate_isbn(isbn) print(validated_isbn) # Output: 1234567890 `

static validate_upc(value: int, **_: any) → int | None¶

Validates 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.

Parameters

value (int) – The UPC value to validate.
**_ (any) – Additional keyword arguments (ignored).

Returns

The validated UPC value, or None if the value is None or not an instance of int.

Return type

Optional[int]

Raises

ValueError – Raised when the length of the UPC value is greater than the maximum
allowed length. –

Example

`python upc = 1234567890 validated_upc = Validations.validate_upc(upc) print(validated_upc) # Output: 1234567890 `

class darkseid.metadata.ImageMetadata¶

Bases: TypedDict

Bookmark: str¶

DoublePage: bool¶

Image: int¶

ImageHeight: str¶

ImageSize: str¶

ImageWidth: str¶

Type: str¶

class darkseid.metadata.Metadata(is_empty: bool = True, tag_origin: str | None = None, info_source: darkseid.metadata.Basic | None = None, series: darkseid.metadata.Series | None = None, issue: str | None = None, collection_title: str | None = None, stories: list[darkseid.metadata.Basic] = <factory>, publisher: darkseid.metadata.Basic | None = None, cover_date: datetime.date | None = None, store_date: datetime.date | None = None, prices: list[darkseid.metadata.Price] = <factory>, gtin: darkseid.metadata.GTIN | None = None, issue_count: int | None = None, genres: list[darkseid.metadata.Basic] = <factory>, comments: str | None = None, volume_count: str | None = None, critical_rating: str | None = None, country: str | None = None, alternate_series: str | None = None, alternate_number: str | None = None, alternate_count: int | None = None, imprint: str | None = None, notes: str | None = None, web_link: str | None = None, manga: str | None = None, black_and_white: bool | None = None, page_count: int | None = None, age_rating: str | None = None, story_arcs: list[darkseid.metadata.Arc] = <factory>, series_group: str | None = None, scan_info: str | None = None, characters: list[darkseid.metadata.Basic] = <factory>, teams: list[darkseid.metadata.Basic] = <factory>, locations: list[darkseid.metadata.Basic] = <factory>, credits: list[darkseid.metadata.Credit] = <factory>, reprints: list[darkseid.metadata.Basic] = <factory>, tags: list[darkseid.metadata.Basic] = <factory>, pages: list[darkseid.metadata.ImageMetadata] = <factory>)¶

Bases: object

Represents metadata for a comic.

is_empty¶

Indicates if the metadata is empty.

Type: bool

tag_origin¶

The origin of the tag.

Type: Optional[str]

info_source¶

The information source.

Type: Optional[Basic]

series¶

The series information.

Type: Optional[Series]

issue¶

The issue information.

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[Basic]

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]

issue_count¶

The count of issues.

Type: Optional[int]

genres¶

The list of genres.

Type: list[Basic]

comments¶

The comments.

Type: Optional[str]

volume_count¶

The count of volumes.

Type: Optional[str]

critical_rating¶

The critical rating.

Type: Optional[str]

country¶

The country.

Type: Optional[str]

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]

imprint¶

The imprint.

Type: Optional[str]

notes¶

The notes.

Type: Optional[str]

web_link¶

The web link.

Type: Optional[str]

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[str]

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]

__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) `

add_credit(new_credit: Credit) → None¶

age_rating: str | None = None¶

alternate_count: int | None = None¶

alternate_number: str | None = None¶

alternate_series: str | None = None¶

black_and_white: bool | None = None¶

characters: list[darkseid.metadata.Basic]¶

collection_title: str | None = None¶

comments: str | None = None¶

country: str | None = None¶

cover_date: datetime.date | None = None¶

credits: list[darkseid.metadata.Credit]¶

critical_rating: str | None = None¶

genres: list[darkseid.metadata.Basic]¶

get_archive_page_index(pagenum: int) → int¶

Converts 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.

Parameters

self (Metadata) – The Metadata object.
pagenum (int) – The displayed page number.

Returns

The page index in the archive.

Return 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]¶

Returns 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: The list of archive page indices of cover pages.
Return type: list[int]

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] `

gtin: darkseid.metadata.GTIN | None = None¶

imprint: str | None = None¶

info_source: darkseid.metadata.Basic | None = None¶

is_empty: bool = True¶

issue: str | None = None¶

issue_count: int | None = None¶

locations: list[darkseid.metadata.Basic]¶

manga: str | None = None¶

notes: str | None = None¶

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.

Parameters

self (Metadata) – The current metadata object.
new_md (Metadata) – The new metadata object to overlay.

Returns

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[darkseid.metadata.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.

Parameters

self (Metadata) – The current metadata object.
new_credits (list[Credit]) – The list of new credits to overlay.

Returns

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")] `

page_count: int | None = None¶

pages: list[darkseid.metadata.ImageMetadata]¶

prices: list[darkseid.metadata.Price]¶

publisher: darkseid.metadata.Basic | None = None¶

reprints: list[darkseid.metadata.Basic]¶

scan_info: str | None = None¶

series: darkseid.metadata.Series | None = None¶

series_group: str | None = None¶

set_default_page_list(count: int) → None¶

Generates 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.

Parameters

self (Metadata) – The Metadata object.
count (int) – The count of pages to generate.

Returns

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)] `

store_date: datetime.date | None = None¶

stories: list[darkseid.metadata.Basic]¶

story_arcs: list[darkseid.metadata.Arc]¶

tag_origin: str | None = None¶

tags: list[darkseid.metadata.Basic]¶

teams: list[darkseid.metadata.Basic]¶

volume_count: str | None = None¶

web_link: str | None = None¶

class darkseid.metadata.PageType¶

Bases: object

These page info classes are exactly the same as the CIX scheme, since it’s unique.

Advertisement = 'Advertisement'¶

BackCover = 'BackCover'¶

Deleted = 'Deleted'¶

Editorial = 'Editorial'¶

FrontCover = 'FrontCover'¶

InnerCover = 'InnerCover'¶

Letters = 'Letters'¶

Other = 'Other'¶

Preview = 'Preview'¶

Roundup = 'Roundup'¶

Story = 'Story'¶

class darkseid.metadata.Price(amount: decimal.Decimal, country: str = 'US')¶

Bases: Validations

amount: Decimal¶

country: str = 'US'¶

static validate_country(value: str, **_: any) → str¶

Validates a country value.

If the value is None, it returns the default country code “US”. Otherwise, it strips any leading or trailing whitespace from the value. If the value is empty after stripping, it raises a ValueError.

If the length of the value is 2, it tries to find the country object using the alpha-2 code. Otherwise, it tries to look up the country object using the value. If the country object is not found, it raises a ValueError.

Parameters

value (str) – The country value to validate.
**_ (any) – Additional keyword arguments (ignored).

Returns

The validated country code.

Return type

str

Raises

ValueError – Raised when the value is empty, or when the country object cannot be
found. –

Example

`python country = "US" validated_country = Validations.validate_country(country) print(validated_country) # Output: "US" `

class darkseid.metadata.Role(name: str, id_: int | None = None, primary: bool = False)¶

Bases: Basic

primary: bool = False¶

Bases: Basic, Validations

format: str | None = None¶

language: str | None = None¶

sort_name: str | None = None¶

static validate_language(value: str, **_: any) → str | None¶

Validates 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.

Parameters

value (str) – The language value to validate.
**_ (any) – Additional keyword arguments (ignored).

Returns

The validated language code, or None if the value is empty.

Return type

Optional[str]

Raises

ValueError – Raised when the language object cannot be found.

Example

`python language = "en" validated_language = Validations.validate_language(language) print(validated_language) # Output: "en" `

volume: int | None = None¶

class darkseid.metadata.Validations¶: Bases: object

darkseid.utils module¶

Some generic utilities.

darkseid.utils.get_recursive_filelist(pathlist: list[pathlib.Path]) → list[pathlib.Path]¶

Returns a path list of comic archives.

Parameters: pathlist (list of Path) – A list of path objects

darkseid.utils.list_to_string(list_of_strings: list[str]) → str¶

Function that takes a list of string and converts it to a string. For example: [“apple”, “banana”, “cherry”] is changed to “apple; banana; cherry”.

Parameters: list_of_strings (list of str) – A list of strings.

darkseid.utils.remove_articles(text: str) → str¶

Takes a string and removes any articles in it.

Parameters: text (str) – A string with articles (ex. ‘and’, ‘a’, ‘the’).

darkseid.utils.unique_file(file_name: Path) → Path¶

Takes a filename and if one already exist with that name, returns a new filename.

Parameters: file_name (Path) – A path objects

darkseid.utils.xlate(data: int | str | None, is_int: bool = False) → int | str | None¶

Module contents¶

Projects version.