0
# Type Management
1

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

4
## Capabilities
5

6
### Type Lookup
7

8
Function to find type instances by searching for specific MIME types or file extensions.
9

10
```python { .api }
11
def get_type(mime=None, ext=None):
12
    """
13
    Returns the file type instance searching by MIME type or file extension.
14

15
    Args:
16
        ext: file extension string. E.g: jpg, png, mp4, mp3
17
        mime: MIME string. E.g: image/jpeg, video/mpeg
18

19
    Returns:
20
        The matched file type instance. Otherwise None.
21
    """
22
```
23

24
**Usage Examples:**
25

26
```python
27
import filetype
28

29
# Find type by extension
30
jpeg_type = filetype.get_type(ext='jpg')
31
if jpeg_type:
32
    print(f'MIME: {jpeg_type.mime}')  # 'image/jpeg'
33

34
# Find type by MIME
35
pdf_type = filetype.get_type(mime='application/pdf')
36
if pdf_type:
37
    print(f'Extension: {pdf_type.extension}')  # 'pdf'
38

39
# Type not found
40
unknown = filetype.get_type(ext='unknown')
41
print(unknown)  # None
42

43
# Use for validation
44
def is_supported_extension(ext):
45
    return filetype.get_type(ext=ext) is not None
46

47
print(is_supported_extension('png'))  # True
48
print(is_supported_extension('xyz'))  # False
49
```
50

51
### Custom Type Registration
52

53
Function to add custom type matchers to extend the package's detection capabilities.
54

55
```python { .api }
56
def add_type(instance):
57
    """
58
    Adds a new type matcher instance to the supported types.
59

60
    Args:
61
        instance: Type inherited instance.
62

63
    Returns:
64
        None
65

66
    Raises:
67
        TypeError: if instance doesn't inherit from filetype.types.Type
68
    """
69
```
70

71
**Usage Examples:**
72

73
```python
74
import filetype
75
from filetype.types.base import Type
76

77
# Define a custom type matcher
78
class CustomType(Type):
79
    """Custom file type matcher."""
80
    
81
    def __init__(self):
82
        super(CustomType, self).__init__(
83
            mime='application/x-custom',
84
            extension='custom'
85
        )
86
    
87
    def match(self, buf):
88
        """Check if buffer matches custom format."""
89
        return (len(buf) >= 4 and 
90
                buf[0:4] == b'CUST')
91

92
# Register the custom type
93
custom_matcher = CustomType()
94
filetype.add_type(custom_matcher)
95

96
# Now the custom type can be detected
97
test_data = b'CUST\x00\x01\x02\x03'
98
kind = filetype.guess(test_data)
99
if kind:
100
    print(f'Extension: {kind.extension}')  # 'custom'
101
    print(f'MIME: {kind.mime}')          # 'application/x-custom'
102

103
# Custom types are added to the beginning of the search list
104
# They take precedence over built-in types
105
```
106

107
### Type Collection Access
108

109
Access to the complete list of supported type matcher instances.
110

111
```python { .api }
112
types: list
113
```
114

115
**Usage Examples:**
116

117
```python
118
import filetype
119

120
# Access all supported types
121
all_types = filetype.types
122
print(f'Total supported types: {len(all_types)}')
123

124
# List all image types
125
image_types = [t for t in filetype.types if 'image/' in t.mime]
126
print('Supported image formats:')
127
for img_type in image_types:
128
    print(f'  .{img_type.extension} ({img_type.mime})')
129

130
# List all supported extensions
131
extensions = [t.extension for t in filetype.types]
132
print('All supported extensions:', sorted(set(extensions)))
133

134
# Find types by category
135
def get_types_by_category(category):
136
    """Get all types matching a MIME category."""
137
    return [t for t in filetype.types if t.mime.startswith(f'{category}/')]
138

139
video_types = get_types_by_category('video')
140
audio_types = get_types_by_category('audio')
141
```
142

143
## Type System Architecture
144

145
### Base Type Class
146

147
All type matchers inherit from the base Type class:
148

149
```python { .api }
150
class Type:
151
    """
152
    Represents the file type object inherited by specific file type matchers.
153
    Provides convenient accessor and helper methods.
154
    """
155
    
156
    def __init__(self, mime: str, extension: str):
157
        """
158
        Initialize type with MIME type and extension.
159
        
160
        Args:
161
            mime (str): MIME type string (e.g., 'image/jpeg')
162
            extension (str): File extension string (e.g., 'jpg')
163
        """
164
    
165
    @property
166
    def mime(self) -> str:
167
        """
168
        Get MIME type string.
169
        
170
        Returns:
171
            MIME type string (e.g., 'image/jpeg', 'video/mp4')
172
        """
173
    
174
    @property  
175
    def extension(self) -> str:
176
        """
177
        Get file extension string.
178
        
179
        Returns:
180
            File extension without dot (e.g., 'jpg', 'png', 'mp4')
181
        """
182
    
183
    def is_extension(self, extension: str) -> bool:
184
        """
185
        Check if this type matches the given extension.
186
        
187
        Args:
188
            extension (str): Extension to check
189
            
190
        Returns:
191
            True if extension matches this type's extension
192
        """
193
    
194
    def is_mime(self, mime: str) -> bool:
195
        """
196
        Check if this type matches the given MIME type.
197
        
198
        Args:
199
            mime (str): MIME type to check
200
            
201
        Returns:
202
            True if MIME type matches this type's MIME type
203
        """
204
    
205
    def match(self, buf: bytearray) -> bool:
206
        """
207
        Check if buffer matches this file type.
208
        Must be implemented by subclasses.
209
        
210
        Args:
211
            buf (bytearray): File header bytes (first 8192 bytes)
212
            
213
        Returns:
214
            True if bytes match this file type, False otherwise
215
            
216
        Raises:
217
            NotImplementedError: If not implemented by subclass
218
        """
219
```
220

221
### Creating Custom Type Matchers
222

223
To create custom type matchers, inherit from the base Type class:
224

225
```python
226
from filetype.types.base import Type
227

228
class MyCustomType(Type):
229
    """Example custom type implementation."""
230
    
231
    MIME = 'application/x-mycustom'
232
    EXTENSION = 'mcf'
233
    
234
    def __init__(self):
235
        super(MyCustomType, self).__init__(
236
            mime=self.MIME,
237
            extension=self.EXTENSION
238
        )
239
    
240
    def match(self, buf):
241
        """
242
        Implement magic number detection logic.
243
        
244
        Args:
245
            buf: bytearray containing first 8192 bytes of file
246
            
247
        Returns:
248
            bool: True if buffer matches this file type
249
        """
250
        # Example: check for specific magic bytes
251
        return (len(buf) >= 8 and
252
                buf[0:4] == b'MCST' and  # Magic signature
253
                buf[4:8] == b'\x01\x00\x00\x00')  # Version
254
```
255

256
### Type Registration Best Practices
257

258
```python
259
# Register custom types early in your application
260
def register_custom_types():
261
    """Register all custom type matchers."""
262
    
263
    # Custom types are checked first (LIFO order)
264
    filetype.add_type(MyCustomType())
265
    filetype.add_type(AnotherCustomType())
266

267
# Call during application initialization
268
register_custom_types()
269

270
# Verify registration
271
custom_type = filetype.get_type(ext='mcf')
272
if custom_type:
273
    print('Custom type registered successfully')
274
```
275

276
## Support Checking
277

278
Utility functions to check if specific MIME types or extensions are supported:
279

280
```python { .api }
281
def is_extension_supported(ext: str) -> bool:
282
    """
283
    Checks if the given extension string is one of the supported by the file matchers.
284

285
    Args:
286
        ext: file extension string. E.g: jpg, png, mp4, mp3
287

288
    Returns:
289
        True if the file extension is supported. Otherwise False.
290
    """
291

292
def is_mime_supported(mime: str) -> bool:
293
    """
294
    Checks if the given MIME type string is one of the supported by the file matchers.
295

296
    Args:
297
        mime: MIME string. E.g: image/jpeg, video/mpeg
298

299
    Returns:
300
        True if the MIME type is supported. Otherwise False.
301
    """
302
```
303

304
**Usage Examples:**
305

306
```python
307
import filetype
308

309
# Check extension support
310
if filetype.is_extension_supported('pdf'):
311
    print('PDF files are supported')
312

313
# Check MIME support  
314
if filetype.is_mime_supported('image/webp'):
315
    print('WebP images are supported')
316

317
# Use for input validation
318
def validate_file_type(filename):
319
    """Validate if file type is supported."""
320
    ext = filename.split('.')[-1].lower()
321
    if filetype.is_extension_supported(ext):
322
        return True
323
    else:
324
        print(f'Unsupported file type: .{ext}')
325
        return False
326

327
# Batch validation
328
supported_files = []
329
for filename in ['doc.pdf', 'image.jpg', 'data.xyz']:
330
    if validate_file_type(filename):
331
        supported_files.append(filename)
332
```