release v3.4.0

feat: Enhance support for CBR format

.gitignore

@@ -173,4 +173,5 @@ pyrightconfig.json
 ### CBZ ###
 *.cbz
 *.pdf
-*.zip
+*.zip
+*cbr

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.4.0] - 2025-07-09
+
+### Added
+
+- Support for PDF files.
+- Support for CBR (Comic Book RAR) files.
+
+### Changed
+
+- Replaced `PyMuPDF` with `pypdf` for PDF handling.
+- Updated third-party license documentation for bundled libraries.
+
+### New Contributors
+
+- [tssujt](https://github.com/tssujt)
+
 ## [3.3.7] - 2025-01-04
 
 ### Fixed
@@ -177,6 +193,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Initial release.
 
+[3.4.0]: https://github.com/hyugogirubato/cbz/releases/tag/v3.4.0
 [3.3.7]: https://github.com/hyugogirubato/cbz/releases/tag/v3.3.7
 [3.3.6]: https://github.com/hyugogirubato/cbz/releases/tag/v3.3.6
 [3.3.5]: https://github.com/hyugogirubato/cbz/releases/tag/v3.3.5

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 hyugogirubato
+Copyright (c) 2025 hyugogirubato
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,6 +1,6 @@
 # CBZ
 
-CBZ is a Python library designed for creating, manipulating, and viewing comic book files in CBZ format. It offers a straightforward interface to pack comic pages into CBZ archives, extract metadata, and display comics using a built-in player.
+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
 
@@ -8,8 +8,9 @@ CBZ is a Python library designed for creating, manipulating, and viewing comic b
 - 📚 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 files to retrieve comic information
-- 🛠️ Built-in player for viewing CBZ comics
+- 📦 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
@@ -73,7 +74,15 @@ if __name__ == '__main__':
 
 ## Player
 
-CBZ includes a command-line player for viewing CBZ comic book files. Simply run cbzplayer <file> to launch the player with the specified CBZ file.
+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>
@@ -81,13 +90,37 @@ usage: cbzplayer [-h] <file>
 Launch CBZ player with a comic book file
 
 positional arguments:
-  <file>      Path to the CBZ comic book file.
+  <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
@@ -96,6 +129,7 @@ The `ComicInfo` class represents a comic book with metadata and pages. It suppor
 
 ```python
 from cbz.comic import ComicInfo
+from cbz.constants import PageType, YesNo, Manga, AgeRating, Format
 from cbz.page import PageInfo
 
 # Example usage:
@@ -135,30 +169,57 @@ Pack the comic into a CBZ file format:
 cbz_content = comic.pack()
 ```
 
-### Unpacking from CBZ
+### Loading from Different Formats
 
-Load a comic from an existing CBZ file:
+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>
-<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>
-
 
 ## Licensing
 
-This software is licensed under the terms of [MIT License](https://github.com/hyugogirubato/cbz/blob/main/LICENSE).  
+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
 
-© hyugogirubato 2024
+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

cbz/__main__.py

@@ -8,7 +8,7 @@ from cbz.comic import ComicInfo
 def main() -> None:
     # Parse command-line arguments
     parser = argparse.ArgumentParser(description='Launch CBZ player with a comic book file')
-    parser.add_argument('comic_path', type=Path, metavar='<file>', help='Path to the CBZ comic book file.')
+    parser.add_argument('comic_path', type=Path, metavar='<file>', help='Path to the CBZ, CBR, or PDF comic book file.')
     args = parser.parse_args()
 
     # Validate the provided path
@@ -17,9 +17,14 @@ def main() -> None:
         print(f'Error: The file "{comic_path}" does not exist or is not a valid file.')
         exit(1)
 
-    # Create ComicInfo object from CBZ file
+    # Create ComicInfo object from comic file
     try:
-        comic_info = ComicInfo.from_pdf(comic_path) if comic_path.suffix == '.pdf' else ComicInfo.from_cbz(comic_path)
+        if comic_path.suffix == '.pdf':
+            comic_info = ComicInfo.from_pdf(comic_path)
+        elif comic_path.suffix == '.cbr':
+            comic_info = ComicInfo.from_cbr(comic_path)
+        else:
+            comic_info = ComicInfo.from_cbz(comic_path)
         # Launch the CBZ player
         comic_info.show()
     except Exception as e:

cbz/comic.py

@@ -5,12 +5,14 @@ import zipfile
 from datetime import datetime, timezone
 from enum import Enum
 from io import BytesIO
-from typing import Union
+from typing import Union, List
 from pathlib import Path
 
-import fitz
+import rarfile
 import xmltodict
 
+from pypdf import PdfReader
+
 from cbz.constants import XML_NAME, COMIC_FIELDS, IMAGE_FORMAT, PAGE_FIELDS
 from cbz.models import ComicModel
 from cbz.page import PageInfo
@@ -22,27 +24,27 @@ class ComicInfo(ComicModel):
     ComicInfo class that represents the comic book information and pages.
     """
 
-    def __init__(self, pages: list[PageInfo], **kwargs):
+    def __init__(self, pages: List[PageInfo], **kwargs):
         """
         Initialize the ComicInfo instance with pages and additional attributes.
 
         Args:
-            pages (list[PageInfo]): List of PageInfo objects representing the comic pages.
+            pages (List[PageInfo]): List of PageInfo objects representing the comic pages.
             **kwargs: Additional attributes for the comic.
 
         Attributes:
-            pages (list[PageInfo]): Stores the comic pages.
+            pages (List[PageInfo]): Stores the comic pages.
         """
         super(ComicInfo, self).__init__(**kwargs)
         self.pages = pages
 
     @classmethod
-    def from_pages(cls, pages: list[PageInfo], **kwargs) -> ComicInfo:
+    def from_pages(cls, pages: List[PageInfo], **kwargs) -> ComicInfo:
         """
         Create a ComicInfo instance from pages and additional attributes.
 
         Args:
-            pages (list[PageInfo]): List of PageInfo objects representing the comic pages.
+            pages (List[PageInfo]): List of PageInfo objects representing the comic pages.
             **kwargs: Additional attributes for the comic.
 
         Returns:
@@ -66,7 +68,25 @@ class ComicInfo(ComicModel):
         """
         if not isinstance(path, (Path, str)):
             raise ValueError(f'Expecting Path object or path string, got {path!r}')
-        return cls.__unpack_zip(path)
+        return cls.__unpack_zip(Path(path))
+
+    @classmethod
+    def from_cbr(cls, path: Union[Path, str]) -> ComicInfo:
+        """
+        Create a ComicInfo instance from a CBR file.
+
+        Args:
+            path (Union[Path, str]): Path to the CBR file.
+
+        Returns:
+            ComicInfo: An instance of ComicInfo.
+
+        Raises:
+            ValueError: If the provided path is not a Path object or a string.
+        """
+        if not isinstance(path, (Path, str)):
+            raise ValueError(f'Expecting Path object or path string, got {path!r}')
+        return cls.__unpack_rar(Path(path))
 
     @classmethod
     def from_pdf(cls, path: Union[Path, str]) -> ComicInfo:
@@ -84,7 +104,7 @@ class ComicInfo(ComicModel):
         """
         if not isinstance(path, (Path, str)):
             raise ValueError(f'Expecting Path object or path string, got {path!r}')
-        return cls.__unpack_pdf(path)
+        return cls.__unpack_pdf(Path(path))
 
     @staticmethod
     def __unpack_pdf(path: Path) -> ComicInfo:
@@ -97,18 +117,89 @@ class ComicInfo(ComicModel):
         Returns:
             ComicInfo: An instance of ComicInfo.
         """
-        pages: list[PageInfo] = []
-        with fitz.open(path) as pf:
-            for element in pf:
-                # Check if the page has images
-                images = element.get_images(full=True)
-                for i, image in enumerate(images):
-                    base = pf.extract_image(image[0])
-                    pages.append(PageInfo.loads(data=base['image']))
+        pages: List[PageInfo] = []
+        reader = PdfReader(path)
+        for page in reader.pages:
+            for image in page.images:
+                pages.append(PageInfo.loads(data=image.data))
 
         assert pages, 'No valid images present in file'
         return ComicInfo.from_pages(pages=pages)
 
+    @staticmethod
+    def __extract_info(items: dict, fields: dict) -> dict:
+        """
+        Extract and convert field information from the provided items and fields.
+
+        Args:
+            items (dict): Dictionary containing item attributes.
+            fields (dict): Dictionary containing field mappings and types.
+
+        Returns:
+            dict: Dictionary with extracted and converted field information.
+        """
+        content = {}
+        for key, (field_key, field_type) in fields.items():
+            if field_key in items:
+                content[key] = field_type(items[field_key])
+        return content
+
+    @staticmethod
+    def __process_archive(archive_file: Union[zipfile.ZipFile, rarfile.RarFile]) -> ComicInfo:
+        """
+        Common logic for processing archive files (CBZ/CBR).
+
+        Args:
+            archive_file (Union[ZipFile, RarFile]): Archive file object (ZipFile or RarFile)
+
+        Returns:
+            ComicInfo: An instance of ComicInfo.
+        """
+        pages = []
+        names = archive_file.namelist()
+        comic_info = {}
+
+        if XML_NAME in names:
+            with archive_file.open(XML_NAME, 'r') as f:
+                comic_info = xmltodict.parse(f.read()).get('ComicInfo', {})
+            names.remove(XML_NAME)
+
+        comic = ComicInfo.__extract_info(
+            items=comic_info,
+            fields=COMIC_FIELDS
+        )
+
+        pages_info = comic_info.get('Pages', {}).get('Page', [])
+        for i, name in enumerate(names):
+            suffix = Path(name).suffix
+            if suffix:
+                assert suffix in IMAGE_FORMAT, f'Unsupported image format: {suffix}'
+                with archive_file.open(name, 'r') as f:
+                    page_info = {}
+                    if i < len(pages_info):
+                        page_info = ComicInfo.__extract_info(
+                            items=pages_info[i],
+                            fields=PAGE_FIELDS
+                        )
+                    page_info['name'] = Path(name).name
+                    pages.append(PageInfo.loads(data=f.read(), **page_info))
+
+        return ComicInfo.from_pages(pages=pages, **comic)
+
+    @staticmethod
+    def __unpack_rar(path: Path) -> ComicInfo:
+        """
+        Unpack a CBR file and create a ComicInfo instance.
+
+        Args:
+            path (Path): Path to the CBR file.
+
+        Returns:
+            ComicInfo: An instance of ComicInfo.
+        """
+        with rarfile.RarFile(path, 'r') as rf:
+            return ComicInfo.__process_archive(rf)
+
     @staticmethod
     def __unpack_zip(path: Path) -> ComicInfo:
         """
@@ -120,56 +211,8 @@ class ComicInfo(ComicModel):
         Returns:
             ComicInfo: An instance of ComicInfo.
         """
-
-        def __info(items: dict, fields: dict) -> dict:
-            """
-            Extract and convert field information from the provided items and fields.
-
-            Args:
-                items (dict): Dictionary containing item attributes.
-                fields (dict): Dictionary containing field mappings and types.
-
-            Returns:
-                dict: Dictionary with extracted and converted field information.
-            """
-            content = {}
-            for key, (field_key, field_type) in fields.items():
-                if field_key in items:
-                    content[key] = field_type(items[field_key])
-            return content
-
-        pages = []
-
         with zipfile.ZipFile(path, 'r', zipfile.ZIP_STORED) as zf:
-            names = zf.namelist()
-            comic_info = {}
-
-            if XML_NAME in names:
-                with zf.open(XML_NAME, 'r') as f:
-                    comic_info = xmltodict.parse(f.read()).get('ComicInfo', {})
-                names.remove(XML_NAME)
-
-            comic = __info(
-                items=comic_info,
-                fields=COMIC_FIELDS
-            )
-
-            pages_info = comic_info.get('Pages', {}).get('Page', [])
-            for i, name in enumerate(names):
-                suffix = Path(name).suffix
-                if suffix:
-                    assert suffix in IMAGE_FORMAT, f'Unsupported image format: {suffix}'
-                    with zf.open(name, 'r') as f:
-                        page_info = {}
-                        if i < len(pages_info):
-                            page_info = __info(
-                                items=pages_info[i],
-                                fields=PAGE_FIELDS
-                            )
-                        page_info['name'] = Path(f.name).name
-                        pages.append(PageInfo.loads(data=f.read(), **page_info))
-
-        return ComicInfo.from_pages(pages=pages, **comic)
+            return ComicInfo.__process_archive(zf)
 
     def get_info(self) -> dict:
         """

cbz/player.py

@@ -3,7 +3,6 @@ import tkinter as tk
 
 from io import BytesIO
 from tkinter import ttk
-from tkinter.constants import DISABLED, NORMAL
 from pathlib import Path
 
 try:
@@ -207,7 +206,7 @@ class Player:
         self.summary_text = tk.Text(self.canvas, wrap=tk.WORD, bg='white', bd=0, padx=10, pady=10)
         self.summary_text.tag_configure('bold', font=('Arial', 13, 'bold'))
         self.summary_text.tag_configure('normal', font=('Arial', 12), lmargin1=10, lmargin2=10)
-        self.summary_text.config(state=DISABLED)
+        self.summary_text.config(state=tk.DISABLED)
 
     def show_page(self) -> None:
         """
@@ -223,8 +222,8 @@ class Player:
             self._show_image_page()
 
         # Update navigation button states based on current page index
-        self.prev_button.config(state=DISABLED if self.current_page == -1 else NORMAL)
-        self.next_button.config(state=DISABLED if self.current_page + 1 == len(self.comic_info.pages) else NORMAL)
+        self.prev_button.config(state=tk.DISABLED if self.current_page == -1 else tk.NORMAL)
+        self.next_button.config(state=tk.DISABLED if self.current_page + 1 == len(self.comic_info.pages) else tk.NORMAL)
 
         # Update page index label text
         self.page_index_label.config(text=f'{self.current_page + 1}/{len(self.comic_info.pages)}')
@@ -239,7 +238,7 @@ class Player:
         # Display summary for the first page
         infos = self.comic_info.get_info()
 
-        self.summary_text.config(state=NORMAL)
+        self.summary_text.config(state=tk.NORMAL)
         self.summary_text.delete('1.0', tk.END)
 
         for key, value in infos.items():
@@ -249,7 +248,7 @@ class Player:
                 self.summary_text.insert(tk.END, f'{key}\n', 'bold')
                 self.summary_text.insert(tk.END, f'{value}\n\n', 'normal')
 
-        self.summary_text.config(state=DISABLED)
+        self.summary_text.config(state=tk.DISABLED)
         self.summary_text.place(relwidth=1, relheight=1)
 
     def _show_image_page(self) -> None:

cbz/utils.py

@@ -8,7 +8,7 @@ from PIL.IcoImagePlugin import IcoFile
 
 def default_attr(value: any) -> any:
     """
-    Provides a default value based on the expected type of an attribute.
+    Provides a default value based on the expected type of attribute.
 
     Args:
         value (any): Expected type or class of the attribute.

pyproject.toml

@@ -4,12 +4,13 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "cbz"
-version = "3.3.7"
-description = "CBZ simplifies creating, managing, and viewing comic book files in CBZ format, offering seamless packaging, metadata handling, and built-in viewing capabilities"
+version = "3.4.0"
+description = "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."
 license = "MIT"
 authors = ["hyugogirubato <65763543+hyugogirubato@users.noreply.github.com>"]
 readme = "README.md"
-keywords = ["python", "cbz", "ebooks", "manga", "comics", "webtoons"]
+repository = "https://github.com/hyugogirubato/cbz"
+keywords = ["python", "cbz", "cbr", "pdf", "ebooks", "manga", "comics", "webtoons"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
@@ -17,7 +18,7 @@ classifiers = [
     "Natural Language :: English",
     "Operating System :: OS Independent",
     "Topic :: Utilities",
-    "Topic :: Software Development :: Libraries :: Python Modules"
+    "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 include = [
     { path = "CHANGELOG.md", format = "sdist" },
@@ -30,11 +31,12 @@ include = [
 "Changelog" = "https://github.com/hyugogirubato/cbz/blob/main/CHANGELOG.md"
 
 [tool.poetry.dependencies]
-python = ">=3.8"
-xmltodict = ">=0.13.0"
+python = ">=3.8,<4.0"
 langcodes = ">=3.4.0"
 Pillow = ">=10.4.0"
-PyMuPDF = ">=1.24.7"
+pypdf = ">=5.7.0"
+rarfile = ">=4.2"
+xmltodict = ">=0.14.2"
 
 [tool.poetry.scripts]
 cbzplayer = "cbz.__main__:main"
@@ -45,4 +47,4 @@ url = "https://pypi.org/simple/"
 priority = "primary"
 
 [certificates]
-localpypi = { cert = false }
+localpypi = { cert = false }