Metadata-Version: 2.4
Name: metabeam
Version: 0.1.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Classifier: Topic :: Multimedia
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Summary: Metadata extraction for any file type: detect MIME from magic bytes, read EXIF/GPS, image/audio/video tags, PDF info, archive contents, hashes, and entropy.
Keywords: metadata,exif,gps,parser,file-type,mime,magic-bytes,forensics,metadata-extraction
Author: rgcsekaraa
License: MIT OR Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/rgcsekaraa/metabeam#readme
Project-URL: Homepage, https://github.com/rgcsekaraa/metabeam
Project-URL: Issues, https://github.com/rgcsekaraa/metabeam/issues
Project-URL: Repository, https://github.com/rgcsekaraa/metabeam

# metabeam (Python)

**Point it at any file and read everything inside.**

metabeam is a metadata extraction engine for any file type. It detects formats
by their magic bytes (never the file extension), runs every applicable parser,
and returns a structured report as a plain Python dict: hashes and entropy,
image geometry, EXIF and GPS, audio tags, video timing, document properties,
archive contents, and binary headers.

The package is a compiled Rust extension (built with
[maturin](https://github.com/PyO3/maturin) and [PyO3](https://pyo3.rs)), so
parsing is fast and the result matches the CLI and Node packages exactly.

## Install

```sh
pip install metabeam
```

Supports CPython 3.8+ on Linux, macOS, and Windows.

## Usage

```python
import metabeam

# Parse a file from disk. Raises OSError if it cannot be read.
report = metabeam.parse("photo.jpg")

print(report["file"]["mime_detected"])    # "image/jpeg"
print(report["file"]["sha256"])           # full hex digest
print(report["jpeg"]["quality_estimate"]) # estimated JPEG quality
print(report["exif"]["gps_decimal"])      # {"latitude": ..., "longitude": ...}
```

Parse bytes that never touch disk (an upload, a download, a database blob):

```python
with open("photo.jpg", "rb") as f:
    report = metabeam.parse_bytes(f.read())
```

The result is a plain dict, so it serializes directly:

```python
import json
print(json.dumps(report, indent=2))
```

### Validate that an upload is really the type it claims

Because detection is by content, not extension, metabeam is a reliable way to
reject spoofed uploads:

```python
import metabeam

def is_real_png(data: bytes) -> bool:
    report = metabeam.parse_bytes(data)
    return report["file"]["mime_detected"] == "image/png"
```

## API

- `metabeam.parse(path: str) -> dict` - parse a file on disk.
- `metabeam.parse_bytes(data: bytes) -> dict` - parse an in-memory buffer.

Every result contains a `file` namespace (size, detected MIME, SHA-256, CRC-32,
entropy). Format-specific namespaces (`jpeg`, `png`, `exif`, `id3`, `mp4`,
`pdf`, `zip`, `elf`, and more) are added when they apply, so a single file can
produce several at once.

## Supported formats

JPEG, PNG, GIF, BMP, WebP/WAV/AVI (RIFF), TIFF/HEIC EXIF, MP3 (ID3),
MP4/MOV/M4A/HEIF, ELF binaries, PDF, gzip, and the ZIP family (docx, xlsx,
pptx, jar, apk, epub). The universal `file` namespace runs on everything.

## Links

- Source, docs, and issues: https://github.com/rgcsekaraa/metabeam
- Also available as a CLI (`cargo install metabeam`) and for Node
  (`npm install metabeam`).

## License

Licensed under either of MIT or Apache-2.0 at your option.
</content>

