Metadata-Version: 2.4
Name: magicprobe-core
Version: 0.1.0
Summary: A Python library for detecting file types by magic bytes
Project-URL: Homepage, https://github.com/n7gj/magicprobe
Project-URL: Repository, https://github.com/n7gj/magicprobe
Project-URL: Issues, https://github.com/n7gj/magicprobe/issues
Project-URL: Changelog, https://github.com/n7gj/magicprobe/blob/main/CHANGELOG.md
License: MIT License
        
        Copyright (c) 2026 Nattapong Jaisabai
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: detection,file-type,filetype,magic,mime
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# magicprobe

A zero-dependency Python library that detects file types by inspecting **magic bytes** — the binary signatures at the start of every file.

```python
import magicprobe

result = magicprobe.probe("photo.jpg")
print(result.name)       # JPEG
print(result.mime_type)  # image/jpeg
print(result.extension)  # .jpg
```

## Features

- **Zero dependencies** — pure Python 3.10+
- **Fast** — reads only the first 262 bytes of each file
- **Extensible** — adding a new file type takes ~10 lines; see [CONTRIBUTING.md](CONTRIBUTING.md)
- **Type-safe** — fully typed, ships with `py.typed`
- **CLI included** — `magicprobe <file>` works out of the box

## Installation

```bash
pip install magicprobe
```

## Usage

### Detect a single file type

```python
import magicprobe

# From a file path (str or pathlib.Path)
result = magicprobe.probe("archive.zip")

# From raw bytes
with open("file.bin", "rb") as f:
    result = magicprobe.probe(f.read())

if result:
    print(result.name)        # "ZIP"
    print(result.mime_type)   # "application/zip"
    print(result.extensions)  # (".zip",)
    print(result.extension)   # ".zip"  ← primary extension shortcut
else:
    print("Unknown file type")
```

### Detect all matching types

Some formats are containers (e.g. a DOCX file is also a ZIP file).
`probe_all()` returns every matching type, ordered from most specific to least specific:

```python
results = magicprobe.probe_all("document.docx")
for r in results:
    print(r.name)  # OOXML, then ZIP
```

### Command-line interface

```bash
# One file
magicprobe image.png
# image.png: PNG (image/png)  [.png]

# Multiple files
magicprobe * 
```

## Supported types

| Category   | Types |
|------------|-------|
| Image      | PNG, JPEG, GIF, WEBP, BMP, TIFF, ICO, AVIF, HEIC |
| Document   | PDF, RTF, OLE2 (doc/xls/ppt), OOXML (docx/xlsx/pptx), EPUB |
| Archive    | ZIP, GZIP, BZIP2, XZ, 7-Zip, RAR, TAR, Zstandard, LZ4 |
| Audio      | MP3, WAV, FLAC, OGG, OPUS, M4A, AIFF |
| Video      | MP4, MOV, AVI, WEBM, MKV, FLV, WMV/ASF |
| Executable | ELF, PE (exe/dll), Mach-O, DEX (Android), WASM |

**Want to add a new type?**  
See [CONTRIBUTING.md](CONTRIBUTING.md) — it takes about 10 lines of code and a test.

## API reference

### `magicprobe.probe(source) → ProbeResult | None`

Detect the file type of `source` (file path or `bytes`).  
Returns the **first** matching `ProbeResult`, or `None` if unknown.

### `magicprobe.probe_all(source) → list[ProbeResult]`

Returns **all** matching `ProbeResult` objects (useful for container formats).

### `ProbeResult`

| Attribute    | Type            | Description |
|--------------|-----------------|-------------|
| `name`       | `str`           | Human-readable name, e.g. `"PNG"` |
| `mime_type`  | `str`           | IANA MIME type, e.g. `"image/png"` |
| `extensions` | `tuple[str, …]` | File extensions, e.g. `(".png",)` |
| `extension`  | `str \| None`   | Primary extension (property) |

## Project structure

```
src/magicprobe/
├── __init__.py       ← public API
├── probe.py          ← probe() / probe_all()
├── result.py         ← ProbeResult dataclass
├── registry.py       ← @register decorator & get_all()
├── __main__.py       ← CLI entry point
└── types/
    ├── base.py       ← FileType ABC
    ├── image.py
    ├── document.py
    ├── archive.py
    ├── audio.py
    ├── video.py
    └── executable.py
```

## Contributing

Contributions are welcome!  
Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.

## License

[MIT](LICENSE)
