# 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 KeyDive from PyPI using Poetry:
```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 <file>` 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] <file>
Launch CBZ player with a comic book file
positional arguments:
<file> 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
<a href="https://github.com/hyugogirubato"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/65763543?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="hyugogirubato"/></a>
<a href="https://github.com/piskunqa"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/38443069?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="piskunqa"/></a>
<a href="https://github.com/OleskiiPyskun"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/75667382?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="OleskiiPyskun"/></a>
<a href="https://github.com/tssujt"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/17313425?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="tssujt"/></a>
<a href="https://github.com/gokender"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/3709740?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="gokender"/></a>
<a href="https://github.com/domenicoblanco"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/9018104?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="domenicoblanco"/></a>
<a href="https://github.com/RivMt"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/40086827?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="RivMt"/></a>
<a href="https://github.com/flolep2607"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/24566964?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="flolep2607"/></a>
## 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
Raw data
{
"_id": null,
"home_page": "https://github.com/hyugogirubato/cbz",
"name": "cbz",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "python, cbz, cbr, pdf, ebooks, manga, comics, webtoons",
"author": "hyugogirubato",
"author_email": "65763543+hyugogirubato@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/bf/c4/acbf04baa3eb1ef0b5f1b26a659001df657b59e977a468142b91484839d9/cbz-3.4.0.tar.gz",
"platform": null,
"description": "# CBZ\n\nCBZ 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.\n\n## Features\n\n- \ud83d\ude80 Seamless Installation via [pip](#installation)\n- \ud83d\udcda Pack images into CBZ format for comics and manga\n- \ud83d\udcdd Extract and manage title, series, format, and more\n- \ud83d\uddbc\ufe0f Handle comic pages with attributes like type and format\n- \ud83d\udce6 Unpack CBZ and CBR files to retrieve comic information, or extract images from PDF files\n- \ud83d\udee0\ufe0f Built-in player for viewing CBZ, CBR, and PDF comics\n- \ud83d\udcda Full CBR (RAR) format support for reading existing archives\n- \u2764\ufe0f Fully Open-Source! Pull Requests Welcome\n\n## Installation\n\nInstall KeyDive from PyPI using Poetry:\n\n```shell\npip install cbz\n```\n\n## Quick Start\n\nHere's a quick example of how to create a CBZ file from a series of images:\n\n````python\nfrom pathlib import Path\n\nfrom cbz.comic import ComicInfo\nfrom cbz.constants import PageType, YesNo, Manga, AgeRating, Format\nfrom cbz.page import PageInfo\n\nPARENT = Path(__file__).parent\n\nif __name__ == '__main__':\n paths = list(Path('path/to/your/images').iterdir())\n\n # Load each page from the 'images' folder into a list of PageInfo objects\n pages = [\n PageInfo.load(\n path=path,\n type=PageType.FRONT_COVER if i == 0 else PageType.BACK_COVER if i == len(paths) - 1 else PageType.STORY\n )\n for i, path in enumerate(paths)\n ]\n\n # Create a ComicInfo object using ComicInfo.from_pages() method\n comic = ComicInfo.from_pages(\n pages=pages,\n title='Your Comic Title',\n series='Your Comic Series',\n number=1,\n language_iso='en',\n format=Format.WEB_COMIC,\n black_white=YesNo.NO,\n manga=Manga.NO,\n age_rating=AgeRating.PENDING\n )\n\n # Show the comic using the show()\n comic.show()\n\n # Pack the comic book content into a CBZ file format\n cbz_content = comic.pack()\n\n # Define the path where the CBZ file will be saved\n cbz_path = PARENT / 'your_comic.cbz'\n\n # Write the CBZ content to the specified path\n cbz_path.write_bytes(cbz_content)\n````\n\n## Player\n\nCBZ includes a command-line player for viewing comic book files in multiple formats. Simply run `cbzplayer <file>` to launch the player with the specified comic book file.\n\n### Supported Formats\n\n- **CBZ** (Comic Book ZIP) - Standard ZIP archives containing images and metadata\n- **CBR** (Comic Book RAR) - RAR archives containing images and metadata\n- **PDF** - Portable Document Format files with embedded images (images only, no metadata)\n\n### Usage\n\n````shell\nusage: cbzplayer [-h] <file>\n\nLaunch CBZ player with a comic book file\n\npositional arguments:\n <file> Path to the CBZ, CBR, or PDF comic book file.\n\noptions:\n -h, --help show this help message and exit\n````\n\n### Examples\n\n```shell\n# View a CBZ file\ncbzplayer my_comic.cbz\n\n# View a CBR file\ncbzplayer my_comic.cbr\n\n# View a PDF file\ncbzplayer my_comic.pdf\n```\n\n### Requirements for CBR Support\n\nCBR file support requires:\n\n- The `rarfile` Python package (automatically installed with CBZ)\n- An external RAR extraction tool such as:\n - `unrar` (recommended) - Available in most package managers\n - `rar` - Commercial RAR archiver\n - `7zip` - Free alternative with RAR support\n\nFor installation instructions and compatibility details, see the [rarfile documentation](https://github.com/markokr/rarfile).\n\n## Detailed Usage\n\n### Creating a ComicInfo Object\n\nThe `ComicInfo` class represents a comic book with metadata and pages. It supports initialization from a list of `PageInfo` objects:\n\n```python\nfrom cbz.comic import ComicInfo\nfrom cbz.constants import PageType, YesNo, Manga, AgeRating, Format\nfrom cbz.page import PageInfo\n\n# Example usage:\npages = [\n PageInfo.load(path='/path/to/page1.jpg', type=PageType.FRONT_COVER),\n PageInfo.load(path='/path/to/page2.jpg', type=PageType.STORY),\n PageInfo.load(path='/path/to/page3.jpg', type=PageType.BACK_COVER),\n]\n\ncomic = ComicInfo.from_pages(\n pages=pages,\n title='My Comic',\n series='Comic Series',\n number=1,\n language_iso='en',\n format=Format.WEB_COMIC,\n black_white=YesNo.NO,\n manga=Manga.NO,\n age_rating=AgeRating.PENDING\n)\n```\n\n### Extracting Metadata\n\nRetrieve comic information as a dictionary using `get_info()`:\n\n```python\ninfo = comic.get_info()\nprint(info)\n```\n\n### Packing into CBZ Format\n\nPack the comic into a CBZ file format:\n\n```python\ncbz_content = comic.pack()\n```\n\n### Loading from Different Formats\n\nLoad a comic from an existing CBZ file (with metadata):\n\n```python\ncomic_from_cbz = ComicInfo.from_cbz('/path/to/your_comic.cbz')\n```\n\nLoad a comic from an existing CBR file (with metadata):\n\n```python\ncomic_from_cbr = ComicInfo.from_cbr('/path/to/your_comic.cbr')\n```\n\nLoad a comic from a PDF file (images only, no metadata):\n\n```python\ncomic_from_pdf = ComicInfo.from_pdf('/path/to/your_comic.pdf')\n```\n\n**Notes**:\n\n- CBR support requires an external RAR extraction tool. For detailed compatibility information and advanced configuration, see the [rarfile documentation](https://github.com/markokr/rarfile).\n- PDF files only provide image content; comic metadata (title, series, etc.) is not available from PDF files.\n\n## Contributors\n\n<a href=\"https://github.com/hyugogirubato\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/65763543?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"hyugogirubato\"/></a>\n<a href=\"https://github.com/piskunqa\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/38443069?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"piskunqa\"/></a>\n<a href=\"https://github.com/OleskiiPyskun\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/75667382?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"OleskiiPyskun\"/></a>\n<a href=\"https://github.com/tssujt\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/17313425?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"tssujt\"/></a>\n<a href=\"https://github.com/gokender\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/3709740?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"gokender\"/></a>\n<a href=\"https://github.com/domenicoblanco\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/9018104?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"domenicoblanco\"/></a>\n<a href=\"https://github.com/RivMt\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/40086827?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"RivMt\"/></a>\n<a href=\"https://github.com/flolep2607\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/24566964?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"flolep2607\"/></a>\n\n## Licensing\n\nThis software is licensed under the terms of [MIT License](https://github.com/hyugogirubato/cbz/blob/main/LICENSE).\nYou can find a copy of the license in the LICENSE file in the root folder.\n\n### Third-Party Licenses\n\nThis project uses the following third-party libraries:\n\n- **[langcodes](https://pypi.org/project/langcodes/)** - MIT License\n- **[Pillow](https://pypi.org/project/Pillow/)** - HPND License\n- **[pypdf](https://pypi.org/project/pypdf/)** - BSD License\n- **[rarfile](https://pypi.org/project/rarfile/)** - ISC License\n- **[xmltodict](https://pypi.org/project/xmltodict/)** - MIT License\n\n* * *\n\n\u00a9 hyugogirubato 2025\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CBZ simplifies creating, managing, and viewing comic book files in CBZ, CBR, and PDF formats, offering seamless packaging, metadata handling and built-in viewing capabilities.",
"version": "3.4.0",
"project_urls": {
"Changelog": "https://github.com/hyugogirubato/cbz/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/hyugogirubato/cbz",
"Issues": "https://github.com/hyugogirubato/cbz/issues",
"Repository": "https://github.com/hyugogirubato/cbz"
},
"split_keywords": [
"python",
" cbz",
" cbr",
" pdf",
" ebooks",
" manga",
" comics",
" webtoons"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d91d2701fb306f478c483835a42c7e5c376f4a07823e97f33d096ba6f79a2deb",
"md5": "205b8b14c697c29f1f4b204190b5a45f",
"sha256": "260db01580501b7737184b31d84d15ecae4e515b526d69d7256644cca31f658f"
},
"downloads": -1,
"filename": "cbz-3.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "205b8b14c697c29f1f4b204190b5a45f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 67918,
"upload_time": "2025-07-09T21:43:12",
"upload_time_iso_8601": "2025-07-09T21:43:12.139729Z",
"url": "https://files.pythonhosted.org/packages/d9/1d/2701fb306f478c483835a42c7e5c376f4a07823e97f33d096ba6f79a2deb/cbz-3.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bfc4acbf04baa3eb1ef0b5f1b26a659001df657b59e977a468142b91484839d9",
"md5": "3cd28bc4c83a514404e5eaa45b833576",
"sha256": "18446f71cf86475eede257619211e7bfd1d7fb089d0e8ca04f2cb14c35b77ea1"
},
"downloads": -1,
"filename": "cbz-3.4.0.tar.gz",
"has_sig": false,
"md5_digest": "3cd28bc4c83a514404e5eaa45b833576",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 68029,
"upload_time": "2025-07-09T21:43:13",
"upload_time_iso_8601": "2025-07-09T21:43:13.390202Z",
"url": "https://files.pythonhosted.org/packages/bf/c4/acbf04baa3eb1ef0b5f1b26a659001df657b59e977a468142b91484839d9/cbz-3.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 21:43:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hyugogirubato",
"github_project": "cbz",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cbz"
}
JSON
