drawlib.tools

drawlib.tools exposes the lazy-loaded programmatic Python developer API powering the drawlib CLI. Use its 28 functions to embed multi-locale HTML, Markdown, PDF, MS Word (.docx), HTML Slide, and MS PowerPoint (.pptx) compilation, single-block diagram export, project/agent scaffolding, broken-link scanning, CSS preset synthesis, and asset cache management directly into Python automation scripts, CI/CD pipelines, and pytest suites.

from drawlib.canvas import save, setup
from drawlib.icons import phosphor
from drawlib.shapes import rectangle
from drawlib.smartarts import BoxList, ChevronProcess
from drawlib.styles import Colors, Styles
from drawlib.text import text

setup(width=134, height=62)

rectangle(
    (67, 31),
    width=124,
    height=52,
    style=Styles.Neutral.patch(shape_fill_color=Colors.Transparent, line_style="dashed", shape_r=2.5),
)
text(
    (67, 53.0),
    "drawlib.tools · Programmatic Automation & Build Pipeline (28 Functions)",
    style=Styles.DarkBold.patch(text_size=11.5),
)

stage_icons = [
    (22.5, phosphor.folder_open, Styles.PrimaryBold),
    (51.5, phosphor.gear_six, Styles.PrimaryBold),
    (80.5, phosphor.magnifying_glass, Styles.PrimaryBold),
    (109.5, phosphor.check_circle, Styles.SecondaryBold),
]
for ix, icon_fn, ist in stage_icons:
    icon_fn((ix, 46.2), width=4.4, style=ist)

pipeline = ChevronProcess(
    style=Styles.Neutral,
    text_style=Styles.DarkBold.patch(text_size=10.5),
    description_style=Styles.Dark.patch(text_size=10.0),
    corner_angle=60.0,
    spacing=1.8,
    flat_left_end=True,
)
pipeline.add("1. Scaffold", description="init_project()")
pipeline.add(
    "2. Compile",
    description="build_html / pdf()",
    style=Styles.PrimaryFlat,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
    description_style=Styles.White.patch(text_size=10.0),
)
pipeline.add("3. Inspect", description="export_code_block()", style=Styles.PrimaryNeutral)
pipeline.add("4. Verify", description="scan_broken_links()", style=Styles.SecondaryNeutral)
pipeline.draw(xy=(10.0, 26.0), width=114.0, height=16.5)

domains = BoxList(
    style=Styles.Neutral,
    text_style=Styles.DarkBold.patch(text_size=10.0),
)
domains.add("HTML / API\nbuild_html()")
domains.add("PDF & Word\nbuild_pdf / docx()")
domains.add("Slide & PPTX\nbuild_slide / pptx()")
domains.add("Agent Rules\ninit_agent_*()")
domains.add("Cache & CSS\ndownload / get_css()", style=Styles.SecondaryNeutral)
domains.draw(xy=(10.0, 8.5), box_width=22.8, box_height=13.0, direction="left")

save()

defbuild_document(input_dir, output_path=None, output_format=None, *, ...)#

Unified dispatcher that compiles a documentation directory into HTML, PDF, MS Word (.docx), or GitHub-Flavored Markdown based on output_format or the file extension of output_path.

from drawlib.tools import build_document

build_document(
    input_dir: str,
    output_path: str | None = None,
    output_format: str | None = None,
    *,
    image_format: str = "png",
    css_mode: str = "external",
    styles_path: str | None = None,
    utils_path: str | None = None,
    no_cache: bool = False,
    timestamp: bool = False,
) -> str

• Returns (str): Absolute path of the generated output directory or file.

defbuild_docx(input_path=None, output_file=None, *, ...)#

Compile a linear doc project directory (emitting <base>_<lang>.docx per configured locale) or a standalone Markdown file (.md) into a native editable Microsoft Word (.docx) document via python-docx.

from drawlib.tools import build_docx

build_docx(
    input_path: str | None = None,
    output_file: str | None = None,
    *,
    input_dir: str | None = None,
    title: str | None = None,
    page_break: bool = True,
    generate_index: bool = False,
    dpi: int = 200,
    styles_path: str | None = None,
    utils_path: str | None = None,
    no_cache: bool = False,
    timestamp: bool = False,
) -> str

• Returns (str): Absolute path to the generated .docx file (or default_lang .docx for doc projects).

defbuild_html(input_dir, output_dir=None, *, ...)#

Compile an i18n-native site, doc, or catalog project directory (drawlib.toml + <lang>/ sources) into static HTML with shared diagram deduplication, per-locale stylesheets, language switcher navigation (when 2+ locales are configured), and a root index.html.

from drawlib.tools import build_html

build_html(
    input_dir: str,
    output_dir: str | None = None,
    *,
    image_format: str = "png",
    styles_path: str | None = None,
    utils_path: str | None = None,
    no_cache: bool = False,
    css_mode: str = "external",
) -> str

• Returns (str): Absolute path of the generated HTML output directory.

defbuild_image(input_path, output_path=None, *, ...)#

Execute one or more standalone Python drawing scripts (.py), script directories, or project Markdown directories in batch mode to render image assets, performing static AST collision checks prior to execution.

from drawlib.tools import build_image

build_image(
    input_path: str | Sequence[str],
    output_path: str | None = None,
    *,
    format: Literal["png", "webp", "jpg", "pdf"] | None = None,
    styles_path: str | None = None,
    utils_path: str | None = None,
    grid: bool = False,
    disable_auto_clear: bool = False,
    enable_auto_initialize: bool = False,
    no_cache: bool = False,
) -> list[str]

• Returns (list[str]): List of executed target file paths.

defbuild_markdown(input_dir, output_dir=None, *, ...)#

Compile an i18n-native site, doc, or catalog project directory into GitHub-Flavored Markdown (<output_dir>/<lang>/ + shared <output_dir>/images/), refusing in-place source overwrites.

from drawlib.tools import build_markdown

build_markdown(
    input_dir: str,
    output_dir: str | None = None,
    *,
    image_format: str = "png",
    styles_path: str | None = None,
    utils_path: str | None = None,
    no_cache: bool = False,
) -> str

• Returns (str): Absolute path of the generated Markdown output directory.

defbuild_pdf(input_path=None, output_file=None, *, ...)#

Compile a doc project directory, slide project directory, or standalone Markdown/HTML file into print-ready vector PDF(s) via headless Chromium (playwright). Project directory builds emit <base>_<lang>.pdf for every configured locale.

from drawlib.tools import build_pdf

build_pdf(
    input_path: str | None = None,
    output_file: str | None = None,
    *,
    input_dir: str | None = None,
    title: str | None = None,
    page_break: bool = True,
    generate_index: bool = False,
    styles_path: str | None = None,
    utils_path: str | None = None,
    no_cache: bool = False,
    timestamp: bool = False,
) -> str

• Returns (str): Absolute path of the generated PDF file (or default_lang PDF for project directories).

defbuild_pptx(input_dir, output_file=None, *, ...)#

Compile an i18n-native Markdown slide project directory into native editable 16:9 (960×540 pt) Microsoft PowerPoint (<stem>_<lang>.pptx) decks (re-exported from drawlib.slide).

from drawlib.tools import build_pptx

build_pptx(
    input_dir: str,
    output_file: str | None = None,
    *,
    title: str | None = None,
    theme: str | None = None,
    dpi: int = 240,
    anim_frame: Literal["first", "last"] = "last",
    styles_path: str | None = None,
    utils_path: str | None = None,
    no_cache: bool = False,
    timestamp: bool = False,
) -> str

• Returns (str): Absolute path to the generated <stem>_<default_lang>.pptx file.

defbuild_slide(input_dir, output_dir=None, *, ...)#

Compile an i18n-native presentation project directory into a standalone multi-locale 16:9 HTML slide deck (re-exported from drawlib.slide).

from drawlib.tools import build_slide

build_slide(
    input_dir: str,
    output_dir: str | None = None,
    *,
    title: str | None = None,
    theme: str | None = None,
    image_format: str = "svg",
    dpi: int | None = None,
    force_image_format: bool = False,
    static_anim_frame: Literal["first", "last"] | None = None,
    styles_path: str | None = None,
    utils_path: str | None = None,
    no_cache: bool = False,
) -> str

• Returns (str): Absolute path to <output_dir>/<default_lang>/index.html.

defclear_cache()#

Delete all locally cached font, icon, and GeoJSON map asset archives downloaded from GitHub Releases.

from drawlib.tools import clear_cache

clear_cache() -> None

defdetect_agent_targets(destination=".")#

Inspect a workspace root directory for existing AI coding agent configuration directories or instruction files (.agents/, .agent/, .claude/, .cursor/, .github/instructions/, .windsurf/, .clinerules/, .roo/, AGENTS.md, GEMINI.md) and return their canonical agent names.

from drawlib.tools import detect_agent_targets

detect_agent_targets(
    destination: str | Path = ".",
) -> list[str]

• Returns (list[str]): Canonical names of detected AI coding agents in deterministic order (e.g., ["antigravity", "claude"]).

defdetect_document_type(file_path, content=None)#

Classify a Markdown (.md, .markdown) or HTML (.html, .htm) file into one of four canonical document types ("markdown_drawlib", "markdown", "html_drawlib", or "html").

from drawlib.tools import detect_document_type

detect_document_type(
    file_path: str,
    content: str | None = None,
) -> DocumentInputInfo

• Returns (DocumentInputInfo): Frozen Pydantic model with fields path, doc_type, has_drawlib, is_markdown, is_html, is_full_html, and block_count.

defdownload_cache(all_assets=True, fonts=False, icons=False, maps=False, browser=False)#

Pre-download font, icon, GeoJSON map packages, and/or headless Chromium (chromium-headless-shell) into the local cache for offline, Docker, or CI/CD environments.

from drawlib.tools import download_cache

download_cache(
    all_assets: bool = True,
    fonts: bool = False,
    icons: bool = False,
    maps: bool = False,
    browser: bool = False,
) -> None

defexport_code_block(file_path=None, target=None, output_path=None, ...)#

Headlessly execute a single drawlib block from a Markdown/HTML file (matched by filename file=... or 1-based block index) or execute a standalone .py script and save the rendered image to disk without opening a GUI window.

from drawlib.tools import export_code_block

export_code_block(
    file_path: str | None = None,
    target: str | None = None,
    output_path: str | None = None,
    styles_path: str | None = None,
    utils_path: str | None = None,
    grid: bool = False,
    no_cache: bool = False,
) -> str

• Returns (str): Absolute path of the exported image file (or "" when listing blocks).

defexport_css(name, output_path=None, target="html", force=False, lang="en")#

Synthesize and write a built-in CSS theme preset to a file on disk.

from drawlib.tools import export_css

export_css(
    name: str,
    output_path: str | None = None,
    target: CssTarget = "html",
    force: bool = False,
    lang: str = "en",
) -> str

• Returns (str): Absolute path of the written CSS file.

defget_agent_instruction(agent, mode="auto", global_scope=False)#

Render the complete Drawlib instruction Markdown/MDC text (including any tool-specific YAML frontmatter) in memory for a target AI coding agent.

from drawlib.tools import get_agent_instruction

get_agent_instruction(
    agent: str,
    mode: AgentTriggerMode = "auto",
    global_scope: bool = False,
) -> str

• Returns (str): Complete formatted instruction string.

defget_css(name=None, target="html", lang="en")#

Synthesize and return a complete standalone CSS stylesheet string combining theme tokens, UI components, and target layout rules.

from drawlib.tools import get_css

get_css(
    name: str | None = None,
    target: CssTarget = "html",
    lang: str = "en",
) -> str

• Returns (str): Synthesized CSS stylesheet text.

definit_agent_instruction(agent, destination=".", mode="auto", ...)#

Write per-agent Drawlib instruction files into modular rule directories (.agents/rules/, .claude/rules/, .cursor/rules/, .github/instructions/, .windsurf/rules/, .clinerules/, .roo/rules/) or non-destructively merge marker-delimited sections into shared AGENTS.md / GEMINI.md files.

from drawlib.tools import init_agent_instruction

init_agent_instruction(
    agent: str | Sequence[str],
    destination: str | Path = ".",
    mode: AgentTriggerMode = "auto",
    global_scope: bool = False,
    output_path: str | Path | None = None,
    force: bool = False,
) -> list[Path]

• Returns (list[Path]): Resolved Path objects of created or updated instruction files.

definit_project(project_type, destination=".", target=None, ...)#

Scaffold a starter Drawlib project (<target>_src/) pre-configured with drawlib.toml, styles.py, utils.py, _assets/, stylesheets/templates, and executable build*.sh scripts.

from drawlib.tools import init_project

init_project(
    project_type: str,
    destination: str | Path = ".",
    target: str | None = None,
    output: str | None = None,
    force: bool = False,
    lang: str = "en",
    style: str | None = None,
    here: bool = False,
) -> list[Path]

• Returns (list[Path]): List of scaffolded Path objects.

deflist_agent_targets()#

Return metadata dictionaries describing all supported AI coding agent instruction targets.

from drawlib.tools import list_agent_targets

list_agent_targets() -> list[dict[str, str]]

deflist_cache()#

Inspect all downloadable font, icon, and GeoJSON map asset packages alongside their local cache status and disk usage.

from drawlib.tools import list_cache

list_cache() -> list[dict[str, Any]]

deflist_css(target="html")#

Return metadata dictionaries for all built-in CSS theme presets available for target.

from drawlib.tools import list_css

list_css(
    target: CssTarget = "html",
) -> list[dict[str, str]]

• Returns (list[dict[str, str]]): Preset dictionaries containing "name", "file", and "description".

deflist_html_css()#

Convenience wrapper returning metadata dictionaries ("name", "file", "description") for all built-in HTML CSS presets (list_css(target="html")).

from drawlib.tools import list_html_css

list_html_css() -> list[dict[str, str]]

deflist_pdf_css()#

Convenience wrapper returning metadata dictionaries ("name", "file", "description") for all built-in PDF CSS presets (list_css(target="pdf")).

from drawlib.tools import list_pdf_css

list_pdf_css() -> list[dict[str, str]]

deflist_project_types()#

Return a mapping of all supported starter project archetype names ("site", "catalog", "doc", "slide", "images") to their human-readable descriptions.

from drawlib.tools import list_project_types

list_project_types() -> dict[str, str]

deflist_slide_css()#

Convenience wrapper returning metadata dictionaries ("name", "file", "description") for all built-in presentation slide CSS presets (list_css(target="slide")).

from drawlib.tools import list_slide_css

list_slide_css() -> list[dict[str, str]]

defscan_broken_links(root_dir)#

Recursively scan all built .html files inside root_dir to verify internal relative links, #slug fragment anchors, and referenced static/diagram assets.

from drawlib.tools import scan_broken_links

scan_broken_links(
    root_dir: str,
) -> tuple[int, int, list[tuple[str, str, str]]]

• Returns (tuple[int, int, list[tuple[str, str, str]]]): (total_html_files, total_links_checked, broken_links), where each entry in broken_links is (html_rel_path, tag_name, target_url).

defserve_docs(directory, port=8000, open_browser=True, skip_check=False, check_only=False)#

Run the local HTTP preview server serving static HTML files from directory, or perform a headless pre-flight broken-link scan and exit when check_only=True.

from drawlib.tools import serve_docs

serve_docs(
    directory: str,
    port: int = 8000,
    open_browser: bool = True,
    skip_check: bool = False,
    check_only: bool = False,
) -> None

defshow_code_block(file_path=None, target=None, styles_path=None, ...)#

Execute a drawlib block from a Markdown/HTML file or a standalone .py script and open the rendered image in a desktop GUI viewer (or delegate to headless export_code_block() when output_path is provided).

from drawlib.tools import show_code_block

show_code_block(
    file_path: str | None = None,
    target: str | None = None,
    styles_path: str | None = None,
    utils_path: str | None = None,
    grid: bool = False,
    output_path: str | None = None,
    no_cache: bool = False,
) -> None