mime

import mime

This module provides functions that allow easy mime type detection from files. It offers support for detecting file type based on name or file headers and it is completely extensible so that you can add declarations for your own custom file types.

See defined functions for example.

The mime API

Every public name in mime, wherever it is declared. Each links to the page that documents it.

Functions

detect_from_name()

mime.detect_from_name(name: string) -> string

Detects the mimetype of a file based on the extension defined in it’s path.

When name has more than one dot-separated suffix (archive. tar.gz), the longest registered extension wins: .tar.gz if it’s registered, falling back to .gz otherwise: rather than whichever single-suffix entry happens to match first.

Example,

import mime
echo mime.detect_from_name('myimage.png')

Parameters

• name (string)

Returns string

Note: Unrecognized extensions (including a name with no extension at all) return 'application/octet-stream' rather than raising.

detect_from_header()

mime.detect_from_header(file: file) -> string

Detects the mimetype of a file based on it’s file header.

When multiple file formats share very similar or shadowing file headers (such as the relationship between Zip files and Docx files), this method will perform an extension before returning it’s result.

Example,

import mime
var f = file('my_file.ext', 'rb')
echo mime.detect_from_header(f)

Parameters

• file (file)

Returns string

Note: For dealing with files without extension, or where the accuracy of the file extension cannot be trusted, this method provides a more efficient lookup.

Note: This method may produce slightly more rigorous results

Note: This method requires that the file must be opened in binary mode.

detect()

mime.detect(file: file) -> string

Performs mimetype detection on a file.

this method is capable of detecting file mimetypes even in the absence of an extension.

If the file is opened in binary mode, it first attempt the more accurate header check. If the header check returns a generic result (i.e. application/octet-stream), it performs an extension lookup.

Example,

import mime
var f = file('myfile', 'rb')

# using 'rb' here for two reasons: 
# 1. Our file has no extension, so extension based detection is impossible
# 2. We want more accuracy by having Mime check file headers

echo mime.detect(f)

Parameters

• file (file)

Returns string

Note: this method gives the best result, but slightly slower than a direct lookup of name or header.

extend()

mime.extend(extension: string, format: instance, overwrite: ?bool) -> bool

Extends the mime module with support for files with the given extension as defined in the given format.

Example,

%> import mime
%> mime.detect_from_name('myfile.ppk')
'application/octet-stream'
%> mime.extend('.ppk', mime.MimeFormat('file/ppk'))
true
%> mime.detect_from_name('myfile.ppk')
'file/ppk'

Parameters

• extension (string)
• format (MimeFormat)
• overwrite (?bool) — Default false. When an entry for extension already exists (including one of this module’s own built-in mappings) and overwrite is false, the existing entry is left untouched and this returns false; pass true to replace it.

Returns bool

Note: the extension MUST start with .

mime_to_extension()

mime.mime_to_extension(mimetype: string)

Looks up the typical file extension (including the leading .) registered for a given mime type: the reverse of detect_from_name().

Example,

%> import mime
%> mime.mime_to_extension('image/png')
'.png'

Parameters

• mimetype (string)

Returns — ?string: nil if no extension is registered for mimetype.

Note: Several extensions can share one mime type (.jpg/.jpeg, .htm/.html); whichever is registered first (in this module’s own declaration order for a built-in type, or whichever extend() call added it for a custom one) is returned.

Classes

MimeFormat

class mime.MimeFormat

Mime format representation class.

Constructor

mime.MimeFormat(mimetype: string, header: ?list)

Parameters

• mimetype (string)
• header (?list) — A list of one or more candidate magic-byte signatures, each itself a list of numbers (0-255) or nil for a byte position to skip (a size field embedded in the middle of a signature, say: see the .webp entry in this module’s own table for an example). nil when name-only detection is all that’s available for this format.

Note: only the first 16 bytes of a file’s header will ever be used; a signature longer than that can never match.

O2021, Richard Ore