|
| 1 | + |
| 2 | + |
| 3 | +The pythonbible library serves several purposes related to the Christian Bible and Scripture references. |
| 4 | + |
| 5 | +<table> |
| 6 | + <tr> |
| 7 | + <td>Latest Version</td> |
| 8 | + <td> |
| 9 | + <a href="https://pypi.org/project/pythonbible/"><img src="https://img.shields.io/pypi/v/pythonbible?color=gold&logo=pypi&logoColor=lightgray"></a><br /> |
| 10 | + <img src="https://img.shields.io/pypi/dm/pythonbible?color=gold"> |
| 11 | + </td> |
| 12 | + </tr> |
| 13 | + <tr> |
| 14 | + <td>License</td> |
| 15 | + <td><a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-orange.svg"></a></td> |
| 16 | + </tr> |
| 17 | + <tr> |
| 18 | + <td>Workflows</td> |
| 19 | + <td> |
| 20 | + <img src="https://github.com/avendesora/pythonbible/actions/workflows/python-package.yml/badge.svg"><br/> |
| 21 | + <img src="https://github.com/avendesora/pythonbible/workflows/CodeQL/badge.svg"><br /> |
| 22 | + <img src="https://github.com/avendesora/pythonbible/actions/workflows/tests.yml/badge.svg"> |
| 23 | + </td> |
| 24 | + </tr> |
| 25 | + <tr> |
| 26 | + <td>Code Quality</td> |
| 27 | + <td> |
| 28 | + <a href="https://www.codacy.com/gh/avendesora/pythonbible/dashboard?utm_source=github.com&utm_medium=referral&utm_content=avendesora/pythonbible&utm_campaign=Badge_Grade"><img src="https://app.codacy.com/project/badge/Grade/dc1333c64b434f7bb813d08750462921"></a><br/> |
| 29 | + <a href="https://app.codacy.com/gh/avendesora/pythonbible/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage"><img src="https://app.codacy.com/project/badge/Coverage/dc1333c64b434f7bb813d08750462921"></a><br /> |
| 30 | + <a href="https://results.pre-commit.ci/latest/github/avendesora/pythonbible/main"><img src="https://results.pre-commit.ci/badge/github/avendesora/pythonbible/main.svg"></a><br /> |
| 31 | + <a href="https://sourcery.ai"><img src="https://img.shields.io/badge/Sourcery-enabled-brightgreen"></a> |
| 32 | + </td> |
| 33 | + </tr> |
| 34 | + <tr> |
| 35 | + <td>Supported Python Versions</td> |
| 36 | + <td><a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue?logo=python&logoColor=lightgray"></a></td> |
| 37 | + </tr> |
| 38 | +</table> |
| 39 | + |
| 40 | +## Documentation |
| 41 | + |
| 42 | +The full documentation for pythonbible can be found at [docs.python.bible](https://docs.python.bible). |
| 43 | + |
| 44 | +## Installation |
| 45 | + |
| 46 | +```shell script |
| 47 | +python3 -m pip install pythonbible |
| 48 | +``` |
| 49 | + |
| 50 | +## Features |
| 51 | + |
| 52 | +### Searching text for scripture references |
| 53 | +Given a text, search for scripture references and return any that are found in a list of NormalizedReferences. |
| 54 | + |
| 55 | +For example, given the following text: |
| 56 | + |
| 57 | +```python |
| 58 | +import pythonbible as bible |
| 59 | + |
| 60 | +text = "The parable of the lost sheep is told in Matthew 18:12-14 and Luke 15:3-7." |
| 61 | +references = bible.get_references(text) |
| 62 | +``` |
| 63 | + |
| 64 | +The search functionality should return the following list of scripture references: |
| 65 | + |
| 66 | +```python |
| 67 | +[ |
| 68 | + NormalizedReference( |
| 69 | + book=<Book.MATTHEW: 40>, |
| 70 | + start_chapter=18, |
| 71 | + start_verse=12, |
| 72 | + end_chapter=18, |
| 73 | + end_verse=14, |
| 74 | + end_book=<Book.MATTHEW: 40> |
| 75 | + ), |
| 76 | + NormalizedReference( |
| 77 | + book=<Book.LUKE: 42>, |
| 78 | + start_chapter=15, |
| 79 | + start_verse=3, |
| 80 | + end_chapter=15, |
| 81 | + end_verse=7, |
| 82 | + end_book=<Book.LUKE: 42> |
| 83 | + ) |
| 84 | +] |
| 85 | +``` |
| 86 | + |
| 87 | +### Converting a normalized scripture reference into a list of integer verse ids |
| 88 | +Any single verse can be identified by an integer that contains the book, chapter, and verse information. |
| 89 | +The first 1-2 digits of the integer id represent the book, the next 3 digits represent the chapter, and the last 3 digits represent the verse. |
| 90 | + |
| 91 | +For example, "Genesis 1:1" would be represented as: |
| 92 | + |
| 93 | +```python |
| 94 | +1001001 |
| 95 | +``` |
| 96 | + |
| 97 | +"John 3:16" would be represented as: |
| 98 | + |
| 99 | +```python |
| 100 | +43003016 |
| 101 | +``` |
| 102 | + |
| 103 | +The book of John is the 43rd book of the Bible, "003" represents the 3rd chapter, and "016" represents the sixteenth verse. |
| 104 | + |
| 105 | +Since the book, chapter, and verses are standardized and unlikely to change, this allows us to reference verses in a very efficient way. |
| 106 | + |
| 107 | +Given a normalized scripture reference, which can contain one or more verses, the conversion functionality will convert that normalized scripture reference into a list of verse id integers. |
| 108 | + |
| 109 | +For example, given the following normalized scripture reference for Genesis 1:1-4: |
| 110 | + |
| 111 | +```python |
| 112 | +import pythonbible as bible |
| 113 | + |
| 114 | +reference = bible.NormalizedReference(bible.Book.GENESIS, 1, 1, 1, 4, bible.Book.GENESIS) |
| 115 | +verse_ids = bible.convert_reference_to_verse_ids(reference) |
| 116 | +``` |
| 117 | + |
| 118 | +The conversion functionality would return the following list of verse id integers: |
| 119 | + |
| 120 | +```python |
| 121 | +(1001001, 1001002, 1001003, 1001004) |
| 122 | +``` |
| 123 | + |
| 124 | +### Converting a list of verse id integers into a list of normalized scripture references |
| 125 | +The reverse of the above feature, we can take a list of integer verse ids and convert it back into a list of normalized scripture references. |
| 126 | + |
| 127 | +For example, the following list of verse ids represents the references Matthew 18:12-14 and Luke 15:3-7. |
| 128 | + |
| 129 | +```python |
| 130 | +import pythonbible as bible |
| 131 | + |
| 132 | +verse_ids = [40018012, 40018013, 40018014, 42015003, 42015004, 42015005, 42015006, 42015007, ] |
| 133 | +references = bible.convert_verse_ids_to_references(verse_ids) |
| 134 | +``` |
| 135 | + |
| 136 | +The conversion functionality would return the following list of normalized scripture references. |
| 137 | + |
| 138 | +```python |
| 139 | +[ |
| 140 | + NormalizedReference( |
| 141 | + book=<Book.MATTHEW: 40>, |
| 142 | + start_chapter=18, |
| 143 | + start_verse=12, |
| 144 | + end_chapter=18, |
| 145 | + end_verse=14, |
| 146 | + end_book=<Book.MATTHEW: 40> |
| 147 | + ), |
| 148 | + NormalizedReference( |
| 149 | + book=<Book.LUKE: 42>, |
| 150 | + start_chapter=15, |
| 151 | + start_verse=3, |
| 152 | + end_chapter=15, |
| 153 | + end_verse=7, |
| 154 | + end_book=<Book.LUKE: 42> |
| 155 | + ) |
| 156 | +] |
| 157 | +``` |
| 158 | + |
| 159 | +### Converting a list of normalized scripture references into a formatted string scripture reference |
| 160 | +Given a list of normalized references, this feature formats them into a human-readable scripture reference string. |
| 161 | + |
| 162 | +It sorts the list so that the references appear in the order they would in the Bible. |
| 163 | +It also combines verses into ranges when possible. |
| 164 | + |
| 165 | +For example: |
| 166 | + |
| 167 | +```python |
| 168 | +import pythonbible as bible |
| 169 | + |
| 170 | +text = "My favorite verses are Philippians 4:8, Isaiah 55:13, and Philippians 4:4-7." |
| 171 | +references = bible.get_references(text) |
| 172 | +formatted_reference = bible.format_scripture_references(references) |
| 173 | +``` |
| 174 | + |
| 175 | +The resulting formatted reference should be: |
| 176 | + |
| 177 | +```python |
| 178 | +'Isaiah 55:13;Philippians 4:4-8' |
| 179 | +``` |
| 180 | + |
| 181 | +There are a couple of reference formatting features not yet implemented: |
| 182 | +* Smarter pluralization of the book of Psalms (i.e. If just one Psalm is referenced, the singular "Psalm" should be used, but if more than one Psalm is referenced, the plural "Psalms" should be used.) |
| 183 | +* Optional exclusion of the chapter number for books that contain only one chapter (e.g. Some prefer references like Obadiah 1-4 rather than Obadiah 1:1-4, since Obadiah contains only one chapter.) |
| 184 | + |
| 185 | +### Formatting Biblical text for print or web display in one or more open-source or public domain versions |
| 186 | + |
| 187 | +This is still a work in progress, but there is some existing functionality related to this. |
| 188 | + |
| 189 | +The related [pythonbible-parser](https://github.com/avendesora/pythonbible-parser/) library includes a parser to parse [OSIS](https://ebible.org/osis/) formatted XML files and convert them into a more efficient format for use in Python. The King James and American Standard OSIS files have been converted into python classes and have been included in the **pythonbible** library and can be currently used to retrieve the text for a single verse: |
| 190 | + |
| 191 | +```python |
| 192 | +import pythonbible as bible |
| 193 | + |
| 194 | +verse_text = bible.get_verse_text(1001001, version=bible.Version.KING_JAMES) |
| 195 | +``` |
| 196 | + |
| 197 | +The resulting verse_text would be: |
| 198 | + |
| 199 | +```python |
| 200 | +'In the beginning God created the heaven and the earth.' |
| 201 | +``` |
| 202 | + |
| 203 | +The version argument is optional and currently defaults to ``AMERICAN_STANDARD``. Ideally, that default will be configurable in a future release. |
0 commit comments