# utils


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Data Structures

Common data structures used across CLI tools:

------------------------------------------------------------------------

### SearchResult

``` python

def SearchResult(
    content_type:str, module_name:str, item_name:str, match_context:str, match_location:str, score:float=1.0
)->None:

```

*Represents a single search result.*

## Display Helper Functions

Common helper functions for formatting display output:

------------------------------------------------------------------------

### print_header

``` python

def print_header(
    title:str, # Header title to display
    width:int=60, # Width of separator line in characters
)->None: # No return value

```

*Print a formatted header with title and separator.*

------------------------------------------------------------------------

### print_not_found

``` python

def print_not_found(
    item_type:str, # Type of item that wasn't found (e.g., 'factory', 'example')
    item_name:str, # Name of the item that wasn't found
    module_name:Optional=None, # Optional module name where search was performed
    config:Optional=None, # Optional configuration
)->None: # No return value

```

*Print a standardized not found message.*

------------------------------------------------------------------------

### print_total

``` python

def print_total(
    item_type:str, # Type of items being counted (e.g., 'factories', 'examples')
    count:int, # Number of items found
    across_modules:bool=False, # Whether count spans multiple modules
)->None: # No return value

```

*Print a standardized total count message.*

------------------------------------------------------------------------

### print_helpful_instructions

``` python

def print_helpful_instructions(
    instructions:List, # List of (description, example) tuples
):

```

*Print helpful instructions section.*

------------------------------------------------------------------------

### display_items_generic

``` python

def display_items_generic(
    items:Union, # Items to display (dict of lists or list)
    title:str, # Title for the display
    item_formatter:Callable, # Function to format each item
    item_type:str, # Type of items for the total message
    instructions:Optional=None, # Help instructions
    not_found_message:Optional=None, # Custom not found message
):

```

*Generic function to display a collection of items with consistent
formatting.*

## Search Helper Functions

Helper functions for search operations:

------------------------------------------------------------------------

### handle_module_not_found

``` python

def handle_module_not_found(
    item_type:str, # Type of items not found (e.g., 'factories', 'examples')
    module_name:str, # Name of the module that wasn't found
    config:Optional=None, # Optional configuration
):

```

*Print standardized error message for module not found.*

------------------------------------------------------------------------

### simple_item_formatter

``` python

def simple_item_formatter(
    name_field:str, # Name of the field containing the item name
    doc_field:str, # Name of the field containing the documentation
)->Callable: # Formatter function

```

*Create a simple formatter for items with name and documentation
fields.*

------------------------------------------------------------------------

### indented_item_formatter

``` python

def indented_item_formatter(
    prefix:str='  ', # Indentation prefix
)->Callable: # Returns a formatter factory

```

*Create a formatter that indents items with a prefix.*

------------------------------------------------------------------------

### extract_match_context

``` python

def extract_match_context(
    text:str, # Text to extract context from
    query:str, # Query string to find
    case_sensitive:bool=False, # Whether to perform case-sensitive search
    context_size:int=30, # Number of characters to show before and after match
)->str: # Context string with match highlighted

```

*Extract context around a match in text.*

------------------------------------------------------------------------

### extract_source_line_context

``` python

def extract_source_line_context(
    source:str, # Source code to search
    query:str, # Query string to find
    case_sensitive:bool=False, # Whether to perform case-sensitive search
)->str: # Line context showing where match was found

```

*Extract line context for a match in source code.*

------------------------------------------------------------------------

### create_search_result

``` python

def create_search_result(
    content_type:str, # Type of content ('factory', 'example', 'helper', 'module')
    module_name:str, # Module where match was found
    item_name:str, # Name of the item that matched
    match_context:str, # Context showing the match
    match_location:str, # Where in the item the match was found ('name', 'doc', 'source')
)->SearchResult: # SearchResult instance with provided fields

```

*Create a SearchResult with standard fields.*

------------------------------------------------------------------------

### search_in_text

``` python

def search_in_text(
    query:str, # Search query
    text:str, # Text to search in
    case_sensitive:bool=False, # Whether to perform case-sensitive search
)->bool: # True if match found

```

*Check if query exists in text.*

------------------------------------------------------------------------

### search_in_name_and_text

``` python

def search_in_name_and_text(
    query:str, # Search query to find
    item_name:str, # Item name to search in
    text:str, # Text (documentation, docstring) to search in
    content_type:str, # Type of content being searched
    module_name:str, # Module containing the item
    text_location:str, # Description of text field (e.g., 'documentation', 'docstring')
    case_sensitive:bool=False, # Whether to perform case-sensitive search
)->List: # List of search results for matches found

```

*Search in both name and text fields, returning search results.*

------------------------------------------------------------------------

### check_factory_usage_patterns

``` python

def check_factory_usage_patterns(
    factory_name:str, # Name of factory to create patterns for
)->List: # List of regex patterns matching factory usage

```

*Get regex patterns to match common factory usage patterns.*

## Enhanced Search Functions

Advanced search helper functions:

------------------------------------------------------------------------

### search_in_fields

``` python

def search_in_fields(
    item:Any, # The item to search in
    query:str, # Search query
    fields:Dict, # field_name -> getter function
    content_type:str, # Type of content being searched
    module_name:str, # Module containing the item
    item_name:str, # Name of the item
    case_sensitive:bool=False, # Whether to perform case-sensitive search
)->List: # List of search results

```

*Search for query in multiple fields of an item.*

------------------------------------------------------------------------

### search_in_source_code

``` python

def search_in_source_code(
    source:str, # Source code to search in
    query:str, # Search query
    content_type:str, # Type of content being searched
    module_name:str, # Module containing the source
    item_name:str, # Name of the item
    case_sensitive:bool=False, # Whether to perform case-sensitive search
)->Optional: # Search result or None

```

*Search in source code and return result with line context.*

------------------------------------------------------------------------

### find_variable_usages

``` python

def find_variable_usages(
    func_src:str, # Source code to search
    var_name:str, # Variable name to find
)->List: # List of (line_number, column, context_type) tuples

```

*Find variable usages by parsing function into an AST.*

------------------------------------------------------------------------

### find_usage_in_items

``` python

def find_usage_in_items(
    target_name:str, # Name of the target (factory/helper) to find usage for
    items:Dict, # Dictionary of module_name -> list of items
    source_getter:Callable, # Function to get source code from item
    item_type:str, # Type of items being searched (for display)
)->List: # List of (module_name, item) tuples

```

*Find items that use a specific target (factory/helper).*

## Module Discovery Helpers

Helper functions for module discovery and iteration:

## Command Generation Helpers

Helper functions for generating CLI commands:

------------------------------------------------------------------------

### get_view_command

``` python

def get_view_command(
    content_type:str, # Type of content ('factory', 'example', 'helper', 'module')
    module_name:str, # Module name
    item_name:str, # Item name (or feature name for examples)
    config:Optional=None, # Optional configuration
)->str: # CLI command to view the item

```

*Get the CLI command to view a specific item.*

------------------------------------------------------------------------

### format_usage_examples

``` python

def format_usage_examples(
    usage_items:List, # List of (module_name, item) tuples
    item_name_getter:Callable, # Function to get item name
    item_type:str, # Type of items ('examples' or 'helpers')
    view_command_type:str, # Type for get_view_command ('example' or 'helper')
)->List: # List of formatted strings

```

*Format usage examples for display.*

------------------------------------------------------------------------

### discover_utility_modules

``` python

def discover_utility_modules(
    config:Optional=None, # Optional configuration, uses active if not provided
    include_submodules:bool=True, # Whether to include submodules
)->List: # List of (module_name, module) tuples

```

*Discover all utility modules based on configuration, including
submodules.*

------------------------------------------------------------------------

### iterate_all_modules_with_items

``` python

def iterate_all_modules_with_items(
    extractor_func:Callable, # Function to extract items from a module
    module_filter:Optional=None, # Optional specific module to filter for
    config:Optional=None, # Optional configuration
)->Dict: # Dictionary mapping module names to their items

```

*Generic iterator for extracting items from all modules.*

------------------------------------------------------------------------

### extract_helper_names_from_test

``` python

def extract_helper_names_from_test(
    source:str, # Source code of the test_<module>_helper_examples function
)->List: # List of helper function names

```

*Extract helper function names from test source code.*

------------------------------------------------------------------------

### load_code_from_file

``` python

def load_code_from_file(
    filepath:str, # Path to file to load
)->Optional: # File contents as string, or None if error

```

*Load code from a file.*

------------------------------------------------------------------------

### list_utility_modules

``` python

def list_utility_modules(
    config:Optional=None, # Optional configuration
)->Dict: # Dictionary mapping module names to their docstrings

```

*List all available utility modules with their docstrings.*

## Export