API Reference

Complete reference documentation for all FailExtract classes, functions, and interfaces.

Note

FailExtract follows a progressive enhancement model. Core functionality is always available, with optional features providing additional capabilities.

Main Module

Failextract - Comprehensive test failure extraction and reporting library.

This library provides advanced capabilities for extracting, analyzing, and reporting test failures in pytest-based testing environments. It automatically captures detailed failure context including fixture information, source code, and dependency chains to aid in debugging and analysis.

Key Features:

• Automatic fixture extraction and dependency analysis

• Multiple output formats (JSON always available, others via extras)

• Thread-safe singleton design for concurrent test execution

• Performance-optimized with intelligent caching

• Extensible formatter system for custom output formats

• Memory management with configurable limits

• Integration with pytest through decorators

Optional Feature Extras:

• Formatters: YAML formatter (pip install failextract[formatters])

• Config: Advanced configuration validation (pip install failextract[config])

• CLI: Rich terminal output (pip install failextract[cli])

Example

Basic usage with the decorator:

>>> from failextract import extract_on_failure
>>>
>>> @extract_on_failure
>>> def test_example():
...     assert 1 == 2, "This will be captured with full context"

Generate comprehensive reports:

>>> from failextract import FailureExtractor, OutputConfig
>>>
>>> extractor = FailureExtractor()
>>> config = OutputConfig("failures.json", format="json")  # JSON always available
>>> extractor.save_report(config)

Author: Failextract Contributors License: Apache 2.0

class failextract.CodeContextExtractor

Bases: object

Extract and manage code context for test failures.

This class provides intelligent code context extraction with configurable depth and context lines. It implements caching for performance and thread-safe operation consistent with FailExtract’s singleton patterns.

Features: - Configurable context lines before/after failure points - Intelligent source code caching with memory management - Thread-safe operation for concurrent test execution - Enhanced error handling for edge cases - Integration with existing source extraction functions

_source_cache

Cache for source files with modification time

Type:

Dict[str, tuple]

_lock

Thread safety lock for cache operations

Type:

threading.RLock

_max_cache_size

Maximum number of cached source files

Type:

int

__init__()

Initialize the CodeContextExtractor with cache and configuration.

static __new__(cls)

Implement thread-safe singleton pattern.

analyze_dependencies(filename, max_depth=3)

Analyze file dependencies and create dependency graph.

Performs recursive dependency analysis starting from a file to build a comprehensive dependency graph including direct imports, transitive dependencies, and circular dependency detection.

Parameters:

• filename (str) – Path to the Python file to analyze

• max_depth (int) – Maximum recursion depth for dependency analysis

Returns:

• ‘direct_imports’: List of directly imported modules

• ’dependency_graph’: Nested dict of dependencies by depth level

• ’circular_dependencies’: List of detected circular dependencies

• ’unresolved_modules’: List of modules that couldn’t be resolved

• ’total_dependencies’: Count of all unique dependencies

Return type:

Dictionary containing dependency analysis with keys

Example

>>> extractor = CodeContextExtractor()
>>> deps = extractor.analyze_dependencies("test_file.py")
>>> print(deps['total_dependencies'])
15

analyze_imports(filename)

Analyze imports in a Python file using static analysis.

Extracts and categorizes all import statements from a Python file, providing detailed information about each import including line numbers, module names, aliases, and import types.

Parameters:

filename (str) – Path to the Python file to analyze

Returns:

• ‘type’: Import type (‘import’, ‘from_import’)

• ’module’: Module name being imported

• ’names’: List of imported names (for from imports)

• ’alias’: Alias used (as clause)

• ’line’: Line number of the import statement

• ’level’: Relative import level (0 for absolute)

Return type:

List of dictionaries containing import information with keys

Example

>>> extractor = CodeContextExtractor()
>>> imports = extractor.analyze_imports("test_file.py")
>>> print(imports[0])
{'type': 'import', 'module': 'os', 'names': [], 'alias': None, 'line': 1, 'level': 0}

build_dependency_graph(root_file, max_depth=3)

Build a comprehensive dependency graph starting from a root file.

Creates a structured dependency graph that can be used for visualization, analysis, and understanding test code relationships.

Parameters:

• root_file (str) – Starting file for dependency analysis

• max_depth (int) – Maximum depth for dependency traversal

Return type:

DependencyGraph

Returns:

DependencyGraph object containing the complete graph structure

clear_cache()

Clear all caches including source, imports, dependencies, AST, execution trace, and coverage.

combine_coverage_with_dependencies(frame)

Combine coverage data with dependency analysis.

Provides comprehensive analysis combining static dependencies, execution traces, and coverage data for complete context.

Parameters:

frame – Frame object containing the execution context

Return type:

Dict[str, Any]

Returns:

Dictionary containing combined analysis results

extract_function_source_with_context(frame, context_lines=5, include_line_numbers=True, max_lines=None)

Extract function source with configurable context lines.

Enhanced version of extract_function_source that provides context lines around the failure point and additional metadata for better presentation.

Parameters:

• frame – Frame object containing the execution context

• context_lines (int) – Number of lines to include before/after the failure line

• include_line_numbers (bool) – Whether to include line number information

• max_lines (Optional[int]) – Maximum number of lines to return (None for no limit)

Returns:

• ‘source’: Source code with context (string)

• ’lines’: Source code lines (list of strings)

• ’failure_line’: Line number where failure occurred

• ’start_line’: Starting line number of the extracted context

• ’end_line’: Ending line number of the extracted context

• ’filename’: Path to the source file

• ’function_name’: Name of the function containing the failure

• ’context_type’: Type of context (‘function’, ‘class’, ‘module’)

• ’include_line_numbers’: Whether line numbers were included

• ’error’: Error message if extraction failed

Return type:

Dictionary containing

Example

>>> extractor = CodeContextExtractor()
>>> context = extractor.extract_function_source_with_context(frame, context_lines=3)
>>> print(context['source'])
def test_example():
    x = 1
    y = 2
    assert x == y  # <- Failure line
    return True

get_cache_stats()

Get cache statistics for debugging and monitoring.

Return type:

Dict[str, Any]

get_coverage_for_file(filename)

Get coverage information for a specific file.

Parameters:

filename (str) – Path to the file to get coverage for

Return type:

Optional[Dict[str, Any]]

Returns:

Coverage information dictionary or None if not available

get_executed_lines_for_function(frame)

Get coverage information for the specific function context.

Analyzes coverage data to determine which lines were executed in the context of the failing function.

Parameters:

frame – Frame object containing the execution context

Return type:

Dict[str, Any]

Returns:

Dictionary containing function-specific coverage information

get_execution_summary()

Get summary of execution trace data.

Return type:

Dict[str, Any]

Returns:

Dictionary containing execution trace analysis

get_function_dependencies(frame)

Get dependencies specific to a function’s execution context.

Analyzes the imports and dependencies relevant to a specific function’s execution, providing contextual dependency information for failure analysis.

Parameters:

frame – Frame object containing the execution context

Return type:

Dict[str, Any]

Returns:

Dictionary containing function-specific dependency information

integrate_coverage_data(coverage_data_file=None)

Integrate with coverage.py data when available.

Loads and processes coverage data to provide insights into which code paths were executed during test runs. This complements static analysis with runtime execution information.

Parameters:

coverage_data_file (Optional[str]) – Path to coverage data file (None for auto-detect)

Return type:

Dict[str, Any]

Returns:

Dictionary containing coverage integration results

integrate_trace_with_dependencies(frame)

Integrate execution trace data with static dependency analysis.

Combines static analysis results with runtime execution information to provide comprehensive dependency context for failure analysis.

Parameters:

frame – Frame object containing the execution context

Return type:

Dict[str, Any]

Returns:

Dictionary containing integrated dependency and execution information

start_execution_trace(file_filters=None, max_trace_entries=1000, mode='static', sample_rate=1)

Start optimized execution tracing for dependency analysis.

Enables execution tracing to track function calls and imports during test execution. This provides runtime dependency information to complement static analysis.

Parameters:

• file_filters (Optional[List[str]]) – List of file paths/patterns to trace (None for all files)

• max_trace_entries (int) – Maximum number of trace entries to keep

• mode (str) – ‘static’ (no runtime, 0% overhead), ‘profile’ (functions), ‘trace’ (lines)

• sample_rate (int) – Sample every Nth call (1=no sampling, 10=sample 10%)

Return type:

None

Note

Defaults to ‘static’ mode for 0% overhead. Use ‘profile’ for <10% overhead with runtime dependency tracking.

stop_execution_trace()

Stop execution tracing and return collected trace data.

Return type:

List[Dict[str, Any]]

Returns:

List of trace entries with execution information

class failextract.FixtureExtractor

Bases: object

Extract fixture definitions and their dependencies.

This class provides functionality to analyze test functions and extract information about pytest fixtures they depend on, including fixture definitions, dependencies, and scope information. It uses caching for performance optimization.

_fixture_cache

Internal cache for fixture definitions to improve performance on repeated lookups.

Type:

Dict[str, Dict[str, Any]]

__init__()

Initialize the FixtureExtractor with an empty cache.

Creates a new instance with an empty fixture cache. The cache will be populated as fixtures are discovered and analyzed.

Example

>>> extractor = FixtureExtractor()
>>> fixtures = extractor.get_fixture_info(my_test_function)
>>> print(len(fixtures))
3

get_fixture_info(test_func, frame_locals=None)

Extract all fixtures used by a test function.

Analyzes the test function’s signature to identify fixture dependencies, then recursively extracts information about each fixture including its definition, scope, dependencies, and source code.

Parameters:

• test_func (Callable) – The test function to analyze for fixture dependencies

• frame_locals (dict) – Optional dictionary of local variables from the test execution frame, used for enhanced fixture discovery

Returns:

• ‘name’: Fixture name

• ’type’: Always ‘fixture’

• ’scope’: Fixture scope (‘function’, ‘class’, ‘module’, ‘session’)

• ’source’: Source code of the fixture function

• ’dependencies’: List of other fixtures this fixture depends on

• ’file’: Path to file containing the fixture definition

Return type:

List of dictionaries containing fixture information with keys

Example

>>> def test_example(user_fixture, db_fixture):
...     pass
>>> extractor = FixtureExtractor()
>>> fixtures = extractor.get_fixture_info(test_example)
>>> print(fixtures[0]['name'])
'user_fixture'
>>> print(fixtures[0]['scope'])
'function'

class failextract.FailureExtractor

Bases: object

Enhanced thread-safe singleton to collect test failures with flexible output.

This class implements a singleton pattern to provide centralized collection of test failure data across the application. It maintains thread-safe access to failure collections and supports configurable memory limits for large test suites.

failures

Collection of test failure data

Type:

List[Dict[str, Any]]

passed

Collection of passed test data (optional)

Type:

List[Dict[str, Any]]

fixture_extractor

Instance for extracting fixture context

Type:

FixtureExtractor

Example

>>> extractor = FailureExtractor()
>>> failure_data = {
...     'test_name': 'test_example',
...     'test_module': 'test_module',
...     'exception_type': 'AssertionError',
...     'exception_message': 'Test failed',
...     'timestamp': '2024-01-01T12:00:00'
... }
>>> extractor.add_failure(failure_data)
>>> print(len(extractor.failures))
1

add_failure(failure_data)

Add a test failure to the collection.

Stores test failure data in the internal collection with thread-safe access. Automatically enforces memory limits if configured.

Parameters:

failure_data (Dict[str, Any]) – Dictionary containing failure information with keys: - ‘test_name’: Name of the failed test - ‘test_module’: Module containing the test - ‘test_file’: File path of the test - ‘exception_type’: Type of exception raised - ‘exception_message’: Exception message - ‘timestamp’: When the failure occurred - Additional context data from fixture extraction

Example

>>> extractor = FailureExtractor()
>>> failure_data = {
...     'test_name': 'test_example',
...     'test_module': 'test_module',
...     'exception_type': 'AssertionError',
...     'exception_message': 'Test failed',
...     'timestamp': '2024-01-01T12:00:00'
... }
>>> extractor.add_failure(failure_data)
>>> print(len(extractor.failures))
1

add_passed(test_data)

Add a passed test to the collection.

Stores passed test data in the internal collection with thread-safe access. Used when include_passed=True in configuration. Automatically enforces memory limits if configured.

Parameters:

test_data (Dict[str, Any]) – Dictionary containing test information with keys: - ‘test_name’: Name of the passed test - ‘test_module’: Module containing the test - ‘test_file’: File path of the test - ‘timestamp’: When the test passed - Additional context data from fixture extraction

Example

>>> extractor = FailureExtractor()
>>> test_data = {
...     'test_name': 'test_successful',
...     'test_module': 'test_module',
...     'test_file': '/path/to/test.py',
...     'timestamp': '2024-01-01T12:00:00'
... }
>>> extractor.add_passed(test_data)
>>> print(len(extractor.passed))
1

clear()

Clear stored data but keep memory limits.

get_memory_limits()

Get current memory limits.

Return type:

Dict[str, Optional[int]]

get_stats()

Get statistics about stored data.

Return type:

Dict[str, Any]

reset()

Reset all stored data and memory limits to defaults.

save_report(config)

Save report with specified configuration.

set_memory_limits(max_failures=None, max_passed=None)

Set memory limits for stored test data.

Parameters:

• max_failures (Optional[int]) – Maximum number of failures to keep (None for unlimited)

• max_passed (Optional[int]) – Maximum number of passed tests to keep (None for unlimited)

class failextract.OutputConfig(output=None, format=None, append=False, include_passed=False, max_failures=None, include_source=True, include_fixtures=True, code_context_lines=5, max_code_lines=100, include_line_numbers=True, enhanced_context=True, include_traceback=True, include_metadata=True, timestamp_format='%Y-%m-%dT%H:%M:%S')

Bases: object

Configuration for output handling and report generation.

This class manages all configuration options for generating test failure reports, including output format, file paths, append behavior, content filtering options, and enhanced code inclusion settings.

filename

Path to output file, None for stdout

Type:

Optional[str]

format

Output format for the report

Type:

OutputFormat

append

Whether to append to existing file

Type:

bool

include_passed

Whether to include passed tests in report

Type:

bool

max_failures

Maximum number of failures to include

Type:

Optional[int]

include_source

Whether to include source code in reports

Type:

bool

include_fixtures

Whether to include fixture information

Type:

bool

code_context_lines

Number of context lines around failure points

Type:

int

max_code_lines

Maximum lines of code to include per failure

Type:

int

include_line_numbers

Whether to include line numbers in source code

Type:

bool

enhanced_context

Whether to use enhanced CodeContextExtractor

Type:

bool

include_traceback

Whether to include traceback information

Type:

bool

include_metadata

Whether to include metadata in reports

Type:

bool

timestamp_format

Format string for timestamps

Type:

str

__init__(output=None, format=None, append=False, include_passed=False, max_failures=None, include_source=True, include_fixtures=True, code_context_lines=5, max_code_lines=100, include_line_numbers=True, enhanced_context=True, include_traceback=True, include_metadata=True, timestamp_format='%Y-%m-%dT%H:%M:%S')

Initialize output configuration with validation.

Creates a new output configuration with automatic format detection from file extensions and comprehensive parameter validation.

Parameters:

• output (Union[str, Path, OutputFormat, None]) – Output destination - file path (str/Path) or format enum. If None, outputs to stdout with JSON format.

• format (Union[str, OutputFormat, None]) – Explicit format specification, overrides format detection from file extension. Can be OutputFormat enum or string.

• append (bool) – If True, append to existing file instead of overwriting

• include_passed (bool) – If True, include passed tests in the report

• max_failures (Optional[int]) – Maximum number of failures to include in report

• include_source (bool) – If True, include source code in failure reports

• include_fixtures (bool) – If True, include fixture information in reports

• code_context_lines (int) – Number of lines to include before/after failure points

• max_code_lines (int) – Maximum total lines of code per failure (performance limit)

• include_line_numbers (bool) – If True, add line numbers to source code display

• enhanced_context (bool) – If True, use enhanced CodeContextExtractor for better context

Raises:

• ValueError – If output format cannot be determined or is invalid

• TypeError – If parameters have incorrect types

Example

>>> # Output to JSON file
>>> config = OutputConfig("failures.json")
>>> print(config.format)
OutputFormat.JSON

>>> # Explicit format override
>>> config = OutputConfig("report.txt", format="markdown")
>>> print(config.format)
OutputFormat.MARKDOWN

>>> # Append mode with filtering
>>> config = OutputConfig(
...     "results.json",
...     append=True,
...     max_failures=50
... )
>>> print(config.append)
True

__str__()

Return string representation of OutputConfig.

class failextract.OutputFormat(value)

Bases: Enum

Supported output formats.

JSON = 'json'

MARKDOWN = 'md'

YAML = 'yaml'

XML = 'xml'

CSV = 'csv'

CUSTOM = 'custom'

class failextract.OutputFormatter

Bases: ABC

Base class for output formatters.

This abstract base class defines the interface that all output formatters must implement. It provides the foundation for creating custom formatters that can render test failure data in various formats.

Subclasses must implement the format() and get_extension() methods to provide format-specific rendering and file extension handling.

abstractmethod format(failures)

Format failure data for output.

Parameters:

failures (List[Dict[str, Any]]) – List of failure dictionaries containing test failure information

Return type:

str

Returns:

Formatted string representation of the failure data

Raises:

NotImplementedError – If not implemented by subclass

abstractmethod get_extension()

Get default file extension for this format.

Return type:

str

Returns:

File extension string (e.g., ‘json’, ‘md’, ‘xml’)

Raises:

NotImplementedError – If not implemented by subclass

class failextract.JSONFormatter

Bases: OutputFormatter

JSON output formatter for test failure reports.

This formatter produces structured JSON output suitable for programmatic processing, integration with tools, and serving as input for other processing systems. The JSON format is always available in FailExtract and does not require any optional dependencies.

The output includes full test failure information with proper JSON serialization handling for Python-specific types like datetime objects.

Example

>>> formatter = JSONFormatter()
>>> failures = [{'test_name': 'test_example', 'timestamp': '2024-01-01'}]
>>> json_output = formatter.format(failures)
>>> print(json_output)
[
  {
    "test_name": "test_example",
    "timestamp": "2024-01-01"
  }
]

format(failures)

Format failure data as JSON.

Parameters:

failures (List[Dict[str, Any]]) – List of failure dictionaries containing test failure information

Return type:

str

Returns:

Pretty-formatted JSON string with 2-space indentation

Note

Uses json.dumps with default=str to handle non-serializable types like datetime objects by converting them to strings.

get_extension()

Get the file extension for JSON files.

Return type:

str

Returns:

File extension ‘.json’

failextract.extract_on_failure(output=None, format=None, include_locals=False, include_fixtures=True, max_depth=10, skip_stdlib=True, extract_classes=True, append=False, custom_formatter=None, code_context_lines=5, enhanced_context=True, include_line_numbers=True, max_code_lines=100)

Enhanced decorator with flexible output options.

Parameters:

• output (Union[str, Path, OutputFormat, OutputConfig, None]) – Output configuration - can be: - str/Path: File path (format detected from extension) - OutputFormat: Format type (uses default filename) - OutputConfig: Full configuration object - None: Use global collection

• format (Union[str, OutputFormat, None]) – Override format detection (when output is a path)

• include_locals (bool) – Include local variables

• include_fixtures (bool) – Extract fixture definitions

• max_depth (int) – Maximum traceback depth

• skip_stdlib (bool) – Skip standard library modules

• extract_classes (bool) – Extract class definitions

• append (bool) – Append to existing file instead of overwriting

• custom_formatter (Optional[OutputFormatter]) – Custom formatter instance

• code_context_lines (int) – Number of context lines around failure points

• enhanced_context (bool) – Whether to use enhanced CodeContextExtractor

• include_line_numbers (bool) – Whether to include line numbers in source code

• max_code_lines (int) – Maximum lines of code per failure frame

Examples

@extract_on_failure(“failures.json”) @extract_on_failure(“report.md”) @extract_on_failure(output=”results.xml”, format=”xml”) @extract_on_failure(OutputFormat.YAML) @extract_on_failure(output=OutputConfig(“report.xml”, append=True))

failextract.extract_failure_info(test_func_or_exception, exception_or_frame=None, args=None, kwargs=None, frame_locals=None, include_locals=False, include_fixtures=True, max_depth=10, skip_stdlib=True, extract_classes=True, code_context_lines=5, enhanced_context=True, include_line_numbers=True, max_code_lines=100, config=None)

Extract comprehensive failure information including fixtures and enhanced code context.

Supports both new signature: extract_failure_info(test_func, exception, args, kwargs, …) And legacy signature: extract_failure_info(exception, frame, config=…)

Parameters:

• test_func_or_exception – The test function that failed OR exception (for backward compatibility)

• exception_or_frame – The exception that was raised OR frame (for backward compatibility)

• args (tuple) – Arguments passed to the test function

• kwargs (dict) – Keyword arguments passed to the test function

• frame_locals (dict) – Local variables from the test frame

• include_locals (bool) – Whether to include local variables in the output

• include_fixtures (bool) – Whether to extract fixture information

• max_depth (int) – Maximum traceback depth to analyze

• skip_stdlib (bool) – Whether to skip standard library frames

• extract_classes (bool) – Whether to extract class source for methods

• code_context_lines (int) – Number of context lines around failure points

• enhanced_context (bool) – Whether to use enhanced CodeContextExtractor

• include_line_numbers (bool) – Whether to include line numbers in source

• max_code_lines (int) – Maximum lines of code per frame

• config – OutputConfig for backward compatibility

Return type:

Dict[str, Any]

Returns:

Dictionary containing comprehensive failure information with enhanced code context

failextract.extract_function_source(frame)

Extract complete function source from a frame.

Return type:

Optional[str]

failextract.save_single_failure(failure_data, filename)

Save a single failure to a file.

failextract.save_failure_report(filename='test_failures_report.json', format='json')

Save all collected failures to a file.

failextract.save_with_config(data, config)

Save single failure with configuration.

failextract.generate_session_report(output='test_failures_report.md', format=None, clear=True)

Generate a report for all collected failures.

failextract.get_available_features()

Get information about available features based on installed extras.

Return type:

dict

Returns:

Dictionary with feature availability information.

failextract.suggest_installation(feature_name)

Suggest installation command for a missing feature.

Parameters:

feature_name (str) – Name of the feature to install

Return type:

str

Returns:

Installation command suggestion

failextract.__getattr__(name)

Dynamic attribute access for optional features with helpful error messages.

Return type:

Any

Core Classes

FailureExtractor

The main singleton class for managing failure data throughout a session.

class failextract.FailureExtractor

Bases: object

Enhanced thread-safe singleton to collect test failures with flexible output.

This class implements a singleton pattern to provide centralized collection of test failure data across the application. It maintains thread-safe access to failure collections and supports configurable memory limits for large test suites.

failures

Collection of test failure data

Type:

List[Dict[str, Any]]

passed

Collection of passed test data (optional)

Type:

List[Dict[str, Any]]

fixture_extractor

Instance for extracting fixture context

Type:

FixtureExtractor

Example

>>> extractor = FailureExtractor()
>>> failure_data = {
...     'test_name': 'test_example',
...     'test_module': 'test_module',
...     'exception_type': 'AssertionError',
...     'exception_message': 'Test failed',
...     'timestamp': '2024-01-01T12:00:00'
... }
>>> extractor.add_failure(failure_data)
>>> print(len(extractor.failures))
1

add_failure(failure_data)

Add a test failure to the collection.

Stores test failure data in the internal collection with thread-safe access. Automatically enforces memory limits if configured.

Parameters:

failure_data (Dict[str, Any]) – Dictionary containing failure information with keys: - ‘test_name’: Name of the failed test - ‘test_module’: Module containing the test - ‘test_file’: File path of the test - ‘exception_type’: Type of exception raised - ‘exception_message’: Exception message - ‘timestamp’: When the failure occurred - Additional context data from fixture extraction

Example

>>> extractor = FailureExtractor()
>>> failure_data = {
...     'test_name': 'test_example',
...     'test_module': 'test_module',
...     'exception_type': 'AssertionError',
...     'exception_message': 'Test failed',
...     'timestamp': '2024-01-01T12:00:00'
... }
>>> extractor.add_failure(failure_data)
>>> print(len(extractor.failures))
1

add_passed(test_data)

Add a passed test to the collection.

Stores passed test data in the internal collection with thread-safe access. Used when include_passed=True in configuration. Automatically enforces memory limits if configured.

Parameters:

test_data (Dict[str, Any]) – Dictionary containing test information with keys: - ‘test_name’: Name of the passed test - ‘test_module’: Module containing the test - ‘test_file’: File path of the test - ‘timestamp’: When the test passed - Additional context data from fixture extraction

Example

>>> extractor = FailureExtractor()
>>> test_data = {
...     'test_name': 'test_successful',
...     'test_module': 'test_module',
...     'test_file': '/path/to/test.py',
...     'timestamp': '2024-01-01T12:00:00'
... }
>>> extractor.add_passed(test_data)
>>> print(len(extractor.passed))
1

save_report(config)

Save report with specified configuration.

set_memory_limits(max_failures=None, max_passed=None)

Set memory limits for stored test data.

Parameters:

• max_failures (Optional[int]) – Maximum number of failures to keep (None for unlimited)

• max_passed (Optional[int]) – Maximum number of passed tests to keep (None for unlimited)

get_memory_limits()

Get current memory limits.

Return type:

Dict[str, Optional[int]]

get_stats()

Get statistics about stored data.

Return type:

Dict[str, Any]

reset()

Reset all stored data and memory limits to defaults.

clear()

Clear stored data but keep memory limits.

FixtureExtractor

Specialized extractor for pytest fixture analysis.

class failextract.FixtureExtractor

Bases: object

Extract fixture definitions and their dependencies.

This class provides functionality to analyze test functions and extract information about pytest fixtures they depend on, including fixture definitions, dependencies, and scope information. It uses caching for performance optimization.

_fixture_cache

Internal cache for fixture definitions to improve performance on repeated lookups.

Type:

Dict[str, Dict[str, Any]]

__init__()

Initialize the FixtureExtractor with an empty cache.

Creates a new instance with an empty fixture cache. The cache will be populated as fixtures are discovered and analyzed.

Example

>>> extractor = FixtureExtractor()
>>> fixtures = extractor.get_fixture_info(my_test_function)
>>> print(len(fixtures))
3

get_fixture_info(test_func, frame_locals=None)

Extract all fixtures used by a test function.

Analyzes the test function’s signature to identify fixture dependencies, then recursively extracts information about each fixture including its definition, scope, dependencies, and source code.

Parameters:

• test_func (Callable) – The test function to analyze for fixture dependencies

• frame_locals (dict) – Optional dictionary of local variables from the test execution frame, used for enhanced fixture discovery

Returns:

• ‘name’: Fixture name

• ’type’: Always ‘fixture’

• ’scope’: Fixture scope (‘function’, ‘class’, ‘module’, ‘session’)

• ’source’: Source code of the fixture function

• ’dependencies’: List of other fixtures this fixture depends on

• ’file’: Path to file containing the fixture definition

Return type:

List of dictionaries containing fixture information with keys

Example

>>> def test_example(user_fixture, db_fixture):
...     pass
>>> extractor = FixtureExtractor()
>>> fixtures = extractor.get_fixture_info(test_example)
>>> print(fixtures[0]['name'])
'user_fixture'
>>> print(fixtures[0]['scope'])
'function'

OutputConfig

Configuration class for report generation.

class failextract.OutputConfig(output=None, format=None, append=False, include_passed=False, max_failures=None, include_source=True, include_fixtures=True, code_context_lines=5, max_code_lines=100, include_line_numbers=True, enhanced_context=True, include_traceback=True, include_metadata=True, timestamp_format='%Y-%m-%dT%H:%M:%S')

Bases: object

Configuration for output handling and report generation.

This class manages all configuration options for generating test failure reports, including output format, file paths, append behavior, content filtering options, and enhanced code inclusion settings.

filename

Path to output file, None for stdout

Type:

Optional[str]

format

Output format for the report

Type:

OutputFormat

append

Whether to append to existing file

Type:

bool

include_passed

Whether to include passed tests in report

Type:

bool

max_failures

Maximum number of failures to include

Type:

Optional[int]

include_source

Whether to include source code in reports

Type:

bool

include_fixtures

Whether to include fixture information

Type:

bool

code_context_lines

Number of context lines around failure points

Type:

int

max_code_lines

Maximum lines of code to include per failure

Type:

int

include_line_numbers

Whether to include line numbers in source code

Type:

bool

enhanced_context

Whether to use enhanced CodeContextExtractor

Type:

bool

include_traceback

Whether to include traceback information

Type:

bool

include_metadata

Whether to include metadata in reports

Type:

bool

timestamp_format

Format string for timestamps

Type:

str

__init__(output=None, format=None, append=False, include_passed=False, max_failures=None, include_source=True, include_fixtures=True, code_context_lines=5, max_code_lines=100, include_line_numbers=True, enhanced_context=True, include_traceback=True, include_metadata=True, timestamp_format='%Y-%m-%dT%H:%M:%S')

Initialize output configuration with validation.

Creates a new output configuration with automatic format detection from file extensions and comprehensive parameter validation.

Parameters:

• output (Union[str, Path, OutputFormat, None]) – Output destination - file path (str/Path) or format enum. If None, outputs to stdout with JSON format.

• format (Union[str, OutputFormat, None]) – Explicit format specification, overrides format detection from file extension. Can be OutputFormat enum or string.

• append (bool) – If True, append to existing file instead of overwriting

• include_passed (bool) – If True, include passed tests in the report

• max_failures (Optional[int]) – Maximum number of failures to include in report

• include_source (bool) – If True, include source code in failure reports

• include_fixtures (bool) – If True, include fixture information in reports

• code_context_lines (int) – Number of lines to include before/after failure points

• max_code_lines (int) – Maximum total lines of code per failure (performance limit)

• include_line_numbers (bool) – If True, add line numbers to source code display

• enhanced_context (bool) – If True, use enhanced CodeContextExtractor for better context

Raises:

• ValueError – If output format cannot be determined or is invalid

• TypeError – If parameters have incorrect types

Example

>>> # Output to JSON file
>>> config = OutputConfig("failures.json")
>>> print(config.format)
OutputFormat.JSON

>>> # Explicit format override
>>> config = OutputConfig("report.txt", format="markdown")
>>> print(config.format)
OutputFormat.MARKDOWN

>>> # Append mode with filtering
>>> config = OutputConfig(
...     "results.json",
...     append=True,
...     max_failures=50
... )
>>> print(config.append)
True

__str__()

Return string representation of OutputConfig.

Decorators and Functions

extract_on_failure

Primary decorator for automatic failure capture.

failextract.extract_on_failure(output=None, format=None, include_locals=False, include_fixtures=True, max_depth=10, skip_stdlib=True, extract_classes=True, append=False, custom_formatter=None, code_context_lines=5, enhanced_context=True, include_line_numbers=True, max_code_lines=100)

Enhanced decorator with flexible output options.

Parameters:

• output (Union[str, Path, OutputFormat, OutputConfig, None]) – Output configuration - can be: - str/Path: File path (format detected from extension) - OutputFormat: Format type (uses default filename) - OutputConfig: Full configuration object - None: Use global collection

• format (Union[str, OutputFormat, None]) – Override format detection (when output is a path)

• include_locals (bool) – Include local variables

• include_fixtures (bool) – Extract fixture definitions

• max_depth (int) – Maximum traceback depth

• skip_stdlib (bool) – Skip standard library modules

• extract_classes (bool) – Extract class definitions

• append (bool) – Append to existing file instead of overwriting

• custom_formatter (Optional[OutputFormatter]) – Custom formatter instance

• code_context_lines (int) – Number of context lines around failure points

• enhanced_context (bool) – Whether to use enhanced CodeContextExtractor

• include_line_numbers (bool) – Whether to include line numbers in source code

• max_code_lines (int) – Maximum lines of code per failure frame

Examples

@extract_on_failure(“failures.json”) @extract_on_failure(“report.md”) @extract_on_failure(output=”results.xml”, format=”xml”) @extract_on_failure(OutputFormat.YAML) @extract_on_failure(output=OutputConfig(“report.xml”, append=True))

generate_session_report

Utility function for session-level reporting.

failextract.generate_session_report(output='test_failures_report.md', format=None, clear=True)

Generate a report for all collected failures.

Enums and Types

OutputFormat

Enumeration of supported output formats.

class failextract.OutputFormat(value)

Bases: Enum

Supported output formats.

JSON = 'json'

MARKDOWN = 'md'

YAML = 'yaml'

XML = 'xml'

CSV = 'csv'

CUSTOM = 'custom'

Formatter Classes

Base Formatter

class failextract.OutputFormatter

Bases: ABC

Base class for output formatters.

This abstract base class defines the interface that all output formatters must implement. It provides the foundation for creating custom formatters that can render test failure data in various formats.

Subclasses must implement the format() and get_extension() methods to provide format-specific rendering and file extension handling.

abstractmethod format(failures)

Format failure data for output.

Parameters:

failures (List[Dict[str, Any]]) – List of failure dictionaries containing test failure information

Return type:

str

Returns:

Formatted string representation of the failure data

Raises:

NotImplementedError – If not implemented by subclass

abstractmethod get_extension()

Get default file extension for this format.

Return type:

str

Returns:

File extension string (e.g., ‘json’, ‘md’, ‘xml’)

Raises:

NotImplementedError – If not implemented by subclass

JSON Formatter

class failextract.JSONFormatter

Bases: OutputFormatter

JSON output formatter for test failure reports.

This formatter produces structured JSON output suitable for programmatic processing, integration with tools, and serving as input for other processing systems. The JSON format is always available in FailExtract and does not require any optional dependencies.

The output includes full test failure information with proper JSON serialization handling for Python-specific types like datetime objects.

Example

>>> formatter = JSONFormatter()
>>> failures = [{'test_name': 'test_example', 'timestamp': '2024-01-01'}]
>>> json_output = formatter.format(failures)
>>> print(json_output)
[
  {
    "test_name": "test_example",
    "timestamp": "2024-01-01"
  }
]

format(failures)

Format failure data as JSON.

Parameters:

failures (List[Dict[str, Any]]) – List of failure dictionaries containing test failure information

Return type:

str

Returns:

Pretty-formatted JSON string with 2-space indentation

Note

Uses json.dumps with default=str to handle non-serializable types like datetime objects by converting them to strings.

get_extension()

Get the file extension for JSON files.

Return type:

str

Returns:

File extension ‘.json’

Markdown Formatter

class failextract.MarkdownFormatter

Bases: OutputFormatter

Markdown output formatter for test failure reports.

This formatter produces well-structured Markdown output with proper headings, code blocks, and formatting. The output includes a table of contents for reports with multiple failures and uses GitHub-flavored Markdown syntax for optimal display.

Features: - Automatic table of contents for reports with 3+ failures - Syntax-highlighted code blocks for source code - Structured sections with clear headings and metadata - Anchor links for easy navigation - Compatible with GitHub, GitLab, and other Markdown renderers

Example

>>> formatter = MarkdownFormatter()
>>> failures = [{'test_name': 'test_example', 'exception_type': 'AssertionError'}]
>>> markdown_output = formatter.format(failures)
>>> print(markdown_output[:30])
# Test Failure Report

Generated

format(failures)

Format failure data as Markdown.

Parameters:

failures (List[Dict[str, Any]]) – List of failure dictionaries containing test failure information

Return type:

str

Returns:

Well-formatted Markdown string with headings, code blocks, and metadata

Note

Automatically generates a table of contents for reports with 3 or more failures. Uses GitHub-flavored Markdown syntax for code highlighting.

get_extension()

Get the file extension for Markdown files.

Return type:

str

Returns:

File extension ‘.md’

XML Formatter

class failextract.XMLFormatter

Bases: OutputFormatter

XML output formatter for test failure reports.

This formatter produces well-formed XML output with proper escaping and CDATA sections for source code. The XML structure includes metadata about the report generation and detailed information for each test failure.

The XML schema includes: - Report metadata (generation time, failure count) - Individual failure elements with full test information - Proper XML escaping for special characters - CDATA sections for source code to preserve formatting

Example

>>> formatter = XMLFormatter()
>>> failures = [{'test_name': 'test_example', 'exception_type': 'AssertionError'}]
>>> xml_output = formatter.format(failures)
>>> print(xml_output[:50])
<?xml version="1.0" encoding="UTF-8"?>
<testFailure

format(failures)

Format failure data as XML.

Parameters:

failures (List[Dict[str, Any]]) – List of failure dictionaries containing test failure information

Return type:

str

Returns:

Well-formed XML string with proper escaping and CDATA sections

Note

Uses XML escaping for text content and CDATA sections for source code to preserve formatting and special characters.

get_extension()

Get the file extension for XML files.

Return type:

str

Returns:

File extension ‘.xml’

CSV Formatter

class failextract.CSVFormatter

Bases: OutputFormatter

CSV output formatter for test failure reports.

This formatter produces comma-separated values output suitable for spreadsheet applications, data analysis tools, and tabular reporting. The CSV format includes essential test failure information in a structured tabular format.

The CSV includes these columns: - Test Name: Name of the failed test - Module: Python module containing the test - File: File path where the test is located - Timestamp: When the failure occurred - Exception Type: Type of exception raised - Exception Message: Error message from the exception - Line Number: Line number where failure occurred (if available)

Example

>>> formatter = CSVFormatter()
>>> failures = [{'test_name': 'test_example', 'test_module': 'test_mod'}]
>>> csv_output = formatter.format(failures)
>>> print(csv_output.split('\n')[0])
Test Name,Module,File,Timestamp,Exception Type,Exception Message,Line Number

format(failures)

Format failure data as CSV.

Parameters:

failures (List[Dict[str, Any]]) – List of failure dictionaries containing test failure information

Return type:

str

Returns:

CSV-formatted string with headers and failure data rows

Note

Uses Python’s csv module for proper escaping and formatting. Extracts line numbers from extracted_code if available.

get_extension()

Get the file extension for CSV files.

Return type:

str

Returns:

File extension ‘.csv’

YAML Formatter (Optional)

Available with pip install failextract[formatters]:

class failextract.YAMLFormatter

Bases: OutputFormatter

YAML output formatter for test failure reports.

This formatter produces human-readable YAML output with proper structure and formatting. YAML is often preferred over JSON for configuration files and human-readable data exchange due to its clean syntax and comment support.

The formatter requires PyYAML as an optional dependency and will raise a helpful error message if the dependency is not installed.

Features: - Clean, human-readable YAML structure - Metadata section with generation time and failure count - Structured failure data with proper YAML formatting - Helpful error message if PyYAML is not installed

Example

>>> formatter = YAMLFormatter()
>>> failures = [{'test_name': 'test_example', 'timestamp': '2024-01-01'}]
>>> yaml_output = formatter.format(failures)
>>> print(yaml_output[:50])
test_failure_report:
  metadata:
    generated: 2024-01-01

format(failures)

Format failure data as YAML.

Parameters:

failures (List[Dict[str, Any]]) – List of failure dictionaries containing test failure information

Return type:

str

Returns:

Human-readable YAML string with structured failure data

Raises:

ImportError – If PyYAML is not installed with helpful installation message

Note

Structures data with metadata section and organized failure information. Uses PyYAML’s default_flow_style=False for readable multi-line output.

get_extension()

Get the file extension for YAML files.

Return type:

str

Returns:

File extension ‘.yaml’

Configuration Classes

Configuration system is always available as part of core functionality:

class failextract.ConfigurationManager

Bases: object

Main configuration manager that handles loading and merging configurations.

__init__()

Initialize configuration manager with default configuration.

load_from_file(file_path)

Load configuration from a file.

Parameters:

file_path (Union[str, Path]) – Path to configuration file

Raises:

ConfigurationError – If file cannot be parsed

Return type:

None

load_from_pyproject_toml(file_path)

Load configuration from pyproject.toml file.

Parameters:

file_path (Union[str, Path]) – Path to pyproject.toml file

Return type:

None

load_from_environment()

Load configuration from environment variables.

Environment variables should be prefixed with FAILEXTRACT_ and use underscore notation for nested sections: FAILEXTRACT_OUTPUT_DEFAULT_FORMAT

Return type:

None

load_from_workspace(start_path)

Load configuration from workspace.

Parameters:

start_path (Union[str, Path]) – Path to start workspace detection from

Return type:

None

merge_configuration(config_data)

Merge configuration data into current configuration.

Parameters:

config_data (Dict[str, Any]) – Configuration data to merge

Return type:

None

get_effective_config()

Get the effective configuration after all merging.

Return type:

ProjectConfig

Returns:

Current effective configuration

create_output_config(filename=None, **kwargs)

Create OutputConfig with project defaults.

Parameters:

• filename (Optional[str]) – Output filename

• **kwargs – Additional OutputConfig parameters

Return type:

OutputConfig

Returns:

OutputConfig instance

get_extraction_config()

Get extraction configuration.

Return type:

ExtractionSection

Returns:

Extraction configuration section

property config_sources: List[str]

Get list of configuration sources that were loaded.

class failextract.ProjectConfig(config_data=None)

Bases: object

Main project configuration class containing all sections.

__init__(config_data=None)

Initialize project configuration.

Parameters:

config_data (Optional[Dict[str, Any]]) – Dictionary containing configuration data

Raises:

ConfigurationError – If configuration is invalid

merge(other_config)

Merge another configuration into this one.

Parameters:

other_config (Dict[str, Any]) – Configuration data to merge in

Return type:

None

to_dict()

Convert configuration to dictionary.

Return type:

Dict[str, Any]

get_output_config(filename=None, **kwargs)

Create an OutputConfig instance with project defaults.

Parameters:

• filename (Optional[str]) – Output filename (overrides project default)

• **kwargs – Additional OutputConfig parameters

Return type:

OutputConfig

Returns:

OutputConfig instance with project defaults applied

class failextract.WorkspaceDetector(max_depth=10, custom_markers=None, custom_patterns=None)

Bases: object

Detects workspace root directories using various strategies.

__init__(max_depth=10, custom_markers=None, custom_patterns=None)

Initialize workspace detector.

Parameters:

• max_depth (int) – Maximum depth to search upward

• custom_markers (Optional[List[str]]) – Custom marker files to look for

• custom_patterns (Optional[List[str]]) – Custom patterns to match

detect_workspace(start_path)

Detect workspace root starting from given path.

Parameters:

start_path (Union[str, Path]) – Path to start detection from

Return type:

Optional[Path]

Returns:

Path to workspace root, or None if not found

CLI Module

Command-line interface is always available as part of core functionality:

Command-line interface for FailExtract.

This module provides a CLI for the FailExtract library, allowing users to: - Generate reports from existing failure data - Configure output formats and destinations - Validate and analyze test failure patterns - Export failure data in various formats - Check available features and installation status

The CLI is designed to work with both interactive usage and automation/CI/CD pipelines, providing structured output and exit codes for scripting.

The CLI automatically adapts based on installed optional features: - Core features (JSON output, basic commands) are always available - Advanced features require extras (e.g., pip install failextract[formatters]) - Helpful error messages guide users to install missing features

Example

Generate a JSON report (always available):

$ failextract report –format json –output failures.json

Generate a markdown report:

$ failextract report –format markdown –output failures.md

Check which features are available:

$ failextract features

Advanced failure analysis (requires analytics extra):

$ failextract analyze –trends

Author: FailExtract Contributors License: Apache 2.0

failextract.cli.create_parser()

Create and configure the argument parser.

Returns:

Configured parser with all commands and options.

Return type:

argparse.ArgumentParser

failextract.cli.format_table_output(data, headers)

Format data as a simple ASCII table for terminal output.

Creates a formatted table with aligned columns suitable for display in terminals. Automatically calculates column widths based on content and provides clean separation between columns.

Parameters:

• data (List[Dict[str, Any]]) – List of dictionaries containing row data where keys match headers

• headers (List[str]) – List of column headers to display

Return type:

str

Returns:

Formatted ASCII table string with headers and aligned data rows

Example

>>> data = [{'name': 'test1', 'status': 'passed'}, {'name': 'test2', 'status': 'failed'}]
>>> headers = ['name', 'status']
>>> table = format_table_output(data, headers)
>>> print(table)
name   status
-----  ------
test1  passed
test2  failed

failextract.cli.cmd_features(args)

Execute the features command to show available and missing features.

Displays information about which FailExtract features are currently available based on installed optional dependencies, and provides installation instructions for missing features.

Parameters:

args (Namespace) – Parsed command line arguments (currently unused for this command)

Returns:

0 for success, 1 for error

Return type:

Exit code

Example Output:

Available Features: - json (always available) - xml (always available) - csv (always available) - markdown (always available)

Missing Features: - yaml (install with: pip install failextract[formatters]) - config (install with: pip install failextract[config])

failextract.cli.cmd_report(args)

Execute the report command.

Parameters:

args (Namespace) – Parsed command line arguments.

Returns:

Exit code (0 for success, 1 for error).

Return type:

int

failextract.cli.cmd_list(args)

Execute the list command.

Parameters:

args (Namespace) – Parsed command line arguments.

Returns:

Exit code (0 for success, 1 for error).

Return type:

int

failextract.cli.cmd_clear(args)

Execute the clear command.

Parameters:

args (Namespace) – Parsed command line arguments.

Returns:

Exit code (0 for success, 1 for error).

Return type:

int

failextract.cli.cmd_stats(args)

Execute the stats command.

Parameters:

args (Namespace) – Parsed command line arguments.

Returns:

Exit code (0 for success, 1 for error).

Return type:

int

failextract.cli.cmd_analyze(args)

Execute the analyze command.

Parameters:

args (Namespace) – Parsed command line arguments.

Returns:

Exit code (0 for success, 1 for error).

Return type:

int

failextract.cli.main()

Main CLI entry point.

Returns:

Exit code (0 for success, non-zero for error).

Return type:

int

Exception Classes

Base Exceptions

exception failextract.ConfigurationError

Bases: Exception

Raised when configuration is invalid or cannot be loaded.

Constants and Settings

Version Information

failextract.__version__ = '1.0.0'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

Built-in Fixtures

failextract.BUILTIN_FIXTURES = {'cache': 'Store and retrieve values across test runs', 'capfd': 'Capture file descriptors stdout/stderr', 'capfdbinary': 'Capture binary file descriptors', 'caplog': 'Capture log messages', 'capsys': 'Capture system stdout/stderr', 'capsysbinary': 'Capture binary system output', 'doctest_namespace': 'Namespace for doctest execution', 'monkeypatch': 'Modify objects, dict items, os.environ, etc.', 'pytestconfig': 'Access to configuration values and plugin manager', 'pytester': 'Plugin testing helper', 'recwarn': 'Record warnings', 'request': 'Pytest request object containing test context', 'tmp_path': 'Temporary directory unique to test invocation', 'tmp_path_factory': 'Factory for creating temporary directories', 'tmpdir': 'Temporary directory (legacy, use tmp_path)'}

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:

d = {} for k, v in iterable:

d[k] = v

dict(**kwargs) -> new dictionary initialized with the name=value pairs

in the keyword argument list. For example: dict(one=1, two=2)

Feature Detection

Runtime Feature Detection

Check what features are available in the current installation:

from failextract import get_available_features

features = get_available_features()
print(f"Available features: {features['available']}")
print(f"Missing features: {features['missing']}")
print(f"Core features: {features['core']}")

Installation Suggestions

Get installation commands for missing features:

from failextract import suggest_installation

# Suggest installation for YAML support
suggestion = suggest_installation("yaml")
print(suggestion)  # "pip install failextract[formatters]"

Utilities and Helpers

Context Analysis

class failextract.CodeContextExtractor

Bases: object

Extract and manage code context for test failures.

This class provides intelligent code context extraction with configurable depth and context lines. It implements caching for performance and thread-safe operation consistent with FailExtract’s singleton patterns.

Features: - Configurable context lines before/after failure points - Intelligent source code caching with memory management - Thread-safe operation for concurrent test execution - Enhanced error handling for edge cases - Integration with existing source extraction functions

_source_cache

Cache for source files with modification time

Type:

Dict[str, tuple]

_lock

Thread safety lock for cache operations

Type:

threading.RLock

_max_cache_size

Maximum number of cached source files

Type:

int

static __new__(cls)

Implement thread-safe singleton pattern.

__init__()

Initialize the CodeContextExtractor with cache and configuration.

extract_function_source_with_context(frame, context_lines=5, include_line_numbers=True, max_lines=None)

Extract function source with configurable context lines.

Enhanced version of extract_function_source that provides context lines around the failure point and additional metadata for better presentation.

Parameters:

• frame – Frame object containing the execution context

• context_lines (int) – Number of lines to include before/after the failure line

• include_line_numbers (bool) – Whether to include line number information

• max_lines (Optional[int]) – Maximum number of lines to return (None for no limit)

Returns:

• ‘source’: Source code with context (string)

• ’lines’: Source code lines (list of strings)

• ’failure_line’: Line number where failure occurred

• ’start_line’: Starting line number of the extracted context

• ’end_line’: Ending line number of the extracted context

• ’filename’: Path to the source file

• ’function_name’: Name of the function containing the failure

• ’context_type’: Type of context (‘function’, ‘class’, ‘module’)

• ’include_line_numbers’: Whether line numbers were included

• ’error’: Error message if extraction failed

Return type:

Dictionary containing

Example

>>> extractor = CodeContextExtractor()
>>> context = extractor.extract_function_source_with_context(frame, context_lines=3)
>>> print(context['source'])
def test_example():
    x = 1
    y = 2
    assert x == y  # <- Failure line
    return True

clear_cache()

Clear all caches including source, imports, dependencies, AST, execution trace, and coverage.

get_cache_stats()

Get cache statistics for debugging and monitoring.

Return type:

Dict[str, Any]

analyze_imports(filename)

Analyze imports in a Python file using static analysis.

Extracts and categorizes all import statements from a Python file, providing detailed information about each import including line numbers, module names, aliases, and import types.

Parameters:

filename (str) – Path to the Python file to analyze

Returns:

• ‘type’: Import type (‘import’, ‘from_import’)

• ’module’: Module name being imported

• ’names’: List of imported names (for from imports)

• ’alias’: Alias used (as clause)

• ’line’: Line number of the import statement

• ’level’: Relative import level (0 for absolute)

Return type:

List of dictionaries containing import information with keys

Example

>>> extractor = CodeContextExtractor()
>>> imports = extractor.analyze_imports("test_file.py")
>>> print(imports[0])
{'type': 'import', 'module': 'os', 'names': [], 'alias': None, 'line': 1, 'level': 0}

analyze_dependencies(filename, max_depth=3)

Analyze file dependencies and create dependency graph.

Performs recursive dependency analysis starting from a file to build a comprehensive dependency graph including direct imports, transitive dependencies, and circular dependency detection.

Parameters:

• filename (str) – Path to the Python file to analyze

• max_depth (int) – Maximum recursion depth for dependency analysis

Returns:

• ‘direct_imports’: List of directly imported modules

• ’dependency_graph’: Nested dict of dependencies by depth level

• ’circular_dependencies’: List of detected circular dependencies

• ’unresolved_modules’: List of modules that couldn’t be resolved

• ’total_dependencies’: Count of all unique dependencies

Return type:

Dictionary containing dependency analysis with keys

Example

>>> extractor = CodeContextExtractor()
>>> deps = extractor.analyze_dependencies("test_file.py")
>>> print(deps['total_dependencies'])
15

get_function_dependencies(frame)

Get dependencies specific to a function’s execution context.

Analyzes the imports and dependencies relevant to a specific function’s execution, providing contextual dependency information for failure analysis.

Parameters:

frame – Frame object containing the execution context

Return type:

Dict[str, Any]

Returns:

Dictionary containing function-specific dependency information

start_execution_trace(file_filters=None, max_trace_entries=1000, mode='static', sample_rate=1)

Start optimized execution tracing for dependency analysis.

Enables execution tracing to track function calls and imports during test execution. This provides runtime dependency information to complement static analysis.

Parameters:

• file_filters (Optional[List[str]]) – List of file paths/patterns to trace (None for all files)

• max_trace_entries (int) – Maximum number of trace entries to keep

• mode (str) – ‘static’ (no runtime, 0% overhead), ‘profile’ (functions), ‘trace’ (lines)

• sample_rate (int) – Sample every Nth call (1=no sampling, 10=sample 10%)

Return type:

None

Note

Defaults to ‘static’ mode for 0% overhead. Use ‘profile’ for <10% overhead with runtime dependency tracking.

stop_execution_trace()

Stop execution tracing and return collected trace data.

Return type:

List[Dict[str, Any]]

Returns:

List of trace entries with execution information

get_execution_summary()

Get summary of execution trace data.

Return type:

Dict[str, Any]

Returns:

Dictionary containing execution trace analysis

integrate_trace_with_dependencies(frame)

Integrate execution trace data with static dependency analysis.

Combines static analysis results with runtime execution information to provide comprehensive dependency context for failure analysis.

Parameters:

frame – Frame object containing the execution context

Return type:

Dict[str, Any]

Returns:

Dictionary containing integrated dependency and execution information

build_dependency_graph(root_file, max_depth=3)

Build a comprehensive dependency graph starting from a root file.

Creates a structured dependency graph that can be used for visualization, analysis, and understanding test code relationships.

Parameters:

• root_file (str) – Starting file for dependency analysis

• max_depth (int) – Maximum depth for dependency traversal

Return type:

DependencyGraph

Returns:

DependencyGraph object containing the complete graph structure

integrate_coverage_data(coverage_data_file=None)

Integrate with coverage.py data when available.

Loads and processes coverage data to provide insights into which code paths were executed during test runs. This complements static analysis with runtime execution information.

Parameters:

coverage_data_file (Optional[str]) – Path to coverage data file (None for auto-detect)

Return type:

Dict[str, Any]

Returns:

Dictionary containing coverage integration results

get_coverage_for_file(filename)

Get coverage information for a specific file.

Parameters:

filename (str) – Path to the file to get coverage for

Return type:

Optional[Dict[str, Any]]

Returns:

Coverage information dictionary or None if not available

get_executed_lines_for_function(frame)

Get coverage information for the specific function context.

Analyzes coverage data to determine which lines were executed in the context of the failing function.

Parameters:

frame – Frame object containing the execution context

Return type:

Dict[str, Any]

Returns:

Dictionary containing function-specific coverage information

combine_coverage_with_dependencies(frame)

Combine coverage data with dependency analysis.

Provides comprehensive analysis combining static dependencies, execution traces, and coverage data for complete context.

Parameters:

frame – Frame object containing the execution context

Return type:

Dict[str, Any]

Returns:

Dictionary containing combined analysis results

Registry Management

failextract.get_available_features()

Get information about available features based on installed extras.

Return type:

dict

Returns:

Dictionary with feature availability information.

failextract.suggest_installation(feature_name)

Suggest installation command for a missing feature.

Parameters:

feature_name (str) – Name of the feature to install

Return type:

str

Returns:

Installation command suggestion

Examples

Basic Usage Example:

from failextract import extract_on_failure, FailureExtractor, OutputConfig

@extract_on_failure
def test_example():
    assert 1 == 2, "This will fail and be captured"

# Run test (it will fail and be captured)
try:
    test_example()
except AssertionError:
    pass

# Generate report
extractor = FailureExtractor()
config = OutputConfig("failures.json", format="json")
extractor.save_report(config)

Advanced Configuration Example:

from failextract import extract_on_failure

@extract_on_failure(
    include_locals=True,        # Capture local variables
    include_fixtures=True,      # Capture pytest fixtures
    max_depth=15,              # Variable inspection depth
    skip_stdlib=False,         # Include all stack frames
    enhanced_context=True,     # Enhanced context analysis
    code_context_lines=10      # Lines of code context
)
def test_detailed():
    user_data = {"id": 123, "name": "Alice"}
    config = {"timeout": 30, "retries": 3}
    assert False, "Detailed context will be captured"

Memory Management Example:

from failextract import FailureExtractor

extractor = FailureExtractor()

# Set memory limits
extractor.set_memory_limits(max_failures=500, max_passed=100)

# Check usage
stats = extractor.get_stats()
print(f"Usage: {stats['failures_count']} failures, {stats['passed_count']} passed")

CLI Usage Examples:

# Generate different format reports
failextract report --format json --output failures.json
failextract report --format markdown --output failures.md
failextract report --format csv --output failures.csv
failextract report --format yaml --output failures.yaml
failextract report --format xml --output failures.xml

# List captured failures
failextract list --format table
failextract list --format json

# Show statistics and analysis
failextract stats --format table
failextract stats --format json

# Check available features
failextract features --format table

# Clear all data
failextract clear --confirm

# Advanced analysis (if analytics extra installed)
# failextract analyze --trends --days 30

Error Handling

Import Error Handling:

try:
    from failextract import extract_on_failure
except ImportError as e:
    print(f"FailExtract not available: {e}")
    print("Install with: pip install failextract")

Feature Availability Checking:

from failextract import OutputConfig, FailureExtractor

def safe_yaml_report():
    """Generate YAML report if possible, JSON otherwise."""
    extractor = FailureExtractor()

    try:
        config = OutputConfig("report.yaml", format="yaml")
        extractor.save_report(config)
        print("Generated YAML report")
    except ImportError:
        print("YAML not available, generating JSON instead")
        config = OutputConfig("report.json", format="json")
        extractor.save_report(config)

Configuration Error Handling:

from failextract import OutputConfig, ConfigurationError

try:
    config = OutputConfig("invalid.txt", format="unsupported_format")
except ValueError as e:  # OutputConfig raises ValueError for invalid parameters
    print(f"Configuration error: {e}")
    # Fall back to default
    config = OutputConfig("backup.json")

Migration Notes

From Version 1.x to 2.x:

• FailureExtractor is now a singleton

• OutputConfig constructor has simplified parameters

• YAML formatter moved to optional [formatters] extra

• CLI moved to optional [cli] extra

Backward Compatibility:

• All core APIs remain compatible

• Optional features gracefully degrade if not installed

• Configuration format remains unchanged

See Also

• Tutorials - Step-by-step learning guides

• How-To Guides - Task-focused solutions

• Discussions - In-depth design discussions