filetype.py

filetype.py is a small, dependency-free Python package that infers a file’s type and MIME type by inspecting the magic number signature at the start of a file or buffer. Unlike libmagic bindings, it is pure Python with no C extensions, making it trivial to install and portable across platforms.

It only needs the first 261 bytes of a file to make a determination, so you can pass a path, bytes, bytearray, or file-like object and get back the extension and MIME type without reading the whole file. It supports a wide range of image, video, audio, archive, document, and font formats, and lets you register custom matchers for formats it does not know about.

What You Get

• A single guess() entry point that accepts a path, bytes, bytearray, or file-like object and returns the matched type with its extension and MIME string
• Built-in matchers for a wide range of image, video, audio, archive, document, and font formats
• Category-specific helpers (image_match, video_match, is_image, is_mime_supported, etc.) for targeted checks
• A pluggable matcher system to register custom file-type detectors
• A command-line entry point (filetype <file>) for quick type inference from the shell

Common Use Cases

• Validating uploaded files by their real content instead of a user-supplied extension
• Routing or filtering files in a pipeline based on detected MIME type
• Inferring the correct extension for files that arrive without one

Under The Hood

Architecture - The package centers on a registry of Type subclasses (filetype/types/) grouped by category (image, video, audio, archive, document, font, application). Each Type defines a MIME string, an extension, and a match(buf) method that tests header bytes. The top-level guess() in filetype/filetype.py delegates to match() in match.py, which reads the header via get_bytes() in utils.py and iterates the TYPES list calling each matcher until one returns true. Helpers in helpers.py provide category-scoped and boolean convenience checks over the same registry.

Tech Stack - Pure Python with zero runtime dependencies and no C extensions or libmagic bindings. Packaging is via setuptools (setup.py) with a console_scripts entry point exposing a filetype CLI through main.py. It targets Python 3.5+ and is tested across versions with tox; development tooling includes pytest and coverage.

Code Quality - The codebase is small, consistent, and well-documented with docstrings on public functions. A full test suite lives in tests/ (test_filetype.py, test_match.py, test_types.py, test_helpers.py, test_utils.py, test_benchmark.py) with binary fixtures, covering matchers, helpers, and edge cases. get_bytes() raises TypeError on unsupported input, giving explicit error handling at the API boundary.

API Design - The public surface is deliberately minimal and ergonomic: guess(), guess_mime(), and guess_extension() each accept a path, bytes, bytearray, or file-like object, so getting started takes a single import and one call. Category helpers and a pluggable add_type() mechanism keep the common path simple while leaving room for extension, and the returned Type object exposes clean .mime/.extension properties.