refspy.models.reference

  1"""Data object for references.
  2
  3References consist of lists of ranges and are entirely numerical objects.
  4
  5They can be set to sort, merge, and join references when added together.
  6"""
  7
  8import collections
  9from typing import Any, Self
 10
 11from pydantic import BaseModel, Field
 12
 13from refspy.types.number import Number
 14from refspy.models.range import Range, combine_ranges, merge_ranges, range as _range
 15from refspy.models.verse import Verse, verse
 16
 17
 18class Reference(BaseModel):
 19    """A reference object represents a list of verse ranges.
 20
 21    References are entirely numeric entities. Matchers are used to find them in
 22    text, and formatters are used to turn them in to canonical links.
 23
 24    It is common to want references to be sorted and combined. Combining means
 25    merging overlapping ranges and joining adjacent ones. This is done by creating
 26    references with sorted(), and the `merge`, and `combine` functions in
 27    `refspy.range.Range`, or calling the methods of the same name on references.
 28
 29    Example:
 30        ```
 31        from reference import merge, combine
 32
 33        assert reference(*sorted(ranges)) == reference(*ranges).sort()
 34        assert reference(*merge(ranges)) == reference(*ranges).merge()
 35        assert reference(*combine(ranges)) == reference(*ranges).combine()
 36        ```
 37    """
 38
 39    ranges: list[Range] = Field(min_length=1)
 40    """
 41    A reference must contain at least one `refspy.range.Range`.
 42
 43    Raises:
 44        ValueError: If ranges is empty
 45    """
 46
 47    def tuple(self) -> tuple:
 48        """For hashing and comparisons"""
 49        return tuple([hash(_) for _ in self.ranges])
 50
 51    def __hash__(self) -> int:
 52        """Unique ID for key values."""
 53        return hash(self.tuple())
 54
 55    def __eq__(self, other) -> bool:  # <-- Should be Self; TypeError requires object
 56        return self.tuple() == other.tuple()
 57
 58    def __add__(self, other: Self) -> Self:
 59        """Overload the addition operator to combine reference ranges into a new object."""
 60        return self.__class__(ranges=[*self.ranges, *other.ranges])
 61
 62    def __lt__(self, other: Self) -> bool:
 63        """
 64        A simple implementation of '<' allows sorting and min/max.
 65        """
 66        common = min(len(self.ranges), len(other.ranges))
 67        for i in range(0, common):
 68            if self.ranges[i].start != other.ranges[i].start:
 69                return self.ranges[i].start < other.ranges[i].start
 70            if self.ranges[i].end != other.ranges[i].end:
 71                return self.ranges[i].end < other.ranges[i].end
 72        return False  # <-- all equal
 73
 74    def equals(self, other: Self) -> bool:
 75        """
 76        Reference equality means that two references have identical ranges.
 77
 78        Note:
 79            We don't use __eq__, as that is already defined in BaseModel.
 80        """
 81        return self.ranges == other.ranges
 82
 83    def overlaps(self, other: Self) -> bool:
 84        """
 85        Two references overlap if ANY of their ranges overlap.
 86        """
 87        return any(
 88            [
 89                self_range.overlaps(other_range)
 90                for other_range in other.ranges
 91                for self_range in self.ranges
 92            ]
 93        )
 94
 95    def contains(self, other: Self) -> bool:
 96        """
 97        A reference contains another if ALL the other's ranges are contained by
 98        ANY of it's own ranges.
 99        """
100        return all(
101            [
102                any([self_range.contains(other_range) for self_range in self.ranges])
103                for other_range in other.ranges
104            ]
105        )
106
107    def adjoins(self, other: Self) -> bool:
108        """Determine adjacency for ranges.
109
110        A reference adjoins another if its maximum range adjoins the other's
111        minimum or vice-versa. This usually only makes sense for simple
112        references with a small number of ranges.
113
114        See `refspy.reference.Reference.adjoins`.
115        """
116        return any(
117            [
118                max(self.ranges).adjoins(min(other.ranges)),
119                min(self.ranges).adjoins(max(other.ranges)),
120            ]
121        )
122
123    def count_books(self) -> int:
124        """Return the total unique books contained in this reference.
125
126        Allow that the same book ID could appear in multiple libraries.
127        """
128        library_books = set()
129        for _ in self.ranges:
130            library_books.add(tuple([_.start.library, _.start.book]))
131            library_books.add(tuple([_.end.library, _.end.book]))
132        return len(library_books)
133
134    def is_book(self: Self) -> bool:
135        """Determine if reference is a whole book."""
136        return self.ranges[0].is_book()
137
138    def is_chapter(self: Self) -> bool:
139        """Determine if reference is a whole chapter."""
140        return self.ranges[0].is_chapter()
141
142    def first_verse(self) -> Verse:
143        """Find the first verse.
144
145        Only sensible if sorted=True
146
147        Note:
148            Consider sorting on the fly if sorted=False
149        """
150        return self.ranges[0].start
151
152    def last_verse(self) -> Verse:
153        """Find the last verse.
154
155        Only sensible if sorted=True
156
157        Note:
158            Consider sorting on the fly if sorted=False
159        """
160        return self.ranges[-1].end
161
162    def last_range(self) -> Range:
163        """Find the last verse.
164
165        Only sensible if sorted=True
166
167        Note:
168            Consider sorting on the fly if sorted=False
169        """
170        return self.ranges[-1]
171
172    def sort(self) -> Self:
173        """Return a sorted reference."""
174        return self.__class__(ranges=sorted(self.ranges))
175
176    def merge(self) -> Self:
177        """Return a merged reference.
178
179        A merged reference is sorted, and has any overlapping ranges merged.
180        """
181        return self.__class__(ranges=merge_ranges(self.ranges))
182
183    def combine(self) -> Self:
184        """Return a combined reference.
185
186        A combined reference is sorted, merged, and has any adjacent ranges combined.
187        """
188        return self.__class__(ranges=combine_ranges(self.ranges))
189
190
191# -----------------------------------
192# Shorthand constructor functions
193# -----------------------------------
194
195
196def reference(*args: Range, **kwargs: Any) -> Reference:
197    """
198    Construct a Reference object from `refspy.range.Range` arguments.
199
200    Example:
201        ```
202        ref = reference(
203            _range(verse(1, 2, 3, 3), verse(1, 2, 3, 4)),
204            _range(verse(1, 2, 3, 6), verse(1, 2, 3, 7))
205        )
206        ```
207    """
208    return Reference(ranges=list(args), **kwargs)
209
210
211def book_reference(library_id: Number, book_id: Number) -> Reference:
212    """
213    Shorthand function for creating book references from `refspy.number.Number`
214    values.
215    """
216    return reference(
217        _range(
218            verse(library_id, book_id, 1, 1),
219            verse(library_id, book_id, 999, 999),
220        )
221    )
222
223
224def chapter_reference(
225    library_id: Number, book_id: Number, chapter_id: Number
226) -> Reference:
227    """
228    Shorthand function for creating chapter references from
229    `refspy.number.Number` values.
230    """
231    return reference(
232        _range(
233            verse(library_id, book_id, chapter_id, 1),
234            verse(library_id, book_id, chapter_id, 999),
235        )
236    )
237
238
239def verse_reference(
240    library_id: Number,
241    book_id: Number,
242    chapter_id: Number,
243    verse_id: Number,
244    verse_end_id: Number | None = None,
245) -> Reference:
246    """
247    Shorthand function for creating verse or range references from
248    `refspy.number.Number` values.
249
250    See `refspy.manager.Manager.bcv`
251    """
252    return reference(
253        _range(
254            verse(library_id, book_id, chapter_id, verse_id),
255            verse(library_id, book_id, chapter_id, verse_end_id or verse_id),
256        )
257    )
258
259
260# -----------------------------------
261# Manipulation functions
262# -----------------------------------
263
264
265def sort_references(references: list[Reference]) -> list[Reference]:
266    """
267    Return the same references in sorted order based on their ranges.
268
269    References implement `__lt__()`, so are innately sortable.
270
271    Note:
272        - use `unique_references(sorted_references(references))` to make the
273          sorted list unique.
274    """
275    return sorted(references)
276
277
278def unique_references(references: list[Reference]) -> list[Reference]:
279    """
280    Return references in the same order, but without duplicates
281
282    References implement `__hash__()`, so can be used in sets. Sets retain
283    the order of inserted items.
284    """
285    ordered = {hash(ref): ref for ref in references}
286    return list(ordered.values())
287
288
289def split_reference(reference: Reference) -> list[Reference]:
290    """Split a single references into a list of references, one for each range it contains."""
291    references = []
292    for rng in reference.ranges:
293        references.append(Reference(ranges=[rng]))
294    return references
295
296
297def join_references(references: list[Reference]) -> Reference:
298    """Join a list of references into a single reference"""
299    ranges = []
300    for ref in references:
301        for rng in ref.ranges:
302            ranges.append(rng)
303    return reference(*ranges)
304
305
306def count_references(references: list[Reference]) -> list[tuple[Reference, int]]:
307    """
308    Return tuples [(ref, count)].
309
310    Because references implement __hash__(), this can be done with the
311    `collections.Counter`. Transform the resulting dict_items iterator into regular
312    tuples for simple typing.
313    """
314    return [(ref, i) for ref, i in collections.Counter(references).items()]
315
316    # reference_count = []
317    # for ref in reference_list:
318    #     found = False
319    #     for key, (counted_ref, count) in enumerate(reference_count):
320    #         if ref == counted_ref and not found:
321    #             reference_count[key] = (counted_ref, count + 1)
322    #             found = True
323    #     if not found:
324    #         reference_count.append((ref, 1))
325    # return reference_count