Package: comicbox
ComicboxA comic book archive metadata reader and writer.✨Features📚Comic FormatsComicbox reads CBZ, CBR, CBT, and optionally PDF. Comicbox archives and writes
CBZ archives and PDF metadata.🏷️Metadata FormatsComicbox reads and writes:ComicRack ComicInfo.xml v2.1 (draft) schema,Comic Book Lover ComicBookInfo schemaCoMet schema.PDF Metadata.Embedding ComicInfo.xml inside PDFS.A variety of filename schemes that encode metadata.UsefulnessComicbox's primary purpose is a library for use byCodex comic reader. The API isn't well
documented, but you can infer what it does pretty easily here:comicbox.comic_archiveas the primary interface.The command line is increasingly useful and can read and write metadata
recursively and extract pages.Limitations and AlternativesComicbox doesnotuse popular metadata database APIs or have a GUI!Comictaggeris a popular
alternative. It does most of what Comicbox does but also automatically tags
comics with the ComicVine API and has a desktop UI.📦InstallationpipinstallcomicboxComicbox supports PDFs as an extra when installed like:pipinstallcomicbox[pdf]DependenciesComicbox generally works without any binary dependencies but requiresunrarbe
on the path to convert CBR into CBZ or extract files from CBRs.⌨️UsageConsoleTypecomicbox-hsee the CLI help.Examplescomicboxtest.cbz-m"{Tags: a,b,c, story_arcs: {d:1,e:'',f:3}"-m"Publisher: SmallComics"-wcrWill 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:comicboxtest.cbz-m"{Tags: a,b,c, story_arcs: {d:1,e:'',f:3}"-m"Publisher: SmallComics"-pA recursive example:comicbox--recurse-m"publisher: SC Comics"-wcr./SmallComicsComics/Will recursively change the publisher to "SC Comics" for every comic found in
under the SmallComicsComics directory.Deleting MetadataTo 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 metadatacomicbox--exportcix"My Overtagged Comic.cbz"# Adjust the metadata in an editor.nvimcomicinfo.xml# Check that importing the metadata will look how you likecomicbox--importcomicinfo.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--importcomicinfo.xml--writecix"My Overtagged Comic.cbz"PackagesComicbox actually installs three different packages:comicboxThe main API and CLI script.comicfn2dictA separate library for parsing comic filenames into dicts it
also includes a CLI script.pdffileA utility library for reading and writing PDF files with an API like
Python's ZipFile⚙️ Configcomicbox accepts command line arguments but also an optional config file and
environment variables.The variables have defaults specified ina default yamlThe environment variables are the variable name prefixed withCOMICBOX_. (e.g.
COMICBOX_COMICINFOXML=0)Log Levelchange logging level:LOGLEVEL=ERRORcomicbox-p<path>🛠DevelopmentYou may access most development tasks from the makefile. Run make to see
documentation.🤔MotivationI didn't like Comictagger's API, so I built this for myself as an educational
exercise and to use as a library forCodex comic reader.📋SchemasComicbox supports reading and writing several comic book metadata schemas.Filename SchemaComicbox includes a pretty good comic archive filename parser. It can extract a
number of common fields from comic archive filenames.LocationNameArchiveThe archive filenameImport/Exportcomicbox-filename.txtPDF SchemaThe pdf metadata standard. Can be exported as an xml file or written directly to
the pdf itself.Adobe PDF NamespaceAdobe PDF Standard§ 14.3.3 Document Information DictionaryPDF metadata is only read or written from and to PDF files.LocationNameArchivePDF internalImport/Exportpdf-metadata.xmlReading Embedded Metadata fromkeywordsComicbox 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 tokeywordsBy default Comicbox will write ComicInfo XML to the keywords field (e.g.-w pdf)Codexsupports 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 SchemaAn old and uncommon comic metadata standard from a defunct comic book reader.CoMet SpecificationLocationNameArchivecomet.xmlImport/Exportcomet.xmlComicBookInfo Schema (Comic Book Lover)The Comic Book Lover schema. A rare but still encountered JSON schema. It
probably survives because Comictagger supports writing it.ComicBookInfoLocationNameArchiveZip & Rar CommentsImport/Exportcomic-book-info.jsonComicInfo Schema (Comic Rack)The Comic Rack schema. The de facto standard of comic book metadata. The Comic
Rack reader is defunct, but theAnansi Projectnow publishes the ComicInfo
spec and has compatibly and conservatively extended it.Anansi ComicInfo v2.1 SpecAlso, an unofficial, undocumented Mylar extension to ComicInfo.xml that encodes
multiple Story Arcs and Story Arc Numbers as CSV values.LocationNameArchivecomicinfo.xmlImport/Exportcomicinfo.xmlComicTagger SchemaThe most useful comic book metadata writer isComicTagger. 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.pyThis 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.LocationNameArchivecomictagger.jsonImport/Exportcomictagger.jsonComicbox SchemaThe comicbox internal data structure which acts as a superset of the above
schemas to allow interpolating.Comicbox JSON SchemaJSON FormatLocationNameArchivecomicbox.jsonImport/Exportcomicbox.jsonYAML FormatYAML is a superset of JSON, so the JSON schema applies here.LocationNameArchivecomicbox.yamlImport/Exportcomicbox.yamlCLI FormatThe 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.LocationNameComicbox CLI-m --metadataArchivecomicbox-cli.yamlImport/Exportcomicbox-cli.yamlEnvironment variablesThere is a special environment variableDEBUG_TRANSFORMthat will print
verbose schema transform information