, cls=None)[source]

Return a decorator for a writer function.

A decorator factory for writer functions.

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

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

The writer must not return a value. Instead it should only mutate the fh in a way consistent with it’s purpose.

If the writer accepts a generator, it should exhaust the generator to ensure that the potentially open filehandle backing said generator is closed.


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


format : str

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

cls : type, optional

The class which a decorated writer will be bound to. If cls is None the writer will be bound as expecting a generator. Default is None.



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