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_base_url(self) -> str:
 23        """Get the URL at which the first page of query results can be found.
 24
 25        Returns:
 26            The URL for the query without pagination information.
 27        """
 28        raise NotImplementedError('Use implementor.')
 29
 30    def get_limit(self) -> OPT_INT:
 31        """Get the page size limit.
 32
 33        Returns:
 34            The maximum number of records to return per page.
 35        """
 36        raise NotImplementedError('Use implementor.')
 37
 38    def get_start_offset(self) -> OPT_INT:
 39        """Get the number of inital records to ignore.
 40
 41        Returns:
 42            The number of records being skipped at the start of the result set.
 43        """
 44        raise NotImplementedError('Use implementor.')
 45
 46    def get_filtering_incomplete(self) -> bool:
 47        """Determine if this cursor is silently filtering incomplete records.
 48
 49        Returns:
 50            Flag indicating if incomplete records should be silently filtered.
 51            If true, they will not be returned during iteration and placed in
 52            the queue at get_invalid(). If false, they will be returned and
 53            those incomplete records' get_complete() will return false.
 54        """
 55        raise NotImplementedError('Use implementor.')
 56
 57    def get_page_url(self, offset: OPT_INT = None,
 58        limit: OPT_INT = None) -> str:
 59        """Get a URL at which a page can be found using this cursor's base url.
 60
 61        Args:
 62            offset: The number of records to skip prior to the page.
 63            limit: The maximum number of records to return in the page.
 64        Returns:
 65            URL at which the requested page can be found.
 66        """
 67        raise NotImplementedError('Use implementor.')
 68
 69    def get_page(self, offset: OPT_INT = None,
 70        limit: OPT_INT = None,
 71        ignore_invalid: bool = False) -> typing.List[afscgap.model.Record]:
 72        """Get a page using this cursor's base url.
 73
 74        Args:
 75            offset: The number of records to skip prior to the page.
 76            limit: The maximum number of records to return in the page.
 77            ignore_invalid: Flag indicating how to handle invalid records. If
 78                true, will silently throw away records which could not be
 79                parsed. If false, will raise an exception if a record can not
 80                be parsed.
 81
 82        Returns:
 83            Results from the page which, regardless of ignore_invalid, may
 84            contain a mixture of complete and incomplete records.
 85        """
 86        raise NotImplementedError('Use implementor.')
 87
 88    def get_invalid(self) -> 'queue.Queue[dict]':
 89        """Get a queue of invalid / incomplete records found so far.
 90
 91        Returns:
 92            Queue with dictionaries containing the raw data returned from the
 93            API that did not have valid values for all required fields. Note
 94            that this will include incomplete records as well if
 95            get_filtering_incomplete() is true and will not contain incomplete
 96            records otherwise.
 97        """
 98        raise NotImplementedError('Use implementor.')
 99
100    def to_dicts(self) -> typing.Iterable[dict]:
101        """Create an iterator which converts Records to dicts.
102
103        Returns:
104            Iterator which returns dictionaries instead of Record objects but
105            has otherwise the same beahavior as iterating in this Cursor
106            directly.
107        """
108        raise NotImplementedError('Use implementor.')
109
110    def get_next(self) -> typing.Optional[afscgap.model.Record]:
111        """Get the next value for this Cursor.
112
113        Returns:
114            The next value waiting if cached in the cursor's results queue or
115            as just retrieved from a new page gathered by HTTP request. Will
116            return None if no remain.
117        """
118        raise NotImplementedError('Use implementor.')
119
120    def __iter__(self) -> typing.Iterator[afscgap.model.Record]:
121        """Indicate that this Cursor can be iterated on.
122
123        Returns:
124            This object as an iterator.
125        """
126        return self
127
128    def __next__(self) -> afscgap.model.Record:
129        """Get the next value for this Cursor inside an interator operation.
130
131        Returns:
132            The next value waiting if cached in the cursor's results queue or
133            as just retrieved from a new page gathered by HTTP request.
134
135        Raises:
136            StopIteration: Raised if no data remain.
137        """
138        next_maybe = self.get_next()
139        if next_maybe is not None:
140            return next_maybe
141        else:
142            raise StopIteration()