Filters
Filters in Bowler are intermediate functions that optionally restrict the set of syntax tree elements originally matched by selectors before being modified. Matched elements must "pass" all filters to get modified – elements that fail a filter will be dropped immediately, and will not be tested by subsequent filters.
All filter functions must match this signature:
def some_filter(node: LN, capture: Capture, filename: Filename) -> bool:
...
| Argument | Description |
|---|---|
| node | The matched syntax tree element. |
| capture | Sub-elements captured by the selector pattern. |
| filename | The file being considered for modification. |
| return value | True if the element should be modified, False otherwise. |
Filter Reference
All filters are accessed as methods on the Query class:
Note: Bowler's API is still in a "provisional" phase. The core concepts will likely stay the same, but individual method signatures may change as the tool matures or gains new functionality.
.filter()
Add a custom filter function to the query.
query.filter(callback: Callback)
| Argument | Description |
|---|---|
| callback | The custom filter function. |
.is_filename()
Restrict modifications to files matching the supplied regular expression[s]. Supports both inclusive and exclusive matches. If both are given, then both must match.
query.is_filename(include: str = None, exclude: str = None)
| Argument | Description |
|---|---|
| include | Only modify files matching the given pattern. |
| exclude | Only modify files that don't match the given pattern. |
.is_call()
Only modify if the matched element is a class, function, or method call. Requires
selector that captures class_call or function_call similar to
.select_function().
query.is_call()
.is_def()
Only modify if the matched element is a class, function, or method definition. Requires
selector that captures class_def or function_def similar to
.select_function().
query.is_def()
.in_class()
Only modify matched elements belonging to the given class, or to a subclass.
Implies use of .is_def().
query.in_class(class_name: str, include_subclasses: bool = True)
| Argument | Description |
|---|---|
| class_name | Name of class or ancestor class to match. |
| include_subclasses | When False, skips elements on subclasses of class_name. |