puremagic

puremagic is a pure Python implementation of magic-number-based file type detection. It reads the header and footer bytes of a file, string, or stream and matches them against a bundled JSON database of known file signatures, returning the most likely extension or MIME type along with a confidence score. Unlike python-magic, which wraps the system libmagic C library, puremagic ships its signature database as JSON and has zero runtime dependencies, making it trivially installable and fully cross-platform on any system with Python 3.12+.

Starting with version 2.0, puremagic adds an optional deep-scan layer that goes beyond raw byte matching for formats where magic numbers alone are ambiguous or insufficient — distinguishing Office Open XML and OpenDocument formats inside ZIP containers, validating MP3 frames, detecting text encodings and line-ending styles, parsing Python source via ast.parse(), and identifying HDF5-based scientific formats such as AnnData and Loom. Deep scan is on by default and can be disabled with an environment variable for callers who want the original lightweight header/footer matching only.

What You Get

• from_file() / from_string() / from_stream() — return the single best-guess extension or MIME type for a file path, raw bytes, or open stream
• magic_file() / magic_string() / magic_stream() — return every candidate match ranked by confidence, including byte offset and human-readable format name
• A command-line tool (python -m puremagic) that scans one or more files or entire directories and prints detected types or MIME types
• An opt-out deep-scan pipeline with format-specific scanners for ZIP-based Office/OpenDocument formats, MP3 frames, text encodings and line endings, Python source, PDF, JSON, HDF5 scientific formats, and several bioinformatics text formats (VCF, SAM, GFF, PLY, VTK)
• A fully typed public API (py.typed marker, dataclass-style PureMagic/PureMagicWithConfidence namedtuples) with no third-party runtime dependencies at all

Common Use Cases

• Validating uploaded file content server-side instead of trusting the client-supplied extension or MIME type
• Sorting or triaging large batches of files by real content type when filenames are missing, wrong, or untrustworthy
• Running file-type detection inside minimal containers, serverless functions, or locked-down CI environments where installing the native libmagic shared library isn’t an option
• Disambiguating ZIP-based document formats (xlsx/docx/pptx vs. odt/ods/odp, including macro-enabled variants) by inspecting internal ZIP structure
• Scripting bulk file-identification tasks from the command line without writing any Python

Under The Hood

Architecture puremagic is organized as a single flat module, puremagic/main.py, built around a loaded-once signature table: magic_data() reads magic_data.json at import time into sorted headers, footers, extension_only, and multi-part lookup structures represented as PureMagic namedtuples. Identification flows through identify_all(), which slices the head/footer bytes of the input at each candidate signature’s offset and checks for an exact match, then determine_confidence() scores matches by signature length and extension agreement. When deep scan is enabled (the default, toggled by the PUREMAGIC_DEEPSCAN env var), perform_magic() hands ambiguous or unmatched results to run_deep_scan(), which dispatches to per-format scanner modules under puremagic/scanners/ (zip, pdf, text, json, python, hdf5, mpeg_audio, sndhdr, cfbf, ogg, asf, ebml) — each implementing a small main(file_path, header, footer) contract that either confirms/refines a match or returns None. This keeps the core matching loop simple while letting format-specific logic live in isolated, independently testable modules.

Tech Stack The project targets Python 3.12+ exclusively (3.7–3.11 users are pointed to the 1.x release line) and declares zero runtime dependencies — the entire signature database ships as a bundled magic_data.json package-data file rather than a compiled C extension. Packaging uses setuptools with setuptools-scm for version derivation from git tags, pyproject.toml-only configuration (no setup.py), and uv for dependency and task management (uv.lock is checked in). The dev toolchain runs entirely through poethepoet task aliases backed by ruff for linting and formatting, ty for type checking, codespell for spell-checking, and twine/GitHub Actions for PyPI publishing on tagged releases.

Code Quality The test suite (test/test_common_extensions.py and test/test_scanners.py, roughly 1,200 lines combined) exercises both the core header/footer matching against real sample files under test/resources/ (images, audio, video, office, archive, system) and each deep-scan module individually, with pytest-cov measuring coverage via .coveragerc. CI runs the full matrix across Python 3.12–3.14 on Ubuntu, macOS, and Windows using GitHub Actions, giving genuine cross-platform verification rather than a single-OS smoke test. Code carries full type hints, ships a py.typed marker for downstream type checkers, and is enforced by ruff check/ruff format plus a ty check type-checking step wired into pre-commit hooks — a notably rigorous setup for a small utility library.

What Makes It Unique puremagic’s core differentiator is being a genuine drop-in for python-magic/libmagic-based detection with literally zero runtime dependencies, which matters in Docker images, serverless functions, and Windows environments where installing the native libmagic shared library is often the single most annoying dependency in an otherwise pure-Python stack. The version-2.0 deep-scan layer pushes it beyond simple byte-signature matching into genuine content-aware analysis — parsing Python source with ast.parse() to distinguish real code from text that merely resembles it, inspecting ZIP internals to tell Office formats apart from OpenDocument formats, and recognizing niche scientific/bioinformatics formats (AnnData, Loom, Cooler, BIOM v2, VCF, SAM, GFF) that general-purpose file-type tools typically don’t cover at all.