bible-xml-parser 0.1.0__tar.gz

bible_xml_parser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bible Parser Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bible_xml_parser-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+recursive-include examples *.py *.xml *.md
+recursive-include tests *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .DS_Store
+recursive-exclude dev-docs *

bible_xml_parser-0.1.0/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: bible-xml-parser
+Version: 0.1.0
+Summary: A Python package for parsing Bible texts in various XML formats (USFX, OSIS, ZEFANIA)
+Author: Omar Zintan
+License: MIT
+Project-URL: Homepage, https://github.com/Omarzintan/bible_parser_python
+Project-URL: Repository, https://github.com/Omarzintan/bible_parser_python
+Project-URL: Issues, https://github.com/Omarzintan/bible_parser_python/issues
+Keywords: bible,parser,xml,usfx,osis,zefania,scripture
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Religion
+Classifier: Topic :: Text Processing :: Markup :: XML
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: typing-extensions>=4.0.0; python_version < "3.9"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# Bible XML Parser
+
+A Python package for parsing Bible texts in various XML formats (USFX, OSIS, ZEFANIA). This package provides both direct parsing and database-backed approaches for handling Bible data in your Python applications.
+
+## Features
+
+- 📖 Parse Bible texts in multiple formats (USFX, OSIS, ZEFANIA)
+- 🔍 Automatic format detection
+- 🚀 Memory-efficient streaming XML parsing using defusedxml
+- 🗄️ SQLite database caching for improved performance
+- 🔎 Full-text search functionality (FTS5)
+- 🔒 Secure XML parsing (protected against XXE attacks)
+- 📝 Type hints throughout for better IDE support
+- 🐍 Python 3.8+ support
+
+## Installation
+
+```bash
+pip install bible-xml-parser
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/Omarzintan/bible_parser_python.git
+cd bible_parser_python
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Direct Parsing Approach
+
+Parse a Bible file directly without database caching:
+
+```python
+from bible_parser import BibleParser
+
+# Parse from file (format auto-detected)
+parser = BibleParser('path/to/bible.xml')
+
+# Or parse from string with explicit format
+xml_content = open('bible.xml').read()
+parser = BibleParser.from_string(xml_content, format='USFX')
+
+# Iterate over books
+for book in parser.books:
+    print(f"{book.title} ({book.id})")
+    print(f"  Chapters: {len(book.chapters)}")
+    print(f"  Verses: {len(book.verses)}")
+
+# Or iterate over verses directly
+for verse in parser.verses:
+    print(f"{verse.book_id} {verse.chapter_num}:{verse.num} - {verse.text}")
+```
+
+### Database Approach (Recommended for Production)
+
+For better performance, use the database approach:
+
+```python
+from bible_parser import BibleRepository
+
+# Create repository
+repo = BibleRepository(xml_path='path/to/bible.xml', format='USFX')
+
+# Initialize database (only needed once)
+repo.initialize('my_bible.db')
+
+# Get all books
+books = repo.get_books()
+for book in books:
+    print(f"{book.title} ({book.id})")
+
+# Get verses from a specific chapter
+verses = repo.get_verses('gen', 1)  # Genesis chapter 1
+for verse in verses:
+    print(f"{verse.num}. {verse.text}")
+
+# Get a specific verse
+verse = repo.get_verse('jhn', 3, 16)  # John 3:16
+if verse:
+    print(verse.text)
+
+# Search for verses containing specific text
+results = repo.search_verses('love')
+print(f"Found {len(results)} verses containing 'love'")
+
+# Don't forget to close
+repo.close()
+```
+
+### Using Context Manager
+
+```python
+from bible_parser import BibleRepository
+
+with BibleRepository(xml_path='bible.xml') as repo:
+    repo.initialize('my_bible.db')
+    
+    # Use the repository
+    verses = repo.get_verses('mat', 5)  # Matthew chapter 5
+    for verse in verses:
+        print(f"{verse.num}. {verse.text}")
+    
+    # Search
+    results = repo.search_verses('faith hope love')
+    for verse in results:
+        print(f"{verse.book_id} {verse.chapter_num}:{verse.num}")
+
+# Database automatically closed
+```
+
+## Supported Formats
+
+### USFX (Unified Standard Format XML)
+```xml
+<usfx>
+  <book id="gen">
+    <c id="1"/>
+    <v id="1">In the beginning...</v>
+  </book>
+</usfx>
+```
+
+### OSIS (Open Scripture Information Standard)
+```xml
+<osis>
+  <osisText>
+    <div type="book" osisID="Gen">
+      <verse osisID="Gen.1.1">In the beginning...</verse>
+    </div>
+  </osisText>
+</osis>
+```
+
+### Zefania XML
+```xml
+<XMLBIBLE>
+  <BIBLEBOOK bnumber="1" bname="Genesis">
+    <CHAPTER cnumber="1">
+      <VERS vnumber="1">In the beginning...</VERS>
+    </CHAPTER>
+  </BIBLEBOOK>
+</XMLBIBLE>
+```
+
+## API Reference
+
+### BibleParser
+
+Main parser class with automatic format detection.
+
+**Methods:**
+- `__init__(source, format=None)` - Initialize parser
+- `from_string(xml_content, format=None)` - Create from XML string
+- `books` - Property that yields Book objects
+- `verses` - Property that yields Verse objects
+
+### BibleRepository
+
+Database-backed repository for efficient Bible data access.
+
+**Methods:**
+- `__init__(xml_path=None, xml_string=None, format=None)` - Initialize repository
+- `initialize(database_name)` - Create/open database
+- `get_books()` - Get all books
+- `get_verses(book_id, chapter_num)` - Get verses from a chapter
+- `get_verse(book_id, chapter_num, verse_num)` - Get a specific verse
+- `get_chapter_count(book_id)` - Get number of chapters in a book
+- `search_verses(query, limit=100)` - Full-text search
+- `close()` - Close database connection
+
+### Data Models
+
+**Verse:**
+- `num` (int) - Verse number
+- `chapter_num` (int) - Chapter number
+- `text` (str) - Verse text
+- `book_id` (str) - Book identifier
+
+**Chapter:**
+- `num` (int) - Chapter number
+- `verses` (List[Verse]) - List of verses
+
+**Book:**
+- `id` (str) - Book identifier (e.g., 'gen', 'mat')
+- `num` (int) - Book number
+- `title` (str) - Book title (e.g., 'Genesis', 'Matthew')
+- `chapters` (List[Chapter]) - List of chapters
+- `verses` (List[Verse]) - Flat list of all verses
+
+## Performance Considerations
+
+### Direct Parsing
+**Pros:**
+- Simple implementation
+- No database setup required
+- Always uses the latest source files
+
+**Cons:**
+- CPU and memory intensive
+- Slower for repeated access
+- Repeated parsing on each run
+
+### Database Approach
+**Pros:**
+- Much faster access once data is loaded
+- Lower memory usage during queries
+- Efficient full-text search with FTS5
+- Works offline without re-parsing
+
+**Cons:**
+- Initial setup time
+- Requires disk space
+- Additional complexity
+
+## Security
+
+This package uses `defusedxml` for secure XML parsing, protecting against:
+- **XXE (XML External Entity) attacks** - Prevents reading local files or making network requests
+- **Billion Laughs attack** - Prevents exponential entity expansion
+- **Quadratic blowup** - Prevents memory exhaustion
+
+All database queries use parameterized statements to prevent SQL injection.
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+- `direct_parsing.py` - Direct parsing example
+- `database_approach.py` - Database caching example
+- `search_example.py` - Full-text search example
+
+## Testing
+
+Run tests with pytest:
+
+```bash
+pytest
+```
+
+With coverage:
+
+```bash
+pytest --cov=bible_parser --cov-report=term-missing
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Inspired by the Ruby [bible_parser](https://github.com/seven1m/bible_parser) library
+- Flutter [bible_parser_flutter](../bible_parser_flutter/) implementation
+- Bible XML files from the [open-bibles](https://github.com/seven1m/open-bibles) repository
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+## Support
+
+- 📫 Issues: [GitHub Issues](https://github.com/Omarzintan/bible_parser_python/issues)
+- 📖 Documentation: [GitHub Wiki](https://github.com/Omarzintan/bible_parser_python/wiki)

bible_xml_parser-0.1.0/README.md

@@ -0,0 +1,269 @@
+# Bible XML Parser
+
+A Python package for parsing Bible texts in various XML formats (USFX, OSIS, ZEFANIA). This package provides both direct parsing and database-backed approaches for handling Bible data in your Python applications.
+
+## Features
+
+- 📖 Parse Bible texts in multiple formats (USFX, OSIS, ZEFANIA)
+- 🔍 Automatic format detection
+- 🚀 Memory-efficient streaming XML parsing using defusedxml
+- 🗄️ SQLite database caching for improved performance
+- 🔎 Full-text search functionality (FTS5)
+- 🔒 Secure XML parsing (protected against XXE attacks)
+- 📝 Type hints throughout for better IDE support
+- 🐍 Python 3.8+ support
+
+## Installation
+
+```bash
+pip install bible-xml-parser
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/Omarzintan/bible_parser_python.git
+cd bible_parser_python
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Direct Parsing Approach
+
+Parse a Bible file directly without database caching:
+
+```python
+from bible_parser import BibleParser
+
+# Parse from file (format auto-detected)
+parser = BibleParser('path/to/bible.xml')
+
+# Or parse from string with explicit format
+xml_content = open('bible.xml').read()
+parser = BibleParser.from_string(xml_content, format='USFX')
+
+# Iterate over books
+for book in parser.books:
+    print(f"{book.title} ({book.id})")
+    print(f"  Chapters: {len(book.chapters)}")
+    print(f"  Verses: {len(book.verses)}")
+
+# Or iterate over verses directly
+for verse in parser.verses:
+    print(f"{verse.book_id} {verse.chapter_num}:{verse.num} - {verse.text}")
+```
+
+### Database Approach (Recommended for Production)
+
+For better performance, use the database approach:
+
+```python
+from bible_parser import BibleRepository
+
+# Create repository
+repo = BibleRepository(xml_path='path/to/bible.xml', format='USFX')
+
+# Initialize database (only needed once)
+repo.initialize('my_bible.db')
+
+# Get all books
+books = repo.get_books()
+for book in books:
+    print(f"{book.title} ({book.id})")
+
+# Get verses from a specific chapter
+verses = repo.get_verses('gen', 1)  # Genesis chapter 1
+for verse in verses:
+    print(f"{verse.num}. {verse.text}")
+
+# Get a specific verse
+verse = repo.get_verse('jhn', 3, 16)  # John 3:16
+if verse:
+    print(verse.text)
+
+# Search for verses containing specific text
+results = repo.search_verses('love')
+print(f"Found {len(results)} verses containing 'love'")
+
+# Don't forget to close
+repo.close()
+```
+
+### Using Context Manager
+
+```python
+from bible_parser import BibleRepository
+
+with BibleRepository(xml_path='bible.xml') as repo:
+    repo.initialize('my_bible.db')
+    
+    # Use the repository
+    verses = repo.get_verses('mat', 5)  # Matthew chapter 5
+    for verse in verses:
+        print(f"{verse.num}. {verse.text}")
+    
+    # Search
+    results = repo.search_verses('faith hope love')
+    for verse in results:
+        print(f"{verse.book_id} {verse.chapter_num}:{verse.num}")
+
+# Database automatically closed
+```
+
+## Supported Formats
+
+### USFX (Unified Standard Format XML)
+```xml
+<usfx>
+  <book id="gen">
+    <c id="1"/>
+    <v id="1">In the beginning...</v>
+  </book>
+</usfx>
+```
+
+### OSIS (Open Scripture Information Standard)
+```xml
+<osis>
+  <osisText>
+    <div type="book" osisID="Gen">
+      <verse osisID="Gen.1.1">In the beginning...</verse>
+    </div>
+  </osisText>
+</osis>
+```
+
+### Zefania XML
+```xml
+<XMLBIBLE>
+  <BIBLEBOOK bnumber="1" bname="Genesis">
+    <CHAPTER cnumber="1">
+      <VERS vnumber="1">In the beginning...</VERS>
+    </CHAPTER>
+  </BIBLEBOOK>
+</XMLBIBLE>
+```
+
+## API Reference
+
+### BibleParser
+
+Main parser class with automatic format detection.
+
+**Methods:**
+- `__init__(source, format=None)` - Initialize parser
+- `from_string(xml_content, format=None)` - Create from XML string
+- `books` - Property that yields Book objects
+- `verses` - Property that yields Verse objects
+
+### BibleRepository
+
+Database-backed repository for efficient Bible data access.
+
+**Methods:**
+- `__init__(xml_path=None, xml_string=None, format=None)` - Initialize repository
+- `initialize(database_name)` - Create/open database
+- `get_books()` - Get all books
+- `get_verses(book_id, chapter_num)` - Get verses from a chapter
+- `get_verse(book_id, chapter_num, verse_num)` - Get a specific verse
+- `get_chapter_count(book_id)` - Get number of chapters in a book
+- `search_verses(query, limit=100)` - Full-text search
+- `close()` - Close database connection
+
+### Data Models
+
+**Verse:**
+- `num` (int) - Verse number
+- `chapter_num` (int) - Chapter number
+- `text` (str) - Verse text
+- `book_id` (str) - Book identifier
+
+**Chapter:**
+- `num` (int) - Chapter number
+- `verses` (List[Verse]) - List of verses
+
+**Book:**
+- `id` (str) - Book identifier (e.g., 'gen', 'mat')
+- `num` (int) - Book number
+- `title` (str) - Book title (e.g., 'Genesis', 'Matthew')
+- `chapters` (List[Chapter]) - List of chapters
+- `verses` (List[Verse]) - Flat list of all verses
+
+## Performance Considerations
+
+### Direct Parsing
+**Pros:**
+- Simple implementation
+- No database setup required
+- Always uses the latest source files
+
+**Cons:**
+- CPU and memory intensive
+- Slower for repeated access
+- Repeated parsing on each run
+
+### Database Approach
+**Pros:**
+- Much faster access once data is loaded
+- Lower memory usage during queries
+- Efficient full-text search with FTS5
+- Works offline without re-parsing
+
+**Cons:**
+- Initial setup time
+- Requires disk space
+- Additional complexity
+
+## Security
+
+This package uses `defusedxml` for secure XML parsing, protecting against:
+- **XXE (XML External Entity) attacks** - Prevents reading local files or making network requests
+- **Billion Laughs attack** - Prevents exponential entity expansion
+- **Quadratic blowup** - Prevents memory exhaustion
+
+All database queries use parameterized statements to prevent SQL injection.
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+- `direct_parsing.py` - Direct parsing example
+- `database_approach.py` - Database caching example
+- `search_example.py` - Full-text search example
+
+## Testing
+
+Run tests with pytest:
+
+```bash
+pytest
+```
+
+With coverage:
+
+```bash
+pytest --cov=bible_parser --cov-report=term-missing
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Inspired by the Ruby [bible_parser](https://github.com/seven1m/bible_parser) library
+- Flutter [bible_parser_flutter](../bible_parser_flutter/) implementation
+- Bible XML files from the [open-bibles](https://github.com/seven1m/open-bibles) repository
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+## Support
+
+- 📫 Issues: [GitHub Issues](https://github.com/Omarzintan/bible_parser_python/issues)
+- 📖 Documentation: [GitHub Wiki](https://github.com/Omarzintan/bible_parser_python/wiki)

bible_xml_parser-0.1.0/examples/README.md

@@ -0,0 +1,113 @@
+# Bible Parser Examples
+
+This directory contains example scripts demonstrating how to use the bible_parser package.
+
+## Sample Files
+
+- **`bible_small_usfx.xml`** - Small sample Bible in USFX format (Genesis 1-2)
+- **`bible_small_osis.xml`** - Small sample Bible in OSIS format (Genesis 1-2)
+
+## Example Scripts
+
+### 1. Direct Parsing (`direct_parsing.py`)
+
+Demonstrates parsing Bible XML files directly without database caching.
+
+**Run:**
+```bash
+cd examples
+python direct_parsing.py
+```
+
+**Features:**
+- Auto-detect Bible format
+- Iterate over books
+- Access verses directly
+- Parse from string
+
+### 2. Database Approach (`database_approach.py`)
+
+Demonstrates using SQLite database for caching and fast access.
+
+**Run:**
+```bash
+cd examples
+python database_approach.py
+```
+
+**Features:**
+- Database initialization
+- List all books
+- Get verses from specific chapters
+- Get specific verses
+- Full-text search
+
+### 3. Search Example (`search_example.py`)
+
+Demonstrates full-text search capabilities using SQLite FTS5.
+
+**Run:**
+```bash
+cd examples
+python search_example.py
+```
+
+**Features:**
+- Simple text search
+- Multi-word search
+- Search in specific books
+- Search statistics
+
+## Using Your Own Bible Files
+
+To use your own Bible XML files, simply change the `xml_file` variable in any example:
+
+```python
+# Use your own file
+xml_file = "/path/to/your/bible.xml"
+
+# Or use one of the sample files
+xml_file = "bible_small_usfx.xml"
+xml_file = "bible_small_osis.xml"
+```
+
+## Supported Formats
+
+The parser automatically detects these formats:
+- **USFX** - Unified Standard Format XML
+- **OSIS** - Open Scripture Information Standard
+- **ZEFANIA** - Zefania XML Bible Markup Language
+
+## Output
+
+Each example will:
+1. Parse the Bible file
+2. Display information about books, chapters, and verses
+3. Demonstrate specific features
+4. Clean up resources automatically
+
+## Database Files
+
+The database examples create a `my_bible.db` file in the examples directory. This file can be reused across runs for faster access. Delete it to re-import from XML.
+
+## Requirements
+
+Make sure the bible_parser package is installed:
+
+```bash
+cd ..
+pip install -e .
+```
+
+## Getting More Bible Files
+
+You can find more Bible XML files at:
+- [Open Bibles Repository](https://github.com/seven1m/open-bibles)
+- Various Bible translation websites
+
+## Notes
+
+- The sample files contain only Genesis chapters 1-2 for demonstration purposes
+- For production use, download complete Bible translations
+- The database approach is recommended for applications that need repeated access
+- The direct parsing approach is good for one-time processing or when you need the latest data