# EPUB Pinyin
A Python tool to add Pinyin annotations above Chinese characters in EPUB files. This tool helps Chinese language learners by automatically adding pronunciation guides to Chinese text while maintaining the EPUB format and structure.
## Features
- Automatically detects Chinese characters in EPUB content
- Adds Pinyin annotations using `<ruby>` tags
- Preserves original EPUB structure and formatting
- Supports tone marks in Pinyin
- Handles complex EPUB structures
- Maintains original file organization
- Processes files in correct spine order
## Installation
You can install the package directly from PyPI:
```bash
pip install epub-pinyin
```
Or install from source:
```bash
git clone https://github.com/tony-develop-2025/epub-pinyin.git
cd epub-pinyin
pip install -e .
```
## Usage
### Command Line
After installation, you can use the tool from the command line:
```bash
epub-pinyin input.epub -o output.epub
```
Or use the module directly:
```bash
python -m epub_pinyin.main input.epub -o output.epub
```
Where:
- `input.epub` is your source EPUB file containing Chinese text
- `-o output.epub` (optional) specifies the output file name (defaults to "input_annotated.epub")
### Python API
You can also use the tool programmatically in your Python code:
```python
from epub_pinyin import process_epub
# Process an EPUB file
process_epub("input.epub", "output.epub")
```
## Example
When rendered in an EPUB reader, the Pinyin appears above each character:
```
nǐ hǎo shì jiè
你好，世界！
```
## Requirements
- Python 3.7 or higher
- beautifulsoup4
- pypinyin
- lxml
## Development
To set up the development environment:
1. Clone the repository:
```bash
git clone https://github.com/tony-develop-2025/epub-pinyin.git
cd epub-pinyin
```
2. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install development dependencies:
```bash
pip install -r requirements-dev.txt
```
4. Run tests:
```bash
pytest tests/
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/tony-develop-2025/epub-pinyin",
"name": "epub-pinyin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Tony",
"author_email": "tony.develop.2025@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/74/8b/9daa22eeb43094e747f08b171a87729167612e68312e593539ac63007130/epub_pinyin-0.1.4.tar.gz",
"platform": null,
"description": "# EPUB Pinyin\n\nA Python tool to add Pinyin annotations above Chinese characters in EPUB files. This tool helps Chinese language learners by automatically adding pronunciation guides to Chinese text while maintaining the EPUB format and structure.\n\n## Features\n\n- Automatically detects Chinese characters in EPUB content\n- Adds Pinyin annotations using `<ruby>` tags\n- Preserves original EPUB structure and formatting\n- Supports tone marks in Pinyin\n- Handles complex EPUB structures\n- Maintains original file organization\n- Processes files in correct spine order\n\n## Installation\n\nYou can install the package directly from PyPI:\n\n```bash\npip install epub-pinyin\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/tony-develop-2025/epub-pinyin.git\ncd epub-pinyin\npip install -e .\n```\n\n## Usage\n\n### Command Line\n\nAfter installation, you can use the tool from the command line:\n\n```bash\nepub-pinyin input.epub -o output.epub\n```\n\nOr use the module directly:\n\n```bash\npython -m epub_pinyin.main input.epub -o output.epub\n```\n\nWhere:\n- `input.epub` is your source EPUB file containing Chinese text\n- `-o output.epub` (optional) specifies the output file name (defaults to \"input_annotated.epub\")\n\n### Python API\n\nYou can also use the tool programmatically in your Python code:\n\n```python\nfrom epub_pinyin import process_epub\n\n# Process an EPUB file\nprocess_epub(\"input.epub\", \"output.epub\")\n```\n\n## Example\n\nWhen rendered in an EPUB reader, the Pinyin appears above each character:\n```\n n\u01d0 h\u01ceo sh\u00ec ji\u00e8\n\u4f60\u597d\uff0c\u4e16\u754c\uff01\n```\n\n\n## Requirements\n\n- Python 3.7 or higher\n- beautifulsoup4\n- pypinyin\n- lxml\n\n## Development\n\nTo set up the development environment:\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/tony-develop-2025/epub-pinyin.git\ncd epub-pinyin\n```\n\n2. Create a virtual environment:\n```bash\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n```\n\n3. Install development dependencies:\n```bash\npip install -r requirements-dev.txt\n```\n\n4. Run tests:\n```bash\npytest tests/\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Add Pinyin annotations to Chinese text in EPUB files",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/tony-develop-2025/epub-pinyin"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6cbbd2f3ccfeefb2bed33594d7ba0aa0227ceb1e821b5f55795c61e9ccc4bfbf",
"md5": "3b09b607c7323728d13d7ea1702020c0",
"sha256": "e826705ffb7ff33092f45b93fe78f1d56deb485f86aec22a4fdddb8f8fc440e3"
},
"downloads": -1,
"filename": "epub_pinyin-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3b09b607c7323728d13d7ea1702020c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9099,
"upload_time": "2025-01-26T13:27:42",
"upload_time_iso_8601": "2025-01-26T13:27:42.944630Z",
"url": "https://files.pythonhosted.org/packages/6c/bb/d2f3ccfeefb2bed33594d7ba0aa0227ceb1e821b5f55795c61e9ccc4bfbf/epub_pinyin-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "748b9daa22eeb43094e747f08b171a87729167612e68312e593539ac63007130",
"md5": "901ee71ea8fa111ec9c351d791fe863b",
"sha256": "5a424eabeffab0d8af9013d850c6884b7248acf3fba17f2e95baf83fdee38c60"
},
"downloads": -1,
"filename": "epub_pinyin-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "901ee71ea8fa111ec9c351d791fe863b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10567,
"upload_time": "2025-01-26T13:27:44",
"upload_time_iso_8601": "2025-01-26T13:27:44.868392Z",
"url": "https://files.pythonhosted.org/packages/74/8b/9daa22eeb43094e747f08b171a87729167612e68312e593539ac63007130/epub_pinyin-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-26 13:27:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tony-develop-2025",
"github_project": "epub-pinyin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "beautifulsoup4",
"specs": [
[
">=",
"4.12.0"
]
]
},
{
"name": "pypinyin",
"specs": [
[
">=",
"0.49.0"
]
]
},
{
"name": "lxml",
"specs": [
[
">=",
"4.9.0"
]
]
}
],
"lcname": "epub-pinyin"
}
JSON
