myepubapp 1.0.1

A powerful text-to-EPUB conversion tool

MyEPUBApp

A powerful and flexible text-to-EPUB conversion tool that transforms plain text files into standard EPUB e-book format with advanced features for content processing and validation.

✨ Features

• 📖 Text to EPUB Conversion: Convert plain text files to fully EPUB-compliant e-books
• 🌏 Chinese Content Support: Specially optimized for Chinese content with automatic Chinese book title mark conversion
• 📑 Intelligent Chapter Detection: Automatically identify and split chapters using special marker symbols
• 🔄 Flexible Operation Modes: Support for creating new EPUB files or appending chapters to existing ones
• ✅ EPUB Validation: Built-in EPUB format validation with detailed compliance checking
• 🏗️ Modular Architecture: Clean, maintainable code structure for easy extension
• 📝 Comprehensive Logging: Detailed operation logging with configurable log levels
• 🎨 Cover Image Support: Add custom cover images to your EPUB files
• 📋 Table of Contents: Automatic generation of navigation and table of contents

🚀 Installation

Requirements

• Python 3.8 or higher
• pip package manager

Option 1: Install from PyPI (Recommended)

pip install myepubapp

Option 2: Install from Source

1. Clone the repository:

git clone https://github.com/eyes1971/myepubapp.git
cd myepubapp

2. Install dependencies:

pip install -r requirements.txt

3. Install in development mode:

pip install -e .

📖 Usage

Basic Usage

1. Create New EPUB File

myepubapp -i input.txt --output-epub output.epub

Automatic Title Generation: Book titles are automatically generated from input filenames (e.g., my_book.txt becomes "My Book")

2. Append Chapters to Existing EPUB

myepubapp -a input.txt --input-epub existing.epub --output-epub updated.epub

3. Validate EPUB File

myepubapp -v --input-epub file.epub

Command Line Options

Option	Short	Description
--init	-i	Initialize mode: create new EPUB file
--append	-a	Append mode: add chapters to existing EPUB
--validate	-v	Validate EPUB file format and structure
input_file		Input text file path (not required for validate mode)
--input-epub	-ie	Existing EPUB file (required for append/validate modes)
--output-epub	-o	Output EPUB file path
--convert-tags	-ct	Convert <> tags to Chinese book title marks 《》
--cover	-c	Path to cover image file

Input File Format

Text files should use special marker symbols for chapter organization:

※☆ Introduction Title
This is the introduction content.
It can span multiple paragraphs and will be displayed as a separate introduction page.

※ⅰ Chapter 1 Title
Chapter content goes here...
Multiple paragraphs are supported.

※ⅱ Chapter 1 Section 1
Subsection content...

※ⅲ Chapter 1 Section 1 Subsection 1
Deeper level content with full formatting support.

Marker Symbols:

• ※☆: Introduction page (creates separate intro page)
• ※ⅰ: Level 1 chapter (h1 heading)
• ※ⅱ: Level 2 chapter (h2 heading)
• ※ⅲ: Level 3 chapter (h3 heading)

📋 Examples

Create Simple EPUB

myepubapp -i sample.txt --output-epub mybook.epub

Create EPUB with Chinese Tag Conversion

myepubapp -i sample.txt --output-epub mybook.epub --convert-tags

Add Cover Image

myepubapp -i sample.txt --output-epub mybook.epub --cover cover.jpg

Append Chapters to Existing EPUB

myepubapp -a chapter2.txt --input-epub mybook.epub --output-epub mybook_updated.epub

Validate EPUB File

myepubapp -v --input-epub mybook.epub

🏗️ Project Structure

myepubapp/
├── core/                    # Core business logic
│   ├── __init__.py
│   ├── book.py             # EPUB book management
│   ├── chapter.py          # Chapter data structures
│   └── metadata.py         # EPUB metadata handling
├── generators/             # Content generation modules
│   ├── __init__.py
│   ├── content.py          # Content processing and chapter generation
│   └── toc.py             # Table of contents generation
├── utils/                  # Utility modules
│   ├── __init__.py
│   ├── epub_validator.py   # EPUB format validation
│   ├── file_handler.py     # File I/O operations
│   ├── logger.py          # Logging configuration
│   └── text_processor.py   # Text processing utilities
├── exceptions/             # Custom exception classes
│   ├── __init__.py
│   └── epub_exceptions.py  # EPUB-specific exceptions
├── cli.py                 # Command-line interface
├── __init__.py            # Package initialization
└── py.typed               # Type hints marker

📋 Dependencies

• ebooklib>=0.18.0: Core EPUB file processing and manipulation
• beautifulsoup4>=4.12.0: HTML/XML parsing and manipulation

🔍 Validation Features

The built-in EPUB validator checks:

• ✅ File structure compliance
• ✅ Required metadata presence
• ✅ MIME type validation
• ✅ Container XML format
• ✅ Content OPF validation
• ✅ Spine and manifest integrity
• ✅ XHTML content validation

📝 Logging

All operations are logged with configurable verbosity. Logs are written to:

• Console output (with appropriate log levels)
• logs/myepubapp.log file (detailed operation logs)

🤝 Contributing

We welcome contributions! Please feel free to:

1. Report bugs via GitHub Issues
2. Submit feature requests
3. Create pull requests with improvements

Development Setup

1. Fork the repository
2. Clone your fork: git clone https://github.com/yourusername/myepubapp.git
3. Create a virtual environment: python -m venv venv
4. Activate the environment: source venv/bin/activate (Linux/Mac) or venv\Scripts\activate (Windows)
5. Install development dependencies: pip install -r requirements.txt
6. Install in development mode: pip install -e .
7. Run tests: python -m pytest

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with ebooklib for EPUB processing
• Uses Beautiful Soup for HTML parsing
• Inspired by the need for simple, reliable text-to-EPUB conversion tools

📞 Support

If you encounter any issues or have questions:

• Check the Issues page
• Create a new issue with detailed information
• Include sample input files and error messages when reporting bugs

📋 Changelog

Version 1.0.1 (2025-09-05)

• 🐛 Fixed: EPUB TOC generation error when using h2/h3 chapter levels
• 🐛 Fixed: Empty <ol> elements in nav.xhtml causing epubcheck validation failures
• 🔧 Improved: TOC generator now properly handles all chapter level combinations (h1, h2, h3)
• 🔧 Improved: Automatic level detection for chapters with skipped levels (e.g., intro → h2)
• ✅ Enhanced: EPUB validation compliance for all supported chapter structures

Version 1.0.0 (2025-09-01)

• ✨ Initial release with full text-to-EPUB conversion functionality
• 📖 Support for Chinese content with automatic title mark conversion
• 📑 Intelligent chapter detection using marker symbols
• 🔄 Flexible operation modes (create new EPUB or append chapters)
• ✅ Built-in EPUB validation with detailed compliance checking
• 🎨 Cover image support
• 📋 Automatic table of contents generation

---

Version: 1.0.1 Author: Sam Weng Repository: https://github.com/eyes1971/myepubapp