Add pagination example using cursors

[ymdpharm]

Hi, thanks for a nice product.

I found it inconvenient that XRPC's get_follows and get_followers are limited to 100 results at a time. So I've added some methods on client to address this issue. I would like to commit the changes to help someone.

There doesn't seem to be test cases yet, but I've verified the behavior.

[MarshalX]

Hi! Thank you for your contribution!

That's a simple pagination that is presented in many methods. Not only in getting followers. I see 2 ways how we can improve understanding of it:

1. Make utils to work with paginations. Doesn't matter which method. It must work with all that supports cursor arg.
2. Move your method with a while loop to examples instead of methods of the clients

What do you think?

[ymdpharm]

I think 1 is better. Pagination should be hidden from users.

There are some issues, one of them is that it would be better to define the return value signature (Response type) on our own to achieve 1.

In this commit, I aimed to quickly provide what the users want, expecting future refactoring.

[MarshalX]

to be honest I really don't want to make hundreds of requests under the hood without the user's understanding. also, I don't want to have to copy and paste for every method that supports the "cursor" param. we need something that will work for all

JUST A PSEUDO CODE THOUGHTS:

def get_all_paginated_entries(callable, *args, **kwargs) -> BaseResponseModel:
    # we will get the return type annotation of callable in runtime and will perform checks that the response contains cursor attr
    # we will get the params data type annotation of callable in runtime and will perform checks that params contains cursor attr
    # we will implement universal loop do deal with cursor
    # we will document this method that it could lead to long execution time and many http request
    ...

Example of usage:

all_followers = get_all_paginated_entries(client.bsky.graph.get_follows, actor='marshal.dev)

using of get_all_paginated_entries method will be clear in the code that it will lead to long execution and it's user's choice

the list of methods with "cursor" is huge:

[ymdpharm]

I really don't want to make hundreds of requests under the hood without the user's understanding.

I understood. I think it also makes sense.
I've moved codes to examples. It may help someone.

I may suggest some solutions next time. Thanks in advance then.

[MarshalX]

thank you! here are a few notes

[MarshalX]

Thank you!