add limit and offset features

[tsm1th]

This is the start of the work to close #106

• [x] Add unit test
• [x] Add integration test
• [x] Add examples in documentation

[tsm1th]

Thinking more about this. If a user provided "offset", then should we assume they only want that single chunk of data?

Example - with some dataset containing 100 records

If I want offset=10 and limit=10, then do I only want records 10-20? Or do I want records 10-100?

Without an offset, I think it's obvious that I want all the records, but chunked to the selected limit.

With an offset, I think it might be beneficial to only return that single chunk... (not the current logic)

Thoughts?

[joewesch]

Hmm, good question. Maybe we need page_size to signify that they just want to change the default paging and indeed return only the specific chunk when they use limit/offset? Since this was @Kircheneer's request I'd appreciate his feedback and thoughts.

[tsm1th]

And for clarity, limit equals page_size in the Nautobot API

[joewesch]

Yes, I just meant a way to differentiate. So you're saying if they just put limit they would modify the page size, but if they provide both limit and offset we should treat it as a single chunk wanted instead? I'm fine with that logic.

[tsm1th]

@joewesch - The SDK is doing a bit of magic for the users that wouldn't exist if they were just using the API. For example, limit is just controlling the page size like you said, but we're retrieving all the results for them instead of making the user do it. The question is whether or not we do that same magic when limit and offset are both defined. (It currently is returning all the chunks for both)

I think it could be beneficial to provide that single chunk functionality for someone using the SDK who might want to handle the chunking themselves. But, why not just use the API if you're needing to go as far as managing the chunking?

[joewesch]

The question is whether or not we do that same magic when limit and offset are both defined. (It currently is returning all the chunks for both)

If we are going to add the options then it should only return a single chunk if they provide both and only change the page size if they only provide limit. Only providing offset should raise the exception as you already have.

I think it could be beneficial to provide that single chunk functionality for someone using the SDK who might want to handle the chunking themselves. But, why not just use the API if you're needing to go as far as managing the chunking?

I can see a few edge cases that it would come in handy. For example, as a replacement for a (currently non-existent) .first() convenience method. Again this is Leo's request so I would like him to weigh in.

[Kircheneer]

I don't actually need this anymore and don't really have anything to contribute, sorry.