Skip to content

Commit e36069b

Browse files
committed
docs(topics/traversal): add rich filtering examples
why: The traversal topic had minimal filtering coverage. Users need practical examples of partial matching, case-insensitive search, regex patterns, and filter chaining. what: - Add cross-reference to new filtering topic - Add partial matching examples (__contains, __startswith, __endswith) - Add case-insensitive matching examples (__istartswith) - Add regex filtering examples (__regex) - Add filter chaining examples (multiple conditions, chained calls) - Add get() with default parameter example - All 23 traversal doctests pass
1 parent deef8bf commit e36069b

File tree

1 file changed

+109
-1
lines changed

1 file changed

+109
-1
lines changed

docs/topics/traversal.md

Lines changed: 109 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -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:
150155
Pane(%... 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

155263
Check if objects are related:

0 commit comments

Comments
 (0)