API Routes¶

Chromium¶

`gotenberg_client._chromium.routes.SyncUrlToPdfRoute` ¶

Synchronous route for converting URLs to PDFs using Chromium.

Implements the synchronous API for converting web pages at specified URLs to PDF documents.

See https://gotenberg.dev/docs/routes#url-into-pdf-route

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`background_graphics() -> Self` ¶

Enables printing of the page background. Equivalent to print_background(print_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`footer(footer: Path) -> Self` ¶

Adds a footer HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`footer`	`Path`	A Path object representing the path to the footer HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`generate_document_outline(*, generate_document_outline: bool) -> Self` ¶

Sets the 'generateDocumentOutline' property.

Parameters:

Name	Type	Description	Default
`generate_document_outline`	`bool`	Whether to generate a document outline	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`header(header: Path) -> Self` ¶

Adds a header HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`header`	`Path`	A Path object representing the path to the header HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`margins(margins: PageMarginsType) -> Self` ¶

Sets the specified page margins.

Parameters:

Name	Type	Description	Default
`margins`	`PageMarginsType`	A `PageMarginsType` class representing the desired page margins.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`no_background_graphics() -> Self` ¶

Disables printing of the page background. Equivalent to print_background(print_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`orient(orient: PageOrientation) -> Self` ¶

Sets the page orientation to either Portrait or Landscape.

Parameters:

Name	Type	Description	Default
`orient`	`PageOrientation`	The desired PageOrientation (PageOrientation.Portrait or PageOrientation.Landscape).	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`page_ranges(ranges: str) -> Self` ¶

Sets the native page range string. Allows for specifying some range or just a few pages.

Parameters:

Name	Type	Description	Default
`ranges`	`str`	The native page range string. This string follows the format expected by the PDF engine. Examples include "1-5", "1,3,5", or "2-4,7". Consult the documentation for the exact expected format.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`prefer_css_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'true'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`prefer_set_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'false'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`print_background(*, print_background: bool) -> Self` ¶

Enables or disables printing the page background.

Parameters:

Name	Type	Description	Default
`print_background`	`bool`	True to print the background, False to not print it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`scale(scale: Union[float, int]) -> Self` ¶

Sets the scale factor for the generated PDF.

Parameters:

Name	Type	Description	Default
`scale`	`Union[float, int]`	The scale factor. A float or integer representing the desired scale. For example, a scale of 2.0 will double the size, while a scale of 0.5 will halve the size.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`single_page(*, use_single_page: bool) -> Self` ¶

Sets the 'singlePage' property to True or False.

Parameters:

Name	Type	Description	Default
`use_single_page`	`bool`	Boolean value indicating whether to render the PDF as a single page. True means treat the document as a single page; False means render it as a multi-page document.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the route, allowing for method chaining.

`size(size: PageSize) -> Self` ¶

Sets the 'pageSize' property to a specified page size.

Parameters:

Name	Type	Description	Default
`size`	`PageSize`	A `PageSize` class representing the desired page size with height, width and units	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

Configures the splitting operation for the route options.

Parameters:

Name	Type	Description	Default
`mode`	`Literal['intervals', 'pages']`	The type of splitting operation. - `intervals`: Split into intervals - `pages`: Split into pages	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_span(span: str) -> Self` ¶

Configures the splitting span for the route options.

Parameters:

Name	Type	Description	Default
`span`	`str`	The splitting span. - Example: "1-3"	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_unify(*, split_unify: bool) -> Self` ¶

Enables or disables splitting for the route options.

Parameters:

Name	Type	Description	Default
`split_unify`	`bool`	Whether to enable or disable splitting. - `True`: Enable splitting - `False`: Disable splitting	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`url(url: str) -> Self` ¶

Sets the URL to convert to PDF.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL of the web page to convert.	required

Returns:

Name	Type	Description
`UrlRoute`	`Self`	This object itself for method chaining.

`gotenberg_client._chromium.routes.AsyncUrlToPdfRoute` ¶

Asynchronous route for converting URLs to PDFs using Chromium.

Implements the asynchronous API for converting web pages at specified URLs to PDF documents.

See https://gotenberg.dev/docs/routes#url-into-pdf-route

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`background_graphics() -> Self` ¶

Enables printing of the page background. Equivalent to print_background(print_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`footer(footer: Path) -> Self` ¶

Adds a footer HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`footer`	`Path`	A Path object representing the path to the footer HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`generate_document_outline(*, generate_document_outline: bool) -> Self` ¶

Sets the 'generateDocumentOutline' property.

Parameters:

Name	Type	Description	Default
`generate_document_outline`	`bool`	Whether to generate a document outline	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`header(header: Path) -> Self` ¶

Adds a header HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`header`	`Path`	A Path object representing the path to the header HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`margins(margins: PageMarginsType) -> Self` ¶

Sets the specified page margins.

Parameters:

Name	Type	Description	Default
`margins`	`PageMarginsType`	A `PageMarginsType` class representing the desired page margins.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`no_background_graphics() -> Self` ¶

Disables printing of the page background. Equivalent to print_background(print_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`orient(orient: PageOrientation) -> Self` ¶

Sets the page orientation to either Portrait or Landscape.

Parameters:

Name	Type	Description	Default
`orient`	`PageOrientation`	The desired PageOrientation (PageOrientation.Portrait or PageOrientation.Landscape).	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`page_ranges(ranges: str) -> Self` ¶

Sets the native page range string. Allows for specifying some range or just a few pages.

Parameters:

Name	Type	Description	Default
`ranges`	`str`	The native page range string. This string follows the format expected by the PDF engine. Examples include "1-5", "1,3,5", or "2-4,7". Consult the documentation for the exact expected format.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`prefer_css_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'true'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`prefer_set_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'false'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`print_background(*, print_background: bool) -> Self` ¶

Enables or disables printing the page background.

Parameters:

Name	Type	Description	Default
`print_background`	`bool`	True to print the background, False to not print it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`scale(scale: Union[float, int]) -> Self` ¶

Sets the scale factor for the generated PDF.

Parameters:

Name	Type	Description	Default
`scale`	`Union[float, int]`	The scale factor. A float or integer representing the desired scale. For example, a scale of 2.0 will double the size, while a scale of 0.5 will halve the size.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`single_page(*, use_single_page: bool) -> Self` ¶

Sets the 'singlePage' property to True or False.

Parameters:

Name	Type	Description	Default
`use_single_page`	`bool`	Boolean value indicating whether to render the PDF as a single page. True means treat the document as a single page; False means render it as a multi-page document.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the route, allowing for method chaining.

`size(size: PageSize) -> Self` ¶

Sets the 'pageSize' property to a specified page size.

Parameters:

Name	Type	Description	Default
`size`	`PageSize`	A `PageSize` class representing the desired page size with height, width and units	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

Configures the splitting operation for the route options.

Parameters:

Name	Type	Description	Default
`mode`	`Literal['intervals', 'pages']`	The type of splitting operation. - `intervals`: Split into intervals - `pages`: Split into pages	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_span(span: str) -> Self` ¶

Configures the splitting span for the route options.

Parameters:

Name	Type	Description	Default
`span`	`str`	The splitting span. - Example: "1-3"	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_unify(*, split_unify: bool) -> Self` ¶

Enables or disables splitting for the route options.

Parameters:

Name	Type	Description	Default
`split_unify`	`bool`	Whether to enable or disable splitting. - `True`: Enable splitting - `False`: Disable splitting	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`url(url: str) -> Self` ¶

Sets the URL to convert to PDF.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL of the web page to convert.	required

Returns:

Name	Type	Description
`UrlRoute`	`Self`	This object itself for method chaining.

`gotenberg_client._chromium.routes.SyncHtmlToPdfRoute` ¶

Synchronous route for converting HTML files to PDFs using Chromium.

Implements the synchronous API for converting HTML files with associated resources to PDF documents.

See https://gotenberg.dev/docs/routes#html-file-into-pdf-route

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`background_graphics() -> Self` ¶

Enables printing of the page background. Equivalent to print_background(print_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`footer(footer: Path) -> Self` ¶

Adds a footer HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`footer`	`Path`	A Path object representing the path to the footer HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`generate_document_outline(*, generate_document_outline: bool) -> Self` ¶

Sets the 'generateDocumentOutline' property.

Parameters:

Name	Type	Description	Default
`generate_document_outline`	`bool`	Whether to generate a document outline	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`header(header: Path) -> Self` ¶

Adds a header HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`header`	`Path`	A Path object representing the path to the header HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`index(index: Path) -> Self` ¶

Sets the main HTML file for conversion.

Parameters:

Name	Type	Description	Default
`index`	`Path`	Path to the HTML file to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`margins(margins: PageMarginsType) -> Self` ¶

Sets the specified page margins.

Parameters:

Name	Type	Description	Default
`margins`	`PageMarginsType`	A `PageMarginsType` class representing the desired page margins.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`no_background_graphics() -> Self` ¶

Disables printing of the page background. Equivalent to print_background(print_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`orient(orient: PageOrientation) -> Self` ¶

Sets the page orientation to either Portrait or Landscape.

Parameters:

Name	Type	Description	Default
`orient`	`PageOrientation`	The desired PageOrientation (PageOrientation.Portrait or PageOrientation.Landscape).	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`page_ranges(ranges: str) -> Self` ¶

Sets the native page range string. Allows for specifying some range or just a few pages.

Parameters:

Name	Type	Description	Default
`ranges`	`str`	The native page range string. This string follows the format expected by the PDF engine. Examples include "1-5", "1,3,5", or "2-4,7". Consult the documentation for the exact expected format.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`prefer_css_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'true'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`prefer_set_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'false'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`print_background(*, print_background: bool) -> Self` ¶

Enables or disables printing the page background.

Parameters:

Name	Type	Description	Default
`print_background`	`bool`	True to print the background, False to not print it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`resource(resource: Path, *, name: Optional[str] = None) -> Self` ¶

Adds a resource file for the HTML to reference.

Parameters:

Name	Type	Description	Default
`resource`	`Path`	Path to the resource file (CSS, JS, images, etc.).	required
`name`	`Optional[str]`	Override the filename if HTML references it differently.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`resources(resources: list[Path]) -> Self` ¶

Adds multiple resource files at once.

Parameters:

Name	Type	Description	Default
`resources`	`list[Path]`	List of paths to resource files.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Uses original filenames; cannot override names in batch mode.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`scale(scale: Union[float, int]) -> Self` ¶

Sets the scale factor for the generated PDF.

Parameters:

Name	Type	Description	Default
`scale`	`Union[float, int]`	The scale factor. A float or integer representing the desired scale. For example, a scale of 2.0 will double the size, while a scale of 0.5 will halve the size.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`single_page(*, use_single_page: bool) -> Self` ¶

Sets the 'singlePage' property to True or False.

Parameters:

Name	Type	Description	Default
`use_single_page`	`bool`	Boolean value indicating whether to render the PDF as a single page. True means treat the document as a single page; False means render it as a multi-page document.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the route, allowing for method chaining.

`size(size: PageSize) -> Self` ¶

Sets the 'pageSize' property to a specified page size.

Parameters:

Name	Type	Description	Default
`size`	`PageSize`	A `PageSize` class representing the desired page size with height, width and units	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

Configures the splitting operation for the route options.

Parameters:

Name	Type	Description	Default
`mode`	`Literal['intervals', 'pages']`	The type of splitting operation. - `intervals`: Split into intervals - `pages`: Split into pages	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_span(span: str) -> Self` ¶

Configures the splitting span for the route options.

Parameters:

Name	Type	Description	Default
`span`	`str`	The splitting span. - Example: "1-3"	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_unify(*, split_unify: bool) -> Self` ¶

Enables or disables splitting for the route options.

Parameters:

Name	Type	Description	Default
`split_unify`	`bool`	Whether to enable or disable splitting. - `True`: Enable splitting - `False`: Disable splitting	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`string_index(index: str) -> Self` ¶

Sets the main HTML content as a string.

Parameters:

Name	Type	Description	Default
`index`	`str`	HTML content to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`string_resource(resource: str, name: str, mime_type: Optional[str] = None) -> Self` ¶

Adds an in-memory string resource.

Parameters:

Name	Type	Description	Default
`resource`	`str`	String content of the resource.	required
`name`	`str`	Name to reference this resource in the HTML.	required
`mime_type`	`Optional[str]`	MIME type of the resource.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`string_resources(resources: list[tuple[str, str, Optional[str]]]) -> Self` ¶

Adds multiple in-memory string resources.

Parameters:

Name	Type	Description	Default
`resources`	`list[tuple[str, str, Optional[str]]]`	List of tuples, each containing: - str: Resource content - str: Resource filename - Optional[str]: Resource MIME type	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The third element of each tuple (Resource Mime-Type) is optional.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`gotenberg_client._chromium.routes.AsyncHtmlToPdfRoute` ¶

Asynchronous route for converting HTML files to PDFs using Chromium.

Implements the asynchronous API for converting HTML files with associated resources to PDF documents.

See https://gotenberg.dev/docs/routes#html-file-into-pdf-route

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`background_graphics() -> Self` ¶

Enables printing of the page background. Equivalent to print_background(print_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`footer(footer: Path) -> Self` ¶

Adds a footer HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`footer`	`Path`	A Path object representing the path to the footer HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`generate_document_outline(*, generate_document_outline: bool) -> Self` ¶

Sets the 'generateDocumentOutline' property.

Parameters:

Name	Type	Description	Default
`generate_document_outline`	`bool`	Whether to generate a document outline	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`header(header: Path) -> Self` ¶

Adds a header HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`header`	`Path`	A Path object representing the path to the header HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`index(index: Path) -> Self` ¶

Sets the main HTML file for conversion.

Parameters:

Name	Type	Description	Default
`index`	`Path`	Path to the HTML file to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`margins(margins: PageMarginsType) -> Self` ¶

Sets the specified page margins.

Parameters:

Name	Type	Description	Default
`margins`	`PageMarginsType`	A `PageMarginsType` class representing the desired page margins.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`no_background_graphics() -> Self` ¶

Disables printing of the page background. Equivalent to print_background(print_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`orient(orient: PageOrientation) -> Self` ¶

Sets the page orientation to either Portrait or Landscape.

Parameters:

Name	Type	Description	Default
`orient`	`PageOrientation`	The desired PageOrientation (PageOrientation.Portrait or PageOrientation.Landscape).	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`page_ranges(ranges: str) -> Self` ¶

Sets the native page range string. Allows for specifying some range or just a few pages.

Parameters:

Name	Type	Description	Default
`ranges`	`str`	The native page range string. This string follows the format expected by the PDF engine. Examples include "1-5", "1,3,5", or "2-4,7". Consult the documentation for the exact expected format.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`prefer_css_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'true'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`prefer_set_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'false'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`print_background(*, print_background: bool) -> Self` ¶

Enables or disables printing the page background.

Parameters:

Name	Type	Description	Default
`print_background`	`bool`	True to print the background, False to not print it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`resource(resource: Path, *, name: Optional[str] = None) -> Self` ¶

Adds a resource file for the HTML to reference.

Parameters:

Name	Type	Description	Default
`resource`	`Path`	Path to the resource file (CSS, JS, images, etc.).	required
`name`	`Optional[str]`	Override the filename if HTML references it differently.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`resources(resources: list[Path]) -> Self` ¶

Adds multiple resource files at once.

Parameters:

Name	Type	Description	Default
`resources`	`list[Path]`	List of paths to resource files.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Uses original filenames; cannot override names in batch mode.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`scale(scale: Union[float, int]) -> Self` ¶

Sets the scale factor for the generated PDF.

Parameters:

Name	Type	Description	Default
`scale`	`Union[float, int]`	The scale factor. A float or integer representing the desired scale. For example, a scale of 2.0 will double the size, while a scale of 0.5 will halve the size.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`single_page(*, use_single_page: bool) -> Self` ¶

Sets the 'singlePage' property to True or False.

Parameters:

Name	Type	Description	Default
`use_single_page`	`bool`	Boolean value indicating whether to render the PDF as a single page. True means treat the document as a single page; False means render it as a multi-page document.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the route, allowing for method chaining.

`size(size: PageSize) -> Self` ¶

Sets the 'pageSize' property to a specified page size.

Parameters:

Name	Type	Description	Default
`size`	`PageSize`	A `PageSize` class representing the desired page size with height, width and units	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

Configures the splitting operation for the route options.

Parameters:

Name	Type	Description	Default
`mode`	`Literal['intervals', 'pages']`	The type of splitting operation. - `intervals`: Split into intervals - `pages`: Split into pages	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_span(span: str) -> Self` ¶

Configures the splitting span for the route options.

Parameters:

Name	Type	Description	Default
`span`	`str`	The splitting span. - Example: "1-3"	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_unify(*, split_unify: bool) -> Self` ¶

Enables or disables splitting for the route options.

Parameters:

Name	Type	Description	Default
`split_unify`	`bool`	Whether to enable or disable splitting. - `True`: Enable splitting - `False`: Disable splitting	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`string_index(index: str) -> Self` ¶

Sets the main HTML content as a string.

Parameters:

Name	Type	Description	Default
`index`	`str`	HTML content to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`string_resource(resource: str, name: str, mime_type: Optional[str] = None) -> Self` ¶

Adds an in-memory string resource.

Parameters:

Name	Type	Description	Default
`resource`	`str`	String content of the resource.	required
`name`	`str`	Name to reference this resource in the HTML.	required
`mime_type`	`Optional[str]`	MIME type of the resource.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`string_resources(resources: list[tuple[str, str, Optional[str]]]) -> Self` ¶

Adds multiple in-memory string resources.

Parameters:

Name	Type	Description	Default
`resources`	`list[tuple[str, str, Optional[str]]]`	List of tuples, each containing: - str: Resource content - str: Resource filename - Optional[str]: Resource MIME type	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The third element of each tuple (Resource Mime-Type) is optional.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`gotenberg_client._chromium.routes.SyncMarkdownToPdfRoute` ¶

Asynchronous route for converting Markdown files to PDFs using Chromium.

Implements the asynchronous API for converting Markdown files with associated resources to PDF documents.

See https://gotenberg.dev/docs/routes#markdown-files-into-pdf-route

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`background_graphics() -> Self` ¶

Enables printing of the page background. Equivalent to print_background(print_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`footer(footer: Path) -> Self` ¶

Adds a footer HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`footer`	`Path`	A Path object representing the path to the footer HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`generate_document_outline(*, generate_document_outline: bool) -> Self` ¶

Sets the 'generateDocumentOutline' property.

Parameters:

Name	Type	Description	Default
`generate_document_outline`	`bool`	Whether to generate a document outline	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`header(header: Path) -> Self` ¶

Adds a header HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`header`	`Path`	A Path object representing the path to the header HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`index(index: Path) -> Self` ¶

Sets the main HTML file for conversion.

Parameters:

Name	Type	Description	Default
`index`	`Path`	Path to the HTML file to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`margins(margins: PageMarginsType) -> Self` ¶

Sets the specified page margins.

Parameters:

Name	Type	Description	Default
`margins`	`PageMarginsType`	A `PageMarginsType` class representing the desired page margins.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`markdown_file(markdown_file: Path) -> Self` ¶

Adds a Markdown file to be converted.

Parameters:

Name	Type	Description	Default
`markdown_file`	`Path`	Path to the Markdown file.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`markdown_files(markdown_files: list[Path]) -> Self` ¶

Adds multiple Markdown files to be converted.

Parameters:

Name	Type	Description	Default
`markdown_files`	`list[Path]`	List of paths to Markdown files.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Files will be processed in the order they're provided.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`no_background_graphics() -> Self` ¶

Disables printing of the page background. Equivalent to print_background(print_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`orient(orient: PageOrientation) -> Self` ¶

Sets the page orientation to either Portrait or Landscape.

Parameters:

Name	Type	Description	Default
`orient`	`PageOrientation`	The desired PageOrientation (PageOrientation.Portrait or PageOrientation.Landscape).	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`page_ranges(ranges: str) -> Self` ¶

Sets the native page range string. Allows for specifying some range or just a few pages.

Parameters:

Name	Type	Description	Default
`ranges`	`str`	The native page range string. This string follows the format expected by the PDF engine. Examples include "1-5", "1,3,5", or "2-4,7". Consult the documentation for the exact expected format.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`prefer_css_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'true'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`prefer_set_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'false'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`print_background(*, print_background: bool) -> Self` ¶

Enables or disables printing the page background.

Parameters:

Name	Type	Description	Default
`print_background`	`bool`	True to print the background, False to not print it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`resource(resource: Path, *, name: Optional[str] = None) -> Self` ¶

Adds a resource file for the HTML to reference.

Parameters:

Name	Type	Description	Default
`resource`	`Path`	Path to the resource file (CSS, JS, images, etc.).	required
`name`	`Optional[str]`	Override the filename if HTML references it differently.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`resources(resources: list[Path]) -> Self` ¶

Adds multiple resource files at once.

Parameters:

Name	Type	Description	Default
`resources`	`list[Path]`	List of paths to resource files.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Uses original filenames; cannot override names in batch mode.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`scale(scale: Union[float, int]) -> Self` ¶

Sets the scale factor for the generated PDF.

Parameters:

Name	Type	Description	Default
`scale`	`Union[float, int]`	The scale factor. A float or integer representing the desired scale. For example, a scale of 2.0 will double the size, while a scale of 0.5 will halve the size.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`single_page(*, use_single_page: bool) -> Self` ¶

Sets the 'singlePage' property to True or False.

Parameters:

Name	Type	Description	Default
`use_single_page`	`bool`	Boolean value indicating whether to render the PDF as a single page. True means treat the document as a single page; False means render it as a multi-page document.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the route, allowing for method chaining.

`size(size: PageSize) -> Self` ¶

Sets the 'pageSize' property to a specified page size.

Parameters:

Name	Type	Description	Default
`size`	`PageSize`	A `PageSize` class representing the desired page size with height, width and units	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

Configures the splitting operation for the route options.

Parameters:

Name	Type	Description	Default
`mode`	`Literal['intervals', 'pages']`	The type of splitting operation. - `intervals`: Split into intervals - `pages`: Split into pages	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_span(span: str) -> Self` ¶

Configures the splitting span for the route options.

Parameters:

Name	Type	Description	Default
`span`	`str`	The splitting span. - Example: "1-3"	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_unify(*, split_unify: bool) -> Self` ¶

Enables or disables splitting for the route options.

Parameters:

Name	Type	Description	Default
`split_unify`	`bool`	Whether to enable or disable splitting. - `True`: Enable splitting - `False`: Disable splitting	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`string_index(index: str) -> Self` ¶

Sets the main HTML content as a string.

Parameters:

Name	Type	Description	Default
`index`	`str`	HTML content to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`string_resource(resource: str, name: str, mime_type: Optional[str] = None) -> Self` ¶

Adds an in-memory string resource.

Parameters:

Name	Type	Description	Default
`resource`	`str`	String content of the resource.	required
`name`	`str`	Name to reference this resource in the HTML.	required
`mime_type`	`Optional[str]`	MIME type of the resource.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`string_resources(resources: list[tuple[str, str, Optional[str]]]) -> Self` ¶

Adds multiple in-memory string resources.

Parameters:

Name	Type	Description	Default
`resources`	`list[tuple[str, str, Optional[str]]]`	List of tuples, each containing: - str: Resource content - str: Resource filename - Optional[str]: Resource MIME type	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The third element of each tuple (Resource Mime-Type) is optional.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`gotenberg_client._chromium.routes.AsyncMarkdownToPdfRoute` ¶

Synchronous route for capturing screenshots from URLs.

Implements the synchronous API for capturing screenshots of web pages at specified URLs.

See https://gotenberg.dev/docs/routes#screenshots-route

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`background_graphics() -> Self` ¶

Enables printing of the page background. Equivalent to print_background(print_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`footer(footer: Path) -> Self` ¶

Adds a footer HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`footer`	`Path`	A Path object representing the path to the footer HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`generate_document_outline(*, generate_document_outline: bool) -> Self` ¶

Sets the 'generateDocumentOutline' property.

Parameters:

Name	Type	Description	Default
`generate_document_outline`	`bool`	Whether to generate a document outline	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`header(header: Path) -> Self` ¶

Adds a header HTML file to the generated PDF.

Parameters:

Name	Type	Description	Default
`header`	`Path`	A Path object representing the path to the header HTML file.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`index(index: Path) -> Self` ¶

Sets the main HTML file for conversion.

Parameters:

Name	Type	Description	Default
`index`	`Path`	Path to the HTML file to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`margins(margins: PageMarginsType) -> Self` ¶

Sets the specified page margins.

Parameters:

Name	Type	Description	Default
`margins`	`PageMarginsType`	A `PageMarginsType` class representing the desired page margins.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`markdown_file(markdown_file: Path) -> Self` ¶

Adds a Markdown file to be converted.

Parameters:

Name	Type	Description	Default
`markdown_file`	`Path`	Path to the Markdown file.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`markdown_files(markdown_files: list[Path]) -> Self` ¶

Adds multiple Markdown files to be converted.

Parameters:

Name	Type	Description	Default
`markdown_files`	`list[Path]`	List of paths to Markdown files.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Files will be processed in the order they're provided.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`no_background_graphics() -> Self` ¶

Disables printing of the page background. Equivalent to print_background(print_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`orient(orient: PageOrientation) -> Self` ¶

Sets the page orientation to either Portrait or Landscape.

Parameters:

Name	Type	Description	Default
`orient`	`PageOrientation`	The desired PageOrientation (PageOrientation.Portrait or PageOrientation.Landscape).	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`page_ranges(ranges: str) -> Self` ¶

Sets the native page range string. Allows for specifying some range or just a few pages.

Parameters:

Name	Type	Description	Default
`ranges`	`str`	The native page range string. This string follows the format expected by the PDF engine. Examples include "1-5", "1,3,5", or "2-4,7". Consult the documentation for the exact expected format.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`prefer_css_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'true'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`prefer_set_page_size() -> Self` ¶

Sets the 'preferCssPageSize' property to 'false'.

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`print_background(*, print_background: bool) -> Self` ¶

Enables or disables printing the page background.

Parameters:

Name	Type	Description	Default
`print_background`	`bool`	True to print the background, False to not print it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`resource(resource: Path, *, name: Optional[str] = None) -> Self` ¶

Adds a resource file for the HTML to reference.

Parameters:

Name	Type	Description	Default
`resource`	`Path`	Path to the resource file (CSS, JS, images, etc.).	required
`name`	`Optional[str]`	Override the filename if HTML references it differently.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`resources(resources: list[Path]) -> Self` ¶

Adds multiple resource files at once.

Parameters:

Name	Type	Description	Default
`resources`	`list[Path]`	List of paths to resource files.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Uses original filenames; cannot override names in batch mode.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`scale(scale: Union[float, int]) -> Self` ¶

Sets the scale factor for the generated PDF.

Parameters:

Name	Type	Description	Default
`scale`	`Union[float, int]`	The scale factor. A float or integer representing the desired scale. For example, a scale of 2.0 will double the size, while a scale of 0.5 will halve the size.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`single_page(*, use_single_page: bool) -> Self` ¶

Sets the 'singlePage' property to True or False.

Parameters:

Name	Type	Description	Default
`use_single_page`	`bool`	Boolean value indicating whether to render the PDF as a single page. True means treat the document as a single page; False means render it as a multi-page document.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the route, allowing for method chaining.

`size(size: PageSize) -> Self` ¶

Sets the 'pageSize' property to a specified page size.

Parameters:

Name	Type	Description	Default
`size`	`PageSize`	A `PageSize` class representing the desired page size with height, width and units	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

Configures the splitting operation for the route options.

Parameters:

Name	Type	Description	Default
`mode`	`Literal['intervals', 'pages']`	The type of splitting operation. - `intervals`: Split into intervals - `pages`: Split into pages	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_span(span: str) -> Self` ¶

Configures the splitting span for the route options.

Parameters:

Name	Type	Description	Default
`span`	`str`	The splitting span. - Example: "1-3"	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_unify(*, split_unify: bool) -> Self` ¶

Enables or disables splitting for the route options.

Parameters:

Name	Type	Description	Default
`split_unify`	`bool`	Whether to enable or disable splitting. - `True`: Enable splitting - `False`: Disable splitting	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`string_index(index: str) -> Self` ¶

Sets the main HTML content as a string.

Parameters:

Name	Type	Description	Default
`index`	`str`	HTML content to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`string_resource(resource: str, name: str, mime_type: Optional[str] = None) -> Self` ¶

Adds an in-memory string resource.

Parameters:

Name	Type	Description	Default
`resource`	`str`	String content of the resource.	required
`name`	`str`	Name to reference this resource in the HTML.	required
`mime_type`	`Optional[str]`	MIME type of the resource.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`string_resources(resources: list[tuple[str, str, Optional[str]]]) -> Self` ¶

Adds multiple in-memory string resources.

Parameters:

Name	Type	Description	Default
`resources`	`list[tuple[str, str, Optional[str]]]`	List of tuples, each containing: - str: Resource content - str: Resource filename - Optional[str]: Resource MIME type	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The third element of each tuple (Resource Mime-Type) is optional.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`gotenberg_client._chromium.routes.SyncScreenshotFromUrlRoute` ¶

Synchronous route for capturing screenshots from URLs.

Implements the synchronous API for capturing screenshots of web pages at specified URLs.

See https://gotenberg.dev/docs/routes#screenshots-route

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`image_optimize_for_quality() -> Self` ¶

Sets the optimization mode to prioritize size reduction.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`image_optimize_for_speed() -> Self` ¶

Sets the optimization mode to prioritize speed.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`output_format(output_format: Literal['png', 'jpeg', 'webp'] = 'png') -> Self` ¶

Sets the output format for the screenshot.

Parameters:

Name	Type	Description	Default
`output_format`	`Literal['png', 'jpeg', 'webp']`	The desired output format. Defaults to "png".	`'png'`

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`quality(quality: int) -> Self` ¶

Sets the quality of the screenshot (0-100).

Parameters:

Name	Type	Description	Default
`quality`	`int`	The desired quality level (0-100).	required

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`url(url: str) -> Self` ¶

Sets the URL to convert to PDF.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL of the web page to convert.	required

Returns:

Name	Type	Description
`UrlRoute`	`Self`	This object itself for method chaining.

`gotenberg_client._chromium.routes.AsyncScreenshotFromUrlRoute` ¶

Asynchronous route for capturing screenshots from URLs.

Implements the asynchronous API for capturing screenshots of web pages at specified URLs.

See https://gotenberg.dev/docs/routes#screenshots-route

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`image_optimize_for_quality() -> Self` ¶

Sets the optimization mode to prioritize size reduction.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`image_optimize_for_speed() -> Self` ¶

Sets the optimization mode to prioritize speed.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`output_format(output_format: Literal['png', 'jpeg', 'webp'] = 'png') -> Self` ¶

Sets the output format for the screenshot.

Parameters:

Name	Type	Description	Default
`output_format`	`Literal['png', 'jpeg', 'webp']`	The desired output format. Defaults to "png".	`'png'`

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`quality(quality: int) -> Self` ¶

Sets the quality of the screenshot (0-100).

Parameters:

Name	Type	Description	Default
`quality`	`int`	The desired quality level (0-100).	required

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`url(url: str) -> Self` ¶

Sets the URL to convert to PDF.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL of the web page to convert.	required

Returns:

Name	Type	Description
`UrlRoute`	`Self`	This object itself for method chaining.

`gotenberg_client._chromium.routes.SyncScreenshotFromHtmlRoute` ¶

Synchronous route for capturing screenshots from HTML files.

Implements the synchronous API for capturing screenshots of HTML files with associated resources.

See https://gotenberg.dev/docs/routes#screenshots-route

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`image_optimize_for_quality() -> Self` ¶

Sets the optimization mode to prioritize size reduction.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`image_optimize_for_speed() -> Self` ¶

Sets the optimization mode to prioritize speed.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`index(index: Path) -> Self` ¶

Sets the main HTML file for conversion.

Parameters:

Name	Type	Description	Default
`index`	`Path`	Path to the HTML file to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`output_format(output_format: Literal['png', 'jpeg', 'webp'] = 'png') -> Self` ¶

Sets the output format for the screenshot.

Parameters:

Name	Type	Description	Default
`output_format`	`Literal['png', 'jpeg', 'webp']`	The desired output format. Defaults to "png".	`'png'`

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`quality(quality: int) -> Self` ¶

Sets the quality of the screenshot (0-100).

Parameters:

Name	Type	Description	Default
`quality`	`int`	The desired quality level (0-100).	required

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`resource(resource: Path, *, name: Optional[str] = None) -> Self` ¶

Adds a resource file for the HTML to reference.

Parameters:

Name	Type	Description	Default
`resource`	`Path`	Path to the resource file (CSS, JS, images, etc.).	required
`name`	`Optional[str]`	Override the filename if HTML references it differently.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`resources(resources: list[Path]) -> Self` ¶

Adds multiple resource files at once.

Parameters:

Name	Type	Description	Default
`resources`	`list[Path]`	List of paths to resource files.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Uses original filenames; cannot override names in batch mode.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`string_index(index: str) -> Self` ¶

Sets the main HTML content as a string.

Parameters:

Name	Type	Description	Default
`index`	`str`	HTML content to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`string_resource(resource: str, name: str, mime_type: Optional[str] = None) -> Self` ¶

Adds an in-memory string resource.

Parameters:

Name	Type	Description	Default
`resource`	`str`	String content of the resource.	required
`name`	`str`	Name to reference this resource in the HTML.	required
`mime_type`	`Optional[str]`	MIME type of the resource.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`string_resources(resources: list[tuple[str, str, Optional[str]]]) -> Self` ¶

Adds multiple in-memory string resources.

Parameters:

Name	Type	Description	Default
`resources`	`list[tuple[str, str, Optional[str]]]`	List of tuples, each containing: - str: Resource content - str: Resource filename - Optional[str]: Resource MIME type	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The third element of each tuple (Resource Mime-Type) is optional.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`gotenberg_client._chromium.routes.AsyncScreenshotFromHtmlRoute` ¶

Asynchronous route for capturing screenshots from HTML files.

Implements the asynchronous API for capturing screenshots of HTML files with associated resources.

See https://gotenberg.dev/docs/routes#screenshots-route

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`image_optimize_for_quality() -> Self` ¶

Sets the optimization mode to prioritize size reduction.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`image_optimize_for_speed() -> Self` ¶

Sets the optimization mode to prioritize speed.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`index(index: Path) -> Self` ¶

Sets the main HTML file for conversion.

Parameters:

Name	Type	Description	Default
`index`	`Path`	Path to the HTML file to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`output_format(output_format: Literal['png', 'jpeg', 'webp'] = 'png') -> Self` ¶

Sets the output format for the screenshot.

Parameters:

Name	Type	Description	Default
`output_format`	`Literal['png', 'jpeg', 'webp']`	The desired output format. Defaults to "png".	`'png'`

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`quality(quality: int) -> Self` ¶

Sets the quality of the screenshot (0-100).

Parameters:

Name	Type	Description	Default
`quality`	`int`	The desired quality level (0-100).	required

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`resource(resource: Path, *, name: Optional[str] = None) -> Self` ¶

Adds a resource file for the HTML to reference.

Parameters:

Name	Type	Description	Default
`resource`	`Path`	Path to the resource file (CSS, JS, images, etc.).	required
`name`	`Optional[str]`	Override the filename if HTML references it differently.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`resources(resources: list[Path]) -> Self` ¶

Adds multiple resource files at once.

Parameters:

Name	Type	Description	Default
`resources`	`list[Path]`	List of paths to resource files.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Uses original filenames; cannot override names in batch mode.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`string_index(index: str) -> Self` ¶

Sets the main HTML content as a string.

Parameters:

Name	Type	Description	Default
`index`	`str`	HTML content to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`string_resource(resource: str, name: str, mime_type: Optional[str] = None) -> Self` ¶

Adds an in-memory string resource.

Parameters:

Name	Type	Description	Default
`resource`	`str`	String content of the resource.	required
`name`	`str`	Name to reference this resource in the HTML.	required
`mime_type`	`Optional[str]`	MIME type of the resource.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`string_resources(resources: list[tuple[str, str, Optional[str]]]) -> Self` ¶

Adds multiple in-memory string resources.

Parameters:

Name	Type	Description	Default
`resources`	`list[tuple[str, str, Optional[str]]]`	List of tuples, each containing: - str: Resource content - str: Resource filename - Optional[str]: Resource MIME type	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The third element of each tuple (Resource Mime-Type) is optional.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`gotenberg_client._chromium.routes.SyncScreenshotFromMarkdownRoute` ¶

Synchronous route for capturing screenshots from Markdown files.

Implements the synchronous API for capturing screenshots of rendered Markdown content.

See https://gotenberg.dev/docs/routes#screenshots-route

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`image_optimize_for_quality() -> Self` ¶

Sets the optimization mode to prioritize size reduction.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`image_optimize_for_speed() -> Self` ¶

Sets the optimization mode to prioritize speed.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`index(index: Path) -> Self` ¶

Sets the main HTML file for conversion.

Parameters:

Name	Type	Description	Default
`index`	`Path`	Path to the HTML file to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`output_format(output_format: Literal['png', 'jpeg', 'webp'] = 'png') -> Self` ¶

Sets the output format for the screenshot.

Parameters:

Name	Type	Description	Default
`output_format`	`Literal['png', 'jpeg', 'webp']`	The desired output format. Defaults to "png".	`'png'`

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`quality(quality: int) -> Self` ¶

Sets the quality of the screenshot (0-100).

Parameters:

Name	Type	Description	Default
`quality`	`int`	The desired quality level (0-100).	required

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`resource(resource: Path, *, name: Optional[str] = None) -> Self` ¶

Adds a resource file for the HTML to reference.

Parameters:

Name	Type	Description	Default
`resource`	`Path`	Path to the resource file (CSS, JS, images, etc.).	required
`name`	`Optional[str]`	Override the filename if HTML references it differently.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`resources(resources: list[Path]) -> Self` ¶

Adds multiple resource files at once.

Parameters:

Name	Type	Description	Default
`resources`	`list[Path]`	List of paths to resource files.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Uses original filenames; cannot override names in batch mode.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`string_index(index: str) -> Self` ¶

Sets the main HTML content as a string.

Parameters:

Name	Type	Description	Default
`index`	`str`	HTML content to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`string_resource(resource: str, name: str, mime_type: Optional[str] = None) -> Self` ¶

Adds an in-memory string resource.

Parameters:

Name	Type	Description	Default
`resource`	`str`	String content of the resource.	required
`name`	`str`	Name to reference this resource in the HTML.	required
`mime_type`	`Optional[str]`	MIME type of the resource.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`string_resources(resources: list[tuple[str, str, Optional[str]]]) -> Self` ¶

Adds multiple in-memory string resources.

Parameters:

Name	Type	Description	Default
`resources`	`list[tuple[str, str, Optional[str]]]`	List of tuples, each containing: - str: Resource content - str: Resource filename - Optional[str]: Resource MIME type	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The third element of each tuple (Resource Mime-Type) is optional.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`gotenberg_client._chromium.routes.AsyncScreenshotFromMarkdownRoute` ¶

Asynchronous route for capturing screenshots from Markdown files.

Implements the asynchronous API for capturing screenshots of rendered Markdown content.

See https://gotenberg.dev/docs/routes#screenshots-route

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`cookies(cookies: list[CookieJar]) -> Self` ¶

Sets cookies for the rendering process.

Parameters:

Name	Type	Description	Default
`cookies`	`list[CookieJar]`	A list of CookieJar objects, each representing a cookie.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`dont_fail_on_exceptions() -> Self` ¶

Disable failing on console exceptions

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

Enable or disable failing on console exceptions

`fail_on_exceptions() -> Self` ¶

Enable failing on console exceptions

`hide_background() -> Self` ¶

Omits the page background. Equivalent to omit_background(omit_background=True).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`image_optimize_for_quality() -> Self` ¶

Sets the optimization mode to prioritize size reduction.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`image_optimize_for_speed() -> Self` ¶

Sets the optimization mode to prioritize speed.

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`index(index: Path) -> Self` ¶

Sets the main HTML file for conversion.

Parameters:

Name	Type	Description	Default
`index`	`Path`	Path to the HTML file to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

Specifies the emulated media type.

Parameters:

Name	Type	Description	Default
`media_type`	`Literal['print', 'screen']`	The media type to emulate. Must be either "print" or "screen".	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`omit_background(*, omit_background: bool) -> Self` ¶

Enables or disables the omission of the page background.

Parameters:

Name	Type	Description	Default
`omit_background`	`bool`	True to omit the background, False to include it.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`output_format(output_format: Literal['png', 'jpeg', 'webp'] = 'png') -> Self` ¶

Sets the output format for the screenshot.

Parameters:

Name	Type	Description	Default
`output_format`	`Literal['png', 'jpeg', 'webp']`	The desired output format. Defaults to "png".	`'png'`

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`quality(quality: int) -> Self` ¶

Sets the quality of the screenshot (0-100).

Parameters:

Name	Type	Description	Default
`quality`	`int`	The desired quality level (0-100).	required

Returns:

Name	Type	Description
`ScreenshotRoute`	`Self`	This object itself for method chaining.

`render_expression(expr: str) -> Self` ¶

Specifies an expression to wait for before rendering begins.

Parameters:

Name	Type	Description	Default
`expr`	`str`	The expression to wait for. The exact format and behavior depend on the underlying rendering engine. Consult the Gotenberg documentation for details.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

Specifies the delay before rendering begins.

Parameters:

Name	Type	Description	Default
`wait`	`Union[float, int, timedelta]`	The delay before rendering begins. This can be a float or integer representing seconds, or a timedelta object.	required

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

Raises:

Type	Description
`NegativeWaitDurationError`	If the wait duration is negative.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`resource(resource: Path, *, name: Optional[str] = None) -> Self` ¶

Adds a resource file for the HTML to reference.

Parameters:

Name	Type	Description	Default
`resource`	`Path`	Path to the resource file (CSS, JS, images, etc.).	required
`name`	`Optional[str]`	Override the filename if HTML references it differently.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`resources(resources: list[Path]) -> Self` ¶

Adds multiple resource files at once.

Parameters:

Name	Type	Description	Default
`resources`	`list[Path]`	List of paths to resource files.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Uses original filenames; cannot override names in batch mode.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`show_background() -> Self` ¶

Includes the page background. Equivalent to omit_background(omit_background=False).

Returns:

Name	Type	Description
`self`	`Self`	The current instance of the class, allowing for method chaining.

`string_index(index: str) -> Self` ¶

Sets the main HTML content as a string.

Parameters:

Name	Type	Description	Default
`index`	`str`	HTML content to use as the main entry point.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The file name will be normalized to "index.html" regardless of original name.

`string_resource(resource: str, name: str, mime_type: Optional[str] = None) -> Self` ¶

Adds an in-memory string resource.

Parameters:

Name	Type	Description	Default
`resource`	`str`	String content of the resource.	required
`name`	`str`	Name to reference this resource in the HTML.	required
`mime_type`	`Optional[str]`	MIME type of the resource.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`string_resources(resources: list[tuple[str, str, Optional[str]]]) -> Self` ¶

Adds multiple in-memory string resources.

Parameters:

Name	Type	Description	Default
`resources`	`list[tuple[str, str, Optional[str]]]`	List of tuples, each containing: - str: Resource content - str: Resource filename - Optional[str]: Resource MIME type	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

The third element of each tuple (Resource Mime-Type) is optional.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

LibreOffice¶

`gotenberg_client._libreoffice.routes.SyncOfficeDocumentToPdfRoute` ¶

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`add_original_document_as_stream(*, add_original_document_as_stream: bool = False) -> Self` ¶

Controls whether the original document should be added as a stream.

Parameters:

Name	Type	Description	Default
`add_original_document_as_stream`	`bool`	Whether to add original document as stream.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`allow_duplicate_form_fields(*, allow_duplicate_form_fields: bool = False) -> Self` ¶

Controls whether duplicate form field names are allowed.

Parameters:

Name	Type	Description	Default
`allow_duplicate_form_fields`	`bool`	Whether to allow duplicate field names.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`convert(input_file_path: Path) -> Self` ¶

Adds a single file to be converted to PDF.

Calling this method multiple times will result in a ZIP containing individual PDFs for each converted file.

Parameters:

Name	Type	Description	Default
`input_file_path`	`Path`	The path to the file to be converted.	required

Returns:

Name	Type	Description
`LibreOfficeConvertRoute`	`Self`	This object itself for method chaining.

`convert_files(file_paths: list[Path]) -> Self` ¶

Adds all provided files for conversion to individual PDFs.

This method adds all files in the provided list for conversion. By default, the resulting PDFs will be zipped together in the response.

Parameters:

Name	Type	Description	Default
`file_paths`	`List[Path]`	A list of paths to the files to be converted.	required

Returns:

Name	Type	Description
`LibreOfficeConvertRoute`	`Self`	This object itself for method chaining.

`convert_ooo_target_to_pdf_target(*, convert_ooo_target_to_pdf_target: bool = False) -> Self` ¶

Controls that target documents with .od[tpgs] extension, will have that extension changed to .pdf when the link is exported to PDF

Parameters:

Name	Type	Description	Default
`convert_ooo_target_to_pdf_target`	`bool`	Whether to convert OOo targets to PDF.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`do_merge() -> Self` ¶

Enables document merging.

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`export_bookmarks(*, export_bookmarks: bool = False) -> Self` ¶

Controls whether bookmarks should be exported.

Parameters:

Name	Type	Description	Default
`export_bookmarks`	`bool`	Whether to export bookmarks.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_bookmarks_to_pdf_destination(*, export_bookmarks_to_pdf_destination: bool = False) -> Self` ¶

Controls whether bookmarks should be exported as PDF destinations.

Parameters:

Name	Type	Description	Default
`export_bookmarks_to_pdf_destination`	`bool`	Whether to convert bookmarks to PDF destinations.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_form_fields(*, export_form_fields: bool = False) -> Self` ¶

Controls whether form fields should be exported.

Parameters:

Name	Type	Description	Default
`export_form_fields`	`bool`	Whether to export form fields.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_hidden_slides(*, export_hidden_slides: bool = False) -> Self` ¶

Controls whether hidden slides should be exported (for presentations).

Parameters:

Name	Type	Description	Default
`export_hidden_slides`	`bool`	Whether to export hidden slides.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_links_relative_fsys(*, export_links_relative_fsys: bool = False) -> Self` ¶

Controls whether links relative to the filesystem should be exported.

Parameters:

Name	Type	Description	Default
`export_links_relative_fsys`	`bool`	Whether to export filesystem-relative links.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_notes(*, export_notes: bool = False) -> Self` ¶

Controls whether document notes should be exported.

Parameters:

Name	Type	Description	Default
`export_notes`	`bool`	Whether to export notes.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_notes_in_margin(*, export_notes_in_margin: bool = False) -> Self` ¶

Controls whether notes should be exported in the margin.

Parameters:

Name	Type	Description	Default
`export_notes_in_margin`	`bool`	Whether to export notes in margin.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_notes_pages(*, export_notes_pages: bool = False) -> Self` ¶

Controls whether notes pages should be exported.

Parameters:

Name	Type	Description	Default
`export_notes_pages`	`bool`	Whether to export notes pages.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_only_notes_pages(*, export_only_notes_pages: bool = False) -> Self` ¶

Controls whether only notes pages should be exported.

Parameters:

Name	Type	Description	Default
`export_only_notes_pages`	`bool`	Whether to export only notes pages.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`flatten(*, flatten: bool = False) -> Self` ¶

Enables or disables flattening for the route options.

By default, flattening is disabled (flatten=False). This option controls whether to flatten PDF documents (e.g., remove page breaks).

Parameters:

Name	Type	Description	Default
`flatten`	`bool`	Whether to enable or disable flattening. - `True`: Enable flattening - `False` (default): Disable flattening	`False`

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`lossless_image_compression(*, lossless_image_compression: bool = False) -> Self` ¶

Controls whether to use lossless image compression.

Parameters:

Name	Type	Description	Default
`lossless_image_compression`	`bool`	Whether to use lossless compression.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`max_image_resolution(max_resolution: Literal[75, 150, 300, 600, 1200]) -> Self` ¶

Sets the maximum image resolution.

Parameters:

Name	Type	Description	Default
`max_resolution`	`Literal[75, 150, 300, 600, 1200]`	Maximum resolution in DPI (must be one of: 75, 150, 300, 600, 1200).	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`merge(*, merge: bool) -> Self` ¶

Controls whether multiple documents should be merged.

Parameters:

Name	Type	Description	Default
`merge`	`bool`	Whether to merge documents.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`no_merge() -> Self` ¶

Disables document merging.

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`orient(orient: PageOrientation) -> Self` ¶

Sets the page orientation for conversion.

Parameters:

Name	Type	Description	Default
`orient`	`PageOrientation`	Either PageOrientation.Portrait or PageOrientation.Landscape.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`page_ranges(ranges: str) -> Self` ¶

Specifies which pages to include in the conversion.

Parameters:

Name	Type	Description	Default
`ranges`	`str`	Page range string (e.g., "1-5,8,11-13").	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`password(password: str) -> Self` ¶

Sets password for password-protected documents.

Parameters:

Name	Type	Description	Default
`password`	`str`	Document password for accessing protected content.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`quality(quality: int) -> Self` ¶

Sets the image quality level for compression.

Parameters:

Name	Type	Description	Default
`quality`	`int`	Quality level from 1 (lowest) to 100 (highest).	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Values outside the valid range will be clamped.

`reduce_image_resolution(*, reduce_image_resolution: bool = False) -> Self` ¶

Controls whether image resolution should be reduced.

Parameters:

Name	Type	Description	Default
`reduce_image_resolution`	`bool`	Whether to reduce image resolution.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`single_page_sheets(*, single_page_sheets: bool = False) -> Self` ¶

Controls whether sheets should be converted as single pages.

Parameters:

Name	Type	Description	Default
`single_page_sheets`	`bool`	Whether each sheet becomes a single page.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`skip_empty_pages(*, skip_empty_pages: bool = False) -> Self` ¶

Controls whether empty pages should be skipped.

Parameters:

Name	Type	Description	Default
`skip_empty_pages`	`bool`	Whether to skip empty pages.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

Configures the splitting operation for the route options.

Parameters:

Name	Type	Description	Default
`mode`	`Literal['intervals', 'pages']`	The type of splitting operation. - `intervals`: Split into intervals - `pages`: Split into pages	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_span(span: str) -> Self` ¶

Configures the splitting span for the route options.

Parameters:

Name	Type	Description	Default
`span`	`str`	The splitting span. - Example: "1-3"	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_unify(*, split_unify: bool) -> Self` ¶

Enables or disables splitting for the route options.

Parameters:

Name	Type	Description	Default
`split_unify`	`bool`	Whether to enable or disable splitting. - `True`: Enable splitting - `False`: Disable splitting	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`update_indexes(*, update_indexes: bool = False) -> Self` ¶

Controls whether document indexes should be updated.

Parameters:

Name	Type	Description	Default
`update_indexes`	`bool`	Whether to update document indexes.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`gotenberg_client._libreoffice.routes.AsyncOfficeDocumentToPdfRoute` ¶

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`add_original_document_as_stream(*, add_original_document_as_stream: bool = False) -> Self` ¶

Controls whether the original document should be added as a stream.

Parameters:

Name	Type	Description	Default
`add_original_document_as_stream`	`bool`	Whether to add original document as stream.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`allow_duplicate_form_fields(*, allow_duplicate_form_fields: bool = False) -> Self` ¶

Controls whether duplicate form field names are allowed.

Parameters:

Name	Type	Description	Default
`allow_duplicate_form_fields`	`bool`	Whether to allow duplicate field names.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`convert(input_file_path: Path) -> Self` ¶

Adds a single file to be converted to PDF.

Calling this method multiple times will result in a ZIP containing individual PDFs for each converted file.

Parameters:

Name	Type	Description	Default
`input_file_path`	`Path`	The path to the file to be converted.	required

Returns:

Name	Type	Description
`LibreOfficeConvertRoute`	`Self`	This object itself for method chaining.

`convert_files(file_paths: list[Path]) -> Self` ¶

Adds all provided files for conversion to individual PDFs.

This method adds all files in the provided list for conversion. By default, the resulting PDFs will be zipped together in the response.

Parameters:

Name	Type	Description	Default
`file_paths`	`List[Path]`	A list of paths to the files to be converted.	required

Returns:

Name	Type	Description
`LibreOfficeConvertRoute`	`Self`	This object itself for method chaining.

`convert_ooo_target_to_pdf_target(*, convert_ooo_target_to_pdf_target: bool = False) -> Self` ¶

Controls that target documents with .od[tpgs] extension, will have that extension changed to .pdf when the link is exported to PDF

Parameters:

Name	Type	Description	Default
`convert_ooo_target_to_pdf_target`	`bool`	Whether to convert OOo targets to PDF.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`do_merge() -> Self` ¶

Enables document merging.

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`export_bookmarks(*, export_bookmarks: bool = False) -> Self` ¶

Controls whether bookmarks should be exported.

Parameters:

Name	Type	Description	Default
`export_bookmarks`	`bool`	Whether to export bookmarks.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_bookmarks_to_pdf_destination(*, export_bookmarks_to_pdf_destination: bool = False) -> Self` ¶

Controls whether bookmarks should be exported as PDF destinations.

Parameters:

Name	Type	Description	Default
`export_bookmarks_to_pdf_destination`	`bool`	Whether to convert bookmarks to PDF destinations.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_form_fields(*, export_form_fields: bool = False) -> Self` ¶

Controls whether form fields should be exported.

Parameters:

Name	Type	Description	Default
`export_form_fields`	`bool`	Whether to export form fields.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_hidden_slides(*, export_hidden_slides: bool = False) -> Self` ¶

Controls whether hidden slides should be exported (for presentations).

Parameters:

Name	Type	Description	Default
`export_hidden_slides`	`bool`	Whether to export hidden slides.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_links_relative_fsys(*, export_links_relative_fsys: bool = False) -> Self` ¶

Controls whether links relative to the filesystem should be exported.

Parameters:

Name	Type	Description	Default
`export_links_relative_fsys`	`bool`	Whether to export filesystem-relative links.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_notes(*, export_notes: bool = False) -> Self` ¶

Controls whether document notes should be exported.

Parameters:

Name	Type	Description	Default
`export_notes`	`bool`	Whether to export notes.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_notes_in_margin(*, export_notes_in_margin: bool = False) -> Self` ¶

Controls whether notes should be exported in the margin.

Parameters:

Name	Type	Description	Default
`export_notes_in_margin`	`bool`	Whether to export notes in margin.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_notes_pages(*, export_notes_pages: bool = False) -> Self` ¶

Controls whether notes pages should be exported.

Parameters:

Name	Type	Description	Default
`export_notes_pages`	`bool`	Whether to export notes pages.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`export_only_notes_pages(*, export_only_notes_pages: bool = False) -> Self` ¶

Controls whether only notes pages should be exported.

Parameters:

Name	Type	Description	Default
`export_only_notes_pages`	`bool`	Whether to export only notes pages.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`flatten(*, flatten: bool = False) -> Self` ¶

Enables or disables flattening for the route options.

By default, flattening is disabled (flatten=False). This option controls whether to flatten PDF documents (e.g., remove page breaks).

Parameters:

Name	Type	Description	Default
`flatten`	`bool`	Whether to enable or disable flattening. - `True`: Enable flattening - `False` (default): Disable flattening	`False`

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`lossless_image_compression(*, lossless_image_compression: bool = False) -> Self` ¶

Controls whether to use lossless image compression.

Parameters:

Name	Type	Description	Default
`lossless_image_compression`	`bool`	Whether to use lossless compression.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`max_image_resolution(max_resolution: Literal[75, 150, 300, 600, 1200]) -> Self` ¶

Sets the maximum image resolution.

Parameters:

Name	Type	Description	Default
`max_resolution`	`Literal[75, 150, 300, 600, 1200]`	Maximum resolution in DPI (must be one of: 75, 150, 300, 600, 1200).	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`merge(*, merge: bool) -> Self` ¶

Controls whether multiple documents should be merged.

Parameters:

Name	Type	Description	Default
`merge`	`bool`	Whether to merge documents.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`no_merge() -> Self` ¶

Disables document merging.

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`orient(orient: PageOrientation) -> Self` ¶

Sets the page orientation for conversion.

Parameters:

Name	Type	Description	Default
`orient`	`PageOrientation`	Either PageOrientation.Portrait or PageOrientation.Landscape.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`page_ranges(ranges: str) -> Self` ¶

Specifies which pages to include in the conversion.

Parameters:

Name	Type	Description	Default
`ranges`	`str`	Page range string (e.g., "1-5,8,11-13").	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`password(password: str) -> Self` ¶

Sets password for password-protected documents.

Parameters:

Name	Type	Description	Default
`password`	`str`	Document password for accessing protected content.	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`quality(quality: int) -> Self` ¶

Sets the image quality level for compression.

Parameters:

Name	Type	Description	Default
`quality`	`int`	Quality level from 1 (lowest) to 100 (highest).	required

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

Note

Values outside the valid range will be clamped.

`reduce_image_resolution(*, reduce_image_resolution: bool = False) -> Self` ¶

Controls whether image resolution should be reduced.

Parameters:

Name	Type	Description	Default
`reduce_image_resolution`	`bool`	Whether to reduce image resolution.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`single_page_sheets(*, single_page_sheets: bool = False) -> Self` ¶

Controls whether sheets should be converted as single pages.

Parameters:

Name	Type	Description	Default
`single_page_sheets`	`bool`	Whether each sheet becomes a single page.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`skip_empty_pages(*, skip_empty_pages: bool = False) -> Self` ¶

Controls whether empty pages should be skipped.

Parameters:

Name	Type	Description	Default
`skip_empty_pages`	`bool`	Whether to skip empty pages.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

Configures the splitting operation for the route options.

Parameters:

Name	Type	Description	Default
`mode`	`Literal['intervals', 'pages']`	The type of splitting operation. - `intervals`: Split into intervals - `pages`: Split into pages	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_span(span: str) -> Self` ¶

Configures the splitting span for the route options.

Parameters:

Name	Type	Description	Default
`span`	`str`	The splitting span. - Example: "1-3"	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_unify(*, split_unify: bool) -> Self` ¶

Enables or disables splitting for the route options.

Parameters:

Name	Type	Description	Default
`split_unify`	`bool`	Whether to enable or disable splitting. - `True`: Enable splitting - `False`: Disable splitting	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`update_indexes(*, update_indexes: bool = False) -> Self` ¶

Controls whether document indexes should be updated.

Parameters:

Name	Type	Description	Default
`update_indexes`	`bool`	Whether to update document indexes.	`False`

Returns:

Name	Type	Description
`Self`	`Self`	This object for method chaining.

PDF/A & PDF/UA Convert¶

`gotenberg_client._pdfa_ua.routes.SyncConvertToArchiveFormatRoute` ¶

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`convert(file_path: Path) -> Self` ¶

Converts a single PDF file to the provided PDF/A format.

Parameters:

Name	Type	Description	Default
`file_path`	`Path`	The path to the PDF file to be converted.	required

Returns:

Name	Type	Description
`PdfAConvertRoute`	`Self`	This object itself for method chaining.

`convert_files(file_paths: list[Path]) -> Self` ¶

Converts multiple PDF files to the provided PDF/A format.

Parameters:

Name	Type	Description	Default
`file_paths`	`List[Path]`	A list of paths to the PDF files to be converted.	required

Returns:

Name	Type	Description
`PdfAConvertRoute`	`Self`	This object itself for method chaining.

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`gotenberg_client._pdfa_ua.routes.AsyncConvertToArchiveFormatRoute` ¶

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`convert(file_path: Path) -> Self` ¶

Converts a single PDF file to the provided PDF/A format.

Parameters:

Name	Type	Description	Default
`file_path`	`Path`	The path to the PDF file to be converted.	required

Returns:

Name	Type	Description
`PdfAConvertRoute`	`Self`	This object itself for method chaining.

`convert_files(file_paths: list[Path]) -> Self` ¶

Converts multiple PDF files to the provided PDF/A format.

Parameters:

Name	Type	Description	Default
`file_paths`	`List[Path]`	A list of paths to the PDF files to be converted.	required

Returns:

Name	Type	Description
`PdfAConvertRoute`	`Self`	This object itself for method chaining.

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

PDF Metadata¶

`gotenberg_client._pdfmetadata.routes.SyncReadPdfMetadataRoute` ¶

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`read_files(file_paths: list[Path]) -> Self` ¶

Adds all provided files for conversion to individual PDFs.

This method adds all files in the provided list for conversion. By default, the resulting PDFs will be zipped together in the response.

Parameters:

Name	Type	Description	Default
`file_paths`	`List[Path]`	A list of paths to the files to be converted.	required

Returns:

Name	Type	Description
`LibreOfficeConvertRoute`	`Self`	This object itself for method chaining.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`gotenberg_client._pdfmetadata.routes.AsyncReadPdfMetadataRoute` ¶

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`read_files(file_paths: list[Path]) -> Self` ¶

Adds all provided files for conversion to individual PDFs.

This method adds all files in the provided list for conversion. By default, the resulting PDFs will be zipped together in the response.

Parameters:

Name	Type	Description	Default
`file_paths`	`List[Path]`	A list of paths to the files to be converted.	required

Returns:

Name	Type	Description
`LibreOfficeConvertRoute`	`Self`	This object itself for method chaining.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`gotenberg_client._pdfmetadata.routes.SyncWritePdfMetadataRoute` ¶

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`gotenberg_client._pdfmetadata.routes.AsyncWritePdfMetadataRoute` ¶

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

Merge PDFs¶

`gotenberg_client._merge.routes.SyncMergePdfsRoute` ¶

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`flatten(*, flatten: bool = False) -> Self` ¶

Enables or disables flattening for the route options.

By default, flattening is disabled (flatten=False). This option controls whether to flatten PDF documents (e.g., remove page breaks).

Parameters:

Name	Type	Description	Default
`flatten`	`bool`	Whether to enable or disable flattening. - `True`: Enable flattening - `False` (default): Disable flattening	`False`

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`merge(files: list[Path]) -> Self` ¶

Add the given files to the merge operation.

This method maintains the ordering of the provided list of files. Note that calling this method multiple times may not result in the expected merge order.

For more details on merging PDFs with Gotenberg, see: https://gotenberg.dev/docs/routes#merge-pdfs-route

Parameters:

Name	Type	Description	Default
`files`	`List[Path]`	A list of Path objects representing the PDF files to be merged.	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance itself, allowing for method chaining.

Note

The files must be valid PDF documents.
The order of the files in the list determines the order in the merged PDF.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`gotenberg_client._merge.routes.AsyncMergePdfsRoute` ¶

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`flatten(*, flatten: bool = False) -> Self` ¶

Enables or disables flattening for the route options.

By default, flattening is disabled (flatten=False). This option controls whether to flatten PDF documents (e.g., remove page breaks).

Parameters:

Name	Type	Description	Default
`flatten`	`bool`	Whether to enable or disable flattening. - `True`: Enable flattening - `False` (default): Disable flattening	`False`

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`merge(files: list[Path]) -> Self` ¶

Add the given files to the merge operation.

This method maintains the ordering of the provided list of files. Note that calling this method multiple times may not result in the expected merge order.

For more details on merging PDFs with Gotenberg, see: https://gotenberg.dev/docs/routes#merge-pdfs-route

Parameters:

Name	Type	Description	Default
`files`	`List[Path]`	A list of Path objects representing the PDF files to be merged.	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance itself, allowing for method chaining.

Note

The files must be valid PDF documents.
The order of the files in the list determines the order in the merged PDF.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

Split PDFs¶

`gotenberg_client._others.routes.SyncSplitRoute` ¶

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`flatten(*, flatten: bool = False) -> Self` ¶

Enables or disables flattening for the route options.

By default, flattening is disabled (flatten=False). This option controls whether to flatten PDF documents (e.g., remove page breaks).

Parameters:

Name	Type	Description	Default
`flatten`	`bool`	Whether to enable or disable flattening. - `True`: Enable flattening - `False` (default): Disable flattening	`False`

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`split(file_path: Path) -> Self` ¶

Adds a single PDF file for splitting

`split_files(file_paths: list[Path]) -> Self` ¶

Adds multiple PDF files for splitting

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

Configures the splitting operation for the route options.

Parameters:

Name	Type	Description	Default
`mode`	`Literal['intervals', 'pages']`	The type of splitting operation. - `intervals`: Split into intervals - `pages`: Split into pages	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_span(span: str) -> Self` ¶

Configures the splitting span for the route options.

Parameters:

Name	Type	Description	Default
`span`	`str`	The splitting span. - Example: "1-3"	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_unify(*, split_unify: bool) -> Self` ¶

Enables or disables splitting for the route options.

Parameters:

Name	Type	Description	Default
`split_unify`	`bool`	Whether to enable or disable splitting. - `True`: Enable splitting - `False`: Disable splitting	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`gotenberg_client._others.routes.AsyncSplitRoute` ¶

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`disable_universal_access() -> Self` ¶

Disables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`enable_universal_access() -> Self` ¶

Enables PDF/UA for the route options.

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`flatten(*, flatten: bool = False) -> Self` ¶

Enables or disables flattening for the route options.

By default, flattening is disabled (flatten=False). This option controls whether to flatten PDF documents (e.g., remove page breaks).

Parameters:

Name	Type	Description	Default
`flatten`	`bool`	Whether to enable or disable flattening. - `True`: Enable flattening - `False` (default): Disable flattening	`False`

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`metadata(author: Optional[str] = None, pdf_copyright: Optional[str] = None, creation_date: Optional[datetime] = None, creator: Optional[str] = None, keywords: Optional[list[str]] = None, marked: Optional[bool] = None, modification_date: Optional[datetime] = None, pdf_version: Optional[float] = None, producer: Optional[str] = None, subject: Optional[str] = None, title: Optional[str] = None, trapped: Optional[Union[bool, TrappedStatus]] = None) -> Self` ¶

Sets PDF metadata for the document.

Parameters:

Name	Type	Description	Default
`author`	`Optional[str]`	Document author name	`None`
`pdf_copyright`	`Optional[str]`	Copyright information	`None`
`creation_date`	`Optional[datetime]`	Document creation date (Note: Gotenberg will override this)	`None`
`creator`	`Optional[str]`	Name of the creating application	`None`
`keywords`	`Optional[list[str]]`	List of keywords/tags for the document	`None`
`marked`	`Optional[bool]`	Whether the PDF is marked for structure	`None`
`modification_date`	`Optional[datetime]`	Last modification date (Note: Gotenberg will override this)	`None`
`pdf_version`	`Optional[float]`	PDF version number (Note: Gotenberg will override this)	`None`
`producer`	`Optional[str]`	Name of the PDF producer	`None`
`subject`	`Optional[str]`	Document subject/description	`None`
`title`	`Optional[str]`	Document title	`None`
`trapped`	`Optional[Union[bool, TrappedStatus]]`	Trapping status (bool or one of: 'True', 'False', 'Unknown')	`None`

Returns:

Type	Description
`Self`	Self for method chaining

Raises:

Type	Description
`InvalidPdfRevisionError`	If the provided PDF revision is outside the valid range
`InvalidKeywordError`	If any metadata keyword values are not allowed
`TypeError`	If any metadata values have incorrect types

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

All routes provide the option to configure the output PDF as a PDF/A format

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`split(file_path: Path) -> Self` ¶

Adds a single PDF file for splitting

`split_files(file_paths: list[Path]) -> Self` ¶

Adds multiple PDF files for splitting

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

Configures the splitting operation for the route options.

Parameters:

Name	Type	Description	Default
`mode`	`Literal['intervals', 'pages']`	The type of splitting operation. - `intervals`: Split into intervals - `pages`: Split into pages	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_span(span: str) -> Self` ¶

Configures the splitting span for the route options.

Parameters:

Name	Type	Description	Default
`span`	`str`	The splitting span. - Example: "1-3"	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`split_unify(*, split_unify: bool) -> Self` ¶

Enables or disables splitting for the route options.

Parameters:

Name	Type	Description	Default
`split_unify`	`bool`	Whether to enable or disable splitting. - `True`: Enable splitting - `False`: Disable splitting	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`universal_access(*, universal_access: bool) -> Self` ¶

Enables or disables PDF/UA based on the provided boolean value.

Parameters:

Name	Type	Description	Default
`universal_access`	`bool`	Whether to enable or disable PDF/UA. - `True`: Enable PDF/UA - `False`: Disable PDF/UA	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance with the updated form data.

Flatten PDFs¶

`gotenberg_client._others.routes.SyncFlattenRoute` ¶

Functions¶

`enter() -> Self` ¶

Enter the context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

Exit the context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`flatten(file_path: Path) -> Self` ¶

Adds a single PDF file for flattening

`flatten_files(file_paths: list[Path]) -> Self` ¶

Adds multiple PDF files for flattening

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request to Gotenberg and process the response.

Sends the request and returns an appropriate response object based on the content type of the response (either SingleFileResponse or ZipFileResponse).

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

Execute the API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`gotenberg_client._others.routes.AsyncFlattenRoute` ¶

Functions¶

`aenter() -> Self` `async` ¶

Enter the async context manager scope.

Resets the route state and returns the route instance.

Returns:

Name	Type	Description
`Self`	`Self`	The route instance.

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

Exit the async context manager scope.

Performs cleanup by calling close() to release resources.

Parameters:

Name	Type	Description	Default
`exc_type`	`Optional[type[BaseException]]`	The exception type, if an exception was raised.	required
`exc_val`	`Optional[BaseException]`	The exception instance, if an exception was raised.	required
`exc_tb`	`Optional[TracebackType]`	The traceback, if an exception was raised.	required

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

Initialize a new BaseRoute instance.

Parameters:

Name	Type	Description	Default
`client`	`ClientT`	The HTTP client used to connect to Gotenberg.	required
`route_url`	`str`	The URL of the specific Gotenberg route.	required
`log`	`Logger`	Logger for recording operations.	required

`close() -> None` ¶

Close and clean up resources used by this route.

This is an alias for reset().

`flatten(file_path: Path) -> Self` ¶

Adds a single PDF file for flattening

`flatten_files(file_paths: list[Path]) -> Self` ¶

Adds multiple PDF files for flattening

`output_filename(filename: str) -> Self` ¶

Set the desired output filename for the generated file.

Sets the Gotenberg-Output-Filename header to control the output filename. See documentation for more details.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The desired filename for the output file.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

`reset() -> None` ¶

Reset the route to its initial state.

Closes all context managers via the ExitStack and clears all set files, form data options, and route-specific headers.

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request and process the response.

Sends the request asynchronously and returns an appropriate response object based on the content type of the response.

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`Error`	Any errors from the HTTP client will be raised.

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

Execute the asynchronous API request with retries and process the response.

Combines post_data_with_retry() with response processing to provide a complete asynchronous operation with retry capability for server errors.

Parameters:

Name	Type	Description	Default
`max_retry_count`	`int`	Maximum number of retry attempts. Defaults to 5.	`5`
`initial_retry_wait`	`float or int`	Initial wait time in seconds. Defaults to 5.0.	`5.0`
`retry_scale`	`float or int`	Multiplier for wait time after each attempt. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`Union[SingleFileResponse, ZipFileResponse]`	SingleFileResponse or ZipFileResponse: A response object containing the result.

Raises:

Type	Description
`MaxRetriesExceededError`	If all retry attempts fail with server errors.
`HTTPStatusError`	If the request fails with a client error (4xx).

`trace_id(trace_id: str) -> Self` ¶

Set a trace ID for request tracing in Gotenberg.

Sets the Gotenberg-Trace header for request tracing. See documentation for more details.

Parameters:

Name	Type	Description	Default
`trace_id`	`str`	The trace ID to use for the request.	required

Returns:

Name	Type	Description
`Self`	`Self`	The route instance for method chaining.

Note

This setting will only be applied for the current route instantiation.

API Routes¶

Chromium¶

gotenberg_client._chromium.routes.SyncUrlToPdfRoute ¶

Functions¶

__enter__() -> Self ¶

__exit__(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None ¶

__init__(client: ClientT, route_url: str, log: logging.Logger) -> None ¶

background_graphics() -> Self ¶

close() -> None ¶

cookies(cookies: list[CookieJar]) -> Self ¶

disable_universal_access() -> Self ¶

dont_fail_on_exceptions() -> Self ¶

enable_universal_access() -> Self ¶

fail_on_console_exception(*, fail_on_console_exception: bool) -> Self ¶

fail_on_exceptions() -> Self ¶

footer(footer: Path) -> Self ¶

generate_document_outline(*, generate_document_outline: bool) -> Self ¶

header(header: Path) -> Self ¶

hide_background() -> Self ¶

margins(margins: PageMarginsType) -> Self ¶

media_type(media_type: Literal['print', 'screen']) -> Self ¶

no_background_graphics() -> Self ¶

omit_background(*, omit_background: bool) -> Self ¶

orient(orient: PageOrientation) -> Self ¶

output_filename(filename: str) -> Self ¶

page_ranges(ranges: str) -> Self ¶

pdf_format(pdf_format: PdfAFormat) -> Self ¶

prefer_css_page_size() -> Self ¶

prefer_set_page_size() -> Self ¶

print_background(*, print_background: bool) -> Self ¶

render_expression(expr: str) -> Self ¶

render_wait(wait: Union[float, int, timedelta]) -> Self ¶

reset() -> None ¶

run() -> Union[SingleFileResponse, ZipFileResponse] ¶

run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse] ¶

scale(scale: Union[float, int]) -> Self ¶

show_background() -> Self ¶

single_page(*, use_single_page: bool) -> Self ¶

size(size: PageSize) -> Self ¶

split_mode(mode: Literal['intervals', 'pages']) -> Self ¶

split_span(span: str) -> Self ¶

split_unify(*, split_unify: bool) -> Self ¶

trace_id(trace_id: str) -> Self ¶

universal_access(*, universal_access: bool) -> Self ¶

url(url: str) -> Self ¶

gotenberg_client._chromium.routes.AsyncUrlToPdfRoute ¶

Functions¶

__aenter__() -> Self async ¶

__aexit__(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None async ¶

__init__(client: ClientT, route_url: str, log: logging.Logger) -> None ¶

background_graphics() -> Self ¶

close() -> None ¶

cookies(cookies: list[CookieJar]) -> Self ¶

disable_universal_access() -> Self ¶

dont_fail_on_exceptions() -> Self ¶

enable_universal_access() -> Self ¶

fail_on_console_exception(*, fail_on_console_exception: bool) -> Self ¶

fail_on_exceptions() -> Self ¶

footer(footer: Path) -> Self ¶

generate_document_outline(*, generate_document_outline: bool) -> Self ¶

header(header: Path) -> Self ¶

hide_background() -> Self ¶

margins(margins: PageMarginsType) -> Self ¶

media_type(media_type: Literal['print', 'screen']) -> Self ¶

no_background_graphics() -> Self ¶

omit_background(*, omit_background: bool) -> Self ¶

orient(orient: PageOrientation) -> Self ¶

output_filename(filename: str) -> Self ¶

page_ranges(ranges: str) -> Self ¶

pdf_format(pdf_format: PdfAFormat) -> Self ¶

prefer_css_page_size() -> Self ¶

prefer_set_page_size() -> Self ¶

print_background(*, print_background: bool) -> Self ¶

render_expression(expr: str) -> Self ¶

render_wait(wait: Union[float, int, timedelta]) -> Self ¶

reset() -> None ¶

run() -> Union[SingleFileResponse, ZipFileResponse] async ¶

run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse] async ¶

scale(scale: Union[float, int]) -> Self ¶

show_background() -> Self ¶

`gotenberg_client._chromium.routes.SyncUrlToPdfRoute` ¶

`enter() -> Self` ¶

`exit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` ¶

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

`background_graphics() -> Self` ¶

`close() -> None` ¶

`cookies(cookies: list[CookieJar]) -> Self` ¶

`disable_universal_access() -> Self` ¶

`dont_fail_on_exceptions() -> Self` ¶

`enable_universal_access() -> Self` ¶

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

`fail_on_exceptions() -> Self` ¶

`footer(footer: Path) -> Self` ¶

`generate_document_outline(*, generate_document_outline: bool) -> Self` ¶

`header(header: Path) -> Self` ¶

`hide_background() -> Self` ¶

`margins(margins: PageMarginsType) -> Self` ¶

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

`no_background_graphics() -> Self` ¶

`omit_background(*, omit_background: bool) -> Self` ¶

`orient(orient: PageOrientation) -> Self` ¶

`output_filename(filename: str) -> Self` ¶

`page_ranges(ranges: str) -> Self` ¶

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

`prefer_css_page_size() -> Self` ¶

`prefer_set_page_size() -> Self` ¶

`print_background(*, print_background: bool) -> Self` ¶

`render_expression(expr: str) -> Self` ¶

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

`reset() -> None` ¶

`run() -> Union[SingleFileResponse, ZipFileResponse]` ¶

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` ¶

`scale(scale: Union[float, int]) -> Self` ¶

`show_background() -> Self` ¶

`single_page(*, use_single_page: bool) -> Self` ¶

`size(size: PageSize) -> Self` ¶

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

`split_span(span: str) -> Self` ¶

`split_unify(*, split_unify: bool) -> Self` ¶

`trace_id(trace_id: str) -> Self` ¶

`universal_access(*, universal_access: bool) -> Self` ¶

`url(url: str) -> Self` ¶

`gotenberg_client._chromium.routes.AsyncUrlToPdfRoute` ¶

`aenter() -> Self` `async` ¶

`aexit(exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) -> None` `async` ¶

`init(client: ClientT, route_url: str, log: logging.Logger) -> None` ¶

`background_graphics() -> Self` ¶

`close() -> None` ¶

`cookies(cookies: list[CookieJar]) -> Self` ¶

`disable_universal_access() -> Self` ¶

`dont_fail_on_exceptions() -> Self` ¶

`enable_universal_access() -> Self` ¶

`fail_on_console_exception(*, fail_on_console_exception: bool) -> Self` ¶

`fail_on_exceptions() -> Self` ¶

`footer(footer: Path) -> Self` ¶

`generate_document_outline(*, generate_document_outline: bool) -> Self` ¶

`header(header: Path) -> Self` ¶

`hide_background() -> Self` ¶

`margins(margins: PageMarginsType) -> Self` ¶

`media_type(media_type: Literal['print', 'screen']) -> Self` ¶

`no_background_graphics() -> Self` ¶

`omit_background(*, omit_background: bool) -> Self` ¶

`orient(orient: PageOrientation) -> Self` ¶

`output_filename(filename: str) -> Self` ¶

`page_ranges(ranges: str) -> Self` ¶

`pdf_format(pdf_format: PdfAFormat) -> Self` ¶

`prefer_css_page_size() -> Self` ¶

`prefer_set_page_size() -> Self` ¶

`print_background(*, print_background: bool) -> Self` ¶

`render_expression(expr: str) -> Self` ¶

`render_wait(wait: Union[float, int, timedelta]) -> Self` ¶

`reset() -> None` ¶

`run() -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

`run_with_retry(*, max_retry_count: int = 5, initial_retry_wait: Union[float, int] = 5.0, retry_scale: Union[float, int] = 2.0) -> Union[SingleFileResponse, ZipFileResponse]` `async` ¶

`scale(scale: Union[float, int]) -> Self` ¶

`show_background() -> Self` ¶

`single_page(*, use_single_page: bool) -> Self` ¶

`size(size: PageSize) -> Self` ¶

`split_mode(mode: Literal['intervals', 'pages']) -> Self` ¶

`split_span(span: str) -> Self` ¶