MT-22678: Add search filter to contact lists get_list

[Rabsztok]

Motivation

https://railsware.atlassian.net/browse/MT-22678

Changes

• Add an optional search argument to contact_lists.get_list — filters contact lists by name (case-insensitive prefix match), per the OpenAPI GET /api/contacts/lists param. Sent only when provided, so the default call is unchanged.

How to test

• client.contact_lists.get_list() — returns all contact lists (unchanged behaviour).
• client.contact_lists.get_list(search="news") — returns only lists whose name starts with "news" (case-insensitive).

Summary by CodeRabbit

• New Features

  • Added optional name-based search when retrieving contact lists.
  • Search supports case-insensitive prefix matching.
  • Added an example demonstrating how to search and display matching lists.

• Documentation

  • Updated the Contacts API documentation to describe the optional search filter.

• Tests

  • Added coverage verifying search parameters and filtered results.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3a75eae9-5bac-4681-ba8a-e1a5d9db312d

📥 Commits

Reviewing files that changed from the base of the PR and between 06c17fd and d272c23.

📒 Files selected for processing (5)

• README.md
• examples/contacts/contact_lists.py
• mailtrap/api/resources/contact_lists.py
• mailtrap/models/contacts.py
• tests/unit/api/contacts/test_contact_lists.py

---

📝 Walkthrough

Walkthrough

Contact list retrieval now accepts an optional search filter, represented by a new request-parameter model and passed as a query parameter. The example, README, and unit tests demonstrate and validate the filtered request.

Changes

Contact list search

Layer / File(s)	Summary
Add search filtering to the contact lists API mailtrap/models/contacts.py, mailtrap/api/resources/contact_lists.py, tests/unit/api/contacts/test_contact_lists.py	Adds optional case-insensitive prefix filtering, sends the search query parameter, and tests the request and response.
Document and demonstrate filtered list searches examples/contacts/contact_lists.py, README.md	Adds a search helper and example invocation, and documents the optional list-name filter.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant ContactListsApi
  participant HTTPClient
  Caller->>ContactListsApi: get_list(search)
  ContactListsApi->>HTTPClient: Send search query parameter
  HTTPClient-->>ContactListsApi: Return filtered contact lists
  ContactListsApi-->>Caller: Return ContactList objects

Loading

Possibly related PRs

• mailtrap/mailtrap-python#36: Introduced the ContactListsApi that this change extends with search filtering.

Suggested reviewers: IgorDobryn, i7an, VladimirTaytor, andrii-porokhnavets

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding a search filter to contact lists get_list.
Description check	✅ Passed	The description covers motivation, changes, and testing, with only the Images and GIFs section omitted.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}