Metadata-Version: 2.4
Name: debugx
Version: 0.1.0
Summary: The most comprehensive offline Python debugging snapshot tool: capture your runtime, system, and project state in one call.
Project-URL: Homepage, https://github.com/debugx/debugx
Project-URL: Documentation, https://github.com/debugx/debugx/tree/main/docs
Project-URL: Repository, https://github.com/debugx/debugx
Project-URL: Issues, https://github.com/debugx/debugx/issues
Project-URL: Changelog, https://github.com/debugx/debugx/blob/main/CHANGELOG.md
Author: debugx contributors
License-Expression: MIT
License-File: LICENSE
Keywords: cli,debugging,devtools,diagnostics,environment,snapshot,troubleshooting
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Logging
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: black>=24.1; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pre-commit>=3.6; extra == 'dev'
Requires-Dist: psutil>=5.9; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: full
Requires-Dist: psutil>=5.9; extra == 'full'
Description-Content-Type: text/markdown

# debugx

**The most comprehensive offline Python debugging snapshot tool.**

`debugx` collects a complete snapshot of your Python runtime, host system, project, and application
environment in a single command -- and writes it out as a beautiful, self-contained HTML dashboard, a
GitHub-issue-ready Markdown file, and a schema-versioned JSON document. Everything runs **100% offline**.
debugx never uploads data anywhere, ever.

```bash
pip install debugx
```

```python
from debugx import capture

capture()
```

That's it. You now have `debug_report.html`, `debug_report.json`, and `debug_report.md` in your current
directory.

## Why debugx?

When a bug report says "it works on my machine," or a teammate needs to understand *exactly* what
environment produced a stack trace, `debugx` gives you one command that answers almost every follow-up
question before it's asked: Python version, installed packages, git branch and dirty state, OS/CPU/memory,
Docker/Kubernetes context, network reachability, recent log lines, the active exception -- masked for
secrets, formatted for humans, and generated in under two seconds.

## Features

- **Runtime**: Python version, executable, virtual environment, pip version, loaded modules, threads, GC stats.
- **System**: OS, hostname, architecture, CPU, memory, disk usage.
- **Project**: git branch/commit/status, `pyproject.toml`/`requirements.txt` detection, Poetry/uv detection, project structure.
- **Environment**: environment variables and packages, with automatic **secret detection and masking**.
- **Network**: hostname, local IP, DNS status, internet reachability, listening ports -- all local, no data sent.
- **Containers**: Docker and Kubernetes detection (namespace, pod, node).
- **Diagnostics**: current exception with syntax-highlighted traceback, call stack, recent log lines, warnings.
- **Plugins**: register your own health checks with `@debugx.plugin` -- e.g. "is my database reachable?"
- **Never crashes**: every collector and plugin is isolated; a failure is recorded, not raised.
- **Never uploads**: no network calls beyond local reachability checks, no telemetry, no analytics.

## Installation

```bash
pip install debugx

# Optional: richer CPU/memory/process metrics via psutil
pip install "debugx[full]"
```

## Basic usage

```python
from debugx import capture

capture()
```

## Advanced usage

```python
from debugx import capture

capture(
    output=["html", "json", "markdown"],
    include_packages=True,
    include_git=True,
    include_network=True,
    include_processes=True,
    include_ports=True,
    include_logs=True,
    include_runtime=True,
    include_docker=True,
    include_kubernetes=True,
    include_project=True,
    include_environment=True,
    include_stacktrace=True,
    include_performance=True,
    include_threads=True,
    mask_secrets=True,
    output_directory="./reports",
    compress=False,
    verbose=False,
)
```

### Capturing an exception

```python
from debugx import capture

try:
    1 / 0
except ZeroDivisionError as exc:
    capture(exception=exc, output=["html"])
```

## CLI

```bash
debugx capture              # write html+json+markdown to the current directory
debugx capture --html -o ./reports
debugx capture --all --compress
debugx capture --no-network --no-processes --verbose
debugx capture --config debugx.toml

debugx report debug_report.json --html   # re-render HTML/Markdown from a saved JSON snapshot

debugx doctor                # environment sanity checks
debugx plugins                # list discovered plugins
debugx system                 # quick system summary, no files written
debugx version
```

Run `debugx --help` or `debugx <command> --help` for the full flag reference.

## Plugins

```python
from debugx import plugin

@plugin(name="database", priority=10, timeout=2.0)
def check_database() -> dict:
    return {"status": "healthy"}
```

Third-party packages can also register plugins via entry points -- see
[`docs/plugin-development.md`](docs/plugin-development.md).

## Security

- debugx **never** makes network requests that send data anywhere; the only network activity is a bare TCP
  handshake / DNS lookup used purely to report reachability.
- debugx **never** executes arbitrary shell commands; `git` is invoked with a fixed argument list only.
- Secrets (passwords, tokens, API keys, JWTs, connection strings, etc.) are detected and replaced with
  `********` by default in every output. See [`SECURITY.md`](SECURITY.md).

## Documentation

- [Architecture](docs/architecture.md)
- [Plugin development](docs/plugin-development.md)
- [API reference](docs/api-reference.md)
- [Examples](examples/)
- [Contributing](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)
- [Roadmap](ROADMAP.md)

## License

MIT -- see [LICENSE](LICENSE).
