tessl/pypi-pipdeptree

Command line utility to show dependency tree of packages.

—

Pending

Overview

Eval results

Files

Warning System

Name: tessl/pypi-pipdeptree
Author: tessl

Configurable warning and error reporting system with different verbosity levels and output control for handling dependency conflicts, validation issues, and other diagnostic information.

Capabilities

Warning Types

Enumeration defining different warning behavior levels.

WarningType = Enum("WarningType", ["SILENCE", "SUPPRESS", "FAIL"])

The three warning levels control output and exit behavior:

SILENCE: No warning output, always return exit code 0
SUPPRESS: Print warnings to stderr, but return exit code 0
FAIL: Print warnings to stderr and return exit code 1 if any warnings occurred

WarningPrinter Class

Main class for managing warning output and tracking warning state.

class WarningPrinter:
    """Non-thread safe class that handles printing warning logic."""
    
    def __init__(self, warning_type: WarningType = WarningType.SUPPRESS) -> None:
        """
        Initialize warning printer with specified behavior.
        
        Parameters:
        - warning_type: Controls warning output and exit code behavior
        """
    
    @property
    def warning_type(self) -> WarningType:
        """Current warning type setting."""
    
    @warning_type.setter
    def warning_type(self, new_warning_type: WarningType) -> None:
        """Update warning type setting."""
    
    def should_warn(self) -> bool:
        """
        Check if warnings should be printed.
        
        Returns:
        False for SILENCE, True for SUPPRESS and FAIL
        """
    
    def has_warned_with_failure(self) -> bool:
        """
        Check if warnings were printed with failure setting.
        
        Returns:
        True if warnings occurred and warning_type is FAIL
        """
    
    def print_single_line(self, line: str) -> None:
        """
        Print a single warning line to stderr.
        
        Marks that a warning has occurred for exit code determination.
        
        Parameters:
        - line: Warning message to print
        """
    
    def print_multi_line(
        self, 
        summary: str, 
        print_func: Callable[[], None], 
        ignore_fail: bool = False
    ) -> None:
        """
        Print a multi-line warning with custom formatting.
        
        Parameters:
        - summary: Warning summary/title
        - print_func: Callback that prints the detailed warning content
        - ignore_fail: If True, don't mark as failure warning
        """

Global Warning Printer

Function to access the global warning printer instance.

def get_warning_printer() -> WarningPrinter:
    """
    Get the global warning printer instance.
    
    Returns:
    Shared WarningPrinter instance used throughout pipdeptree
    """

Usage Examples

Basic Warning Configuration

from pipdeptree._warning import get_warning_printer, WarningType

# Get global warning printer
warning_printer = get_warning_printer()

# Configure warning behavior
warning_printer.warning_type = WarningType.FAIL

# Check configuration
if warning_printer.should_warn():
    print("Warnings will be printed")

if warning_printer.warning_type == WarningType.FAIL:
    print("Warnings will cause exit code 1")

Single Line Warnings

from pipdeptree._warning import get_warning_printer

warning_printer = get_warning_printer()

# Print simple warning
warning_printer.print_single_line("Package version conflict detected")

# Check if this was a failure warning
if warning_printer.has_warned_with_failure():
    print("This warning should cause non-zero exit code")

Multi-Line Warning Output

from pipdeptree._warning import get_warning_printer

def print_detailed_conflicts():
    """Function that prints detailed conflict information."""
    print("* package-a==1.0")
    print("  - dependency-x [required: >=2.0, installed: 1.5]")
    print("* package-b==2.0") 
    print("  - dependency-y [required: <1.0, installed: 1.2]")

warning_printer = get_warning_printer()

# Print multi-line warning with custom content
warning_printer.print_multi_line(
    summary="Conflicting dependencies found",
    print_func=print_detailed_conflicts
)

# Output:
# Warning!!! Conflicting dependencies found:
# * package-a==1.0
#   - dependency-x [required: >=2.0, installed: 1.5]
# * package-b==2.0
#   - dependency-y [required: <1.0, installed: 1.2]
# ------------------------------------------------------------------------

Integration with CLI

from pipdeptree._cli import get_options
from pipdeptree._warning import get_warning_printer, WarningType

# Parse CLI warning option
options = get_options(['--warn', 'fail'])

# Configure warning printer based on CLI option
warning_printer = get_warning_printer()
warning_printer.warning_type = options.warn

# Use throughout application
if warning_printer.should_warn():
    warning_printer.print_single_line("Validation issue detected")

# Determine exit code
exit_code = 1 if warning_printer.has_warned_with_failure() else 0

Integration with Validation

from pipdeptree._validate import validate, conflicting_deps
from pipdeptree._warning import get_warning_printer

# Configure warnings
warning_printer = get_warning_printer()
warning_printer.warning_type = WarningType.SUPPRESS

# Validation uses warning printer internally
validate(dependency_tree)  # Prints warnings if conflicts found

# Check if validation found issues
if warning_printer.has_warned_with_failure():
    print("Validation failed")

# Manual conflict checking with warning integration
conflicts = conflicting_deps(dependency_tree)
if conflicts and warning_printer.should_warn():
    warning_printer.print_multi_line(
        "Dependency conflicts detected",
        lambda: render_conflicts_text(conflicts)
    )

Warning Output Format

Single Line Format

Simple warning messages printed directly to stderr:

Package pattern 'nonexistent*' not found in dependency tree

Multi-Line Format

Structured warnings with header, content, and footer:

Warning!!! Conflicting dependencies found:
* Django==3.0.0
 - requests [required: >=2.25.0, installed: 2.20.0]
* mypackage==1.0.0
 - urllib3 [required: >=1.26, installed: 1.25.11]
------------------------------------------------------------------------

Informational Messages

Some multi-line warnings can be marked as informational:

Warning!!! Invalid requirement strings found:
mypackage
  Skipping "invalid>=requirement string"
NOTE: This warning isn't a failure warning.
------------------------------------------------------------------------

Integration Points

CLI Warning Control

The warning system integrates with CLI argument parsing:

# Suppress warnings but show them
pipdeptree --warn suppress

# Silence all warnings
pipdeptree --warn silence  

# Treat warnings as failures
pipdeptree --warn fail

Validation Integration

Validation functions automatically use the warning system:

Conflict detection: Prints conflicts when should_warn() returns True
Cycle detection: Prints circular dependencies when enabled
Invalid requirements: Reports malformed requirement strings

Text Output Integration

The warning system only activates for text output modes:

# Warnings disabled for structured output formats
is_text_output = not any([options.json, options.json_tree, options.output_format])
if not is_text_output:
    options.warn = WarningType.SILENCE

Exit Code Determination

The warning system controls application exit codes:

def _determine_return_code(warning_printer: WarningPrinter) -> int:
    """Determine exit code based on warning state."""
    return 1 if warning_printer.has_warned_with_failure() else 0