Bundle API¶
The bundle module handles the .bugbundle file format.
Overview¶
from bugsafe.bundle.schema import BugBundle, CaptureOutput
from bugsafe.bundle.writer import write_bundle
from bugsafe.bundle.reader import read_bundle
# Create a bundle
bundle = BugBundle(
capture=CaptureOutput(
stdout="output",
stderr="error",
exit_code=1,
command=["python", "script.py"],
)
)
# Write to file
write_bundle(bundle, "crash.bugbundle")
# Read from file
loaded = read_bundle("crash.bugbundle")
Schema¶
BugBundle¶
Complete bug bundle containing all captured data.
bugsafe.bundle.schema.BugBundle ¶
Bases: BaseModel
Complete bug bundle.
Attributes:
| Name | Type | Description |
|---|---|---|
metadata | BundleMetadata | Bundle metadata. |
capture | CaptureOutput | Captured command output. |
traceback | Traceback | None | Parsed traceback (if available). |
environment | Environment | None | Environment snapshot. |
redaction_report | dict[str, int] | Summary of redactions by category. |
CaptureOutput¶
Captured command output.
bugsafe.bundle.schema.CaptureOutput ¶
Bases: BaseModel
Captured command output.
Attributes:
| Name | Type | Description |
|---|---|---|
stdout | str | Standard output (redacted). |
stderr | str | Standard error (redacted). |
exit_code | int | Process exit code. |
duration_ms | int | Execution duration in milliseconds. |
command | list[str] | The executed command. |
timed_out | bool | Whether the command timed out. |
truncated | bool | Whether output was truncated. |
Traceback¶
Structured Python traceback.
bugsafe.bundle.schema.Traceback ¶
Bases: BaseModel
Structured representation of a Python traceback.
Attributes:
| Name | Type | Description |
|---|---|---|
exception_type | str | The type of exception raised. |
message | str | The exception message. |
frames | list[Frame] | List of stack frames. |
chained | list[Traceback] | None | Chained exceptions (cause/context). |
Environment¶
Environment snapshot.
bugsafe.bundle.schema.Environment ¶
Bases: BaseModel
Environment snapshot.
Attributes:
| Name | Type | Description |
|---|---|---|
python_version | str | Full Python version string. |
python_executable | str | Path to Python executable. |
platform | str | Platform identifier string. |
packages | list[PackageInfo] | List of installed packages. |
env_vars | dict[str, str] | Filtered environment variables. |
cwd | str | Current working directory. |
git | GitInfo | None | Git repository information. |
virtualenv | bool | Whether running in virtualenv. |
in_container | bool | Whether running in container. |
ci_detected | bool | Whether running in CI. |
BundleMetadata¶
Bundle metadata.
bugsafe.bundle.schema.BundleMetadata ¶
Bases: BaseModel
Bundle metadata.
Attributes:
| Name | Type | Description |
|---|---|---|
version | str | Bundle format version. |
created_at | datetime | Creation timestamp. |
bugsafe_version | str | bugsafe version used to create bundle. |
redaction_salt_hash | str | SHA256 hash of redaction salt. |
Reader/Writer Functions¶
read_bundle¶
bugsafe.bundle.reader.read_bundle(path) ¶
Read and parse a .bugbundle file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path | Path | Path to the bundle file. | required |
Returns:
| Type | Description |
|---|---|
BugBundle | Parsed BugBundle. |
Raises:
| Type | Description |
|---|---|
BundleNotFoundError | If file doesn't exist. |
BundleCorruptError | If ZIP is invalid. |
BundleParseError | If JSON parsing fails. |
BundleSchemaError | If schema validation fails. |
BundleVersionError | If version is unsupported. |
create_bundle¶
bugsafe.bundle.writer.create_bundle(bundle, path, *, overwrite=True) ¶
Create a .bugbundle file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bundle | BugBundle | The BugBundle to write. | required |
path | Path | Output path for the bundle. | required |
overwrite | bool | Whether to overwrite existing file. | True |
Raises:
| Type | Description |
|---|---|
BundleWriteError | If writing fails. |
BundleSizeError | If bundle exceeds size limit. |
FileExistsError | If file exists and overwrite=False. |
validate_bundle¶
bugsafe.bundle.writer.validate_bundle(path) ¶
Validate a bundle file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path | Path | Path to the bundle. | required |
Returns:
| Type | Description |
|---|---|
ValidationResult | ValidationResult with validity status and any issues. |