djangobible 0.0.16__py3-none-any.whl → 0.3.0__py3-none-any.whl

djangobible/__init__.py

@@ -1,9 +1,11 @@
-"""
-djangobible python library.
-
-djangobible lets you easily associate Django models with Bible Scripture references and search accordingly.
-"""
-
-__version__ = "0.0.16"
-
-from pythonbible import *
+"""djangobible python library.
+
+djangobible lets you easily associate Django models with Bible Scripture references and
+search accordingly.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.3.0"
+
+from pythonbible import *

djangobible/apps.py

@@ -1,5 +1,11 @@
-from django.apps import AppConfig
-
-
-class DjangoBibleConfig(AppConfig):
-    name: str = "djangobible"
+"""The app config for the djangobible library."""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class DjangoBibleConfig(AppConfig):
+    """The app config for the djangobible library."""
+
+    name: str = "djangobible"

djangobible/fields.py

@@ -1,58 +1,99 @@
-from typing import Callable, List, Optional, Union
-
-import pythonbible as bible
-from django import forms
-from django.db import models
-from django.utils.functional import cached_property
-
-from .validators import validate_verse
-
-
-class VerseField(models.IntegerField):
-    def get_prep_value(self, value):
-        if value is None:
-            return None
-
-        if isinstance(value, str):
-            validate_verse(value)
-            value = bible.convert_references_to_verse_ids(bible.get_references(value))[
-                0
-            ]
-
-        return super().get_prep_value(value)
-
-    @cached_property
-    def validators(self) -> List[Callable]:
-        return [validate_verse]
-
-    def to_python(self, value: Optional[Union[int, str]]) -> Optional[str]:
-        if value is None or isinstance(value, str):
-            return value
-
-        return bible.format_scripture_references(
-            bible.convert_verse_ids_to_references([value])
-        )
-
-    def from_db_value(
-        self, value: Optional[Union[int, str]], expression, connection
-    ) -> Optional[str]:
-        return self.to_python(value)
-
-    def formfield(self, **kwargs) -> forms.Field:
-        return super().formfield(
-            **{
-                "form_class": forms.CharField,
-                **kwargs,
-            }
-        )
-
-    def get_db_prep_value(
-        self, value: Optional[Union[int, str]], *args, **kwargs
-    ) -> Optional[int]:
-        if value is None:
-            return None
-
-        if isinstance(value, int):
-            return value
-
-        return bible.convert_references_to_verse_ids(bible.get_references(value))[0]
+"""Custom Django model fields for djangobible."""
+
+from __future__ import annotations
+
+from typing import Any
+from typing import Callable
+
+import pythonbible as bible
+from django import forms
+from django.core.exceptions import ValidationError
+from django.db import models
+from django.utils.functional import cached_property
+
+from djangobible.validators import validate_verse
+
+
+class VerseField(models.Field):
+    """Custom Django model field to represent a Verse."""
+
+    def get_prep_value(self: VerseField, value: int | str | None) -> int:
+        """Validate and convert the value to a verse id int."""
+        if isinstance(value, str):
+            validate_verse(value)
+            value = bible.convert_references_to_verse_ids(
+                bible.get_references(value),
+            )[0]
+        elif isinstance(value, int) and not bible.is_valid_verse_id(value):
+            error_message = f"{value} is not a valid verse id."
+            raise ValidationError(error_message)
+
+        return super().get_prep_value(value)
+
+    @cached_property
+    def validators(self: VerseField) -> list[Callable]:
+        """Return the list of validators for this field."""
+        return [validate_verse]
+
+    def to_python(
+        self: VerseField,
+        value: int | str | None,
+    ) -> str | None:
+        """Convert the value into a text scripture reference."""
+        if value is None or isinstance(value, str):
+            return value
+
+        return bible.format_scripture_references(
+            bible.convert_verse_ids_to_references([value]),
+        )
+
+    def from_db_value(
+        self: VerseField,
+        value: int | str | None,
+        expression: Any,
+        connection: Any,
+    ) -> str | None:
+        """Convert the value from the DB."""
+        return self.to_python(value)
+
+    def formfield(
+        self: VerseField,
+        form_class: type[forms.Field] | None = None,
+        choices_form_class: type[forms.Field] | None = None,
+        **kwargs: Any,
+    ) -> forms.Field:
+        """Make sure the form field is a CharField."""
+        return super().formfield(
+            **{
+                "form_class": forms.CharField,
+                **kwargs,
+            },
+        )
+
+    def get_db_prep_save(
+        self: VerseField,
+        value: int | str | None,
+        **kwargs: Any,
+    ) -> int | None:
+        """Validate and convert the value to a verse id int before saving to the DB."""
+        if not value:
+            return None
+
+        if isinstance(value, str):
+            references = bible.get_references(value)
+
+            if verse_ids := bible.convert_references_to_verse_ids(references):
+                value = verse_ids[0]
+            else:
+                error_message = f"{value} does not contain a valid Scripture reference."
+                raise ValidationError(error_message)
+
+        if not bible.is_valid_verse_id(value):
+            error_message = f"{value} is not a valid verse id."
+            raise ValidationError(error_message)
+
+        return int(value)
+
+    def get_internal_type(self: VerseField) -> str:
+        """Return the internal type (IntegerField) for the VerseField field."""
+        return "IntegerField"

djangobible/migrations/0001_initial.py

@@ -1,42 +1,43 @@
-# Generated by Django 3.1.2 on 2020-10-10 00:44
-
-import django.db.models.deletion
-from django.db import migrations, models
-
-
-class Migration(migrations.Migration):
-
-    initial = True
-
-    dependencies = [
-        ("contenttypes", "0002_remove_content_type_name"),
-    ]
-
-    operations = [
-        migrations.CreateModel(
-            name="VerseRelation",
-            fields=[
-                (
-                    "id",
-                    models.AutoField(
-                        auto_created=True,
-                        primary_key=True,
-                        serialize=False,
-                        verbose_name="ID",
-                    ),
-                ),
-                ("verse", models.PositiveIntegerField()),
-                ("object_id", models.PositiveIntegerField()),
-                (
-                    "content_type",
-                    models.ForeignKey(
-                        on_delete=django.db.models.deletion.CASCADE,
-                        to="contenttypes.contenttype",
-                    ),
-                ),
-            ],
-            options={
-                "db_table": "verse_relation",
-            },
-        ),
-    ]
+# Generated by Django 3.1.2 on 2020-10-10 00:44
+
+from __future__ import annotations
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("contenttypes", "0002_remove_content_type_name"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="VerseRelation",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("verse", models.PositiveIntegerField()),
+                ("object_id", models.PositiveIntegerField()),
+                (
+                    "content_type",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to="contenttypes.contenttype",
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "verse_relation",
+            },
+        ),
+    ]

djangobible/migrations/__init__.py

@@ -1 +0,0 @@
-"""Database migration(s) for the djangobible library."""

djangobible/models.py

@@ -1,62 +1,89 @@
-import pythonbible as bible
-from django.contrib.contenttypes.fields import GenericForeignKey, GenericRelation
-from django.contrib.contenttypes.models import ContentType
-from django.db import models
-
-
-class VerseRelation(models.Model):
-    verse = models.PositiveIntegerField(null=False, blank=False)
-
-    # Below the mandatory fields for generic relation
-    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
-    object_id = models.PositiveIntegerField()
-    content_object = GenericForeignKey()
-
-    class Meta:
-        db_table = u"verse_relation"
-
-    def save(self, *args, **kwargs):
-        if not bible.is_valid_verse_id(self.verse):
-            raise bible.InvalidVerseError(verse_id=self.verse)
-
-        super(VerseRelation, self).save(*args, **kwargs)
-
-
-class ScriptureIndexedModelManager(models.Manager):
-    def filter_by_verse_ids(self, verse_ids):
-        content_type = ContentType.objects.get_for_model(self.model)
-        verse_relations = VerseRelation.objects.filter(
-            content_type=content_type, verse__in=verse_ids
-        )
-        object_ids = verse_relations.values_list("object_id", flat=True)
-        return self.get_queryset().filter(pk__in=object_ids)
-
-
-class ScriptureIndexedModel(models.Model):
-    verses = GenericRelation(VerseRelation)
-    objects = ScriptureIndexedModelManager()
-
-    class Meta:
-        """ScriptureIndexed Model is an abstract model."""
-
-        abstract = True
-
-    def add_verse(self, verse_id):
-        # will raise an error if object.id is null
-        VerseRelation(content_object=self, verse=verse_id).save()
-
-    def set_verses(self, verse_ids):
-        # Delete any existing verse relations
-        self.verses.all().delete()
-
-        # Create new verse relation objects
-        verse_relations = []
-
-        for verse_id in verse_ids:
-            verse_relations.append(VerseRelation(content_object=self, verse=verse_id))
-
-        VerseRelation.objects.bulk_create(verse_relations)
-
-    @property
-    def verse_ids(self):
-        return [verse_relation.verse for verse_relation in self.verses.all()]
+"""Custom Django managers and models for djangobible."""
+
+from __future__ import annotations
+
+import pythonbible as bible
+from django.contrib.contenttypes.fields import GenericForeignKey
+from django.contrib.contenttypes.fields import GenericRelation
+from django.contrib.contenttypes.models import ContentType
+from django.db import models
+
+
+class VerseRelation(models.Model):
+    """Custom Django model for a verse relation."""
+
+    verse = models.PositiveIntegerField(null=False, blank=False)
+
+    # Below the mandatory fields for generic relation
+    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
+    object_id = models.PositiveIntegerField()
+    content_object = GenericForeignKey()
+
+    class Meta:
+        """Set the DB table name."""
+
+        db_table = "verse_relation"
+
+    def save(
+        self: VerseRelation,
+        force_insert: bool = False,
+        force_update: bool = False,
+        using: str | None = None,
+        update_fields: list[str] | None = None,
+    ) -> None:
+        """Save the instance to the DB."""
+        if not bible.is_valid_verse_id(self.verse):
+            raise bible.InvalidVerseError(verse_id=self.verse)
+
+        super().save(force_insert, force_update, using, update_fields)
+
+
+class ScriptureIndexedModelManager(models.Manager):
+    """Custom Django model manager for ScriptureIndexedModel."""
+
+    def filter_by_verse_ids(
+        self: ScriptureIndexedModelManager,
+        verse_ids: list[int] | None,
+    ) -> models.QuerySet:
+        """Return the Query Set for the objects related to the given verse ids."""
+        content_type = ContentType.objects.get_for_model(self.model)
+        verse_relations = VerseRelation.objects.filter(
+            content_type=content_type,
+            verse__in=verse_ids,
+        )
+        object_ids = verse_relations.values_list("object_id", flat=True)
+        return self.get_queryset().filter(pk__in=object_ids)
+
+
+class ScriptureIndexedModel(models.Model):
+    """An abstract Django model with a many-to-many relationship for verses."""
+
+    verses = GenericRelation(VerseRelation)
+    objects = ScriptureIndexedModelManager()
+
+    class Meta:
+        """ScriptureIndexed Model is an abstract model."""
+
+        abstract = True
+
+    def add_verse(self: ScriptureIndexedModel, verse_id: int | None) -> None:
+        """Add a verse to the related verses."""
+        VerseRelation(content_object=self, verse=verse_id).save()
+
+    def set_verses(self: ScriptureIndexedModel, verse_ids: list[int] | None) -> None:
+        """Overwrite the related verses with the given list of verse ids."""
+        self.verses.all().delete()
+
+        if not verse_ids:
+            return
+
+        verse_relations = [
+            VerseRelation(content_object=self, verse=verse_id) for verse_id in verse_ids
+        ]
+
+        VerseRelation.objects.bulk_create(verse_relations)
+
+    @property
+    def verse_ids(self: ScriptureIndexedModel) -> list[int]:
+        """Return the list of related verse id integers."""
+        return [verse_relation.verse for verse_relation in self.verses.all()]

djangobible/templatetags/verse_tags.py

@@ -1,61 +1,61 @@
-from typing import Optional
-
-import pythonbible as bible
-from django import template
-
-register = template.Library()
-
-
-@register.simple_tag
-def verse_reference(verse_id: int, **kwargs) -> str:
-    """For a given verse id return the formatted scripture reference string
-
-    :param verse_id:
-    :return: the scripture reference string for the given verse id
-    """
-    book: bible.Book
-    chapter: int
-    verse: int
-    book, chapter, verse = bible.get_book_chapter_verse(verse_id)
-
-    version_id: Optional[str] = kwargs.get("version")
-
-    if version_id:
-        kwargs["version"] = _get_version(version_id)
-
-    return bible.format_single_reference(book, chapter, verse, chapter, verse, **kwargs)
-
-
-@register.simple_tag
-def verse_text(verse_id: int, **kwargs) -> str:
-    """For a given verse id and version, return the verse text string
-
-    :param verse_id:
-    :return: the verse text for the given verse id and version
-    """
-    version_id: Optional[str] = kwargs.get("version")
-    text: str = ""
-
-    if version_id is not None:
-        text = bible.get_verse_text(verse_id, _get_version(version_id))
-    else:
-        text = bible.get_verse_text(verse_id)
-
-    include_verse_numbers: bool = kwargs.get("include_verse_numbers", False)
-
-    if include_verse_numbers:
-        text = f"{bible.get_verse_number(verse_id)}. {text}"
-
-    return text
-
-
-def _get_version(version_id: str) -> Optional[bible.Version]:
-    try:
-        return bible.Version[version_id]
-    except KeyError:
-        try:
-            return bible.Version(version_id)
-        except ValueError:
-            pass
-
-    return None
+"""Custom tags for djangobible."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from typing import Any
+
+import pythonbible as bible
+from django import template
+
+register = template.Library()
+
+
+@register.simple_tag
+def verse_reference(verse_id: int, **kwargs: Any) -> str:
+    """For a given verse id return the formatted scripture reference string.
+
+    :param verse_id:
+    :return: the scripture reference string for the given verse id
+    """
+    book: bible.Book
+    chapter: int
+    verse: int
+    book, chapter, verse = bible.get_book_chapter_verse(verse_id)
+
+    if version_id := kwargs.get("version"):
+        kwargs["version"] = _get_version(version_id)  # type: ignore[arg-type,assignment]
+
+    reference = bible.NormalizedReference(book, chapter, verse, chapter, verse)
+
+    return bible.format_single_reference(reference, **kwargs)
+
+
+@register.simple_tag
+def verse_text(verse_id: int, **kwargs: Any) -> str:
+    """For a given verse id and version, return the verse text string.
+
+    :param verse_id:
+    :return: the verse text for the given verse id and version
+    """
+    version_id: str | None = kwargs.get("version")  # type: ignore[assignment]
+    text: str = (
+        bible.get_verse_text(verse_id, _get_version(version_id))
+        if version_id
+        else bible.get_verse_text(verse_id)
+    )
+    include_verse_numbers: bool = kwargs.get("include_verse_numbers", False)  # type: ignore[assignment]
+
+    return (
+        f"{bible.get_verse_number(verse_id)}. {text}" if include_verse_numbers else text
+    )
+
+
+def _get_version(version_id: str) -> bible.Version | None:
+    try:
+        return bible.Version[version_id]
+    except KeyError:
+        with suppress(ValueError):
+            return bible.Version(version_id)
+
+    return bible.versions.DEFAULT_VERSION

djangobible/validators.py

@@ -1,25 +1,30 @@
-from typing import List, Optional
-
-import pythonbible as bible
-from django.core.exceptions import ValidationError
-
-
-def validate_verse(value: Optional[str]) -> None:
-    if value is None:
-        return
-
-    references: List[bible.NormalizedReference] = bible.get_references(value)
-
-    if len(references) == 0:
-        raise ValidationError("Not a valid reference.")
-
-    if len(references) > 1:
-        raise ValidationError("Only single verse references allowed.")
-
-    verse_ids: List[int] = bible.convert_references_to_verse_ids(references)
-
-    if len(verse_ids) == 0:
-        raise ValidationError("Not a valid reference.")
-
-    if len(verse_ids) > 1:
-        raise ValidationError("Only single verse references allowed.")
+"""Validators for djangobible custom Fields."""
+
+from __future__ import annotations
+
+from django.core.exceptions import ValidationError
+from pythonbible import NormalizedReference
+from pythonbible import convert_references_to_verse_ids
+from pythonbible import get_references
+
+
+def validate_verse(verse_value: str | None) -> None:
+    """Validate that the given value is a valid string representation of a verse."""
+    if verse_value is None:
+        return
+
+    references: list[NormalizedReference] = get_references(verse_value)
+
+    if not references:
+        error_message = "Not a valid reference."
+        raise ValidationError(error_message)
+
+    if len(references) > 1:
+        error_message = "Only single verse references allowed."
+        raise ValidationError(error_message)
+
+    verse_ids: list[int] = convert_references_to_verse_ids(references)
+
+    if len(verse_ids) > 1:
+        error_message = "Only single verse references allowed."
+        raise ValidationError(error_message)

djangobible-0.3.0.dist-info/METADATA

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: djangobible
+Version: 0.3.0
+Author: Nathan Patton
+Author-email: Nathan Patton <npatton@gmail.com>
+License-Expression: MIT
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: django>=4.2.0
+Requires-Dist: pythonbible==0.14.0
+Requires-Python: >=3.10
+Project-URL: Source, https://github.com/avendesora/djangobible
+Description-Content-Type: text/markdown
+
+# djangobible
+
+The djangobible library is a Django app that wraps the [pythonbible](https://github.com/avendesora/pythonbible) library and provides models, managers, and other tools to easily index an object by a scripture reference.
+
+<table>
+    <tr>
+        <td>Latest Version</td>
+        <td>
+            <a href="https://pypi.org/project/djangobible/"><img src="https://img.shields.io/pypi/v/djangobible?color=gold&logo=pypi&logoColor=lightgray"></a>
+            <img src="https://img.shields.io/pypi/dm/djangobible?color=gold">
+        </td>
+    </tr>
+    <tr>
+        <td>License</td>
+        <td><a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-orange.svg"></a></td>
+    </tr>
+    <tr>
+        <td>Tests</td>
+        <td>
+            <img src="https://github.com/avendesora/djangobible/actions/workflows/tests.yml/badge.svg">
+            <img src="https://github.com/avendesora/djangobible/workflows/Django%20CI/badge.svg"><br/>
+            <a href="https://app.codacy.com/gh/avendesora/djangobible/coverage/dashboard"><img src="https://app.codacy.com/project/badge/Coverage/83a28131bf6642ed9e439344122686fc"></a>
+        </td>
+    </tr>
+    <tr>
+        <td>Code Quality</td>
+        <td>
+            <img src="https://github.com/avendesora/djangobible/workflows/CodeQL/badge.svg">
+            <a href="https://app.codacy.com/gh/avendesora/djangobible?utm_source=github.com&utm_medium=referral&utm_content=avendesora/djangobible&utm_campaign=Badge_Grade_Settings"><img src="https://api.codacy.com/project/badge/Grade/ca34603bdaf8446ba288430b69092093"></a><br/>
+            <a href="https://results.pre-commit.ci/latest/github/avendesora/djangobible/main"><img src="https://results.pre-commit.ci/badge/github/avendesora/djangobible/main.svg"></a>
+            <a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
+        </td>
+    </tr>
+    <tr>
+        <td>Supported Python/Django Versions</td>
+        <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><br />
+            <a href="https://www.djangoproject.com/download/"><img src="https://img.shields.io/badge/Django-4.2%20%7C%205.0%20%7C%205.1%20%7C%205.2-blue"></a><br />
+        </td>
+    </tr>
+</table>
+
+## Installation
+
+Pip install the djangobible library.
+
+```shell script
+pip install djangobible
+```
+
+Add djangobible to your Django project's ``INSTALLED_APPS`` setting:
+
+```python
+INSTALLED_APPS = [
+    ...,  # other apps
+    "djangobible",
+]
+```
+
+Run the django migrations for djangobible
+
+```shell script
+./manage.py migrate djangobible
+```
+
+### Settings
+
+There currently are no settings (other than INSTALLED_APPS) related to the djangobible project. In the future, it would be nice to have settings that determine things like the available versions of the Bible and the default version.
+
+Also, once support is implemented for multiple locales and languages, there could be related settings for that functionality.
+
+## Features
+
+The djangobible library is a complete wrapper for the [pythonbible](https://github.com/avendesora/pythonbible) library, so importing the djangobible library as:
+
+```python
+import djangobible as bible
+```
+
+will provide all the same functionality as importing the pythonbible library as:
+
+```python
+import pythonbible as bible
+```
+
+This includes features such as:
+- Searching text for Scripture references
+- Converting a normalized scripture reference into a list of integer verse ids
+- Converting a list of verse id integers into a list of normalized scripture references
+- Converting a list of normalized scripture references into a formatted string scripture reference
+- Retrieving the Biblical text (in one or more open-source or public domain versions) for a given verse ID integer
+
+For more information, see the [pythonbible documentation](https://github.com/avendesora/pythonbible).
+
+In addition, the djangobible library includes the following features:
+
+### Template Tags
+
+There are currently two template tags provided by the djangobible library: ``verse_reference`` and ``verse_text``.
+
+#### verse_reference
+
+The ``verse_reference`` template tag, given a verse ID and a Bible version, returns the appropriate Scripture reference string.
+
+For example, given ``verse_id = 1001001`` and ``version = djangobible.Version.KING_JAMES``, the following snippet from a Django template:
+
+```html
+{% load verse_tags %}
+...
+{% verse_reference verse_id version=version %}
+```
+
+would display:
+
+```
+Genesis 1:1
+```
+
+The version parameter is optional, and the current default is King James, though that will ideally be configurable in the future.
+
+There is another optional parameter, ``full_title``, which is a boolean flag to determine whether to display the long version or the short version of the book of the Bible title. It defaults to ``False``, which displays the short version. For example, given ``verse_id = 1001001`` and ``version = djangobible.Version.KING_JAMES`` and ``full_title = True``, the following snippet from a Django template:
+
+```html
+{% load verse_tags %}
+...
+{% verse_reference verse_id version=version full_title=full_title %}
+```
+
+would display:
+
+```
+The First Book of Moses, called Genesis 1:1
+```
+
+#### verse_text
+
+The ``verse_text`` template tag, given a verse ID and a Bible version, returns the appropriate text of that Bible verse.
+
+For example, given ``verse_id = 1001001`` and ``version = djangobible.Version.KING_JAMES``, the following snippet from a Django template:
+
+```html
+{% load verse_tags %}
+...
+{% verse_text verse_id %}
+```
+
+would display:
+
+```
+In the beginning God created the heaven and the earth.
+```
+
+The version parameter is optional, and the current default is King James, though that will ideally be configurable in the future.
+
+### One-to-many style relationships between verses and Django models
+
+For situations where an instance of a Django model needs to be associated with a single verse, that Django model can have a field of type ``VerseField``.
+
+For example:
+
+```python
+from django.db import models
+
+import djangobible as bible
+
+
+class MyModel(models.Model):
+    ...  # other fields
+
+    verse = bible.VerseField()
+```
+
+The underlying implementation of ``VerseField`` is an ``IntegerField`` which stores the verse ID of the associated verse.
+
+Having this custom field type provides several benefits:
+- The Django admin (and Wagtail) form contains a text field for the verse rather than an integer field and allows the user to enter the Scripture reference text rather than the verse id, which they may not know. It then validates that text to ensure it references one, and only one, verse.
+- As just mentioned, this allows for validation, not only that the value is one, and only one, verse id, but that it is also a valid verse id (i.e. that it represents a book, chapter, and verse of the Bible that actually exists).
+- More readable query filters (e.g. ``MyModel.objects.filter(verse=1001001)`` is valid, but so is ``MyModel.objects.filter(verse="Genesis 1:1")``).
+
+You can set the verse field with either the int verse ID or the string reference:
+
+```python
+my_object = MyModel.objects.create(name="my object")
+my_object.verse = 1001001
+my_object.save()
+```
+
+or
+
+```python
+my_object = MyModel.objects.create(name="my object")
+my_object.verse = "Genesis 1:1"
+my_object.save()
+```
+
+You can filter the objects in the query set by either the int verse ID or the string reference:
+
+```python
+MyModel.objects.filter(verse=1001001)
+```
+
+or
+
+```python
+MyModel.objects.filter(verse="Genesis 1:1")
+```
+
+In any of the above examples, if the verse is not a valid verse ID integer or string reference for a single verse, then a ``ValidationError`` will be raised.
+
+### Many-to-many style relationships between verses and Django models
+
+> **WARNING**: This is still a work in progress, and this functionality does not yet exist in a stable form.
+
+There are situations where an instance of a Django model needs to be associated with multiple verses. The current intended solution, inspired by the [django-taggit](https://github.com/jazzband/django-taggit) library, is to implement this feature in such a way that you would add this relationship to your model like:
+
+```python
+from django.db import models
+
+import djangobible as bible
+
+
+class MyModel(models.Model):
+    ...  # other fields
+
+    verses = bible.VerseManager()
+```
+
+Then you could add, remove, and reference those verses with something like:
+
+```
+>>> my_object = MyModel.objects.create(name="My Object")
+>>> my_object.verses.add("Genesis 1:1-3")
+>>> my_object.verses.all()
+[<Verse: Genesis 1:1>, <Verse: Genesis 1:2>, <Verse: Genesis 1:3>]
+>>> my_object.verses.remove("Genesis 1:2")
+>>> my_object.verses.all()
+[<Verse: Genesis 1:1>, <Verse: Genesis 1:3>]
+>>> MyModel.objects.filter(verses__in=[1001001])
+[<MyModel: My Object>]
+```
+
+Ideally, the form field would be a text field where the user could enter a list of Scripture references (e.g. "Genesis 1:1,3-10;Psalm 119;Luke 2:1-18;John 3:16")

djangobible-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+djangobible/__init__.py,sha256=y0MkH-8--IsNMjbM6ftQqFHZA7J9R-Z0NXc07iRKURI,230
+djangobible/apps.py,sha256=lJgCh5Hj0i-nuTS_1s9HmwMNgVX-i1nFEIJkVsUbOfs,244
+djangobible/fields.py,sha256=i8KYKQY1K6ZJm2FSFmirutwBWM5Xfbtnp7pDC8dLUFw,3189
+djangobible/migrations/0001_initial.py,sha256=5lNyBJtwuZSchhDbxeIfiWGPcf308PGl0Mc5uCxI5c0,1200
+djangobible/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djangobible/models.py,sha256=qDCKczj9nOYauVErkae14gfRaZSs0R-1mzuN3q5KD9E,3082
+djangobible/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djangobible/templatetags/verse_tags.py,sha256=xL-ZWOugyBKM1UyfLb7Hm3RD98Quu8_PhoAHV3UueGg,1811
+djangobible/validators.py,sha256=nAtbb7Epwehd8oZ7ATSWKTcKCHklZZXYGlmLoUq7gow,996
+djangobible-0.3.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+djangobible-0.3.0.dist-info/METADATA,sha256=tBriLOnfPvHh6XF-mw0Nvh_LhgCQUQ3hQ3Wwa0u2quU,10306
+djangobible-0.3.0.dist-info/RECORD,,

{djangobible-0.0.16.dist-info → djangobible-0.3.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: flit 3.0.0
+Generator: uv 0.8.24
 Root-Is-Purelib: true
-Tag: py3-none-any
+Tag: py3-none-any

djangobible-0.0.16.dist-info/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2020 Nathan Patton
-
-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.

djangobible-0.0.16.dist-info/METADATA

@@ -1,69 +0,0 @@
-Metadata-Version: 2.1
-Name: djangobible
-Version: 0.0.16
-Summary: djangobible python library.
-Home-page: https://github.com/avendesora/django-bible
-License: UNKNOWN
-Author: Nathan Patton
-Author-email: npatton@gmail.com
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-Classifier: License :: OSI Approved :: MIT License
-Requires-Dist: Django >=3.0.0
-Requires-Dist: pythonbible >=0.3.0
-Requires-Dist: defusedxml >=0.6.0 ; extra == "all"
-Requires-Dist: bandit >=1.7.0 ; extra == "dev"
-Requires-Dist: black >=20.8b1 ; extra == "dev"
-Requires-Dist: mypy >=0.800 ; extra == "dev"
-Requires-Dist: prospector >=1.3.1 ; extra == "dev"
-Requires-Dist: pytest-django >=4.1.0 ; extra == "test"
-Provides-Extra: all
-Provides-Extra: dev
-Provides-Extra: doc
-Provides-Extra: test
-
-# djangobible
-
-The djangobible library is a Django app that wraps the [pythonbible](https://github.com/avendesora/python-bible) library and provides models, managers, and other tools to easily index an object by a scripture reference.
-
-[![PyPI version](https://img.shields.io/pypi/v/djangobible?color=blue&logo=pypi&logoColor=lightgray)](https://pypi.org/project/djangobible/)
-[![license MIT](https://img.shields.io/badge/license-MIT-orange.svg)](https://opensource.org/licenses/MIT)
-
-![Django CI](https://github.com/avendesora/django-bible/workflows/Django%20CI/badge.svg)
-![CodeQL](https://github.com/avendesora/django-bible/workflows/CodeQL/badge.svg)
-[![Codacy Badge](https://api.codacy.com/project/badge/Grade/ca34603bdaf8446ba288430b69092093)](https://app.codacy.com/gh/avendesora/django-bible?utm_source=github.com&utm_medium=referral&utm_content=avendesora/django-bible&utm_campaign=Badge_Grade_Settings)
-[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/83a28131bf6642ed9e439344122686fc)](https://www.codacy.com/gh/avendesora/django-bible/dashboard?utm_source=github.com&utm_medium=referral&utm_content=avendesora/django-bible&utm_campaign=Badge_Coverage)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-
-[![Python 3.9](https://img.shields.io/badge/python-3.7%20%7C%203.8%20%7C%203.9-blue?logo=python&logoColor=lightgray)](https://www.python.org/downloads/release/python-390/)
-
-## Installation
-
-```shell script
-pip install djangobible
-```
-
-### Optional Dependencies
-
-If the [defusedxml](https://github.com/tiran/defusedxml) library is installed, djangobible/pythonbible will use it to parse XML files rather than the builtin xml.etree library.
-
-To install djangobible with all optional dependencies, use the following command.
-
-```shell script
-pip install djangobible[all]
-```
-
-### Python 3.6
-
-Python 3.6 is not officially supported (djangobible is only tested on Python 3.7+). However, djangobible should work on Python 3.6 if you have the dataclasses library installed:
-
-```shell script
-pip install dataclasses
-```
-
-If you are using Python 3.7+, the dataclasses library is included in the Python standard library, and you do not need to explicitly install the dataclasses library.
-
-## Features
-
-coming soon...
-

djangobible-0.0.16.dist-info/RECORD

@@ -1,13 +0,0 @@
-djangobible/__init__.py,sha256=WJsSnOYpaHtBZGcuUvP3q6RVhamr0h6zgoF1G2ZnDr0,205
-djangobible/apps.py,sha256=4gQL65CrE3l0NwXrc2FUPa4JloRDmZLTnDgY7yNHMYo,107
-djangobible/fields.py,sha256=qg0bl5OrYkG9L2J0Ujut0sK1V3aFb7fygawslkLaPOU,1687
-djangobible/models.py,sha256=Xq9oKJ7ad3H9tBdnq6pphDLg9SGgeEBpzI7cwaF3DJA,2155
-djangobible/validators.py,sha256=57ohY35gLnx_UX6HX0iAjzucP5PQhjy9XrmYS4Y9OpM,755
-djangobible/migrations/0001_initial.py,sha256=4-oLb6VPP7vgM7pQCJPrhNK38gXXsAQAjZP5DyiTy1U,1207
-djangobible/migrations/__init__.py,sha256=WTz0_YW5SQ15TP6YCRewyvAxEH42kbunv9TXBe0CQZM,58
-djangobible/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-djangobible/templatetags/verse_tags.py,sha256=4REewf7FoxwYe805HgUEY2K3h_eXqwgKZ93Qq3rn1e4,1671
-djangobible-0.0.16.dist-info/LICENSE,sha256=-wYMucoVWThISsSvFSvSV2tvgMozWtBuLy-gG1ztGIw,1091
-djangobible-0.0.16.dist-info/WHEEL,sha256=CqyTrkghQBNsEzLD3HbCSEIJ_fY58-XpoU29dUzwHSk,81
-djangobible-0.0.16.dist-info/METADATA,sha256=atONJqA9PUdsCbp-zl-I6yu0GX5b8o67yAWXJ1dUd8k,3075
-djangobible-0.0.16.dist-info/RECORD,,