versiref 0.1.0__tar.gz

versiref-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.aider*

versiref-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

versiref-0.1.0/.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    "mypy-type-checker.importStrategy": "fromEnvironment",
+    "mypy-type-checker.ignorePatterns": [
+        "build/*.py"
+    ],
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "ruff.configuration": "pyproject.toml"
+}

versiref-0.1.0/CONVENTIONS.MD

@@ -0,0 +1,4 @@
+# Coding conventions that aider MUST follow
+
+- Only use comments when necessary, since they can become outdated. Instead, strive to make the code self-explanatory.
+- When comments are used, they should add useful information that is not readily apparent from the code.

versiref-0.1.0/DESIGN.md

@@ -0,0 +1,88 @@
+# VersiRef Design Document
+
+VersiRef is a Python package for sophisticated parsing, manipulation, and printing of references to the Bible.
+
+This design document was created prior to the implementation, and so may not fully correspond to it.
+
+## SimpleBibleRef
+
+An instance of `SimpleBibleRef` represents a sequence of verse ranges within a single book of the Bible.
+These ranges are not necessarily in numeric order because the person who creates the citation may prefer a different order.
+The class is naive in that it doesn't specify its versification (this is something like `datetime`'s naive classes, which don't specify a time zone).
+In the simplest case, it designates a single chapter and verse, such as John 3:16.
+More generally, each range contains a start chapter, start verse, start subverse, end chapter, end verse, and end subverse.
+Each range also has `original_text: Optional[str]`: this is the text from which the range was parsed, if any.
+The class stores a list of such ranges, a book ID, and the `original_text` from which the book ID was parsed.
+Book IDs are the three-letter codes used by Paratext, e.g., "GEN", "1CO", or "JHN".
+The start and end chapter numbers will almost always be the same, but the volume of data is probably not large enough to justify complicating the code by optimizing for that.
+Similarly, subverse divisions (e.g., "a" or "d") will often not be used: when there is none, the subverse will be an empty string.
+We can just store all six values for each range, even in the trivial case where the range is a single verse.
+Chapter and verse numbers are `int`s: on careful consideration, we never need to use strings for either.
+Although some Bible translations use letters for "chapter numbers" (e.g., Greek Esther in Rahlfs and NAB), we don't need to support that explicitly: Paratext's scheme represents these as numbered chapters with a different book name (ESG instead of EST).
+The rare case of verse numbers like "4kk" can be represented as verse 4, subverse "kk": that is how it would parse anyway.
+As a special case, a `SimpleBibleRef` with an empty list of ranges refers to the entire book.
+The constructor takes a book ID and an `original_text`, which defaults to `None`.
+
+## BibleRef
+
+An instance of `BibleRef` represents a sequence of verse ranges within a one or more books of the Bible.
+It holds an array of `SimpleBibleRef` and the `Versification` they use.
+
+## Versification
+
+An instance of `Versification` represents a way of dividing the text of the Bible into chapters and verses.
+Versifications are defined by JSON data that is loaded from a file when an instance is created.
+Alternatively, the JSON data could be converted to Python data and stored as constants in code.
+The `last_verse(book, chapter)` method returns the integer number of the last verse of the given chapter of the given book.
+If the book is unknown or the chapter does not exist, it returns -1.
+An initial, trivial implementation will not load a data file and will simply return 99 from `last_verse()` regardless of its arguments.
+Support for mapping verses between versifications can be added at a later stage.
+
+For versification data, we can use JSON files from a [UBSCAP GitHub repo](https://github.com/ubsicap/versification_json).
+These are under an MIT license.
+As the README notes, some of the files contain errors: there are mappings from verses that do not exist according to the max verse counts.
+However, it seems the best starting point available, and those known errors will be harmless because such mappings will never be applied.
+There's a JSON schema in the repo that can be used for validation.
+The `maxVerses` property of the top-level object contains the data `last_verse()` must return.
+
+The JSON files have data for Paratext's seven standard versifications.
+Mappings are defined relative to the mapping called "Original" (`org.json`) for lack of a better name: This uses the BHS OT, the UBS GNT NT, and the "Catholic" deuterocanon.
+
+It would not be hard to derive `maxVerses` and `excludedVerses` data for specific Bibles from verse lists exported from Accordance.
+Mappings for these Bibles are an open question.
+
+### Mapping verses between versifications
+
+This would have to be done one range at a time, mapping the start and end of each.
+When mapping a range start, if the location maps to a range, we pick the start of the range.
+When mapping a range end, if the location maps to a range, we pick the end of the range.
+For example, if 1KI 18:33 maps to 1KI 18:33-34 and we are mapping a range that starts at 1KI 18:33, then the mapped range starts at 1KI 18:33.
+But if we are mapping a range that ends at 1KI 18:33, then the mapped range ends at 1KI 18:34.
+However, we might not at first need code to handle the case where a location maps to a range, since it seems Paratext doesn't handle that. Consequently, its files don't define such mappings, even though there are cases in which they ought to be used.
+
+## Style
+
+A `Style` defines how a `SimpleBibleRef` or `BibleRef` is converted to a string and how strings are parsed to produce these classes.
+
+* `names`: maps Bible book IDs to string abbreviations or to full names, depending on the style.
+* `chapter_verse_separator`: Separates chapter number from verse ranges Defaults to ":".
+* `verse_range_separator`: Separates ranges of verses in a single chapter. Defaults to ", ".
+* `chapter_separator`: Defaults to "; ".
+* `recognized_names`: maps abbreviations and/or full names to Bible book IDs. For flexibility in parsing, this typically recognizes additional abbreviations beyond those used in `names`. It defaults to the inverse of `names`.
+
+### Named sets of book names/abbreviations
+
+We need to have a way of supplying named sets of book names and book name abbreviations, so users can select, e.g., short SBL abbreviations.
+These sets are simply dictionaries, but perhaps we need to store them in files or allow users to define their own set of abbreviations in a file.
+
+### Bible IDs that require special handling
+
+* PSA: we need to allow for both a singular and a plural form. The latter can be coded in abbreviation lists as PSAS, e.g., `"PSA": "Psalm", "PSAS": "Psalms"
+* PS2: this is Psalm 151. It uses the PSA abbreviation (or PSAS when referenced with other psalms). Any abbreviation defined for PS2 will be ignored. Perhaps we should issue a warning if it's defined.
+* ESG: this is Greek portions of Esther. Special handling may be required when it uses the same name as EST but letters for chapters (e.g., NABRE).
+
+## RefParser
+
+The constructor takes a `Style` and builds a PEG parser that recognizes Bible references in that style.
+Whitespace is generally ignored by the parser (default for `pyparser`).
+Various methods support parsing a whole string to a `SimpleBibleRef` or `BibleRef`, scanning a long string for references, and transforming a long string (e.g., to tag references).

versiref-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michael F. Polis
+
+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.

versiref-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: versiref
+Version: 0.1.0
+Summary: A package for sophisticated parsing, manipulation, and printing of references to the Bible
+Project-URL: Homepage, https://github.com/fiapps/versiref
+Project-URL: Issues, https://github.com/fiapps/versiref/issues
+Author-email: "Fr. John Lawrence M. Polis" <emptier-sank-dose@duck.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Religion
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Religion
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Requires-Dist: pyparsing>=3.2.3
+Description-Content-Type: text/markdown
+
+# VersiRef
+
+VersiRef is a Python package for sophisticated parsing, manipulation, and printing of references to the Bible.
+
+## Features
+
+- Parse and manipulate Bible references.
+- Support for different versification systems (e.g., original language \[BHS + UBS GNT\], "English," LXX, Vulgate).
+- Query information about chapters and verses in different books of the Bible.
+
+## Overview of `versiref` classes
+
+- `BibleRef` represents a sequence of verse ranges within one or more books of the Bible.
+    - It has a `Versification` and a list of `SimpleBibleRef`s.
+- `Versification` represents a division of the Bible into chapters and verses. Different texts of the Bible do this differently.
+- `SimpleBibleRef` represents a sequence of verse ranges within a single book of the Bible.
+    - It can be used independently of a `BibleRef`, but since it has no `Versification`, you need to supply a `Versification` for all operations that require one.
+    - It contains a list of `VerseRange`s: this is a data class not intended to be used independently.
+- `RefStyle` defines separators and book names or abbreviations to use in formatting or parsing a reference.
+    - This gives the package the versatility to handle different styles and languages.
+- `RefParser` creates PEG parsers based on a `RefStyle` and `Versification`.
+    - These can be used to parse a single reference or to find all references in a long string, e.g., the content of a text file.
+
+## Examples
+
+### Convert references from one style to another
+
+```python
+from pyparsing import ParseException
+from versiref import RefParser, RefStyle, standard_names, Versification
+
+def parse_reference(reference: str) -> None:
+    """Parse argument and print result."""
+    # Expect SBL abbreviations in the input
+    sbl_abbrevs = standard_names("en-sbl_abbreviations")
+    sbl_style = RefStyle(names=sbl_abbrevs)
+    # Use typical versification for English Bibles
+    versification = Versification.named("eng")
+    # Build parser for style
+    parser = RefParser(sbl_style, versification)
+    # Use Italian CEI Bible style for output
+    cei_abbrevs = standard_names("it-cei_abbreviazioni")
+    cei_style = RefStyle(names=cei_abbrevs, chapter_verse_separator=",", verse_range_separator=".")
+    try:
+        ref = parser.parse(reference, silent=False)
+        # Check whether it refers to verse ranges that exist
+        if not ref.is_valid():
+            print(f"Warning: {reference} is not a valid reference.")
+        print(ref.format(cei_style))
+    except ParseException as e:
+        print(f"Could not parse reference: {reference}")
+        print(e)
+
+# Prints "Gv 7,53–8,11"
+parse_reference("John 7:53–8:11")
+```
+
+### Look for references in a string
+
+```python
+from versiref import RefParser, RefStyle, Versification, standard_names
+
+def scan_string(content: str) -> None:
+    """Count and print the Bible references in content."""
+    # Use SBL abbreviations
+    sbl_abbrevs = standard_names("en-sbl_abbreviations")
+    style = RefStyle(names=sbl_abbrevs)
+    # But also recognize abbreviations from the Chicago Manual of Style
+    style.also_recognize("en-cmos_short")
+    # Use typical versification for English Bibles
+    versification = Versification.named("eng")
+    # Build parser for style
+    parser = RefParser(style, versification)
+    count = 0
+    for ref, start, end in parser.scan_string(content):
+        # Check for out-of-range chapter or verse
+        if not ref.is_valid():
+            print(f"Warning: {ref.format(style)} is not a valid reference.")
+        else:
+            # Print in SBL style
+            print(ref.format(style))
+        count += 1
+    print(f"Found {count} references.")
+
+text = """
+Today's readings are Acts 2:1-11; Ps 104:1,24,29-30,31,34; 1 Cor 12:3b-7,12-13; Jn 20:19-23.
+The prophecy in Is 7:10-14 is important background for Lk 1:26-38.
+The Septuagint has a Ps 118:120, but English Bibles don't.
+"""
+scan_string(text)
+```
+
+Output:
+
+```
+Acts 2:1–11; Ps 104:1, 24, 29–30, 31, 34; 1 Cor 12:3b–7, 12–13; John 20:19–23
+Isa 7:10–14
+Luke 1:26–38
+Warning: Ps 118:120 is not a valid reference.
+Found 4 references.
+```

versiref-0.1.0/README.md

@@ -0,0 +1,101 @@
+# VersiRef
+
+VersiRef is a Python package for sophisticated parsing, manipulation, and printing of references to the Bible.
+
+## Features
+
+- Parse and manipulate Bible references.
+- Support for different versification systems (e.g., original language \[BHS + UBS GNT\], "English," LXX, Vulgate).
+- Query information about chapters and verses in different books of the Bible.
+
+## Overview of `versiref` classes
+
+- `BibleRef` represents a sequence of verse ranges within one or more books of the Bible.
+    - It has a `Versification` and a list of `SimpleBibleRef`s.
+- `Versification` represents a division of the Bible into chapters and verses. Different texts of the Bible do this differently.
+- `SimpleBibleRef` represents a sequence of verse ranges within a single book of the Bible.
+    - It can be used independently of a `BibleRef`, but since it has no `Versification`, you need to supply a `Versification` for all operations that require one.
+    - It contains a list of `VerseRange`s: this is a data class not intended to be used independently.
+- `RefStyle` defines separators and book names or abbreviations to use in formatting or parsing a reference.
+    - This gives the package the versatility to handle different styles and languages.
+- `RefParser` creates PEG parsers based on a `RefStyle` and `Versification`.
+    - These can be used to parse a single reference or to find all references in a long string, e.g., the content of a text file.
+
+## Examples
+
+### Convert references from one style to another
+
+```python
+from pyparsing import ParseException
+from versiref import RefParser, RefStyle, standard_names, Versification
+
+def parse_reference(reference: str) -> None:
+    """Parse argument and print result."""
+    # Expect SBL abbreviations in the input
+    sbl_abbrevs = standard_names("en-sbl_abbreviations")
+    sbl_style = RefStyle(names=sbl_abbrevs)
+    # Use typical versification for English Bibles
+    versification = Versification.named("eng")
+    # Build parser for style
+    parser = RefParser(sbl_style, versification)
+    # Use Italian CEI Bible style for output
+    cei_abbrevs = standard_names("it-cei_abbreviazioni")
+    cei_style = RefStyle(names=cei_abbrevs, chapter_verse_separator=",", verse_range_separator=".")
+    try:
+        ref = parser.parse(reference, silent=False)
+        # Check whether it refers to verse ranges that exist
+        if not ref.is_valid():
+            print(f"Warning: {reference} is not a valid reference.")
+        print(ref.format(cei_style))
+    except ParseException as e:
+        print(f"Could not parse reference: {reference}")
+        print(e)
+
+# Prints "Gv 7,53–8,11"
+parse_reference("John 7:53–8:11")
+```
+
+### Look for references in a string
+
+```python
+from versiref import RefParser, RefStyle, Versification, standard_names
+
+def scan_string(content: str) -> None:
+    """Count and print the Bible references in content."""
+    # Use SBL abbreviations
+    sbl_abbrevs = standard_names("en-sbl_abbreviations")
+    style = RefStyle(names=sbl_abbrevs)
+    # But also recognize abbreviations from the Chicago Manual of Style
+    style.also_recognize("en-cmos_short")
+    # Use typical versification for English Bibles
+    versification = Versification.named("eng")
+    # Build parser for style
+    parser = RefParser(style, versification)
+    count = 0
+    for ref, start, end in parser.scan_string(content):
+        # Check for out-of-range chapter or verse
+        if not ref.is_valid():
+            print(f"Warning: {ref.format(style)} is not a valid reference.")
+        else:
+            # Print in SBL style
+            print(ref.format(style))
+        count += 1
+    print(f"Found {count} references.")
+
+text = """
+Today's readings are Acts 2:1-11; Ps 104:1,24,29-30,31,34; 1 Cor 12:3b-7,12-13; Jn 20:19-23.
+The prophecy in Is 7:10-14 is important background for Lk 1:26-38.
+The Septuagint has a Ps 118:120, but English Bibles don't.
+"""
+scan_string(text)
+```
+
+Output:
+
+```
+Acts 2:1–11; Ps 104:1, 24, 29–30, 31, 34; 1 Cor 12:3b–7, 12–13; John 20:19–23
+Isa 7:10–14
+Luke 1:26–38
+Warning: Ps 118:120 is not a valid reference.
+Found 4 references.
+```

versiref-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "versiref"
+version = "0.1.0"
+description = "A package for sophisticated parsing, manipulation, and printing of references to the Bible"
+readme = "README.md"
+authors = [
+    { name = "Fr. John Lawrence M. Polis", email = "emptier-sank-dose@duck.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Religion",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Religion",
+    "Topic :: Text Processing",
+]
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+    "pyparsing>=3.2.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/fiapps/versiref"
+Issues = "https://github.com/fiapps/versiref/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/versiref"]
+
+[tool.hatch.build.targets.wheel.sources]
+"data" = "src/versiref/data"
+
+[tool.mypy]
+strict = true
+exclude = [
+    'build',
+]
+
+[tool.ruff.lint]
+select = ["D"]
+ignore = ["D203", "D213"]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[dependency-groups]
+dev = [
+    "mypy>=1.15.0",
+    "pytest>=8.3.5",
+    "ruff>=0.11.4",
+]

versiref-0.1.0/src/versiref/__init__.py

@@ -0,0 +1,21 @@
+"""versiref can parse, manipulate, and format references to Bible verses.
+
+It is versatile in that it can handle complex references, different
+versifications, and it is flexible about the format is parses and the output it
+generates.
+"""
+
+from versiref.bible_ref import BibleRef, SimpleBibleRef, VerseRange
+from versiref.ref_parser import RefParser
+from versiref.ref_style import RefStyle, standard_names
+from versiref.versification import Versification
+
+__all__ = [
+    "BibleRef",
+    "SimpleBibleRef",
+    "VerseRange",
+    "RefParser",
+    "RefStyle",
+    "Versification",
+    "standard_names",
+]