Return a decorator for a sniffer function.

A decorator factory for sniffer functions. Sniffers may only be registered to simple formats. Sniffers for compound formats are automatically generated from their component simple formats.

A sniffer function should have at least the following signature: <format_name>_sniffer(fh). fh is always an open filehandle. This decorator provides the ability to use filepaths in the same argument position as fh. They will automatically be opened and closed.

The sniffer must not close the filehandle, cleanup will be handled external to the sniffer and is not its concern.

**kwargs are not passed to a sniffer, and a sniffer must not use them.

The job of a sniffer is to determine if a file appears to be in the given format and to ‘sniff’ out any kwargs that would be of use to a reader function.

The sniffer must return a tuple of (True, <kwargs dict>) if it believes fh is a given format. Otherwise it should return (False, {}).


Failure to adhere to the above interface specified for a sniffer will result in unintended side-effects.

The sniffer may determine membership of a file in as many or as few lines of the file as it deems necessary.


format : str

A format name which a decorated sniffer will be bound to.



A decorator to be used on a sniffer. The decorator will raise a if there already exists a sniffer bound to the format.

See also