Converter

Document Processing Orchestrator Converter Package.

Modules:

Name	Description
BaseConverter	Abstract base class for document converters.
UnoserverConverter	File converter using unoserver and a caller-chosen output extension.
UnoserverDocToDocxConverter	DOC to DOCX converter using unoserver. Will be removed in the next minor version.
UnoserverHostLocation	How UnoClient transfers files to unoserver.
ConversionError	Exception raised when document conversion fails.

BaseConverter

Bases: ABC

Base class for document converters.

convert(source, output, **kwargs) abstractmethod

Convert a source document and write the result into the output directory.

Parameters:

Name	Type	Description	Default
source	str	The input source to convert. Typically a file path.	required
output	str	The output directory where the converted file will be saved.	required
**kwargs	Any	Additional keyword arguments for customization.	{}

Returns:

Name	Type	Description
str	str	The path to the converted output file.

Raises:

Type	Description
ConversionError	If conversion fails or the output is missing.

ConversionError(message)

Bases: Exception

Exception raised when a document conversion fails.

Initialize the ConversionError class.

Parameters:

Name	Type	Description	Default
message	str	The message to display when the exception is raised.	required

UnoserverConverter(host, port, convert_to, host_location=UnoserverHostLocation.REMOTE)

Bases: BaseConverter

Converts a file with a networked unoserver instance to convert_to.

The source suffix is not checked. LibreOffice selects the import filter from the file bytes. Conversion timeout is owned by unoserver (--conversion-timeout). UnoClient.convert() is a blocking XML-RPC call and cannot cancel LibreOffice work.

Attributes:

Name	Type	Description
host	str	Hostname of the unoserver XML-RPC endpoint.
port	int	Port of the unoserver XML-RPC endpoint.
convert_to	str	Output extension LibreOffice exports, without a dot.
host_location	UnoserverHostLocation	How files are transferred to unoserver.

Initialize the UnoserverConverter.

Parameters:

Name	Type	Description	Default
host	str	Hostname of the unoserver.	required
port	int	Port of the unoserver XML-RPC endpoint.	required
convert_to	str	Output extension LibreOffice exports, without a dot (for example docx or xlsx).	required
host_location	UnoserverHostLocation | str	How files are transferred to unoserver (auto, remote, or local). Defaults to UnoserverHostLocation.REMOTE.	REMOTE

Raises:

Type	Description
ImportError	If the unoserver extra is not installed.
ValueError	If host_location is not a valid UnoserverHostLocation.

convert(source, output, **kwargs)

Convert a file via unoserver to the extension given at construction.

The source suffix is not checked. LibreOffice selects the import filter from the file bytes. Writes a unique temporary file in output, then replaces {stem}.{convert_to} only after that temporary file exists and is non-empty. An existing final file is left unchanged when conversion fails.

UnoClient.convert() is a blocking XML-RPC call. This method cannot cancel LibreOffice work. Conversion timeout is owned by unoserver (--conversion-timeout), not this client.

Parameters:

Name	Type	Description	Default
source	str	Path to the input file.	required
output	str	The output directory where the converted file will be saved.	required
**kwargs	Any	Unused; accepted for interface compatibility.	{}

Returns:

Name	Type	Description
str	str	Path to the converted file, {output}/{source_stem}.{convert_to}.

Raises:

Type	Description
ConversionError	If the source is missing, conversion fails, or the output file is missing or empty.

UnoserverDocToDocxConverter(host, port, host_location=UnoserverHostLocation.REMOTE)

Bases: UnoserverConverter

Converts DOC files to DOCX using a networked unoserver instance.

TODO(deprecated): Remove in the next minor version. Replaced by UnoserverConverter with convert_to="docx".

Conversion timeout is owned by unoserver (--conversion-timeout). UnoClient.convert() is a blocking XML-RPC call and cannot cancel LibreOffice work.

Attributes:

Name	Type	Description
host	str	Hostname of the unoserver XML-RPC endpoint.
port	int	Port of the unoserver XML-RPC endpoint.
convert_to	str	Output extension. Always docx.
host_location	UnoserverHostLocation	How files are transferred to unoserver.

Initialize the UnoserverDocToDocxConverter.

Parameters:

Name	Type	Description	Default
host	str	Hostname of the unoserver.	required
port	int	Port of the unoserver XML-RPC endpoint.	required
host_location	UnoserverHostLocation | str	How files are transferred to unoserver (auto, remote, or local). Defaults to UnoserverHostLocation.REMOTE.	REMOTE

Raises:

Type	Description
ImportError	If the unoserver extra is not installed.
ValueError	If host_location is not a valid UnoserverHostLocation.

UnoserverHostLocation

Bases: StrEnum

How UnoClient transfers files to unoserver.

AUTO infers local vs remote from the hostname (127.0.0.1 / localhost use paths). REMOTE sends file bytes over XML-RPC and does not need a shared filesystem. LOCAL passes filesystem paths; the worker and unoserver must share a mount.