Deprecate collection retrieving with retrieve()

Currently retrieve() is being used for object retrieval when an object ID is given, and collection retrieval for account-level objects when an object ID is not given. Due to this, there's no easy way to pass arguments to the collection such as limit, offset or a range query, since they will be treat as an object ID. The current workaround in retrieve() is to pass a string param, e.g. ?limit=100 which is not the cleanest way.

>>> omise.Transaction.retrieve()
<Collection at 0x7f6ef55b0ab8>
>>> omise.Transaction.retrieve('trxn_test_4xuy2z4w5vmvq4x5pfs')
<Transaction id='trxn_test_4xuy2z4w5vmvq4x5pfs' at 0x7fd953fa1990>
>>> omise.Transaction.retrieve('?limit=100')
<Collection at 0x7d7ec4ae0c93>

In order to make the Python API more explicit between retrieving a single object and a collection, I propose that we should deprecate the use of retrieve() without any arguments, and introduce list() for retrieving a collection. This change should allow retrieve() to be simplified and allow us to do more with the Collection proxy object:

My propose about list() is that it should be an iterator that automatically handle paging by default (the LazyCollection, in this case, limit can be used to adjust retrieval size) and list(lazy=False) that will not perform the automatic paging (which means the user have to track and work on limit and offset by themselves.

For collection that is returned as part of other objects will now require to use the list_name() method to retrieve the collection (e.g. list_card()) in which will behave the same way as list() method.

Calling list() should now return a LazyCollection:

>>> txs = omise.Transaction.list()
<LazyCollection at 0x7f55b0ab8>

LazyCollection should retrieve more collections during iteration if internal total == limit and raise StopIteration if there's no further values in a collection. This means at worst case (total == limit), one extra empty request will be made to confirm that there's no more object in the collection:

>>> list(txs)
[<Transaction id='trxn_test_4xuy2z4w5vmvq4x5pfs' at 0x7fd953fa1990>, ...]
>>> len(txs)
38

Or in case of collection that are returned as part of an object:

>>> customer = omise.Customer.retrieve('cust_test_4xsjvylia03ur542vn6')
<Customer id='cust_test_4xtrb759599jsxlhkrb' at 0x7fb02625f990>
>>> card = customer.list_cards()
<LazyCollection at 0x7f55b0ab8>

Note:

retrieve() should work the same way for at least 6 months after list() has been introduced.
After list() is implemented, retrieve() without object ID should warn about the deprecation.

cc @jakyns

omise / omise-python

Deprecate collection retrieving with retrieve() #18