ComicView Image Archive Viewer Development Assistant

Expert assistant for developing and maintaining ComicView, a Python-based image archive viewer for ZIP, RAR, CBR, and CBZ files. Built with PyQt5 for cross-platform comic book reading and photo collection viewing.

Project Context

ComicView is a fullscreen slideshow application for browsing image archives with:

Project Structure

```

src/image_archive_viewer/

├── viewer.py # Main UI and application logic

├── archive_reader.py # Archive reading and image processing

├── logging_setup.py # Logging configuration

└── __init__.py # Package initialization

tests/

├── fixtures/ # Test archives and creation scripts

├── test_*.py # Unit test modules

└── conftest.py # Shared test fixtures

pyproject.toml # Project configuration and dependencies

uv.lock # Dependency lock file

```

Development Workflow

Installation and Setup

1. **Install in development mode:**

```bash

uv pip install -e .

```

2. **Install from PyPI:**

```bash

# As a uv tool

uv tool install image-archive-viewer

# Or via pip

pip install image-archive-viewer

```

3. **RAR support requirement:**

- **macOS/Linux**: Install `unrar` via package manager (e.g., Homebrew)

- **Windows**: Download from [RARLab](https://www.rarlab.com/rar_add.htm) and add to PATH

Running the Application

```bash

Basic launch (opens file dialog)

comic_view

With verbose logging (console + image_archive_viewer.log)

comic_view -v

```

Testing

```bash

Run all tests (CI-safe, headless compatible)

pytest

Verbose output

pytest -v

Specific test module

pytest tests/test_archive_reader.py

Generate test fixtures

cd tests/fixtures && python create_test_fixtures.py

```

**Test modules:**

Building

```bash

Build distribution package

python -m build

Or with uv

uv build

```

Key Implementation Details

Image Processing Pipeline

1. Archive opened with appropriate library based on extension

2. Images converted: PIL Image → QImage (RGB888) → QPixmap

3. All images cached in memory as QPixmap objects

4. Archive contents sorted alphabetically

Zoom and Pan System

UI Overlay System

Event Handling

Progressive Loading

1. First image loaded immediately in `load_images()`

2. Remaining images loaded via `QTimer.singleShot(0, self.load_remaining_images)`

3. Startup overlay updated when loading completes

4. Graceful error handling for `rarfile.BadRarFile`

Code Guidelines

Dependencies

```python

Core dependencies (pyproject.toml)

PyQt5 # Complete GUI framework

Pillow # Image processing (PIL.Image)

rarfile # RAR/CBR archive support

External: unrar command-line tool

```

Memory Management

Error Handling Patterns

Architecture Principles

When Making Changes

1. **Read existing code first** - Understand current implementations before modifying

2. **Run tests** - Ensure `pytest` passes after changes

3. **Test all formats** - Verify ZIP, CBZ, RAR, and CBR support

4. **Check cross-platform** - Consider Linux, macOS, and Windows compatibility

5. **Update logging** - Add appropriate debug/info messages for new features

6. **Maintain zoom/pan** - Preserve cursor-centered zoom behavior

7. **Keep overlays functional** - Ensure help and startup overlays work correctly

Compatibility Notes

Common Tasks

Adding New Archive Format

1. Update `archive_reader.py` with new format detection

2. Add appropriate library dependency to `pyproject.toml`

3. Create test fixtures in `tests/fixtures/`

4. Add test cases to `test_archive_reader.py`

Modifying UI Controls

1. Update event handlers in `viewer.py`

2. Update help overlay text with new key bindings

3. Test keyboard, mouse, and wheel interactions

4. Ensure zoom/pan behavior remains consistent

Improving Performance

1. Review image caching strategy in `load_remaining_images()`

2. Consider QPixmap conversion efficiency

3. Profile memory usage with large archives

4. Test progressive loading timing