Metadata-Version: 2.4
Name: magicprobe-core
Version: 0.2.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 Python library that detects file types by delegating to the system
[libmagic](https://www.darwinsys.com/file/) C library via `ctypes`.
No third-party Python packages are required.

```python
import magicprobe

result = magicprobe.probe("photo.jpg")
if result:
    print(result.mime_type)  # image/jpeg
```

## Requirements

- Python 3.10+
- The **libmagic** shared library installed on the system:

```bash
# macOS
brew install libmagic

# Debian / Ubuntu
apt install libmagic1
```

## Installation

```bash
pip install magicprobe
```

## Usage

### Detect the type of a file

```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)       # "application/zip"
    print(result.mime_type)  # "application/zip"
else:
    print("Unknown file type")
```

### Detect all matching types

`probe_all()` returns every MIME type libmagic reports for the source,
ordered from most to least specific:

```python
results = magicprobe.probe_all("document.docx")
for r in results:
    print(r.mime_type)
```

### Command-line interface

```bash
magicprobe image.png
# image.png: image/png (image/png)  [—]

magicprobe file1 file2 file3
```

## API reference

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

Detect the file type of `source`.

- `source` — a file path (`str` or `pathlib.Path`) or raw `bytes` / `bytearray`.
- Returns the first matching `ProbeResult`, or `None` if libmagic cannot identify the type.

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

Same as `probe()` but returns all matching `ProbeResult` objects.
Returns an empty list if the type is unknown.

### `ProbeResult`

| Attribute    | Type              | Description |
|--------------|-------------------|-------------|
| `name`       | `str`             | MIME type string returned by libmagic, e.g. `"image/png"` |
| `mime_type`  | `str`             | IANA MIME type, e.g. `"image/png"` |
| `extensions` | `tuple[str, ...]` | File extensions (empty tuple in the current release) |
| `extension`  | `str \| None`     | Primary extension, or `None` (property) |

## Project structure

```
src/magicprobe/
├── __init__.py      — public API (probe, probe_all, ProbeResult)
├── probe.py         — probe() / probe_all() implementation
├── result.py        — ProbeResult dataclass
├── libmagic_c.py    — ctypes wrapper for the system libmagic library
└── __main__.py      — CLI entry point
```

## Contributing

Contributions are welcome.  
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.

## License

[MIT](LICENSE)
