afscgap.cursor

 1"""
 2Interfaces for cursor objects which iterate over real or inferred records.
 3
 4(c) 2023 Regents of University of California / The Eric and Wendy Schmidt Center
 5for Data Science and the Environment at UC Berkeley.
 6
 7This file is part of afscgap released under the BSD 3-Clause License. See
 8LICENSE.md.
 9"""
10
11import queue
12import typing
13
14import afscgap.model
15
16from afscgap.typesdef import OPT_INT
17
18
19class Cursor(typing.Iterable[afscgap.model.Record]):
20    """Interface for objects allowing generation / retrieval of records."""
21
22    def get_limit(self) -> OPT_INT:
23        """Get the overall limit.
24
25        Returns:
26            The maximum number of records to return.
27        """
28        raise NotImplementedError('Use implementor.')
29
30    def get_filtering_incomplete(self) -> bool:
31        """Determine if this cursor is silently filtering incomplete records.
32
33        Returns:
34            Flag indicating if incomplete records should be silently filtered.
35            If true, they will not be returned during iteration and placed in
36            the queue at get_invalid(). If false, they will be returned and
37            those incomplete records' get_complete() will return false.
38        """
39        raise NotImplementedError('Use implementor.')
40
41    def get_invalid(self) -> 'queue.Queue[dict]':
42        """Get a queue of invalid / incomplete records found so far.
43
44        Returns:
45            Queue with dictionaries containing the raw data returned from the
46            remote that did not have valid values for all required fields. Note
47            that this will include incomplete records as well if
48            get_filtering_incomplete() is true and will not contain incomplete
49            records otherwise.
50        """
51        raise NotImplementedError('Use implementor.')
52
53    def to_dicts(self) -> typing.Iterable[dict]:
54        """Create an iterator which converts Records to dicts.
55
56        Returns:
57            Iterator which returns dictionaries instead of Record objects but
58            has otherwise the same beahavior as iterating in this Cursor
59            directly.
60        """
61        raise NotImplementedError('Use implementor.')
62
63    def get_next(self) -> typing.Optional[afscgap.model.Record]:
64        """Get the next value for this Cursor.
65
66        Returns:
67            The next value waiting if cached in the cursor's results queue or
68            as just retrieved from a new page gathered by HTTP request. Will
69            return None if no remain.
70        """
71        raise NotImplementedError('Use implementor.')
72
73    def __iter__(self) -> typing.Iterator[afscgap.model.Record]:
74        """Indicate that this Cursor can be iterated on.
75
76        Returns:
77            This object as an iterator.
78        """
79        return self
80
81    def __next__(self) -> afscgap.model.Record:
82        """Get the next value for this Cursor inside an interator operation.
83
84        Returns:
85            The next value waiting if cached in the cursor's results queue or
86            as just retrieved from a new page gathered by HTTP request.
87
88        Raises:
89            StopIteration: Raised if no data remain.
90        """
91        next_maybe = self.get_next()
92        if next_maybe is not None:
93            return next_maybe
94        else:
95            raise StopIteration()