Metadata-Version: 2.4
Name: ufedlib_py
Version: 1.0.0
Summary: ufedlib_py is Python port of UFEDLib (.ufdr/report.xml parser)
Author: Rahul Bali
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# UFEDLib_py

UFEDLib_py library parses Cellebrite UFED/UFDR output files into Python dataclasses and 
provides a high-level `ReportData` object for easier access and processing of forensic report data.

inspired by or complementary to the C# **UFEDLib** project originally created by Sönke Eilers  [(https://github.com/SEilers/UFEDLib)].
Thanks to the author for the outstanding C# foundation!

## Features

- Reads Cellebrite UFED outputs:
  - `.ufdr` files (zip containing `report.xml`)
  - raw `report.xml`
- Scans available model types
- Parses a single model type or all models + metadata (ReportData)
- Single-pass `parse_all` for large UFDR files
- CLI + Python API

## Install

Editable install (for development):

```powershell
python -m pip install -e .
```

Install from a built wheel:

```powershell
python -m pip install dist\ufedlib_py-1.0.0-py3-none-any.whl
```

## CLI

Scan model types:

```powershell
ufedlib_py scan --input "C:\path\to\case.ufdr"
```

Parse a model type:

```powershell
ufedlib_py parse --input "C:\path\to\case.ufdr" --model "Contact"
```

Parse all supported models + metadata:

```powershell
ufedlib_py parse-all --input "C:\path\to\case.ufdr" --json
```

Limit parse-all to specific models and log progress:

```powershell
ufedlib_py parse-all --input "C:\path\to\case.ufdr" --model "Call" --model "Contact" --progress-every 1000
```

Include unknown model types detected in the file:

```powershell
ufedlib_py parse-all --input "C:\path\to\case.ufdr" --include-unknown-models
```

## Python API

Parse all models + metadata:

```python
from ufedlib_py import parse_all

def on_progress(model_type: str, count: int) -> None:
    print(f"{model_type}: {count}")

report = parse_all(
    r"C:\path\to\case.ufdr",
    model_types=["Call", "Contact"],
    progress_callback=on_progress,
    progress_every=1000,
)

print(report.DeviceInfo)
print(len(report.Models.get("Call", [])))
```

Parse a single model:

```python
from ufedlib_py import parse_data

calls = parse_data(r"C:\path\to\case.ufdr", "Call")
```

Discover models:

```python
from ufedlib_py import scan_models, get_supported_models

all_in_file = scan_models(r"C:\path\to\case.ufdr")
supported = get_supported_models()
```

## Performance tips

- Use `model_types` in `parse_all` to limit work.
- `parse_all` uses a single-pass XML stream for large files.
- Use `progress_every` for visibility on long-running parses.

## Model coverage

List models detected in a report:

```powershell
ufedlib_py scan --input "C:\path\to\case.ufdr"
```

Check which models are supported by this library:

```python
from ufedlib_py import get_supported_models, get_unsupported_models

supported = get_supported_models()
unsupported = get_unsupported_models(r"C:\path\to\case.ufdr")
```

## Schema notes

- UFED XML often stores scalar values inside `<field><value>...</value></field>`.
- Nested `<model>` blocks are parsed into typed dataclasses when a `type` attribute is present.
- Some nested fields are post-processed into dictionaries and lists for easier consumption.

## Troubleshooting

- **Progress errors or missing callbacks**: reinstall the package in the active venv using
  `python -m pip install -e .` to ensure you are running the latest code.
- **Model not registered**: confirm the model appears in `scan` output and is included in
  `get_supported_models()`.
- **Large file performance**: use `parse_all(..., model_types=[...])` to limit work.

## Build a wheel

```powershell
python -m pip install build
python -m build
```
