0
# filetype
1

2
A small and dependency-free Python package to infer file type and MIME type by checking the magic numbers signature of a file or buffer. The package provides high-performance file type detection for 80+ file formats across multiple categories without requiring external dependencies.
3

4
## Package Information
5

6
- **Package Name**: filetype
7
- **Language**: Python
8
- **Installation**: `pip install filetype`
9

10
## Core Imports
11

12
```python
13
import filetype
14
```
15

16
Common usage patterns:
17

18
```python
19
from filetype import guess, guess_mime, guess_extension
20
```
21

22
For category-specific operations:
23

24
```python
25
from filetype import is_image, is_video, is_audio
26
```
27

28
## Basic Usage
29

30
```python
31
import filetype
32

33
# Basic file type detection from file path
34
kind = filetype.guess('/path/to/file.jpg')
35
if kind is None:
36
    print('Cannot guess file type!')
37
else:
38
    print('File extension: %s' % kind.extension)
39
    print('File MIME type: %s' % kind.mime)
40

41
# Detection from bytes buffer
42
with open('/path/to/file.jpg', 'rb') as f:
43
    header = f.read(261)  # Read first 261 bytes
44
    kind = filetype.guess(header)
45
    print('File type:', kind.extension if kind else 'Unknown')
46

47
# Direct MIME type detection
48
mime = filetype.guess_mime('/path/to/file.pdf')
49
print('MIME type:', mime)  # 'application/pdf'
50

51
# Direct extension detection
52
ext = filetype.guess_extension('/path/to/file.png')
53
print('Extension:', ext)  # 'png'
54
```
55

56
## Architecture
57

58
The filetype package is built around a modular type matcher system:
59

60
- **Type System**: Base `Type` class with specialized implementations for each file format
61
- **Magic Number Detection**: Analyzes first 8192 bytes of files to identify format signatures
62
- **Category Organization**: File types grouped into logical categories (image, video, audio, etc.)
63
- **Extensible Design**: Custom type matchers can be added via the `add_type()` function
64

65
The package supports multiple input types (file paths, bytes, bytearray, file-like objects) and provides both general detection and category-specific matching functions.
66

67
## Constants and Variables
68

69
The package exposes several module-level constants and variables for advanced usage:
70

71
```python { .api }
72
types: List[Type]
73
"""List of all supported type matcher instances. Allows iteration over all file types."""
74

75
__version__: str
76
"""Package version string (e.g., '1.2.0')."""
77

78
version: str  
79
"""Package version string (alias for __version__)."""
80
```
81

82
**Usage Examples:**
83

84
```python
85
import filetype
86

87
# Get package version
88
print(f'filetype version: {filetype.__version__}')
89

90
# Iterate over all supported types
91
for file_type in filetype.types:
92
    print(f'{file_type.extension} -> {file_type.mime}')
93

94
# Filter types by category
95
image_types = [t for t in filetype.types if 'image/' in t.mime]
96
print(f'Supported image formats: {len(image_types)}')
97
```
98

99
## Capabilities
100

101
### Core Detection Functions
102

103
Primary file type detection functionality that analyzes magic number signatures to identify file types and return structured type information.
104

105
```python { .api }
106
def guess(obj):
107
    """
108
    Infers the type of the given input.
109

110
    Args:
111
        obj: path to file, bytes or bytearray.
112

113
    Returns:
114
        The matched type instance. Otherwise None.
115

116
    Raises:
117
        TypeError: if obj is not a supported type.
118
    """
119

120
def guess_mime(obj):
121
    """
122
    Infers the file type and returns its MIME type.
123

124
    Args:
125
        obj: path to file, bytes or bytearray.
126

127
    Returns:
128
        The matched MIME type as string. Otherwise None.
129

130
    Raises:
131
        TypeError: if obj is not a supported type.
132
    """
133

134
def guess_extension(obj):
135
    """
136
    Infers the file type and returns its file extension.
137

138
    Args:
139
        obj: path to file, bytes or bytearray.
140

141
    Returns:
142
        The matched file extension as string. Otherwise None.
143

144
    Raises:
145
        TypeError: if obj is not a supported type.
146
    """
147
```
148

149
[Core Detection](./core-detection.md)
150

151
### Type Management
152

153
Functions for managing and querying the type matcher system, including support for custom type matchers and type lookup by MIME type or extension.
154

155
```python { .api }
156
def get_type(mime=None, ext=None):
157
    """
158
    Returns the file type instance searching by MIME type or file extension.
159

160
    Args:
161
        ext: file extension string. E.g: jpg, png, mp4, mp3
162
        mime: MIME string. E.g: image/jpeg, video/mpeg
163

164
    Returns:
165
        The matched file type instance. Otherwise None.
166
    """
167

168
def add_type(instance):
169
    """
170
    Adds a new type matcher instance to the supported types.
171

172
    Args:
173
        instance: Type inherited instance.
174

175
    Returns:
176
        None
177

178
    Raises:
179
        TypeError: if instance doesn't inherit from filetype.types.Type
180
    """
181
```
182

183
[Type Management](./type-management.md)
184

185
### Category Detection Functions
186

187
High-level functions for checking if a file belongs to specific categories like images, videos, or documents, providing quick boolean results for common use cases. Also includes utility functions for checking extension and MIME type support.
188

189
```python { .api }
190
def is_extension_supported(ext):
191
    """
192
    Checks if the given extension string is supported by the file matchers.
193

194
    Args:
195
        ext (str): file extension string. E.g: jpg, png, mp4, mp3
196

197
    Returns:
198
        True if the file extension is supported. Otherwise False.
199
    """
200

201
def is_mime_supported(mime):
202
    """
203
    Checks if the given MIME type string is supported by the file matchers.
204

205
    Args:
206
        mime (str): MIME string. E.g: image/jpeg, video/mpeg
207

208
    Returns:
209
        True if the MIME type is supported. Otherwise False.
210
    """
211

212
def is_image(obj):
213
    """
214
    Checks if a given input is a supported type image.
215

216
    Args:
217
        obj: path to file, bytes or bytearray.
218

219
    Returns:
220
        True if obj is a valid image. Otherwise False.
221

222
    Raises:
223
        TypeError: if obj is not a supported type.
224
    """
225

226
def is_video(obj):
227
    """
228
    Checks if a given input is a supported type video.
229

230
    Args:
231
        obj: path to file, bytes or bytearray.
232

233
    Returns:
234
        True if obj is a valid video. Otherwise False.
235

236
    Raises:
237
        TypeError: if obj is not a supported type.
238
    """
239

240
def is_audio(obj):
241
    """
242
    Checks if a given input is a supported type audio.
243

244
    Args:
245
        obj: path to file, bytes or bytearray.
246

247
    Returns:
248
        True if obj is a valid audio. Otherwise False.
249

250
    Raises:
251
        TypeError: if obj is not a supported type.
252
    """
253
```
254

255
[Category Detection](./category-detection.md)
256

257
### Category-Specific Matching
258

259
Advanced matching functions that search within specific file type categories, providing more targeted detection when you know the expected file category.
260

261
```python { .api }
262
def image_match(obj):
263
    """
264
    Matches the given input against the available image type matchers.
265

266
    Args:
267
        obj: path to file, bytes or bytearray.
268

269
    Returns:
270
        Type instance if matches. Otherwise None.
271

272
    Raises:
273
        TypeError: if obj is not a supported type.
274
    """
275

276
def video_match(obj):
277
    """
278
    Matches the given input against the available video type matchers.
279

280
    Args:
281
        obj: path to file, bytes or bytearray.
282

283
    Returns:
284
        Type instance if matches. Otherwise None.
285

286
    Raises:
287
        TypeError: if obj is not a supported type.
288
    """
289

290
def audio_match(obj):
291
    """
292
    Matches the given input against the available audio type matchers.
293

294
    Args:
295
        obj: path to file, bytes or bytearray.
296

297
    Returns:
298
        Type instance if matches. Otherwise None.
299

300
    Raises:
301
        TypeError: if obj is not a supported type.
302
    """
303
```
304

305
[Category Matching](./category-matching.md)
306

307
## Supported File Types
308

309
The package supports 80+ file formats across 7 categories:
310

311
- **Images (17 types)**: JPG, PNG, GIF, WebP, TIFF, BMP, PSD, ICO, HEIC, AVIF, CR2, JXR, DCM, DWG, XCF, JPX, APNG
312
- **Videos (10 types)**: MP4, MKV, AVI, MOV, WebM, FLV, MPEG, WMV, M4V, 3GP
313
- **Audio (9 types)**: MP3, WAV, OGG, FLAC, AAC, MIDI, M4A, AMR, AIFF
314
- **Fonts (4 types)**: WOFF, WOFF2, TTF, OTF
315
- **Documents (9 types)**: DOC, DOCX, PDF, XLS, XLSX, PPT, PPTX, ODT, ODS, ODP
316
- **Archives (36 types)**: ZIP, TAR, RAR, 7Z, GZ, BZ2, XZ, DEB, RPM, CAB, EXE, SWF, RTF, PS, SQLITE, AR, Z, LZOP, LZ, ELF, LZ4, ZSTD, BR, DCM, EPUB, NES, CRX, EOT, and others
317
- **Applications (1 type)**: WASM
318

319
## CLI Usage
320

321
The package includes a command-line interface for file type detection:
322

323
```bash
324
# Install provides the 'filetype' command
325
pip install filetype
326

327
# Check file types
328
filetype -f file1.jpg file2.png file3.pdf
329

330
# Show version
331
filetype --version
332
```