Getting Started

Installation

To install, use your favorite package manager and do the equivalent of:

pip install vref-utils

Usage

from vref_utils import Vref

niv = Vref("./en-NIV11.txt")

jhn3v16 = niv["JHN 3:16"][0]
print(jhn3v16)
# For God so loved the world that he gave his one and only Son, that whoever believes in him shall not perish but have eternal life.

Note that __get_item__ (the function called by niv["JHN 3:16"]) returns a VerseList. The VerseList class allows us to iterate through the verses using a generator, but we can also access elements using indices or slices. Here, we use [0] to get the first (and only) Verse.

print(repr(jhn3v16))
# Verse(verse="JHN 3:16", text="For God so loved the world that he gave his one and only Son, that whoever believes in him shall not perish but have eternal life.")

The Verse class supports the __str__ and __repr__ methods. So casting the first element to a string by printing it prints the text. You can also return the verse text using the .text attribute. Likewise, you can get the verse reference using the .reference attribute.

print(jhn3v16.text)
# For God so loved the world that he gave his one and only Son, that whoever believes in him shall not perish but have eternal life.

print(jhn3v16.reference)
# JHN 3:16

Printing the reference is not useful when there is only one verse, but you can select multiple verses using ranges like "JHN 3:16-JHN 3:17" or selections like "JHN 3:16,JHN 3:17" or a combination of both like "JHN 3:16,JHN 3:17-JHN 3:18".

print(niv["JHN 3:16-JHN 3:17,JHN 3:18"])
# VerseList([
#   Verse(verse="JHN 3:16", text="For God so loved the world that he gave his one and only Son,..."),
#   Verse(verse="JHN 3:17", text="For God did not send his Son into the world to condemn the wo..."),
#   Verse(verse="JHN 3:18", text="Whoever believes in him is not condemned, but whoever does no...")
# ])

Note:

• Book names must be valid USFM book names.
• Chapter and verse numbers must be valid.
• Books and chapters must be specified in full for ranges/selections.
  • ❌ JHN 1:1-2
  • ❌ JHN 1:1-1:2
  • ✅ JHN 1:1-JHN 1:2
• May include multiple ranges/selections separated by ",".
  • ✅ JHN 1:1-JHN 1:2,JHN 1:4

Custom Versification Formats

By default, the org versification system is used (and packaged in vref-utils). If you have vref files that use a different versification system, you can specify it when creating the Vref object.

from vref_utils import Vref

niv = Vref("./en-NIV11.txt", "custom_vref.txt")
# or, with named arguments:
niv = Vref("./en-MYBIBLE.txt", versification_vref_path="custom_vref.txt")

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
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

(back to top)

License

Distributed under the MIT License. See LICENSE.md for more information.

(back to top)