Transdoc Handlers

Transdoc uses Python's entrypoints specification to discover and use Transdoc handler plugins.

Handler responsibilities

Handler plugins should perform the following functions:

• Inform Transdoc of the file extensions they can handle.
• When given a file, load it and apply transformations using Transdoc's API.

Adding your library as a transdoc handler

In your pyproject.toml, include the following:

[project.entry-points.'transdoc.handlers']
plugin_name = 'plugin_module_name:entrypoint'

Module contents

The entrypoint object should have a number of methods, such that it matches the TransdocHandler protocol.

transdoc.TransdocHandler

A language handler plugin for transdoc.

matches_file(file_path) abstractmethod

Given a file path, return whether this handler is capable of transforming the given file.

Parameters:

Name	Type	Description	Default
file_path	str	The file path of the input.	required

Returns:

Type	Description
bool	Whether the file can be transformed using this transformer.

transform_file(transformer, in_path, in_file, out_file) abstractmethod

Transforms the contents of the file at in_path, writing the transformed output into the file at out_path.

If any errors occur during transformation, they should be collected and raised as an ExceptionGroup[TransdocError].

Parameters:

Name	Type	Description	Default
transformer	TransdocTransformer	Use transformer.apply on any strings where rules should be applied.	required
in_path	str	Path to input file, to be used in error reporting.	required
in_file	IO	File to read input from.	required
out_file	IO | None	The file to write the output to, or None if no output should be produced.	required

Raises:

Type	Description
ExceptionGroup[TransdocError]	errors encountered during transformation.