| Name | spewer JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A Python debugging library for detailed code execution tracing |
| upload_time | 2025-07-31 20:52:26 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
debugging
tracing
development
debug
trace
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Spewer
A Python debugging library for detailed code execution tracing. This library provides utilities for tracing Python code execution with detailed information about variables, function calls, and execution flow.
## Features
- **Line-by-line execution tracing**: See exactly which lines are being executed
- **Variable value inspection**: View the values of variables at each execution step
- **Module filtering**: Trace only specific modules or all modules
- **Context manager support**: Use with `with` statements for automatic cleanup
- **Lightweight**: Minimal overhead and dependencies
Note: Implemented to avoid using pdb manual effort. This is not going to replace pyinstrument, py-spy, and several other performance and profiling debugging tools. This is a simple tool just to counter manual effort of pdb, and it can go deep inside the dependency and print those traces in a basic format which can be done by pyinstrument and other profiling tools as well, but again this is targeting a basic pdb flaw of manual inspection. This is just an inspection tool.
## Installation
### From PyPI (when published)
```bash
pip install spewer
```
### From source
```bash
git clone https://github.com/Agent-Hellboy/spewer.git
cd spewer
pip install -e .
```
## Usage
### Basic Usage
```python
from spewer import spew, unspew
# Start tracing
spew(show_values=True)
# Your code here
def my_function():
x = 10
y = 20
return x + y
result = my_function()
# Stop tracing
unspew()
```
### Using Context Manager
```python
from spewer import SpewContext
# Automatic start/stop of tracing
with SpewContext(show_values=True):
def my_function():
x = 10
y = 20
return x + y
result = my_function()
```
### Module-Specific Tracing
```python
from spewer import spew, unspew
# Only trace specific modules
spew(trace_names=['my_module'], show_values=True)
# Your code here
import my_module
my_module.some_function()
unspew()
```
### Tracing Without Variable Values
```python
from spewer import SpewContext
# Trace execution without showing variable values
with SpewContext(show_values=False):
def my_function():
x = 10
y = 20
return x + y
result = my_function()
```
## API Reference
### Functions
#### `spew(trace_names=None, show_values=False)`
Install a trace hook which writes detailed logs about code execution.
**Parameters:**
- `trace_names` (Optional[List[str]]): List of module names to trace. If None, traces all modules.
- `show_values` (bool): Whether to show variable values during tracing.
#### `unspew()`
Remove the trace hook installed by `spew()`.
### Classes
#### `Spewer(trace_names=None, show_values=True)`
A trace hook class that provides detailed debugging information.
**Parameters:**
- `trace_names` (Optional[List[str]]): List of module names to trace. If None, traces all modules.
- `show_values` (bool): Whether to show variable values during tracing.
#### `SpewContext(trace_names=None, show_values=False)`
Context manager for automatic spew/unspew operations.
**Parameters:**
- `trace_names` (Optional[List[str]]): List of module names to trace. If None, traces all modules.
- `show_values` (bool): Whether to show variable values during tracing.
## Example Output
When tracing with `show_values=True`, you'll see output like:
```
__main__:15: x = 10
x=10
__main__:16: y = 20
y=20
__main__:17: result = x + y
x=10 y=20 result=30
__main__:18: print(f"Result: {result}")
result=30
```
## Notes
- The library uses Python's `sys.settrace()` which can impact performance
- Only one trace hook can be active at a time
- The context manager automatically handles cleanup even if exceptions occur
- Variable inspection works best with simple variable names (avoid complex expressions)
## License
This library is based on the Gunicorn debug module released under the MIT license. The original Gunicorn debug module is Copyright (c) 2009-2024 Benoît Chesneau and Copyright (c) 2009-2015 Paul J. Davis.
### Attribution
This project builds upon the excellent debugging utilities from the Gunicorn web server project. The core tracing functionality was adapted from Gunicorn's debug module, which provides robust execution tracing capabilities. We've enhanced the original implementation with:
- **Type hints** for better IDE support
- **Context manager integration** for automatic cleanup
- **Enhanced error handling** for problematic objects
- **Improved documentation** and examples
- **Modern Python packaging** structure
The original Gunicorn debug module can be found at: https://github.com/benoitc/gunicorn/blob/master/gunicorn/debug.py
**Future Enhancements**: We plan to further enhance this library with additional features to improve usability, including more output formats, advanced filtering options, and better integration with existing debugging workflows.
Raw data
{
"_id": null,
"home_page": null,
"name": "spewer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Prince Roshan <princekrroshan01@gmail.com>",
"keywords": "debugging, tracing, development, debug, trace",
"author": null,
"author_email": "Prince Roshan <princekrroshan01@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/69/ba/8162228e42e26344357c4a689b1058264edbd64d4f018c6fb8bb82063fe3/spewer-0.1.0.tar.gz",
"platform": null,
"description": "# Spewer\n\nA Python debugging library for detailed code execution tracing. This library provides utilities for tracing Python code execution with detailed information about variables, function calls, and execution flow.\n\n## Features\n\n- **Line-by-line execution tracing**: See exactly which lines are being executed\n- **Variable value inspection**: View the values of variables at each execution step\n- **Module filtering**: Trace only specific modules or all modules\n- **Context manager support**: Use with `with` statements for automatic cleanup\n- **Lightweight**: Minimal overhead and dependencies\n\nNote: Implemented to avoid using pdb manual effort. This is not going to replace pyinstrument, py-spy, and several other performance and profiling debugging tools. This is a simple tool just to counter manual effort of pdb, and it can go deep inside the dependency and print those traces in a basic format which can be done by pyinstrument and other profiling tools as well, but again this is targeting a basic pdb flaw of manual inspection. This is just an inspection tool.\n\n## Installation\n\n### From PyPI (when published)\n\n```bash\npip install spewer\n```\n\n### From source\n\n```bash\ngit clone https://github.com/Agent-Hellboy/spewer.git\ncd spewer\npip install -e .\n```\n\n## Usage\n\n### Basic Usage\n\n```python\nfrom spewer import spew, unspew\n\n# Start tracing\nspew(show_values=True)\n\n# Your code here\ndef my_function():\n x = 10\n y = 20\n return x + y\n\nresult = my_function()\n\n# Stop tracing\nunspew()\n```\n\n### Using Context Manager\n\n```python\nfrom spewer import SpewContext\n\n# Automatic start/stop of tracing\nwith SpewContext(show_values=True):\n def my_function():\n x = 10\n y = 20\n return x + y\n \n result = my_function()\n```\n\n### Module-Specific Tracing\n\n```python\nfrom spewer import spew, unspew\n\n# Only trace specific modules\nspew(trace_names=['my_module'], show_values=True)\n\n# Your code here\nimport my_module\nmy_module.some_function()\n\nunspew()\n```\n\n### Tracing Without Variable Values\n\n```python\nfrom spewer import SpewContext\n\n# Trace execution without showing variable values\nwith SpewContext(show_values=False):\n def my_function():\n x = 10\n y = 20\n return x + y\n \n result = my_function()\n```\n\n## API Reference\n\n### Functions\n\n#### `spew(trace_names=None, show_values=False)`\n\nInstall a trace hook which writes detailed logs about code execution.\n\n**Parameters:**\n- `trace_names` (Optional[List[str]]): List of module names to trace. If None, traces all modules.\n- `show_values` (bool): Whether to show variable values during tracing.\n\n#### `unspew()`\n\nRemove the trace hook installed by `spew()`.\n\n### Classes\n\n#### `Spewer(trace_names=None, show_values=True)`\n\nA trace hook class that provides detailed debugging information.\n\n**Parameters:**\n- `trace_names` (Optional[List[str]]): List of module names to trace. If None, traces all modules.\n- `show_values` (bool): Whether to show variable values during tracing.\n\n#### `SpewContext(trace_names=None, show_values=False)`\n\nContext manager for automatic spew/unspew operations.\n\n**Parameters:**\n- `trace_names` (Optional[List[str]]): List of module names to trace. If None, traces all modules.\n- `show_values` (bool): Whether to show variable values during tracing.\n\n## Example Output\n\nWhen tracing with `show_values=True`, you'll see output like:\n\n```\n__main__:15: x = 10\n x=10\n__main__:16: y = 20\n y=20\n__main__:17: result = x + y\n x=10 y=20 result=30\n__main__:18: print(f\"Result: {result}\")\n result=30\n```\n\n## Notes\n\n- The library uses Python's `sys.settrace()` which can impact performance\n- Only one trace hook can be active at a time\n- The context manager automatically handles cleanup even if exceptions occur\n- Variable inspection works best with simple variable names (avoid complex expressions)\n\n## License\n\nThis library is based on the Gunicorn debug module released under the MIT license. The original Gunicorn debug module is Copyright (c) 2009-2024 Beno\u00eet Chesneau and Copyright (c) 2009-2015 Paul J. Davis.\n\n### Attribution\n\nThis project builds upon the excellent debugging utilities from the Gunicorn web server project. The core tracing functionality was adapted from Gunicorn's debug module, which provides robust execution tracing capabilities. We've enhanced the original implementation with:\n\n- **Type hints** for better IDE support\n- **Context manager integration** for automatic cleanup\n- **Enhanced error handling** for problematic objects\n- **Improved documentation** and examples\n- **Modern Python packaging** structure\n\nThe original Gunicorn debug module can be found at: https://github.com/benoitc/gunicorn/blob/master/gunicorn/debug.py\n\n**Future Enhancements**: We plan to further enhance this library with additional features to improve usability, including more output formats, advanced filtering options, and better integration with existing debugging workflows. \n",
"bugtrack_url": null,
"license": null,
"summary": "A Python debugging library for detailed code execution tracing",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/Agent-Hellboy/spewer/issues",
"Documentation": "https://github.com/Agent-Hellboy/spewer#readme",
"Homepage": "https://github.com/Agent-Hellboy/spewer",
"Repository": "https://github.com/Agent-Hellboy/spewer"
},
"split_keywords": [
"debugging",
" tracing",
" development",
" debug",
" trace"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ce3d68da2be540636d87d41e92d00f0b1973e07d6ca18532d06e1a5923ddf909",
"md5": "61e9c99f9ea9c7fc8615616cb64298bf",
"sha256": "33346a7dd0ac6eea5efa52e79d7e2146a63546b2ce963556e0c1505a40e5eaed"
},
"downloads": -1,
"filename": "spewer-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "61e9c99f9ea9c7fc8615616cb64298bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 4166,
"upload_time": "2025-07-31T20:52:25",
"upload_time_iso_8601": "2025-07-31T20:52:25.672875Z",
"url": "https://files.pythonhosted.org/packages/ce/3d/68da2be540636d87d41e92d00f0b1973e07d6ca18532d06e1a5923ddf909/spewer-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "69ba8162228e42e26344357c4a689b1058264edbd64d4f018c6fb8bb82063fe3",
"md5": "c7a3181e59dd0243d44e2b38327e6633",
"sha256": "58c4d545c19dcc08626d77ea40bdc13203f99235fdc770afeea7b6e8ed697a5b"
},
"downloads": -1,
"filename": "spewer-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c7a3181e59dd0243d44e2b38327e6633",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 5403,
"upload_time": "2025-07-31T20:52:26",
"upload_time_iso_8601": "2025-07-31T20:52:26.777478Z",
"url": "https://files.pythonhosted.org/packages/69/ba/8162228e42e26344357c4a689b1058264edbd64d4f018c6fb8bb82063fe3/spewer-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 20:52:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Agent-Hellboy",
"github_project": "spewer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "spewer"
}
