🐛 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
🎯 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
📚 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 ReportsFound a bug? Open an issue with:
|
✨ Feature RequestsHave an idea? Request a feature with:
|
📋 Contribution Guidelines
- Fork & Clone: Fork the repo and clone your fork
- Branch: Create a feature branch (
git checkout -b feature/amazing-feature) - Code: Write your code following our style guide
- Test: Add tests and ensure all tests pass
- Document: Update documentation as needed
- Commit: Use conventional commits (
feat:,fix:,docs:, etc.) - 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
Metadata
Release files for pydvlp-debug 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pydvlp_debug-0.1.0.tar.gz | 27.8 kB | Without provenance | Details for pydvlp_debug-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pydvlp_debug-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pydvlp_debug-0.1.0-py3-none-any.whl |
Total release size: 36.7 kB
Release files / pydvlp_debug-0.1.0.tar.gz
| Download URL | pydvlp_debug-0.1.0.tar.gz |
|---|---|
| Size | 27.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f9de3bc76df67843501ce12cf542f924451e110c75d39d62994ad23440f54885
|
|
BLAKE2b-256 checksum How to use checksums |
1aaa179349cdffdad4807c0e16e712787d228b8dc1881cabf2b1c847ba43a311
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
pdm/2.25.5 CPython/3.12.3 Linux/6.6.87.2-microsoft-standard-WSL2
|
Release files / pydvlp_debug-0.1.0-py3-none-any.whl
| Download URL | pydvlp_debug-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1d47a6912c55fb8a568d8751531753bdc28a2da38536729a498824ea289c1821
|
|
BLAKE2b-256 checksum How to use checksums |
7cea486f42ea22ab509a8db15b4a48cc6ab4d607830e4eb643ef7354220ff7dd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
pdm/2.25.5 CPython/3.12.3 Linux/6.6.87.2-microsoft-standard-WSL2
|
Security for pydvlp-debug 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.