How can I render one (or multiple) qmd documents from a Python script?

[nimoralesp]

Description

I'm mostly an R user, and I know that I can render one/multiple documents from a .R script using the Quarto library with a code like this:

library(quarto)

# Rendering a .docx
quarto_render(
  input = "quarto-file.qmd"
  , output_format = "docx"
  , output_file = "report-name.docx"
  , execute_params = list(format = list(docx = list("reference-doc" = "template.docx")))
)

I'd like to know if there's a Python library to do this. I saw a Quarto package for Python but I didn't find the functions.

[cscheid]

I'd like to know if there's a Python library to do this.

Not a particularly well-supported one, unfortunately. It's simple enough to use python's subprocess library and call subprocess.run, though: https://docs.python.org/3/library/subprocess.html

[mcanouil]

What's the context of needing Python?

Because Quarto CLI is independent of the language and is a CLI, it means you can use Bash/PowerShell to run Quarto using for loops, YAML parameters in files, etc.

[edalfon]

I was exactly in the same situation as @nimoralesp, so here's my use case to answer this ...

What's the context of needing Python?

I have a pipeline orchestrated by Prefect, which is a python-centric workflow orchestration tool (sort of like R's targets). The pipeline is a pretty standard thing; extract some data from a DB, clean and process it, then run some models. In several of those steps, we would build a report, a dashboard or similar. Quarto certainly excels for those tasks. So we basically would like to just add rendering those reports/dashboards as part of the pipeline, so that they will be updated whenever the upstream dependencies change.

Because Quarto CLI is independent of the language and is a CLI, it means you can use Bash/PowerShell to run Quarto using for loops, YAML parameters in files, etc.

So yeah, we can certainly go and manually run quarto render on the command line. But that just feels anticlimactic. Since all the pipeline is written in python, it just feels natural to want to render the reports from python. And it would be a breeze to integrate quarto in such data processing pipelines if something like import quarto; quarto.render(file_or_project_qmd) were possible.

In R, this is pretty straightforward because you can render Quarto docs/projects from within the R code. The equivalent of our Python use case in R is simply a {targets} pipeline. You add a target that renders the document, and that target depends on the upstream steps of data extraction and cleaning. It would be great to be able to do the same in Python. (Yes, I suppose subprocess kinda works, but it feels unnecessarily hacky.)

[mcanouil]

I did not say to run Quarto manually.
You can call CLI from Python.
Take a look at https://github.com/mcanouil/generate-quarto-invoices/blob/main/generate-invoices.py

(Yes, I suppose subprocess kinda works, but it feels unnecessarily hacky.)

There is no other way to call external programs.

R/targets uses the exact same process, though the wrapper is https://github.com/quarto-dev/quarto-r.
In the end, it is still calling Quarto CLI. So, yes you don't use system/subprocess yourself, but you do use a function that does that.

FYI, there is some work in progress to have a Python wrapper as well: https://github.com/quarto-dev/quarto-cli-pypi.
There is/was https://github.com/quarto-dev/quarto-python but I don't know the status. It might not get all the new subcommands and flags mapped.

[cderv]

There is/was quarto-dev/quarto-python but I don't know the status. It might not get all the new subcommands and flags mapped.

This is the source code of the quarto python interface on pypi : https://pypi.org/project/quarto/

It probably is not supporting all new commands indeed as it was not updated since a long time. We'll update to make it more generic and future-proof on new version.

[edalfon]

I did not say to run Quarto manually. You can call CLI from Python. Take a look at https://github.com/mcanouil/generate-quarto-invoices/blob/main/generate-invoices.py

my bad!, I saw Bash/PowerShell and I certainly thought you meant do it manually ;)

(Yes, I suppose subprocess kinda works, but it feels unnecessarily hacky.)

There is no other way to call external programs.

R/targets uses the exact same process, though the wrapper is https://github.com/quarto-dev/quarto-r. In the end, it is still calling Quarto CLI. So, yes you don't use system/subprocess yourself, but you do use a function that does that.

FYI, there is some work in progress to have a Python wrapper as well: https://github.com/quarto-dev/quarto-cli-pypi.

Great to hear a wrapper is in progress!!!. My main concern of using subprocess was how to make sure it works in the correct environment and so on. I haven't tried, though. So I am just not sure. But in my mind, I kinda anticipated issues with that, particularly, when you move your pipeline from the local context and you deploy it somewhere else.

[mcanouil]

Great to hear a wrapper is in progress!!!. My main concern of using subprocess was how to make sure it works in the correct environment and so on. I haven't tried, though. So I am just not sure. But in my mind, I kinda anticipated issues with that, particularly, when you move your pipeline from the local context and you deploy it somewhere else.

Well, this possible issue doesn't go away even when using an official wrapper.
For instance, if Quarto is not in the PATH, then the R/Python wrappers will have a very hard time to locate it. There are some fallbacks, but if a user install Quarto manually in a non standard directory without adding it to the PATH, then you get the issue and there is nothing Quarto devs can do to guess what exotic things users did.

Take a look at the code: https://github.com/quarto-dev/quarto-python/blob/main/quarto/render.py
There is nothing fancy, it's a call using subprocess.