, cls=None)[source]

Return a decorator for a reader function.

A decorator factory for reader functions.

A reader function should have at least the following signature: <format_name>_to_<class_name_or_generator>(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 reader must not close the filehandle, cleanup will be handled external to the reader and is not its concern. This is true even in the case of generators.

Any additional **kwargs will be passed to the reader and may be used if necessary.

The reader must return an instance of cls if cls is not None. Otherwise the reader must return a generator. The generator need not deal with closing the fh. That is already handled by this decorator.


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


format : str

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

cls : type, optional

The class which a decorated reader will be bound to. When cls is None the reader will be bound as returning a generator. Default is None.



A decorator to be used on a reader. The decorator will raise a if there already exists a reader bound to the same permutation of fmt and cls.

See also