File Handlers

As their name implies, File Handlers deal with file operations. They manage reading input files and writing output files, along with dealing with naming and interpreting different file structures.

The BaseFileHandler class

As with engines, File Handlers subclass the BaseFileHandler class found in clypher.src.file_handlers.base_filehandler.py, which provides a simple interface for common operations, such as reading and writing files.

class file_handlers.base_filehandler.BaseFileHandler(files, output_dir=None, force_overwrite=False, recursive=False)

Provides a simple base interface for new file handlers. Resolves all input paths and converts them into absolute paths.

Can also recursively walk a directory, adding all its files to the input.

Is also able to resolve relative input paths such as “ . “ and “../foo”.

Parameters:

  • files (list[Path]) – The list of input paths coming from the CLI.

  • output_dir (Path or None, optional) – The output directory, defaults to the current working dir.

  • force_overwrite (bool, optional) – Force overwriting output files, defaults to True.

  • recursive (bool, optional) – Recursively walk all input directories, adding all files to the input, default to False.

Raises:

  • FileNotFoundError – If any input path, or the output directory, doesn’t exist.

  • ValueError – If the output directory is a file.

file_list

The list of input files. Every entry is an absolute path.

out

Output directory.

force_ow

Force overwriting of output files.

list_files(path, recursive=False)

List all the files in the current directory and return a list of absolute paths. If recursive, recursively walk the directory, listing all files.

Parameters:

  • path (Path) – The path to list all files from.

  • recursive (bool, optional) – If True, recursively walk the directory, adding all files to the input. (default is False)

Returns:

A list of absolute paths.

Return type:

list[Path]

abstract request()

Return the next file to process. Must be implemented by a concrete class.

abstract write()

Given bytes, write them to a file. Must be implemented by a concrete class.

Adding new File Handlers

While it is uncertain whether future versions might continue to work this way, right now, any File Handler that subclassess BaseFileHandler and implements a request() and a write() method will be considered valid.

The only convention is for request() to return bytes, how it achieves this is completely up to you.