@@ -136,7 +136,12 @@ True
136136
137137## Filtering and Finding Objects
138138
139- Find windows by index:
139+ libtmux collections support Django-style filtering with ` filter() ` and ` get() ` .
140+ For comprehensive coverage of all lookup operators, see {ref}` querylist-filtering ` .
141+
142+ ### Basic Filtering
143+
144+ Find windows by exact attribute match:
140145
141146``` python
142147>> > session.windows.filter(window_index = window.window_index) # doctest: +ELLIPSIS
@@ -150,6 +155,109 @@ Get a specific pane by ID:
150155Pane(% ... Window(@ ... ... , Session($ ... ... )))
151156```
152157
158+ ### Partial Matching
159+
160+ Use lookup suffixes like ` __contains ` , ` __startswith ` , ` __endswith ` :
161+
162+ ``` python
163+ >> > # Create windows to demonstrate filtering
164+ >> > w1 = session.new_window(window_name = " app-frontend" )
165+ >> > w2 = session.new_window(window_name = " app-backend" )
166+ >> > w3 = session.new_window(window_name = " logs" )
167+
168+ >> > # Find windows starting with 'app-'
169+ >> > session.windows.filter(window_name__startswith = ' app-' ) # doctest: +ELLIPSIS
170+ [Window(@ ... ... :app- frontend, Session($ ... ... )), Window(@ ... ... :app- backend, Session($ ... ... ))]
171+
172+ >> > # Find windows containing 'end'
173+ >> > session.windows.filter(window_name__contains = ' end' ) # doctest: +ELLIPSIS
174+ [Window(@ ... ... :app- frontend, Session($ ... ... )), Window(@ ... ... :app- backend, Session($ ... ... ))]
175+
176+ >> > # Clean up
177+ >> > w1.kill()
178+ >> > w2.kill()
179+ >> > w3.kill()
180+ ```
181+
182+ ### Case-Insensitive Matching
183+
184+ Prefix any lookup with ` i ` for case-insensitive matching:
185+
186+ ``` python
187+ >> > # Create windows with mixed case
188+ >> > w1 = session.new_window(window_name = " MyApp" )
189+ >> > w2 = session.new_window(window_name = " myapp-worker" )
190+
191+ >> > # Case-insensitive search
192+ >> > session.windows.filter(window_name__istartswith = ' myapp' ) # doctest: +ELLIPSIS
193+ [Window(@ ... ... :MyApp, Session($ ... ... )), Window(@ ... ... :myapp- worker, Session($ ... ... ))]
194+
195+ >> > # Clean up
196+ >> > w1.kill()
197+ >> > w2.kill()
198+ ```
199+
200+ ### Regex Filtering
201+
202+ For complex patterns, use ` __regex ` or ` __iregex ` :
203+
204+ ``` python
205+ >> > # Create versioned windows
206+ >> > w1 = session.new_window(window_name = " release-v1.0" )
207+ >> > w2 = session.new_window(window_name = " release-v2.0" )
208+ >> > w3 = session.new_window(window_name = " dev" )
209+
210+ >> > # Match semantic version pattern
211+ >> > session.windows.filter(window_name__regex = r ' v\d + \. \d + ' ) # doctest: +ELLIPSIS
212+ [Window(@ ... ... :release- v1.0, Session($ ... ... )), Window(@ ... ... :release- v2.0, Session($ ... ... ))]
213+
214+ >> > # Clean up
215+ >> > w1.kill()
216+ >> > w2.kill()
217+ >> > w3.kill()
218+ ```
219+
220+ ### Chaining Filters
221+
222+ Multiple conditions can be combined:
223+
224+ ``` python
225+ >> > # Create windows for chaining example
226+ >> > w1 = session.new_window(window_name = " api-prod" )
227+ >> > w2 = session.new_window(window_name = " api-staging" )
228+ >> > w3 = session.new_window(window_name = " web-prod" )
229+
230+ >> > # Multiple conditions in one call (AND)
231+ >> > session.windows.filter(
232+ ... window_name__startswith = ' api' ,
233+ ... window_name__endswith = ' prod'
234+ ... ) # doctest: +ELLIPSIS
235+ [Window(@ ... ... :api- prod, Session($ ... ... ))]
236+
237+ >> > # Chained calls (also AND)
238+ >> > session.windows.filter(
239+ ... window_name__contains = ' api'
240+ ... ).filter(
241+ ... window_name__contains = ' staging'
242+ ... ) # doctest: +ELLIPSIS
243+ [Window(@ ... ... :api- staging, Session($ ... ... ))]
244+
245+ >> > # Clean up
246+ >> > w1.kill()
247+ >> > w2.kill()
248+ >> > w3.kill()
249+ ```
250+
251+ ### Get with Default
252+
253+ Avoid exceptions when an object might not exist:
254+
255+ ``` python
256+ >> > # Returns None instead of raising ObjectDoesNotExist
257+ >> > session.windows.get(window_name = " nonexistent" , default = None ) is None
258+ True
259+ ```
260+
153261## Checking Relationships
154262
155263Check if objects are related:
0 commit comments