Add Pagination Helper: paginate() Method for Automatic Pagination Handling

[LifeJiggy]

✨ Add Pagination Helper: paginate() Method for Automatic Pagination Handling

This PR introduces a powerful paginate() helper method to the pydo Client class. It streamlines the process of iterating through paginated API results, making it dramatically easier for users to work with large datasets.

---

🛠️ Problem Solved

Previously, users had to manually handle pagination by:

• Tracking page numbers
• Parsing next page URLs
• Managing loops and edge cases
• Writing repetitive boilerplate code

---

🚀 Solution

The new paginate() method:

• Automatically iterates through all result pages
• Yields individual items (generator-based, memory efficient)
• Encapsulates all pagination logic internally
• Works with any paginated endpoint

---

🧑‍💻 Usage

Before (Manual):

page = 1
while True:
    resp = client.ssh_keys.list(per_page=50, page=page)
    for key in resp["ssh_keys"]:
        process(key)
    if "next" not in resp.get("links", {}).get("pages", {}):
        break
    page += 1

After (Automatic):

for key in client.paginate(client.ssh_keys.list, per_page=50):
    process(key)

---

🌟 Key Features

• Memory Efficient: Uses generators, does not load all data at once
• Flexible: Works with any paginated endpoint (droplets, keys, etc.)
• Simple: Pass any paginated method and optional parameters
• Backward Compatible: Manual pagination remains supported

---

🧪 Testing

• Comprehensive tests for both multi-page and single-page scenarios
• Mocked tests ensure reliability
• All existing functionality preserved

---

📄 Files Changed

• src/pydo/_patch.py — Added paginate() method
• README.md — Updated documentation with usage examples
• tests/mocked/test_client_customizations.py — Added pagination tests

---

💥 Impact

• Major UX Improvement: Makes handling large datasets much simpler
• Developer Productivity: Greatly reduces boilerplate code
• Error Reduction: Eliminates common manual pagination bugs
• Zero Breaking Changes: Fully backward compatible

---

Feedback and suggestions are welcome!