# CBZ CBZ is a Python library designed for creating, manipulating, and viewing comic book files in CBZ, CBR, and PDF formats. It offers a straightforward interface to pack comic pages into CBZ archives, extract metadata from CBZ and CBR files, and display comics using a built-in player. ## Features - 🚀 Seamless Installation via [pip](#installation) - 📚 Pack images into CBZ format for comics and manga - 📝 Extract and manage title, series, format, and more - 🖼️ Handle comic pages with attributes like type and format - 📦 Unpack CBZ and CBR files to retrieve comic information, or extract images from PDF files - 🛠️ Built-in player for viewing CBZ, CBR, and PDF comics - 📚 Full CBR (RAR) format support for reading existing archives - ❤️ Fully Open-Source! Pull Requests Welcome ## Installation Install CBZ from PyPI using pip: ```shell pip install cbz ``` ## Quick Start Here's a quick example of how to create a CBZ file from a series of images: ````python from pathlib import Path from cbz.comic import ComicInfo from cbz.constants import PageType, YesNo, Manga, AgeRating, Format from cbz.page import PageInfo PARENT = Path(__file__).parent if __name__ == '__main__': paths = list(Path('path/to/your/images').iterdir()) # Load each page from the 'images' folder into a list of PageInfo objects pages = [ PageInfo.load( path=path, type=PageType.FRONT_COVER if i == 0 else PageType.BACK_COVER if i == len(paths) - 1 else PageType.STORY ) for i, path in enumerate(paths) ] # Create a ComicInfo object using ComicInfo.from_pages() method comic = ComicInfo.from_pages( pages=pages, title='Your Comic Title', series='Your Comic Series', number=1, language_iso='en', format=Format.WEB_COMIC, black_white=YesNo.NO, manga=Manga.NO, age_rating=AgeRating.PENDING ) # Show the comic using the show() comic.show() # Pack the comic book content into a CBZ file format cbz_content = comic.pack() # Define the path where the CBZ file will be saved cbz_path = PARENT / 'your_comic.cbz' # Write the CBZ content to the specified path cbz_path.write_bytes(cbz_content) ```` ## Player CBZ includes a command-line player for viewing comic book files in multiple formats. Simply run `cbzplayer ` to launch the player with the specified comic book file. ### Supported Formats - **CBZ** (Comic Book ZIP) - Standard ZIP archives containing images and metadata - **CBR** (Comic Book RAR) - RAR archives containing images and metadata - **PDF** - Portable Document Format files with embedded images (images only, no metadata) ### Usage ````shell usage: cbzplayer [-h] Launch CBZ player with a comic book file positional arguments: Path to the CBZ, CBR, or PDF comic book file. options: -h, --help show this help message and exit ```` ### Examples ```shell # View a CBZ file cbzplayer my_comic.cbz # View a CBR file cbzplayer my_comic.cbr # View a PDF file cbzplayer my_comic.pdf ``` ### Requirements for CBR Support CBR file support requires: - The `rarfile` Python package (automatically installed with CBZ) - An external RAR extraction tool such as: - `unrar` (recommended) - Available in most package managers - `rar` - Commercial RAR archiver - `7zip` - Free alternative with RAR support For installation instructions and compatibility details, see the [rarfile documentation](https://github.com/markokr/rarfile). ## Detailed Usage ### Creating a ComicInfo Object The `ComicInfo` class represents a comic book with metadata and pages. It supports initialization from a list of `PageInfo` objects: ```python from cbz.comic import ComicInfo from cbz.constants import PageType, YesNo, Manga, AgeRating, Format from cbz.page import PageInfo # Example usage: pages = [ PageInfo.load(path='/path/to/page1.jpg', type=PageType.FRONT_COVER), PageInfo.load(path='/path/to/page2.jpg', type=PageType.STORY), PageInfo.load(path='/path/to/page3.jpg', type=PageType.BACK_COVER), ] comic = ComicInfo.from_pages( pages=pages, title='My Comic', series='Comic Series', number=1, language_iso='en', format=Format.WEB_COMIC, black_white=YesNo.NO, manga=Manga.NO, age_rating=AgeRating.PENDING ) ``` ### Extracting Metadata Retrieve comic information as a dictionary using `get_info()`: ```python info = comic.get_info() print(info) ``` ### Packing into CBZ Format Pack the comic into a CBZ file format: ```python cbz_content = comic.pack() ``` ### Loading from Different Formats Load a comic from an existing CBZ file (with metadata): ```python comic_from_cbz = ComicInfo.from_cbz('/path/to/your_comic.cbz') ``` Load a comic from an existing CBR file (with metadata): ```python comic_from_cbr = ComicInfo.from_cbr('/path/to/your_comic.cbr') ``` Load a comic from a PDF file (images only, no metadata): ```python comic_from_pdf = ComicInfo.from_pdf('/path/to/your_comic.pdf') ``` **Notes**: - CBR support requires an external RAR extraction tool. For detailed compatibility information and advanced configuration, see the [rarfile documentation](https://github.com/markokr/rarfile). - PDF files only provide image content; comic metadata (title, series, etc.) is not available from PDF files. ## Contributors

## Licensing This software is licensed under the terms of [MIT License](https://github.com/hyugogirubato/cbz/blob/main/LICENSE). You can find a copy of the license in the LICENSE file in the root folder. ### Third-Party Licenses This project uses the following third-party libraries: - **[langcodes](https://pypi.org/project/langcodes/)** - MIT License - **[Pillow](https://pypi.org/project/Pillow/)** - HPND License - **[pypdf](https://pypi.org/project/pypdf/)** - BSD License - **[rarfile](https://pypi.org/project/rarfile/)** - ISC License - **[xmltodict](https://pypi.org/project/xmltodict/)** - MIT License * * * © hyugogirubato 2025