Using Transdoc programmatically

Transdoc can be used to transform files and text programmatically.

Creating a rule-set

Transdoc represents rule-sets using TransdocTransformer objects.

transdoc.TransdocTransformer

Transdoc transformer, responsible for applying rules to given inputs.

__init__(rules)

Create an instance of a TransdocTransformer, given the given rule-set.

Parameters:

Name	Type	Description	Default
rules	dict[str, TransdocRule]	Dictionary, mapping between rule names, and their corresponding functions.	required

from_file(rule_file) classmethod

Create a TransdocTransformer by loading rules from a Python file.

Items are considered to be rules if they are callable, and if they are contained within the module's __all__ attribute (if one exists).

Parameters:

Name	Type	Description	Default
rule_file	Path	path to Python file to load from.	required

Returns:

Type	Description
TransdocTransformer	Transformer with rules loaded from the given Python file.

from_namespace(namespace) classmethod

Create a TransdocTransformer from attributes on a namespace (module or object).

Attributes are considered to be rules if they are callable, and if they are contained within the namespace's __all__ attribute (if one exists).

Parameters:

Name	Type	Description	Default
namespace	Any	Namespace to collect rules from. This can be a Python module, or any other object.	required

Returns:

Type	Description
TransdocTransformer	Transformer with rules loaded from the given namespace.

transform(input, filename, position_offset=SourcePos(1, 1), indentation='')

Apply the Transdoc rules to the given input, returning the result.

Parameters:

Name	Type	Description	Default
input	str	Input string to transform	required
filename	str	Name of file which the input string belongs to, used in error reporting.	required
position_offset	SourcePos	Source position to use when offsetting source positions in errors.	SourcePos(1, 1)
indentation	str	String to use for indentation (eg ' ' * 4 for 4 spaces, or '\t' for one tab).	''

Returns:

Type	Description
str	Resultant text.

Collecting handlers

Handlers are used to handle various file-types to ensure information is transformed correctly (eg by preventing nested sets from being transformed in Python source code).

You can load all available handlers using transdoc.handlers.get_all_handlers. You can also implement the transdoc.handlers.TransdocHandler protocol to create your own handlers.

transdoc.get_all_handlers()

Returns a list of all handler objects.

This includes Transdoc built-in handlers, as well as any detected plugins.

Returns:

Type	Description
list[TransdocHandler]	Handlers found through package metadata, and default handlers.

Transforming inputs

You can transform text by using the following functions.

transdoc.transform(transformer, input, path='<string>', handler=None)

Transform the given input string using Transdoc.

Parameters:

Name	Type	Description	Default
transformer	TransdocTransformer	Transformer with all desired transformation rules.	required
input	str	Input string to transform.	required
path	str, optional = "<string>"	Name of input string to use when reporting errors.	'<string>'
handler	TransdocHandler	Handler to use for transformation. Defaults to PlaintextHandler() when not provided.	None

Returns:

Type	Description
str	Transformed text.

transdoc.transform_file(handlers, transformer, in_path, in_file, out_file)

Given an input file, its path and an output file, transform the file using the given handlers.

If no handlers are able to handle the file, a TransdocHandlerError is raised. To avoid this, explicitly choose a handler, and use its transform_file method instead.

Parameters:

Name	Type	Description	Default
handlers	Sequence[TransdocHandler]	List of handlers to consider for transforming the file.	required
transformer	TransdocTransformer	Transformer to use.	required
in_path	str	Path of the input file	required
in_file	IO	Input file	required
out_file	IO | None	Output file, if output is desired.	required

Raises:

Type	Description
TransdocHandlerError	No handlers that match input file

transdoc.transform_tree(handlers, transformer, input, output, *, force=False)

Transform all files within a tree.

This takes all files that are descendants of the input file, and transforms them, writing the results into the corresponding location on the output path.

Parameters:

Name	Type	Description	Default
handlers	Sequence[TransdocHandler]	Handlers to consider using when transforming files.	required
transformer	TransdocTransformer	Transformer rules to use.	required
input	Path	Input path to transform. If a directory is given, all its descendants are transformed. If a regular file's path is given, it is transformed.	required
output	Path | None	Destination path. If a directory was given for input, a directory will be created at this path, and populated with the transformed contents of the input directory. If a regular file was given for input, the transformed output is written at that path.	required
force	bool, optional = False	Whether to remove the output if it already exists, rather than erroring. Defaults to False.	False

Raises:

Type	Description
FileExistsError	If output exists as a file or non-empty directory, and the force option was not set.
ExceptionGroup	Any exceptions that occurred while transforming the files.