pydvlp-debug 0.1.0

Professional Python development utilities with advanced debugging, profiling, tracing, benchmarking, and code analysis tools

🐛 PyDvlp Debug

Professional Python Development Utilities

---

A comprehensive Python development utilities library with advanced debugging, profiling, tracing, benchmarking, and code analysis tools. Zero required dependencies, minimal overhead, production-ready.

📖 Documentation • 🚀 Quick Start • 💡 Examples • 🤝 Contributing

---

✨ Features

🐛 Enhanced Debugging Ice-cream style debugging with debug.ice() Automatic variable name detection Rich console output with syntax highlighting Context-aware debugging with correlation IDs 📊 Performance Profiling Time and memory profiling with decorators Production-safe sampling and thresholds Statistical analysis with percentiles Context-based profiling for granular insights 🔍 Execution Tracing Function call flow tracking Call graph generation and visualization Distributed tracing with correlation IDs Configurable sampling rates

⚡ Benchmarking Suite Microbenchmark utilities with statistics Comparative performance analysis Memory usage benchmarking Automated regression detection 📝 Structured Logging Rich console, JSON, and plain text formats Context-aware logging with metadata Multiple log levels with color coding Integration with popular logging frameworks 🔬 Code Analysis Type coverage analysis and scoring Complexity metrics (cyclomatic, cognitive, Halstead) Static analysis orchestration (mypy, pyflakes) Automated code quality recommendations

🎯 Core Principles

• 🚀 Zero Dependencies - Core functionality works without any optional packages
• ⚡ Minimal Overhead - <1% performance impact when enabled, zero when disabled
• 🔧 Production Ready - Automatic environment detection and optimization
• 🎛️ Highly Configurable - Environment variables and programmatic configuration
• 🧩 Modular Design - Use only what you need, when you need it
• 🔒 Type Safe - Full type annotations and mypy validation

---

🚀 Quick Start

Installation

PDM (Recommended)	Poetry	pip
pdm add pydvlp-debug	poetry add pydvlp-debug	pip install pydvlp-debug

📦 Installation Options

# 🎯 Basic installation (fallback implementations)
pip install pydvlp-debug

# 🚀 Full installation (all features)
pip install "pydvlp-debug[all]"

# 🎛️ Specific features
pip install "pydvlp-debug[analysis]"   # Code analysis tools  
pip install "pydvlp-debug[profiling]"  # Advanced profiling
pip install "pydvlp-debug[rich]"       # Rich console output
pip install "pydvlp-debug[tracing]"    # Execution tracing

Basic Usage

from pydvlp.debug import debugkit

# 🐛 Enhanced debugging
user_data = {"id": 123, "name": "Alice", "role": "admin"}
debugkit.ice("User loaded", user_data)
# 🔍 User loaded | user_data={'id': 123, 'name': 'Alice', 'role': 'admin'}

# 📊 Context management with automatic timing
with debugkit.context("user_processing", user_id=123) as ctx:
    ctx.debug("Starting user validation")
    validate_user(user_data)
    ctx.checkpoint("validation_complete")
    
    ctx.debug("Processing user data") 
    result = process_user(user_data)
    ctx.success("User processing complete", result_count=len(result))

# ⚡ Function instrumentation
@debugkit.instrument(profile=True, analyze=True)
def calculate_metrics(data: list[dict]) -> dict:
    """Calculate user metrics with automatic profiling and analysis."""
    return {
        "total_users": len(data),
        "active_users": len([u for u in data if u.get("active", False)]),
        "avg_score": sum(u.get("score", 0) for u in data) / len(data)
    }

# The function now automatically logs performance and code quality metrics
metrics = calculate_metrics([user_data])

🔧 Configuration

# Environment variables
export PYDVLP_ENVIRONMENT=production     # development | testing | production
export PYDVLP_DEBUG_ENABLED=true         # Enable debug output  
export PYDVLP_PROFILE_ENABLED=false      # Enable profiling
export PYDVLP_LOG_LEVEL=INFO             # DEBUG | INFO | WARNING | ERROR
export PYDVLP_LOG_FORMAT=rich            # rich | json | plain

# Programmatic configuration
debugkit.configure(
    debug_enabled=True,
    profile_enabled=True, 
    log_level="DEBUG",
    trace_sampling_rate=0.1
)

---

📊 Performance Showcase

Operation	Without PyDvlp	With PyDvlp	Overhead
Function call	125 ns	127 ns	1.6%
Context manager	245 ns	251 ns	2.4%
Debug disabled	125 ns	125 ns	0.0%
Production mode	125 ns	125 ns	0.0%

Benchmarks run on Python 3.11, Intel i7-12700K

---

🎯 Use Cases

🧑‍💻 Development # Quick debugging debug.ice(complex_data) # Performance analysis @profile.profile_performance def slow_function(): pass # Code quality report = debugkit.analyze_code(my_function)

🧪 Testing # Test instrumentation @debugkit.instrument( profile=True, trace=True ) def test_performance(): assert benchmark_function() < 1.0

🏭 Production # Error-only logging @debugkit.instrument( log=True, profile=False ) def api_endpoint(request): return process_request(request)

---

📚 Documentation

📖 Guide	🎯 Description	🔗 Link
🚀 Getting Started	Installation, configuration, first steps	📖 Read
🔧 Configuration	Environment variables, settings, presets	⚙️ Configure
🏆 Best Practices	Patterns, performance, production tips	💡 Learn
🔌 API Reference	Complete API documentation	📚 Reference
💡 Examples	Working code examples	🎮 Examples

---

💻 Advanced Examples

🎯 Real-world Web API Debugging

from pydvlp.debug import debugkit
from flask import Flask, request

app = Flask(__name__)

@app.route('/api/users/<int:user_id>')
@debugkit.instrument(profile=True, analyze=True, trace=True)
def get_user(user_id: int):
    """Get user with comprehensive instrumentation."""
    
    with debugkit.context("user_lookup", user_id=user_id) as ctx:
        # Database query with debug info
        ctx.debug("Querying database", table="users", id=user_id)
        user = db.query_user(user_id)
        
        if not user:
            ctx.error("User not found", user_id=user_id)
            return {"error": "User not found"}, 404
        
        ctx.checkpoint("user_found")
        
        # Permission check
        ctx.debug("Checking permissions")
        if not has_permission(request.user, user):
            ctx.error("Permission denied", 
                     requester=request.user.id, 
                     target_user=user_id)
            return {"error": "Permission denied"}, 403
        
        ctx.checkpoint("permissions_ok")
        
        # Format response
        response = format_user_response(user)
        ctx.success("User lookup complete", 
                   user_id=user_id, 
                   response_size=len(str(response)))
        
        return response

📊 Data Processing Pipeline

from pydvlp.debug import debugkit, benchmark

class DataPipeline:
    """High-performance data processing pipeline."""
    
    def __init__(self):
        self.metrics = {}
    
    @debugkit.instrument(profile=True, analyze=True)
    def process_batch(self, data: list[dict]) -> dict:
        """Process data batch with full instrumentation."""
        
        with debugkit.context("batch_processing", size=len(data)) as ctx:
            # Validation stage
            with benchmark.timer("validation"):
                ctx.debug("Validating data")
                valid_data = self.validate_data(data)
                ctx.checkpoint("validation_complete", 
                             valid_count=len(valid_data))
            
            # Transformation stage  
            with benchmark.timer("transformation"):
                ctx.debug("Transforming data")
                transformed = self.transform_data(valid_data)
                ctx.checkpoint("transformation_complete")
            
            # Aggregation stage
            with benchmark.timer("aggregation"):
                ctx.debug("Aggregating results")
                results = self.aggregate_results(transformed)
                ctx.success("Processing complete", 
                           results_count=len(results))
            
            # Performance summary
            timings = benchmark.get_timings()
            ctx.record("stage_timings", timings)
            
            return results
    
    @benchmark.measure(iterations=1000)
    def validate_data(self, data: list[dict]) -> list[dict]:
        """Validate input data - benchmarked for optimization."""
        return [item for item in data if self.is_valid(item)]

🔍 Code Quality Monitoring

#!/usr/bin/env python3
"""Automated code quality monitoring for CI/CD."""

from pydvlp.debug import debugkit
from pathlib import Path
import sys

def quality_gate():
    """Enforce code quality standards."""
    
    # Quality thresholds
    MIN_SCORE = 75
    MAX_COMPLEXITY = 15
    MIN_TYPE_COVERAGE = 0.8
    
    failed_functions = []
    
    # Analyze all Python files
    for py_file in Path("src").rglob("*.py"):
        functions = extract_functions_from_file(py_file)
        
        for func in functions:
            with debugkit.context("quality_check", function=func.__name__) as ctx:
                # Comprehensive analysis
                report = debugkit.analyze_code(func)
                
                ctx.debug("Analysis complete",
                         score=report.combined_score,
                         complexity=report.complexity_analysis.cyclomatic_complexity,
                         type_coverage=report.type_analysis.type_coverage)
                
                # Check quality gates
                issues = []
                
                if report.combined_score < MIN_SCORE:
                    issues.append(f"Low quality score: {report.combined_score}")
                
                if report.complexity_analysis.cyclomatic_complexity > MAX_COMPLEXITY:
                    issues.append(f"High complexity: {report.complexity_analysis.cyclomatic_complexity}")
                
                if report.type_analysis.type_coverage < MIN_TYPE_COVERAGE:
                    issues.append(f"Low type coverage: {report.type_analysis.type_coverage:.1%}")
                
                if issues:
                    ctx.error("Quality gate failed",
                             function=func.__name__, 
                             issues=issues)
                    failed_functions.append((func.__name__, issues))
                else:
                    ctx.success("Quality gate passed")
    
    # Summary
    if failed_functions:
        debugkit.error("Code quality check failed",
                      failed_count=len(failed_functions),
                      total_functions=len(all_functions))
        
        for func_name, issues in failed_functions:
            print(f"❌ {func_name}:")
            for issue in issues:
                print(f"   - {issue}")
        
        return 1
    else:
        debugkit.success("All functions pass quality gates")
        return 0

if __name__ == "__main__":
    sys.exit(quality_gate())

---

🛠️ Development

🔧 Development Setup

# Clone repository
git clone https://github.com/pr1m8/pydvlp-debug.git
cd pydvlp-debug

# Install PDM (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -
# Or use pipx: pipx install pdm

# Install dependencies
pdm install

# Install pre-commit hooks
pdm run pre-commit install

# Run tests
pdm run pytest

# Run with coverage
pdm run pytest --cov=pydvlp --cov-report=html

# Type checking
pdm run mypy src/

# Code formatting
pdm run black src/ tests/
pdm run isort src/ tests/

# Linting
pdm run ruff check src/ tests/

🧪 Testing

# Run all tests
pdm run pytest

# Run with coverage
pdm run pytest --cov=pydvlp.debug --cov-report=html --cov-report=term

# Run specific test categories
pdm run pytest -m "not slow"           # Skip slow tests
pdm run pytest -m "integration"        # Integration tests only
pdm run pytest tests/test_profiling.py # Specific module

# Performance tests
pdm run pytest --benchmark-only

# Generate test report
pdm run pytest --html=reports/pytest_report.html --self-contained-html

Test Coverage: 95%+ | Test Count: 126 | Performance Tests: 15

---

🏆 Project Quality

📊 Metric	📈 Status	🎯 Target
Test Coverage		>90%
Type Coverage		100%
Code Quality		A Grade
Performance		<2%
Documentation		100%

---

🤝 Contributing

We welcome contributions! 🎉

🐛 Bug Reports Found a bug? Open an issue with: Clear description Reproduction steps Expected vs actual behavior Environment details

✨ Feature Requests Have an idea? Request a feature with: Use case description Proposed API design Implementation considerations Alternative solutions

📋 Contribution Guidelines

1. Fork & Clone: Fork the repo and clone your fork
2. Branch: Create a feature branch (git checkout -b feature/amazing-feature)
3. Code: Write your code following our style guide
4. Test: Add tests and ensure all tests pass
5. Document: Update documentation as needed
6. Commit: Use conventional commits (feat:, fix:, docs:, etc.)
7. Push: Push to your fork and create a pull request

Code Standards:

• ✅ Black formatting
• ✅ isort imports
• ✅ Type hints
• ✅ Comprehensive tests
• ✅ Google-style docstrings
• ✅ Performance considerations

🌟 Contributors

---

📊 Project Stats

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⭐ Star us on GitHub • 📖 Read the Docs • 🌐 Developer Portfolio

---

Made with ❤️ by William R. Astley, for developers