python-scriptures 2.1.2

python-scriptures is a Python package and regular expression library for validating, extracting, and normalizing biblical scripture references from blocks of text.

python-scriptures is a Python 2 and Python 3 compatible package and regular expression library for validating, extracting and normalizing biblical scripture references from blocks of text.

For more information, see http://www.davisd.com/projects/python-scriptures/

Typical usage is as follows:

#!/usr/bin/env python

>>> import scriptures
>>> scriptures.extract('This is a test Rom 3:23-28 and 1 JOHn 2')
[('Romans', 3, 23, 3, 28), ('I John', 2, 1, 2, 29)]

Range validation is performed automatically and invalid references are not extracted.

>>> import scriptures
>>> scriptures.extract('Romans 3:23 is real, but Romans 2:30 is invalid.')
[('Romans', 3, 23, 3, 23)]

Multi-Chapter references work:

>>> import scriptures
>>> scriptures.extract('You can specify a range of chapters like Rev 2-3')
[('Revelation of Jesus Christ', 2, 1, 3, 22)]

References with single chapter books do not require the chapter be specified.

>>> import scriptures
>>> scriptures.extract('You can specify a single verse such as Jude 4')
[('Jude', 1, 4, 1, 4)]
>>> scriptures.extract('Or specify multiple verses with jude 2-5...')
[('Jude', 1, 2, 1, 5)]

Installation

A setup script (setup.py) is provided. To install, simply run the script with the install command:

$ python setup.py install

Or just put the scriptures package somewhere on the Python path.

API

Return Values

When a “scripture reference” is returned, it is always a five value tuple consisting of:

(‘Book name’, start chapter, start verse, end chapter, end verse)

Functions

There are four public functions exposed by this package.

extract

Extract a list of tupled scripture references from a block of text.

Arguments:

text – the block of text containing potential scripture references

Example:

>>> import scriptures
>>> scriptures.extract('This is a test Rom 3:23-28 and 1 JOHn 2')
[('Romans', 3, 23, 3, 28), ('I John', 2, 1, 2, 29)]

reference_to_string

Get a display friendly string from a scripture reference.

Arguments:

bookname – the full or abbreviated book name

chapter – the starting chapter

Optional Arguments:

verse – the starting verse

end_chapter – the ending chapter

end_verse – the ending verse

Examples:

>>> import scriptures
>>> scriptures.reference_to_string('acts', 1)
'Acts 1'
>>> scriptures.reference_to_string('John', 3, 16)
'John 3:16'
>>> scriptures.reference_to_string('Rom', 3, 23, 3, 28)
'Romans 3:23-28'
>>> scriptures.reference_to_string('ecc', 1, 2, 2)
'Ecclesiastes 1:2-2:26'

Single Chapter Book Examples:

>>> import scriptures
>>> scriptures.reference_to_string('jude', 1, 4)
'Jude 4'
>>> scriptures.reference_to_string('2john', 1, 4, 1, 7)
'II John 4-7'

normalize_reference

Get a complete five value tuple scripture reference with full book name from partial data.

Arguments:

bookname – the full or abbreviated book name

chapter – the starting chapter

Optional Arguments:

verse – the starting verse

end_chapter – the ending chapter

end_verse – the ending verse

Examples:

>>> import scriptures
>>> scriptures.normalize_reference('acts', 1)
('Acts', 1, 1, 1, 26)
>>> scriptures.normalize_reference('John', 3, 16)
('John', 3, 16, 3, 16)
>>> scriptures.normalize_reference('Rom', 3, 23, 3, 28)
('Romans', 3, 23, 3, 28)
>>> scriptures.normalize_reference('ecc', 1, 2, 2)
('Ecclesiastes', 1, 2, 2, 26)

is_valid_reference

Check to see if a scripture reference is valid.

Arguments:

bookname – the full or abbreviated book name

chapter – the starting chapter

Optional Arguments:

verse – the starting verse

end_chapter – the ending chapter

end_verse – the ending verse

Examples:

>>> import scriptures
>>> scriptures.is_valid_reference('John', 3, 16)
True
>>> scriptures.is_valid_reference('ecc', 1, 2, 2)
True
>>> scriptures.is_valid_reference('Romans', 2, 30)
False
>>> scriptures.is_valid_reference('Romans', 2, 20, 2, 29)
True

Regular Expressions

There are two compiled regular expression patterns exposed by this package.

book_re

Match a valid abbreviation or book name.

Examples:

>>> import scriptures
>>> import re
>>> re.findall(scriptures.book_re, 'Matt test Ecclesiastes and 2 peter')
['Matt', 'Ecclesiastes', '2 peter']

scripture_re

Match a scripture reference pattern from a valid abbreviation or book name.

Examples:

>>> import scriptures
>>> import re
>>> re.findall(scriptures.scripture_re, 'Matt 3 & Acts 1:2-3 Rev 2:1-3:2')
[('Matt', '3', '', '', ''), ('Acts', '1', '2', '', '3'),
('Rev', '2', '1', '3', '2')]

Unicode

This library is unicode compatible and recognizes the u2013 en dash and u2014 em dash.

Author

David Davis <[e-mail]> http://www.davisd.com