utils

Utility functions for CLI tools

Data Structures

Common data structures used across CLI tools:

SearchResult


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:

display_items_generic


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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