feat: pagination (#819)

* feat: add pagination interfaces

* feat: base pager implementation

* fix: make pages immutable

* feat: _KeyPager overrides

* test: mock client update

* test: _BasePager tests

* fix: clean up

* feat: update default page size to 200

* feat: reusable get_all

* feat: _KeyPager

* feat: _BookmarkPager

* refactor: pagination entry point factory API

* refactor: renames

* test: updates for new entry point and renames

* chore: remove TODO comment

* feat: add pagination option validation

* fix: use Sequence type for interfaces

* fix: add missing type

* fix: opts deletion error

* fix: return from all docs _get_next_page_options

* test: extract common page mocks

* test: add pagination operation tests

* test: share error code

* test: add pagination error tests

* docs: pagination examples

docs: pagination examples

* fix: Optional[str] for python 3.9

* test: itertools.batched fix for older versions

---------

Co-authored-by: Rich Ellis <ricellis@users.noreply.github.com>
Co-authored-by: Richard Ellis <RICELLIS@uk.ibm.com>

Author: Kornel-Toth

ibmcloudant/__init__.py

@@ -23,6 +23,7 @@
 from .couchdb_session_token_manager import CouchDbSessionTokenManager
 from .cloudant_v1 import CloudantV1
 from .features.changes_follower import ChangesFollower
+from .features.pagination import Pager, PagerType, Pagination
 
 # sdk-core's __construct_authenticator works with a long switch-case so monkey-patching is required
 get_authenticator.__construct_authenticator = new_construct_authenticator