Sync vs Async Compilation

Sync vs Async Compilation

Sync — client.compile()

Blocks until the PDF is ready.

result = client.compile(latex)
Path("out.pdf").write_bytes(result.pdf)

Use sync when:

• Document compiles in < 30 seconds
• You want simple, sequential code
• Building a web endpoint that returns the PDF inline

Async — client.async_compile() + client.wait_for_job()

Submit and get a job ID immediately. Poll separately.

# 1. Submit — returns instantly
job = client.async_compile(latex, engine="lualatex")
print(job.job_id, job.status)  # "abc-123", "pending"

# 2. Wait (polls automatically every 2 seconds)
result = client.wait_for_job(job.job_id)
Path("out.pdf").write_bytes(result.pdf)

Use async when:

• Large documents (books, theses)
• Batch processing many documents
• You want to show progress to the user
• You need to decouple submission from retrieval

Manual Polling

import time

job = client.async_compile(latex)

while True:
    status = client.get_job(job.job_id)

    if status.status == "completed":
        pdf = client.get_job_pdf(job.job_id)  # one-time download
        Path("out.pdf").write_bytes(pdf)
        break

    if status.status == "failed":
        print(f"Failed: {status.error}")
        print(f"Log: {status.log}")
        break

    print(f"Status: {status.status} — waiting...")
    time.sleep(2)

Job Lifecycle

submitted → pending → processing → completed
                                 → failed

• pending — queued, not yet started
• processing — engine is running
• completed — PDF ready for one-time download
• failed — LaTeX error or timeout; check status.log

Convenience: compile_to_file

Skip the result object and write directly:

client.compile_to_file(latex, "output.pdf")
client.compile_to_file(latex, "output.pdf", engine="xelatex")
client.compile_to_file(latex, "output.pdf", smart=True)  # auto-detect engine

Cleanup

PDFs auto-delete after the first get_job_pdf() call. Explicit cleanup:

client.delete_job(job_id)

Comparison

	compile()	async_compile()
Returns	PDF immediately	Job ID immediately
Blocks caller	Yes	No
Best for	< 30s docs	Large / batch
Poll required	No	Yes