skbio.io.registry.Format.sniffer

Format.sniffer(override=False)

Decorate a function to act as the sniffer for this format.

The function should take one argument which will be an implementation of either io.TextIOBase or io.BufferedReader depending on if the format is text or binary, respectively.

The sniffer will always receive a filehandle which is pointing to the beginning of the file. It must return a tuple of bool and a dict of suggested keyword arguments (if any) to pass to the reader.

Note

Keyword arguments are not permitted in sniffers. Sniffers may not raise exceptions; if an exception is thrown by a sniffer, the user will be asked to report it on our issue tracker.

Parameters:

overridebool, optional

If True, the existing sniffer will be overriden.

Raises:

DuplicateRegistrationError

When override is False and a sniffer is already registered for this format.

Examples

>>> from skbio.io.registry import Format
>>> # If developing a new format for skbio, use the create_format()
>>> # factory instead of this constructor.
>>> myformat = Format('myformat')
>>> @myformat.sniffer()
... def myformat_sniffer(fh):
...     check = fh.read(8) == "myformat"
...     if check:
...         version = int(fh.read(1))
...         return True, {'version': version}
...     return False, {}
...
>>> myformat_sniffer(["myformat2\n", "some content\n"])
(True, {'version': 2})
>>> myformat_sniffer(["something else\n"])
(False, {})