Metadata-Version: 2.4
Name: dnbflib
Version: 1.0.0
Summary: Read, edit, export, and rebuild .NET BinaryFormatter / NRBF streams.
Project-URL: Documentation, https://github.com/yntha/dnbflib#readme
Project-URL: Issues, https://github.com/yntha/dnbflib/issues
Project-URL: Source, https://github.com/yntha/dnbflib
Author-email: yntha <126660548+yntha@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.11
Requires-Dist: pydatastreams
Description-Content-Type: text/markdown

# dnbflib

`dnbflib` reads, indexes, edits, exports, and rebuilds .NET BinaryFormatter / NRBF
binary streams in Python.

## Warning
BinaryFormatter is unsafe for untrusted data. Use this library for inspection, migration, recovery, and editing of files you already trust. Do not accept arbitrary BinaryFormatter payloads from users or the network.

## Status

The current maintained APIs are:

- `DNBFDocument` for memory-conscious object graph traversal and edits.
- `export_dnbf_to_yaml` / `rebuild_yaml_export` for lossless editable YAML packages.
- `DNBFRecordStore` for SQLite-backed record storage and inspection.
- `DNBFWriter` for rebuilding streams from raw records or writable record objects.

-----

## Requirements

- Python 3.11 or newer.
- `pydatastreams`, installed automatically by package managers.

## Installation

From PyPI, once published:

```console
pip install dnbflib
```

From a local checkout:

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

## Object traversal

```python
from dnbflib import DNBFDocument

with DNBFDocument.open("save.dat") as doc:
    life = doc.one(class_name="Life", where=lambda obj: obj.member("Name").value == "Alex")
    finances = life.member("Finances").deref()
    finances.member("BankBalance").set(123456)
    doc.write("edited.dat")
```

`DNBFDocument.open()` uses an mmap-backed source file and an offset index. Prefer
`doc.write(...)` over `doc.to_bytes()` for large files because it streams output chunks.

If more than one object matches a class name, use `one(..., where=...)` to disambiguate:

```python
with DNBFDocument.open("save.dat") as doc:
    life = doc.one(class_name="Life", where=lambda obj: obj.member("Name").value == "Alex")
```

## YAML export

```python
from dnbflib import export_dnbf_to_yaml, rebuild_yaml_export

export_dnbf_to_yaml("save.dat", "save_export")
rebuilt = rebuild_yaml_export("save_export")
```

The export is lossless by default. It writes a `manifest.yaml` index and nested per-record
directories containing `record.yaml`, `raw.bin`, and decoded sidecar files when useful.

The repository also includes a command-line export example:

```console
python examples/export_to_yaml.py save.dat save_export --verify
```

## Record Store

```python
from dnbflib import DNBFRecordStore, DNBFWriter, RecordTypeEnumeration

store = DNBFRecordStore(":memory:", source_bytes=b"\x0b")
store.add_raw_record(record_type=RecordTypeEnumeration.MessageEnd, offset=0, raw=b"\x0b")

rebuilt = DNBFWriter.from_record_store(store).to_bytes()
assert rebuilt == b"\x0b"
```

## Public API

The top-level `dnbflib` package exports:

- `DNBFDocument`, `DNBFObjectNode`, `DNBFMemberNode`
- `DNBFRecordStore`, `StoredRecord`
- `DNBFWriter`
- `export_dnbf_to_yaml`, `export_record_store_to_yaml`, `rebuild_yaml_export`
- `RecordTypeEnumeration`, `BinaryTypeEnumeration`, `PrimitiveTypeEnumeration`
- `BinaryObjectString`
- traversal errors such as `ObjectNotFoundError`, `AmbiguousObjectError`, `MemberNotFoundError`, and `AmbiguousMemberError`

Further details on this library are available in [docs/index.html](docs/index.html).

## License

`dnbflib` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
