Perihelion Signal Processor (PeSPr)

🚀 Project Status: In active development. All components subject to change. Contributions and feedback welcome.

🎯 Intent: Enhance and automate error handling, recovery, propagation management, and logging in Python projects by integrating static and dynamic analysis with tools like DynEL.

🛠️ Goals:

• Automate error handling and logging configuration
• Improve error propagation and control flow
• Integrate with CI/CD pipelines and IDEs
• Optimize performance for scalability

Table of Contents

1. Description
2. Installation
3. Usage
   • Basic Example
   • Advanced Usage
4. Features
5. Configuration
6. Testing
7. Development Setup
8. Proposed Implementation
   • Proof of Concept (POC)
   • Minimum Viable Product (MVP)
9. Security Best Practices
10. Contribution
11. License
12. Contact
13. Troubleshooting
14. Acknowledgments
15. References

Description

PeSPr (Perihelion Signal Processor) is a sister project to DynEL (Dynamic Error Logging), designed to automate the generation of DynEL configuration files. It leverages static analysis tools (Mypy, Astroid) and dynamic analysis (pytest) to extract exception types, error-prone code segments, and runtime behaviors, creating a robust error handling and logging framework for Python projects.

Installation

Install PeSPr via pip:

pip install pespr

For development, use UV to manage dependencies. See Development Setup.

Usage

Basic Example

Analyze a project to generate a dynel_config.yaml:

pespr analyze /path/to/your/project

Advanced Usage

Generate or update configurations with additional options:

pespr generate-config /path/to/your/project --output dynel_config.yaml
pespr update-config /path/to/your/project

Features

• Static Analysis: Extracts exception data using Mypy and Astroid
• Dynamic Analysis: Integrates runtime data with pytest
• Error Catalog: Comprehensive registry of error types
• Logging: Advanced formatting and outputs via Loguru
• CI/CD Integration: Automates config generation in pipelines
• Extensibility: Supports custom error handlers and plugins

Configuration

Configure PeSPr with a pespr_config.yaml file:

analysis:
  ignore_dirs: ['tests', 'docs']
  max_depth: 5
logging:
  level: INFO
  output: ['file', 'console']
ci_integration:
  enabled: true
  report_format: json

See the Configuration Guide for details.

Testing

Run tests with pytest:

pytest

Install development dependencies first (see Development Setup).

Development Setup

1. Clone the repository:

   git clone https://github.com/tzervas/pespr.git

2. Navigate to the directory:

   cd pespr

3. Install dependencies with UV:

   uv sync

4. Configure via pespr_config.yaml or environment variables.
5. Run the application:

   python main.py

Proposed Implementation

Proof of Concept (POC)

Basic static analysis and config generation:

from pespr import analyze_project

config = analyze_project('/path/to/project')
config.save('dynel_config.yaml')

Minimum Viable Product (MVP)

Configurable integration with DynEL:

from pespr import PeSPrConfig, generate_config

config = PeSPrConfig()
config.load('pespr_config.yaml')
generate_config('/path/to/project', config)

Security Best Practices

🔒

• Validate all inputs to prevent injection or errors
• Use structured error handling to avoid crashes
• Secure logging to prevent sensitive data leaks
• Keep dependencies updated to address vulnerabilities

Contribution

See the Developer Guide and CONTRIBUTING.md for contribution details.

License

MIT License. See LICENSE for more information.

Contact

• Author: Tyler Zervas
• GitHub: tzervas
• X: @vec_wt_tech

Troubleshooting

Check the issue tracker for common problems or contact the author.

Acknowledgments

Thanks to the teams behind Mypy, Astroid, Loguru, and pytest.

References

• DynEL Documentation
• UV Documentation