Plugin Interface

Contract

Plugins are simply an object that implements the appropriate contract, which is a build method that follows the following signature:

build(self, build_info)

Executes the plugin in the current build.

Parameters

build_info (BuildInfo) – The information for the current build.

Types

The following types are passed to plugins during the build.

class pysmith.BuildInfo

Contains information for the current build.

metadata: dict(str, object)

The global metadata for the build.

files: dict(str, FileInfo)

The files uses the file path relative to the source folder as the key and FileInfo objects as the values. Keys can be added or removed by the plugin, and files can be modified. At the end of the processing pipeline, files will be written based on the keys relative to the destination directory.

get_files_by_pattern(match_pattern)

Retrieves files from the files object using the given glob pattern.

Parameters

match_pattern (str) – The pattern to pass to fnmatch.filter().

get_files_by_regex(regex)

Retrieves files from the files object using the given regex.

Parameters

regex (re.Pattern) – The regular expression to use, compiled using re.compile().

rename_file(file_name, new_file_name)

Renames a file in the files object. If the new file name matches the old, no action is taken.

Parameters

• file_name (str) – The existing name of the file.

• new_file_name (str) – The new name for the file.

class pysmith.FileInfo

Contains the data for a file to be processed.

name: str

The file name.

path: str

The full path of the file.

stats: os.stat_result

The stats of the file, as returned by os.stat().

metadata: dict(str, object)

The metadata of the file. This is a generic dictionary that can be modified by plugins.

contents: bytes

The raw binary contents of the file.

Logging

If plugins wish to log message, they should create a logger using logging.getLogger(), passing pysmith.plugin.<plugin_name> as the logger name. enable_logging() configures logging under the pysmith namespace, so plugins should use this name for logging to be configured correctly.

Utils

The following utilities are also available for plugins to use.

pysmith.plugin_util.lambda_or_metadata_selector(selector)

Ensures that the given selector is a function. If a str is provided, it will be converted into a function that queries the file’s metadata for the provided key.

Parameters

selector – The selector.

Returns

func(FileInfo)