Skip to content

Python API

pip install kolinsky installs the package for CPython 3.9 and later. Everything below is importable from kolinsky. The option names are those of the Rust crate and the command line; the guides show them in use.

Functions

render

kolinsky.render(src, *, base_url=None, stylesheets=(), options=None, pdf=None) -> Result

Engine().render(...) with the shared default engine.

render_async

async kolinsky.render_async(src, *, base_url=None, stylesheets=(), options=None, pdf=None) -> Result

Engine().render_async(...) with the shared default engine.

Classes

Attachment

kolinsky.Attachment(path, *, relationship='unspecified', name=None, description=None)

A file embedded in the PDF.

Attribute Type Description
path str
relationship str = 'unspecified'
name Optional[str] = None
description Optional[str] = None

Box

One box fragment of a page; lengths in pt, page coordinates.

Attribute Type Description
kind str
x float
y float
width float
height float
element Optional[Element]
pseudo Optional[str]
text Optional[str]
children List[Box]
rect Tuple[float, float, float, float] The border box as (x, y, width, height).

Diagnostic

A problem found by a call.

Attribute Type Description
severity str
code str
message str
url Optional[str] = None
source Optional[str] = None
line Optional[int] = None
column Optional[int] = None
category Optional[str] The strict-mode category of the code, or None.

Document

A laid-out document.

Attribute Type Description
page_count int The number of pages.
pages Tuple[Page, ...] The pages in order.
  • query(selector) -> List[Match]: The boxes whose element matches the selector list, by page and then tree order.
  • append(other) -> None: Moves the pages of other to the end of this document; other is used up.
  • to_pdf(**pdf) -> Result: The PDF with the PDF options given as keywords.
  • write_pdf(target, **pdf) -> Tuple[Diagnostic, ...]: Writes the PDF to a path (replaced once the PDF is complete) or a binary file object.

Element

The element that generated a box.

Attribute Type Description
tag str
id Optional[str] = None

Engine

kolinsky.Engine(*, fonts=(), system_fonts=True, fetcher=None)

The rendering engine. One engine can be used from several threads at once.

  • layout(src, *, base_url=None, stylesheets=(), options=None) -> Document: Lays out the source into a Document.
  • render(src, *, base_url=None, stylesheets=(), options=None, pdf=None) -> Result: Lays out and writes the source in one call.
  • async render_async(src, *, base_url=None, stylesheets=(), options=None, pdf=None) -> Result: render in a worker thread; cancelling the awaiting task does not stop it.

Match

A box matched by Document.query.

Attribute Type Description
page_index int
box Box

Options

kolinsky.Options(media='print', author_styles=True, page_size=None, margin=None, allow_network=False, root=None, timeout=30.0, max_resource_size=67108864, strict=False)

The render options.

Attribute Type Description
media str = 'print'
author_styles bool = True
page_size Optional[str] = None
margin Optional[str] = None
allow_network Union[bool, Tuple[str, ...]] = False
root Union[str, os.PathLike, None] = None
timeout float = 30.0
max_resource_size int = 67108864
strict Union[bool, Tuple[str, ...]] = False

Page

A page of a laid-out document.

Attribute Type Description
index int
width float
height float
name Optional[str]
  • boxes() -> List[Box]: The top-level boxes: the root element's box, the margin boxes, then the footnote area.

PdfOptions

kolinsky.PdfOptions(title=None, authors=None, subject=None, keywords=None, language=None, creation_date=None, standards=(), tagged=False, outline=False, pages=None, attachments=(), deterministic=False)

The PDF options.

Attribute Type Description
title Optional[str] = None
authors Optional[Tuple[str, ...]] = None
subject Optional[str] = None
keywords Optional[Tuple[str, ...]] = None
language Optional[str] = None
creation_date Optional[datetime.datetime] = None
standards Tuple[str, ...] = ()
tagged bool = False
outline bool = False
pages Optional[str] = None
attachments Tuple[Union[Attachment, str, os.PathLike], ...] = ()
deterministic bool = False

Request

One resource the engine asks a fetcher for.

Attribute Type Description
url str The absolute URL asked for.
kind str What the resource is for: document, stylesheet, image, font or attachment.
  • default(url=None) -> Resource: Fetches the URL, or another URL, with the default fetcher and the render's access policy.

Resource

kolinsky.Resource(data, content_type=None, url=None)

A resource returned by a fetcher.

Attribute Type Description
data bytes
content_type Optional[str] = None
url Optional[str] = None

Result

The PDF bytes of a render and the diagnostics of the call.

Attribute Type Description
pdf bytes
diagnostics Tuple[Diagnostic, ...] = ()

Url

Marks a string as a URL source, base URL or stylesheet.

Exceptions

KolinskyError

kolinsky.KolinskyError(message, *, diagnostics=())

The base class of the engine's failures.

KolinskyFetchError

kolinsky.KolinskyFetchError(message, *, kind='failed', url=None, diagnostics=())

A resource that cannot be loaded. Subclass of KolinskyError.

KolinskyParseError

An option value, a query selector or font data that does not parse. Subclass of KolinskyError, ValueError.

KolinskyPdfError

The PDF cannot be produced. Subclass of KolinskyError.

KolinskyStrictError

Strict mode turned diagnostics into an error. Subclass of KolinskyError.

__version__

The version of the package, a str.