fix: allow comi.number to be a float

Bump actions/checkout from 5 to 6

.github/workflows/test.yml

@@ -10,10 +10,10 @@ jobs:
         python-version: [ "3.8", "3.9", "3.10", "3.11", "3.12", "3.13" ]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 

CHANGELOG.md

@@ -4,6 +4,33 @@ 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.5] - 2025-10-19
+
+### Changed
+
+- More flexible suffix checking to support complex archive paths.
+- Improved validation in `PageInfo.load()` to handle empty or invalid data correctly.
+
+## [3.4.4] - 2025-09-21
+
+### Added
+
+- Added `[pillow]` extension to support `.jxl` and `.avif` images.
+
+### Fixed
+
+- Files in the input archives are now sorted alphabetically.
+
+## [3.4.3] - 2025-08-31
+
+### Changed
+
+- Bump actions/checkout from 4 to 5.
+
+### Fixed
+
+- Fix ComicInfo XML parsing for single page comic.
+
 ## [3.4.2] - 2025-07-26
 
 ### Added
@@ -205,6 +232,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Initial release.
 
+[3.4.5]: https://github.com/hyugogirubato/cbz/releases/tag/v3.4.5
+[3.4.4]: https://github.com/hyugogirubato/cbz/releases/tag/v3.4.4
+[3.4.3]: https://github.com/hyugogirubato/cbz/releases/tag/v3.4.3
 [3.4.2]: https://github.com/hyugogirubato/cbz/releases/tag/v3.4.2
 [3.4.1]: https://github.com/hyugogirubato/cbz/releases/tag/v3.4.1
 [3.4.0]: https://github.com/hyugogirubato/cbz/releases/tag/v3.4.0

README.md

@@ -216,10 +216,12 @@ This project uses the following third-party libraries:
 
 - **[langcodes](https://pypi.org/project/langcodes/)** - MIT License
 - **[Pillow](https://pypi.org/project/Pillow/)** - HPND License
+- **[pillow-avif-plugin](https://pypi.org/project/pillow-avif-plugin/)** - MIT License
+- **[pillow-jxl-plugin](https://pypi.org/project/pillow-jxl-plugin/)** - MIT 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/__init__.py

@@ -1,2 +1,9 @@
 from .comic import ComicInfo
 from .page import PageInfo
+
+# Register optional Pillow plugins
+for _plugin in ('pillow_avif', 'pillow_jxl'):
+    try:
+        __import__(_plugin)
+    except ImportError:
+        pass

cbz/comic.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 import zipfile
 
 from datetime import datetime, timezone
@@ -156,12 +157,12 @@ class ComicInfo(ComicModel):
             ComicInfo: An instance of ComicInfo.
         """
         pages = []
-        names = archive_file.namelist()
+        names = sorted(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', {})
+                comic_info = xmltodict.parse(f.read(), force_list=('Page',)).get('ComicInfo', {})
             names.remove(XML_NAME)
 
         comic = ComicInfo.__extract_info(
@@ -172,8 +173,13 @@ class ComicInfo(ComicModel):
         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}'
+
+            # Some archives may contain folders or hidden files (e.g., ".extra/" or "__MACOSX/.DS_Store")
+            # that could corrupt the suffix detection and cause invalid image handling.
+            if suffix not in IMAGE_FORMAT:
+                logging.warning(f'Skipping unsupported or invalid file: {name!r} (suffix={suffix!r})')
+                continue
+
             with archive_file.open(name, 'r') as f:
                 page_info = {}
                 if i < len(pages_info):

cbz/constants.py

@@ -3,189 +3,195 @@ from typing import Union
 
 from langcodes import Language
 
-XML_NAME = 'ComicInfo.xml'
+XML_NAME = "ComicInfo.xml"
 IMAGE_FORMAT = {
-    '.jpeg', '.jpg',  # Joint Photographic Experts Group
-    '.png',  # Portable Network Graphics
-    '.gif',  # Graphics Interchange Format
-    '.bmp',  # Bitmap Image File
-    '.tiff', '.tif',  # Tagged Image File Format
-    '.webp'  # Web Picture Format
+    ".jpeg",
+    ".jpg",  # JPEG (Joint Photographic Experts Group)
+    ".png",  # PNG (Portable Network Graphics)
+    ".gif",  # GIF (Graphics Interchange Format)
+    ".bmp",  # BMP (Bitmap Image File)
+    ".tiff",
+    ".tif",  # TIFF (Tagged Image File Format)
+    ".webp",  # WebP (Web Picture Format, by Google)
+    ".jxl",  # JPEG XL (Next-generation JPEG format)
+    ".avif",  # AVIF (AV1 Image File Format, based on AV1 codec)
 }
 
 
 class YesNo(Enum):
-    UNKNOWN = 'Unknown'
-    NO = 'No'
-    YES = 'Yes'
+    UNKNOWN = "Unknown"
+    NO = "No"
+    YES = "Yes"
 
 
 class Manga(Enum):
-    UNKNOWN = 'Unknown'
-    NO = 'No'
-    YES = 'Yes'
-    RIGHT_LEFT = 'YesAndRightToLeft'
+    UNKNOWN = "Unknown"
+    NO = "No"
+    YES = "Yes"
+    RIGHT_LEFT = "YesAndRightToLeft"
 
 
 class PageType(Enum):
-    FRONT_COVER = 'FrontCover'
-    INNER_COVER = 'InnerCover'
-    ROUNDUP = 'Roundup'
-    STORY = 'Story'
-    ADVERTISEMENT = 'Advertisement'
-    EDITORIAL = 'Editorial'
-    LETTERS = 'Letters'
-    PREVIEW = 'Preview'
-    BACK_COVER = 'BackCover'
-    OTHER = 'Other'
-    DELETED = 'Deleted'
+    FRONT_COVER = "FrontCover"
+    INNER_COVER = "InnerCover"
+    ROUNDUP = "Roundup"
+    STORY = "Story"
+    ADVERTISEMENT = "Advertisement"
+    EDITORIAL = "Editorial"
+    LETTERS = "Letters"
+    PREVIEW = "Preview"
+    BACK_COVER = "BackCover"
+    OTHER = "Other"
+    DELETED = "Deleted"
 
 
 class AgeRating(Enum):
-    UNKNOWN = 'Unknown'
-    ADULTS18 = 'Adults Only 18+'
-    CHILDHOOD = 'Early Childhood'
-    EVERYONE = 'Everyone'
-    EVERYONE10 = 'Everyone 10+'
-    G = 'G'
-    KIDS = 'Kids to Adults'
-    M = 'M'
-    MA15 = 'MA15+'
-    MATURE17 = 'Mature 17+'
-    PG = 'PG'
-    R18 = 'R18+'
-    PENDING = 'Rating Pending'
-    TEEN = 'Teen'
-    X18 = 'X18+'
+    UNKNOWN = "Unknown"
+    ADULTS18 = "Adults Only 18+"
+    CHILDHOOD = "Early Childhood"
+    EVERYONE = "Everyone"
+    EVERYONE10 = "Everyone 10+"
+    G = "G"
+    KIDS = "Kids to Adults"
+    M = "M"
+    MA15 = "MA15+"
+    MATURE17 = "Mature 17+"
+    PG = "PG"
+    R18 = "R18+"
+    PENDING = "Rating Pending"
+    TEEN = "Teen"
+    X18 = "X18+"
 
 
 class Format(Enum):
-    UNKNOWN = 'Unknown'
+    UNKNOWN = "Unknown"
     # ONE_SHOT = '1 Shot'
     # ONE_SHOT = '1/2',
     # ONE_SHOT = '1-Shot'
-    ANNOTATION = 'Annotation'
+    ANNOTATION = "Annotation"
     # ANNOTATIONS = 'Annotations'
-    ANNUAL = 'Annual'
-    ANTHOLOGY = 'Anthology'
+    ANNUAL = "Annual"
+    ANTHOLOGY = "Anthology"
     # BLACK_WHITE = 'B&W'
     # BLACK_WHITE = 'B/W'
     # BLACK_WHITE = 'B&&W'
-    BLACK_WHITE = 'Black & White'
+    BLACK_WHITE = "Black & White"
     # BOX_SET = 'Box Set'
-    BOX_SET = 'Box-Set'
-    CROSSOVER = 'Crossover'
-    DIRECTOR_CUT = 'Director\'s Cut'
-    EPILOGUE = 'Epilogue'
-    EVENT = 'Event'
-    FCBD = 'FCBD'
-    FLYER = 'Flyer'
+    BOX_SET = "Box-Set"
+    CROSSOVER = "Crossover"
+    DIRECTOR_CUT = "Director's Cut"
+    EPILOGUE = "Epilogue"
+    EVENT = "Event"
+    FCBD = "FCBD"
+    FLYER = "Flyer"
     # GIANT_SIZE = 'Giant'
     # GIANT_SIZE = 'Giant Size'
-    GIANT_SIZE = 'Giant-Size'
-    GRAPHIC_NOVEL = 'Graphic Novel'
+    GIANT_SIZE = "Giant-Size"
+    GRAPHIC_NOVEL = "Graphic Novel"
     # HARDCOVER = 'Hardcover'
-    HARDCOVER = 'Hard-Cover'
+    HARDCOVER = "Hard-Cover"
     # KING_SIZE = 'King'
     # KING_SIZE = 'King Size'
-    KING_SIZE = 'King-Size'
-    LIMITED_SERIES = 'Limited Series'
-    MAGAZINE = 'Magazine'
-    NSFW = 'NSFW'
+    KING_SIZE = "King-Size"
+    LIMITED_SERIES = "Limited Series"
+    MAGAZINE = "Magazine"
+    NSFW = "NSFW"
     # ONE_SHOT = 'One Shot'
-    ONE_SHOT = 'One-Shot'
-    POINT1 = 'Point 1'
-    PREVIEW = 'Preview'
-    PROLOGUE = 'Prologue'
-    REFERENCE = 'Reference'
-    REVIEW = 'Review'
-    REVIEWED = 'Reviewed'
-    SCANLATION = 'Scanlation'
-    SCRIPT = 'Script'
-    SERIES = 'Series'
-    SKETCH = 'Sketch'
-    SPECIAL = 'Special'
+    ONE_SHOT = "One-Shot"
+    POINT1 = "Point 1"
+    PREVIEW = "Preview"
+    PROLOGUE = "Prologue"
+    REFERENCE = "Reference"
+    REVIEW = "Review"
+    REVIEWED = "Reviewed"
+    SCANLATION = "Scanlation"
+    SCRIPT = "Script"
+    SERIES = "Series"
+    SKETCH = "Sketch"
+    SPECIAL = "Special"
     # TRADE_PAPER_BACK = 'TPB'
-    TRADE_PAPER_BACK = 'Trade Paper Back'
+    TRADE_PAPER_BACK = "Trade Paper Back"
     # WEB_COMIC = 'WebComic'
-    WEB_COMIC = 'Web Comic'
+    WEB_COMIC = "Web Comic"
     # YEAR_ONE = 'Year 1'
-    YEAR_ONE = 'Year One'
+    YEAR_ONE = "Year One"
 
 
 class Rating(float):
 
     def __new__(cls, value: Union[int, float] = -1) -> float:
-        assert -1 <= float(value) <= 5, f'Rating must be between 0 and 5, input {value}'
+        assert -1 <= float(value) <= 5, f"Rating must be between 0 and 5, input {value}"
         return super().__new__(cls, value)
 
 
 class LanguageISO(str):
 
-    def __new__(cls, value: str = '') -> str:
-        assert not value or Language.get(str(value)).is_valid(), f'Invalid {value} language'
+    def __new__(cls, value: str = "") -> str:
+        assert (
+            not value or Language.get(str(value)).is_valid()
+        ), f"Invalid {value} language"
         return super().__new__(cls, value)
 
 
 COMIC_FIELDS = {
-    'title': ('Title', str),
-    'series': ('Series', str),
-    'number': ('Number', int),
-    'count': ('Count', int),
-    'volume': ('Volume', int),
-    'alternate_series': ('AlternateSeries', str),
-    'alternate_number': ('AlternateNumber', int),
-    'alternate_count': ('AlternateCount', int),
-    'summary': ('Summary', str),
-    'notes': ('Notes', str),
-    'year': ('Year', int),
-    'month': ('Month', int),
-    'day': ('Day', int),
-    'writer': ('Writer', str),
-    'penciller': ('Penciller', str),
-    'inker': ('Inker', str),
-    'colorist': ('Colorist', str),
-    'letterer': ('Letterer', str),
-    'cover_artist': ('CoverArtist', str),
-    'editor': ('Editor', str),
-    'translator': ('Translator', str),
-    'publisher': ('Publisher', str),
-    'imprint': ('Imprint', str),
-    'genre': ('Genre', str),
-    'tags': ('Tags', str),
-    'web': ('Web', str),
-    'format': ('Format', Format),
-    'ean': ('EAN', str),
-    'black_white': ('BlackAndWhite', YesNo),
-    'manga': ('Manga', Manga),
-    'characters': ('Characters', str),
-    'teams': ('Teams', str),
-    'locations': ('Locations', str),
-    'scan_information': ('ScanInformation', str),
-    'story_arc': ('StoryArc', str),
-    'story_arc_number': ('StoryArcNumber', int),
-    'series_group': ('SeriesGroup', str),
-    'age_rating': ('AgeRating', AgeRating),
-    'main_character_or_team': ('MainCharacterOrTeam', str),
-    'review': ('Review', str),
-    'language_iso': ('LanguageISO', LanguageISO),
-    'community_rating': ('CommunityRating', Rating),
-    'added': ('Added', str),
-    'released': ('Released', str),
-    'file_size': ('FileSize', int),
-    'file_modified_time': ('FileModifiedTime', str),
-    'file_creation_time': ('FileCreationTime', str),
-    'book_price': ('BookPrice', str),
-    'custom_values_store': ('CustomValuesStore', str)
+    "title": ("Title", str),
+    "series": ("Series", str),
+    "number": ("Number", float),
+    "count": ("Count", int),
+    "volume": ("Volume", int),
+    "alternate_series": ("AlternateSeries", str),
+    "alternate_number": ("AlternateNumber", int),
+    "alternate_count": ("AlternateCount", int),
+    "summary": ("Summary", str),
+    "notes": ("Notes", str),
+    "year": ("Year", int),
+    "month": ("Month", int),
+    "day": ("Day", int),
+    "writer": ("Writer", str),
+    "penciller": ("Penciller", str),
+    "inker": ("Inker", str),
+    "colorist": ("Colorist", str),
+    "letterer": ("Letterer", str),
+    "cover_artist": ("CoverArtist", str),
+    "editor": ("Editor", str),
+    "translator": ("Translator", str),
+    "publisher": ("Publisher", str),
+    "imprint": ("Imprint", str),
+    "genre": ("Genre", str),
+    "tags": ("Tags", str),
+    "web": ("Web", str),
+    "format": ("Format", Format),
+    "ean": ("EAN", str),
+    "black_white": ("BlackAndWhite", YesNo),
+    "manga": ("Manga", Manga),
+    "characters": ("Characters", str),
+    "teams": ("Teams", str),
+    "locations": ("Locations", str),
+    "scan_information": ("ScanInformation", str),
+    "story_arc": ("StoryArc", str),
+    "story_arc_number": ("StoryArcNumber", int),
+    "series_group": ("SeriesGroup", str),
+    "age_rating": ("AgeRating", AgeRating),
+    "main_character_or_team": ("MainCharacterOrTeam", str),
+    "review": ("Review", str),
+    "language_iso": ("LanguageISO", LanguageISO),
+    "community_rating": ("CommunityRating", Rating),
+    "added": ("Added", str),
+    "released": ("Released", str),
+    "file_size": ("FileSize", int),
+    "file_modified_time": ("FileModifiedTime", str),
+    "file_creation_time": ("FileCreationTime", str),
+    "book_price": ("BookPrice", str),
+    "custom_values_store": ("CustomValuesStore", str),
 }
 
 PAGE_FIELDS = {
-    'image': ('@Image', int),
-    'type': ('@Type', PageType),
-    'double': ('@DoublePage', bool),
-    'key': ('@Key', str),
-    'bookmark': ('@Bookmark', str),
-    'image_size': ('@ImageSize', int),
-    'image_width': ('@ImageWidth', int),
-    'image_height': ('@ImageHeight', int)
+    "image": ("@Image", int),
+    "type": ("@Type", PageType),
+    "double": ("@DoublePage", bool),
+    "key": ("@Key", str),
+    "bookmark": ("@Bookmark", str),
+    "image_size": ("@ImageSize", int),
+    "image_width": ("@ImageWidth", int),
+    "image_height": ("@ImageHeight", int),
 }

cbz/models.py

@@ -1,5 +1,19 @@
-from cbz.constants import COMIC_FIELDS, PAGE_FIELDS, Format, YesNo, Manga, AgeRating, LanguageISO, Rating, PageType
+from cbz.constants import (
+    COMIC_FIELDS,
+    PAGE_FIELDS,
+    Format,
+    YesNo,
+    Manga,
+    AgeRating,
+    LanguageISO,
+    Rating,
+    PageType,
+)
 from cbz.utils import verify_attr, default_attr
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
 
 
 class BaseModel:
@@ -21,7 +35,7 @@ class BaseModel:
             # Set default values for each attribute based on its type
             setattr(self, key, kwargs.get(key, default_attr(field_type)))
 
-    def __setattr__(self, key: str, value: any) -> None:
+    def __setattr__(self, key: str, value: "Any") -> None:
         """
         Sets the value of an attribute and verifies its type.
 
@@ -39,6 +53,9 @@ class BaseModel:
                 value = field_type(value)
             # Verify that the assigned value matches the expected type
             verify_attr(field_type, key, value)
+            if isinstance(value, float):
+                if value.is_integer():
+                    value = int(value)
         except (AttributeError, KeyError):
             pass
         super().__setattr__(key, value)
@@ -50,9 +67,15 @@ class BaseModel:
         Returns:
             str: A string representation of the object, displaying its class name and attribute key-value pairs.
         """
-        return '{name}({items})'.format(
+        return "{name}({items})".format(
             name=self.__class__.__name__,
-            items=', '.join([f'{k}={repr(v)}' for k, v in self.__dict__.items() if not k.startswith('_')])
+            items=", ".join(
+                [
+                    f"{k}={repr(v)}"
+                    for k, v in self.__dict__.items()
+                    if not k.startswith("_")
+                ]
+            ),
         )
 
 
@@ -60,9 +83,10 @@ class ComicModel(BaseModel):
     """
     Model for representing comic book metadata.
     """
+
     title: str
     series: str
-    number: int
+    number: float
     count: int
     volume: int
     alternate_series: str
@@ -124,6 +148,7 @@ class PageModel(BaseModel):
     """
     Model for representing comic book pages.
     """
+
     type: PageType
     double: bool
     image_size: int

cbz/page.py

@@ -75,6 +75,8 @@ class PageInfo(PageModel):
             data = base64.b64decode(data)
         if not isinstance(data, bytes):
             raise ValueError(f'Expecting Bytes or Base64 input, got {data!r}')
+        if not data.strip():
+            raise ValueError(f'Empty or null data provided (length={len(data)})')
         return cls(data, **kwargs)
 
     @classmethod
@@ -98,7 +100,7 @@ class PageInfo(PageModel):
         path = Path(path)
         with path.open(mode='rb') as f:
             kwargs.setdefault('name', path.name)
-            return cls(f.read(), **kwargs)
+            return cls.loads(f.read(), **kwargs)
 
     def show(self) -> None:
         """

pyproject.toml

@@ -1,15 +1,10 @@
-[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
-
-[tool.poetry]
+[project]
 name = "cbz"
-version = "3.4.2"
+version = "3.4.5"
 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>"]
+authors = [{name="hyugogirubato", email="65763543+hyugogirubato@users.noreply.github.com"}]
 readme = "README.md"
-repository = "https://github.com/hyugogirubato/cbz"
 keywords = [
     "python",
     "cbz",
@@ -29,36 +24,29 @@ classifiers = [
     "Topic :: Utilities",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-include = [
-    { path = "CHANGELOG.md", format = "sdist" },
-    { path = "README.md", format = "sdist" },
-    { path = "LICENSE", format = "sdist" },
+requires-python = ">=3.8,<4.0"
+
+dependencies= [
+"langcodes>=3.4.0",
+"Pillow>=10.4.0",
+"pypdf >=5.7.0",
+"rarfile>=4.2",
+"xmltodict>=0.14.2"
 ]
 
+
 [tool.poetry.urls]
 "Issues" = "https://github.com/hyugogirubato/cbz/issues"
 "Changelog" = "https://github.com/hyugogirubato/cbz/blob/main/CHANGELOG.md"
 
-[tool.poetry.dependencies]
-python = ">=3.8,<4.0"
-langcodes = ">=3.4.0"
-Pillow = ">=10.4.0"
-pypdf = ">=5.7.0"
-rarfile = ">=4.2"
-xmltodict = ">=0.14.2"
 
-[tool.poetry.scripts]
-cbzplayer = "cbz.__main__:main"
+[project.optional-dependencies]
+pillow = ["pillow-avif-plugin>=1.5.2", "pillow-jxl-plugin>=1.3.4"]
 
-[[tool.poetry.source]]
-name = "localpypi"
-url = "https://pypi.org/simple/"
-priority = "primary"
+[dependency-groups]
+dev = ["pytest>=7.4.0,<9.0.0", "pytest-cov>=5.0.0"]
 
 
-[tool.poetry.group.dev.dependencies]
-pytest = ">=7.4.0,<9.0.0"
-pytest-cov = ">=5.0.0"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

tests/test_comic.py

@@ -1,3 +1,4 @@
+import tempfile
 from pathlib import Path
 from typing import List
 
@@ -157,3 +158,22 @@ class TestComicInfo:
 
         assert comic.title == 'Empty Test'
         assert len(comic.pages) == 0
+
+    def test_single_page_comic_load(self, images_dir):
+        """Test loading comic with a single page."""
+        image_paths = sorted(list(images_dir.iterdir()))[:1]
+        pages = [PageInfo.load(path=path) for path in image_paths]
+
+        comic = ComicInfo.from_pages(pages=pages, title="Single Page Test")
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_path = Path(temp_dir) / "single_page.cbz"
+            data = comic.pack()
+            with open(temp_path, "wb") as f:
+                f.write(data)
+
+            assert temp_path.exists()
+
+            comic_loaded = ComicInfo.from_cbz(temp_path)
+            assert comic_loaded.title == "Single Page Test"
+            assert len(comic_loaded.pages) == 1