versiref 0.1.0__py3-none-any.whl

versiref/ref_style.py

@@ -0,0 +1,127 @@
+"""RefStyle definitions for Bible reference formatting and parsing.
+
+This module provides the RefStyle class which defines how Bible references
+are converted to and from strings.
+"""
+
+import json
+from dataclasses import dataclass, field
+from importlib import resources
+from typing import Union
+
+
+def _invert(d: dict[str, str]) -> dict[str, str]:
+    """Invert an ID->name dictionary, resolving conflicts if possible.
+
+    In the event of a PSA/PSAS conflict or a EST/ESG conflict, the former of the
+    pair is preferred. Any other conflict will raise a ValueError.
+    """
+    inverted: dict[str, str] = {}
+    for k, v in d.items():
+        if v in inverted:
+            if inverted[v] == "PSA" or inverted[v] == "PSAS":
+                inverted[v] = "PSA"
+            elif inverted[v] == "EST" or inverted[v] == "ESG":
+                inverted[v] = "EST"
+            else:
+                raise ValueError(f"Both {inverted[v]} and {k} are abbreviated as {v}.")
+        else:
+            inverted[v] = k
+    return inverted
+
+
+@dataclass
+class RefStyle:
+    """Defines how a SimpleBibleRef is converted to and from strings.
+
+    A RefStyle primarily holds data that specifies the formatting conventions
+    for Bible references. Formatting and parsing is done by other classes
+    that use a RefStyle as a specification.
+
+    Attributes:
+        names: Maps Bible book IDs to string abbreviations or full names
+        chapter_verse_separator: Separates chapter number from verse ranges
+        range_separator: Separates the ends of a range. Defaults to an en dash.
+        following_verse: indicates the range ends at the verse following the start
+        following_verses: indicates the range continues for an unspecified number of verses
+        verse_range_separator: Separates ranges of verses in a single chapter
+        chapter_separator: Separates ranges of verses in different chapters
+        recognized_names: Maps abbreviations/names to Bible book IDs for parsing
+
+    """
+
+    names: dict[str, str]
+    chapter_verse_separator: str = ":"
+    range_separator: str = "–"
+    following_verse: str = "f"
+    following_verses: str = "ff"
+    verse_range_separator: str = ", "
+    chapter_separator: str = "; "
+    recognized_names: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Initialize recognized_names if not provided.
+
+        By default, recognized_names is the inverse of names, allowing
+        parsing of the same abbreviations used for formatting.
+        """
+        if not self.recognized_names:
+            self.recognized_names = _invert(self.names)
+
+    def also_recognize(self, names: Union[dict[str, str], str]) -> None:
+        """Add a set of book names to the recognized_names mapping.
+
+        In the event of a conflict, the existing name will be preferred.
+
+        Args:
+            names: Either dictionary mapping names or abbreviations to book IDs
+            or a string that names a standard set of names, e.g.,
+            "en-sbl_abbreviations".
+
+        """
+        if isinstance(names, str):
+            names = _invert(standard_names(names))
+        self.recognized_names.update(
+            {
+                name: id
+                for name, id in names.items()
+                if name not in self.recognized_names
+            }
+        )
+
+
+def standard_names(identifier: str) -> dict[str, str]:
+    """Load and return a standard set of book names.
+
+    These can be passed to RefStyle(). Since the return value is freshly
+    created, it can be modified to customize the abbreviations (e.g,
+    names["SNG"] = "Cant") without fear of changing the set of names for other
+    callers.
+
+    Args:
+        identifier: The identifier for the names file, e.g.,
+        "en-sbl_abbreviations"
+
+    Returns:
+        A dictionary mapping book IDs to names or abbreviations.
+
+    Raises:
+        FileNotFoundError: If the names file doesn't exist
+        json.JSONDecodeError: if the file contains invalid JSON
+        ValueError: If the JSON is not in the expected format
+        The latter two represent internal errors in the package.
+
+    """
+    # Use importlib.resources to find the file
+    data = json.loads(
+        resources.files("versiref")
+        .joinpath("data", "book_names", f"{identifier}.json")
+        .read_text()
+    )
+    if not isinstance(data, dict):
+        raise ValueError(f"Invalid format in {identifier}.json: not a dictionary")
+    if not all(isinstance(k, str) and isinstance(v, str) for k, v in data.items()):
+        raise ValueError(
+            f"Invalid format in {identifier}.json: all keys and values must be strings"
+        )
+    return data

versiref/versification.py

@@ -0,0 +1,135 @@
+"""Versification class for handling Bible chapter and verse divisions."""
+
+import json
+from dataclasses import dataclass, field
+from importlib import resources
+from typing import Optional
+
+
+@dataclass
+class 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.
+    The class provides methods to query information about the versification, such as the last verse
+    of a given chapter in a given book.
+    """
+
+    max_verses: dict[str, list[int]] = field(default_factory=dict)
+    identifier: Optional[str] = None
+
+    @classmethod
+    def from_file(
+        cls, file_path: str, identifier: Optional[str] = None
+    ) -> "Versification":
+        """Create an instance from a JSON file.
+
+        Args:
+            file_path: path to a JSON file containing an object with maxVerses
+            identifier: identifier to store in the constructed Versififaction
+        Raises:
+            FileNotFoundError: file_path does not exist
+            json.JSONDecodeError: file_path is not well-formed JSON
+            ValueError: file_path does not match schema
+        Returns:
+            Newly constructed Versification
+
+        """
+        with open(file_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if "maxVerses" in data:
+            # Convert string verse counts to integers
+            max_verses = {}
+            for book, verses in data["maxVerses"].items():
+                max_verses[book] = [int(v) for v in verses]
+            return cls(max_verses, identifier)
+        else:
+            raise ValueError("Versification file does not match schema")
+
+    @classmethod
+    def named(cls, identifier: str) -> "Versification":
+        """Create an instance of a standard versification.
+
+        Constructs an instance by loading JSON data from the package's data
+        directory.
+
+        Args:
+            identifier: Standard versification identifier (e.g., "org", "eng",
+            "LXX", "Vulgata")
+                This is converted to lowercase to find the file to load.
+
+        Raises:
+            FileNotFoundError: If the named file doesn't exist
+            json.JSONDecodeError: if the file contains invalid JSON ValueError: If the JSON is not in the expected format
+            The latter two represent internal errors in the package.
+
+        Returns:
+            A newly constructed Versification
+
+        """
+        filename = f"{identifier.lower()}.json"
+
+        path = resources.files("versiref").joinpath("data", "versifications", filename)
+        if path.is_file():
+            return cls.from_file(str(path), identifier)
+        else:
+            raise FileNotFoundError(f"Unknown versification identifier: {identifier}")
+
+    def includes(self, book_id: str) -> bool:
+        """Check if the given book ID is included in this versification.
+
+        Args:
+            book_id: The book ID (using Paratext three-letter codes)
+
+        Returns:
+            True if the book is included in this versification, False otherwise.
+
+        """
+        if book_id == "PSAS":  # Plural form of PSA
+            book_id = "PSA"
+        return book_id in self.max_verses
+
+    def is_single_chapter(self, book: str) -> bool:
+        """Check if the given book is a single-chapter book.
+
+        Args:
+            book: The book ID (using Paratext three-letter codes)
+
+        Returns:
+            True if the book has only one chapter, False otherwise.
+
+        """
+        if book not in self.max_verses:
+            return False
+        # The plural form of PSA requires special handling.
+        if book == "PSAS":
+            book = "PSA"
+        return len(self.max_verses[book]) == 1
+
+    def last_verse(self, book: str, chapter: int) -> int:
+        """Return the number of the last verse of the given chapter of the given book.
+
+        Args:
+            book: The book ID (using Paratext three-letter codes)
+            chapter: The chapter number
+
+        Returns:
+            The number of the last verse, or -1 if the book or chapter doesn't exist
+
+        """
+        # Trivial implementation returns 99 for any book and chapter
+        if not self.max_verses:
+            return 99
+
+        # Check if the book exists in the versification
+        if book == "PSAS":  # plural of PSA
+            book = "PSA"
+        if book not in self.max_verses:
+            return -1
+
+        # Check if the chapter exists in the book
+        if chapter < 0 or chapter > len(self.max_verses[book]):
+            return -1
+
+        # Return the verse count as an integer
+        return self.max_verses[book][chapter - 1]

versiref-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,24 @@
+versiref/__init__.py,sha256=3uQ8CnJzBRxQLgoi52Mo4enh3MvarDyya9SVzZdDrp4,601
+versiref/bible_ref.py,sha256=12H25dlIBbZWElsQYNz_ZujFOzr0TXncuDB_23edjW8,16067
+versiref/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+versiref/ref_parser.py,sha256=ef359WpR_tlTumym28_MaH6Zp0dyVixTEm8eHkmIyqQ,22266
+versiref/ref_style.py,sha256=iRPCPqbgJDDvRPmFixLU2IGMDA0inMOZ3mdAB57354Q,4672
+versiref/versification.py,sha256=FQsKJ35YspRLBzkjWSRs6jVOVx1xVqELICJYGQW3LGk,4712
+versiref/data/book_names/en-cmos_long.json,sha256=nxSutcEoBVXHvA3UwzKi3Y8z7NEqr_8lTAMelsoDSWc,1517
+versiref/data/book_names/en-cmos_short.json,sha256=8ZO3d3wXGL3FSYj38PBdepjOkbQoSPBNq8_zw-PDGTc,1403
+versiref/data/book_names/en-sbl_abbreviations.json,sha256=8GenBCjOqFUbH25Kzw1eaxb2LMxqJBh8F0UI5peqhzc,1575
+versiref/data/book_names/en-sbl_names.json,sha256=DL3EnhZzAlvYQW0m7rRfrZhDWakVaWrMk5Y-nSivnjQ,1979
+versiref/data/book_names/it-cei_abbreviazioni.json,sha256=U9j2SkqMjJfKb9QHz0rjxjZov6Da7p4tGqDd5p34Sf0,1157
+versiref/data/book_names/it-cei_nomi.json,sha256=oDAmVxZF-8bvjsUb0uU1KpYFaqHE3Qv887ttY_FWTiI,1524
+versiref/data/versifications/eng.json,sha256=UWICP44GBPzpaknX-4zqc-9pmSiEbRDWIhC9SILoEzg,27681
+versiref/data/versifications/lxx.json,sha256=SWYDojZV6Wub4wFCt1snrpxp5LTZXPYKwgpvSejR9Ak,33953
+versiref/data/versifications/nabre.json,sha256=K66K6csQhh5TssMFz9Tsmnu-X04dkea-VEt7q8seFjk,15468
+versiref/data/versifications/nova-vulgata.json,sha256=4J6gAuiaqGzfvdTLabH_LHUHCAHgZIw3rvWA1PyNBqA,33317
+versiref/data/versifications/org.json,sha256=O44GX7WSEAJl_5686nH1N2kn-gPAhYRPMFjUY6Lpysc,21077
+versiref/data/versifications/rsc.json,sha256=znZgOjXbV_0OD9A3Oqxu9N-luzjwjXmlv67JiGsxPok,23139
+versiref/data/versifications/rso.json,sha256=Re9PapvlfZs-bogtcEmRp8Sxtk2ftWGoQkAbqIJjNAU,29748
+versiref/data/versifications/vulgata.json,sha256=MI4u2oQbBhPchjuJOunUsNJg1MeAqStPF7DcU42w-MY,33617
+versiref-0.1.0.dist-info/METADATA,sha256=WAzGnjJaNnFLL4r0sWT2v-EdNhYEEH6l8xrV7lK0LWw,5228
+versiref-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+versiref-0.1.0.dist-info/licenses/LICENSE,sha256=15zx8RJP7jG7okR50pC9aCpkaWcCzGDBzKif3PMBXPo,1073
+versiref-0.1.0.dist-info/RECORD,,

versiref-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

versiref-0.1.0.dist-info/licenses/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.