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¶
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¶
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 ofotherto the end of this document;otheris 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¶
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 aDocument.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:renderin 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¶
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¶
The base class of the engine's failures.
KolinskyFetchError¶
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.