Metadata-Version: 2.4
Name: rawdumper
Version: 1.0.0
Summary: A tool and library infrastructure for hexadecimal analysis, reversing, searching, dumping and more.
Home-page: https://codeberg.org/Zamanhuseyinli/Rawdumper
License: GPL-3.0-or-later
Project-URL: Repository, https://codeberg.org/Zamanhuseyinli/Rawdumper
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: adamlibrary>=1.7.1
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# rawdumper

Rawdumper is a library based on [adamlibrary](https://codeberg.org/Zamanhuseyinli/Adam-cpython/) designed to convert hexadecimal code into binary by directly dumping the hexadecimal code in Python, and to analyze hexadecimal data, offering search and reversing support.

This is a **library first, CLI second**: importing `rawdumper` never
parses argv or touches stdin. The command-line interface is a thin,
optional layer on top.

## Install

```bash
pip install -e .
```

## Library usage

```python
import rawdumper

data = open("file.bin", "rb").read()

# Render a hex dump as text
print(rawdumper.dump(data, width=16))

# Search for a byte pattern
offsets = rawdumper.find(data, b"needle")
print(rawdumper.contains(data, b"needle"))

# Shannon entropy (bits per byte)
print(rawdumper.entropy(data))

# Restore a hex dump back to binary
text = rawdumper.dump(data, squeeze=False)
restored = rawdumper.restore(text)
assert restored == data
```

Every function in the public API (`rawdumper.dump`, `rawdumper.find`,
`rawdumper.entropy`, `rawdumper.restore`, etc.) is a plain function that
takes `bytes` in and returns a value — no global state, no CLI
side effects.

## Optional CLI

Installing this package also registers a `rawdumper` console script,
and the package can be run directly as a module:

```bash
rawdumper file.bin
python -m rawdumper file.bin --width 8 --find "Wolf" --stats
python -m rawdumper --reverse dump.hex -o restored.bin
```

CLI flags:

| Flag | Description |
|---|---|
| `--width N` | bytes per line (default 16) |
| `--offset N` | starting offset, `0x..` supported |
| `--length N` | number of bytes to read |
| `--find TEXT` | search for a pattern and highlight matching lines |
| `--octal` | show bytes in octal instead of hex |
| `--no-squeeze` | disable collapsing of repeated identical lines |
| `--stats` | print size and Shannon entropy before the dump |
| `--reverse` | treat input as a hex dump and restore it to binary |
| `-o, --output` | output path when used with `--reverse` |

## What's C-backed and why

| Module | adamlibrary function used | Purpose |
|---|---|---|
| `rawdumper.core` | `adam.memcpy` | chunk byte copying |
| `rawdumper.core` | `datasetname.itoa` | decimal→octal string formation |
| `rawdumper.search` | `memreplication_cutline.memchr` | byte pattern search |
| `rawdumper.stats` | `math.log` | Shannon entropy calculation |
| `rawdumper.reverse` | `stringer.strdup` | owned copy of input before parsing |

## Package layout

```
rawdumper/
├── __init__.py    # public API surface (dump, find, entropy, restore, ...)
├── core.py        # dump/format logic
├── search.py      # pattern search
├── stats.py        # entropy
├── reverse.py     # hex-to-binary restore
└── __main__.py    # optional CLI, only runs via `python -m rawdumper` or the console script
```
