Skip to main content

Comicbox

A comic book archive metadata reader and writer.

✨ Features

📚Comic Formats

Comicbox reads CBZ, CBR, CBT, and optionally PDF. Comicbox archives and writes CBZ archives and PDF metadata.

🏷️ Metadata Formats

Comicbox reads and writes:

Usefulness

Comicbox's primary purpose is a library for use by Codex comic reader. The API isn't well documented, but you can infer what it does pretty easily here: comicbox.comic_archive as the primary interface.

The command line is increasingly useful and can read and write metadata recursively and extract pages.

Limitations and Alternatives

Comicbox does not use popular metadata database APIs or have a GUI!

Comictagger is a popular alternative. It does most of what Comicbox does but also automatically tags comics with the ComicVine API and has a desktop UI.

📦 Installation

pip install comicbox

Comicbox supports PDFs as an extra when installed like:

pip install comicbox[pdf]

Dependencies

Comicbox generally works without any binary dependencies but requires unrar be on the path to convert CBR into CBZ or extract files from CBRs.

⌨️ Usage

Console

Type

comicbox -h

see the CLI help.

Examples

comicbox test.cbz -m "{Tags: a,b,c, story_arcs: {d:1,e:'',f:3}" -m "Publisher: SmallComics" -w cr

Will write those tags to comicinfo.xml in the archive.

Be sure to add spaces after colons so they are detected as valid YAML key value pairs. This is easy to forget.

But it's probably better to use the --print action to see what it's going to do before you actually write to the archive:

comicbox test.cbz -m "{Tags: a,b,c, story_arcs: {d:1,e:'',f:3}" -m "Publisher: SmallComics" -p

A recursive example:

comicbox --recurse -m "publisher: 'SC Comics'" -w cr ./SmallComicsComics/

Will recursively change the publisher to "SC Comics" for every comic found in under the SmallComicsComics directory.

Escaping YAML

the -m command line argument accepts the YAML language for tags. Certain characters like \,:;_()$%^@ are part of the YAML language. To successful include them as data in your tags, look up "Escaping YAML" documentation online

Deleting Metadata

To delete metadata from the cli you're best off exporting the current metadata, editing the file and then re-importing it with the delete previous metadata option:

# export the current metadata
comicbox --export cix "My Overtagged Comic.cbz"
# Adjust the metadata in an editor.
nvim comicinfo.xml
# Check that importing the metadata will look how you like
comicbox --import comicinfo.xml -p "My Overtagged Comic.cbz"
# Delete all previous metadata from the comic (careful!)
comicbox --delete "My Overtagged Comic.cbz"
# Import the metadata into the file and write it.
comicbox --import comicinfo.xml --write cix "My Overtagged Comic.cbz"

Quirks

The comicbox.yaml format represents the ComicInfo.xml Web tag as an identifiers.url tag. Fear not, you don't have to remember this. The CLI accepts heterogeneous tag types with the -m option, so you can type:

comicbox -p -m "Web: https://foo.com" mycomic.cbz

and the identifier tag should appear in comicbox.yaml as:

identifiers:
  nss: foo.com
  url: https://foo.com

Packages

Comicbox actually installs three different packages:

  • comicbox The main API and CLI script.
  • comicfn2dict A separate library for parsing comic filenames into dicts it also includes a CLI script.
  • pdffile A utility library for reading and writing PDF files with an API like Python's ZipFile

⚙️ Config

comicbox accepts command line arguments but also an optional config file and environment variables.

The variables have defaults specified in a default yaml

The environment variables are the variable name prefixed with COMICBOX_. (e.g. COMICBOX_COMICINFOXML=0)

Log Level

change logging level:

LOGLEVEL=ERROR comicbox -p <path>

🛠 Development

You may access most development tasks from the makefile. Run make to see documentation.

🤔 Motivation

I didn't like Comictagger's API, so I built this for myself as an educational exercise and to use as a library for Codex comic reader.

📋 Schemas

Comicbox supports reading and writing several comic book metadata schemas.

Filename Schema

Comicbox includes a pretty good comic archive filename parser. It can extract a number of common fields from comic archive filenames.

Location Name
Archive The archive filename
Import/Export comicbox-filename.txt

PDF Schema

The pdf metadata standard. Can be exported as an xml file or written directly to the pdf itself.

Adobe PDF Namespace Adobe PDF Standard § 14.3.3 Document Information Dictionary

PDF metadata is only read or written from and to PDF files.

Location Name
Archive PDF internal
Import/Export pdf-metadata.xml

Reading Embedded Metadata from keywords

Comicbox will read most any metadata standard it supports from the keywords field. If that fails it will consider the keywords field as a comma delimited "Tags" field.

Writing ComicInfo.xml to keywords

By default Comicbox will write ComicInfo XML to the keywords field (e.g. -w pdf)

Codex supports this because it uses Comicbox. Other comic readers do not support PDF embedded ComicInfo.xml, but since they already have ComicInfo.xml parsers it's possible that they might someday.

If Comicbox JSON is included in the write formats (e.g. -w pdf,json) Comicbox will write comicbox.json to the keywords field instead. It is unlikely that any other comic reader other than Codex will ever support this.

CoMet Schema

An old and uncommon comic metadata standard from a defunct comic book reader.

CoMet Specification

Location Name
Archive comet.xml
Import/Export comet.xml

ComicBookInfo Schema (Comic Book Lover)

The Comic Book Lover schema. A rare but still encountered JSON schema. It probably survives because Comictagger supports writing it.

ComicBookInfo

Location Name
Archive Zip & Rar Comments
Import/Export comic-book-info.json

ComicInfo Schema (Comic Rack)

The Comic Rack schema. The de facto standard of comic book metadata. The Comic Rack reader is defunct, but the Anansi Project now publishes the ComicInfo spec and has compatibly and conservatively extended it.

Anansi ComicInfo v2.1 Spec Also, an unofficial, undocumented Mylar extension to ComicInfo.xml that encodes multiple Story Arcs and Story Arc Numbers as CSV values.

Location Name
Archive comicinfo.xml
Import/Export comicinfo.xml

ComicTagger Schema

The most useful comic book metadata writer is ComicTagger. It supports the ComicVine API, is extensible to other APIs, and features a nice desktop GUI. Internally, Comictagger keeps a metadata object to work with the schemas it supports. This schema allows the import and export of that schema.

Comictaggger genericmetadata.py

This schema may only be useful to developers. The author of ComicTagger offers no promises as to the stability of this API and I am very lazy, so the chances of this drifting out of date are anyone's guess. It was included because it was easy to do.

Location Name
Archive comictagger.json
Import/Export comictagger.json

Comicbox Schema

The comicbox internal data structure which acts as a superset of the above schemas to allow interpolating.

Comicbox JSON Schema

JSON Format

Location Name
Archive comicbox.json
Import/Export comicbox.json

YAML Format

YAML is a superset of JSON, so the JSON schema applies here.

Location Name
Archive comicbox.yaml
Import/Export comicbox.yaml

CLI Format

The Comicbox CLI uses "flow style" YAML, which is an all on one line format to enter metadata on the command line.

Specifying metadata on the command line like this is additive.

Location Name
Comicbox CLI -m --metadata
Archive comicbox-cli.yaml
Import/Export comicbox-cli.yaml

Environment variables

There is a special environment variable DEBUG_TRANSFORM that will print verbose schema transform information

Metadata

Release files for comicbox 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for comicbox 1.2.0
File Size Uploaded Provenance Actions
comicbox-1.2.0.tar.gz 81.3 MB Without provenance Details for comicbox-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for comicbox 1.2.0
File Interpreter ABI Platform Actions
comicbox-1.2.0-py3-none-any.whl Python 3 none any Details for comicbox-1.2.0-py3-none-any.whl

Total release size: 81.4 MB

Release files / comicbox-1.2.0.tar.gz

Download URL comicbox-1.2.0.tar.gz
Size 81.3 MB
Tags Source
SHA-256 checksum
How to use checksums
c4669222aa9385db1f14938455b758dad649243603f5b99bbdd62989c7b8c9c9
BLAKE2b-256 checksum
How to use checksums
ae456a5fa017dd042266c84c4b26067cc69b7db389c249b5c0d9dfebcff80186
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.3 CPython/3.12.1 Linux/5.15.0-1057-aws

Release files / comicbox-1.2.0-py3-none-any.whl

Download URL comicbox-1.2.0-py3-none-any.whl
Size 104.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
52c7ee767666581095c0071039fdb2dcf8400329c5a2a60b6a3e03718da9a45e
BLAKE2b-256 checksum
How to use checksums
0a7be2dd0e38f2eb8b4f547800c4d5fc5248539132a56ad0a1188b163c8f9519
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.3 CPython/3.12.1 Linux/5.15.0-1057-aws

Security for comicbox 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page