Execution options: Why are there differences between syntax options?

[floholl]

Description

I am trying to include Python code blocks in Quarto documents that

• show the source code
• but also its results
• while displaying a filename for the code.

However, this only works for specifying the filename option as a "special comment" (see below), but not for specifying it as an option right next to {python filename="..."}. I wonder why?

Steps to reproduce

1. Save the following Quarto document to my.qmd:

# Works: Print code with filename & without result

```{.python filename="my.py"}
sum = 0
i = 1
     
while i <= 100: 
    if i % 2 == 0: 
        sum += i 
    i += 1 
     
print('The sum of all even numbers between 1 and 100 is:', sum)
```


# Works: Print Python code with result & without filename

```{python}
sum = 0
i = 1
     
while i <= 100: 
	if i % 2 == 0: 
		sum += i 
	i += 1 
     
print('The sum of all even numbers between 1 and 100 is:', sum)
```


# Does not work (why?): Print code with result & with filename

Specifically, the **result is printed, but the `filename` option is being ignored**. Why?

```{python filename="my.py"}
sum = 0
i = 1
     
while i <= 100: 
    if i % 2 == 0: 
        sum += i 
    i += 1 
     
print('The sum of all even numbers between 1 and 100 is:', sum)
```


# Works: Specify filename as "special comment" instead

If I specify the `filename` execution option as a "special comment", it works, however,
i.e., source code, result, and filename are all being printed:

```{python}
#| filename: my.py

sum = 0
i = 1
     
while i <= 100: 
    if i % 2 == 0: 
        sum += i 
    i += 1 
     
print('The sum of all even numbers between 1 and 100 is:', sum)
```

2. Render via

   quarto render my.qmd --to html
   

3. View resulting my.html in a browser

Why do the last two examples behave differently?

I guess more generally, I am confused about the difference between specifying execution options as

• "special comments" (as in the last example in the .qmd document above) vs.
• right after {python filename="my.py"} (as in the penultimate example in the .qmd document above).

I am guessing that this is not really a bug, but due to some fundamental difference between these two syntax options that I do not understand. In general, I find the latter a little easier to read (which is why I'd prefer to use it), but clearly there are differences between these two? Are these documented anywhere on https://quarto.org? What is the reason for these differences?

Output of quarto check for reference

Quarto 1.6.42
[✓] Checking environment information...
      Quarto cache location: /home/flo/.cache/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.4.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.46.3: OK
      Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.6.42
      Path: /opt/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: (not installed)
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Using: Installation From Path
      Path: /usr/bin
      Version: 2024

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.12.7
      Path: /usr/bin/python3
      Jupyter: 5.7.2
      Kernels: python3

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........OK
      Version: 4.4.1
      Path: /usr/lib/R
      LibPaths:
        - /usr/local/lib/R/site-library
        - /usr/lib/R/site-library
        - /usr/lib/R/library
      knitr: 1.48
      rmarkdown: 2.27

[✓] Checking Knitr engine render......OK

[mcanouil]

Could you properly format your post using code blocks for code and terminal outputs? Thanks.
If your code contains code blocks, you need to enclose it using more backticks, i.e., usually four ````.
See https://quarto.org/bug-reports.html#formatting-make-githubs-markdown-work-for-us.

[floholl]

Ah, yes, sorry, the whole thing had meant to be a single .qmd MWE, but I had forgotten to enclose it in a code block accordingly. ut I've now edited to better separate MWE from actual question content - hopefully this works?

[cderv]

Let me try to clarify the context

```{.python filename="my.py"}
```

this syntax is not related to execution. So this is not execution options.
This syntax is for source code cell and they can take language as class, and some attribute. This is inherited from Pandoc and its fenced_code_attributes extension.

The attributes you can set on those code cells are not the same as the ones for execution. Some can be common, mainly the one you can set on the execution cell that maps to a source code attribute (like filename)

```{python}
```

This syntax is from Quarto and is used for execution. It is a different syntax. In Quarto, options for execution are passed using special comments with YAML.

You can't pass options to execution using {python option="value"} with Jupyter engine. Though you say about

In general, I find the latter a little easier to read (which is why I'd prefer to use it),

Do you have an example using a Python cell where this is working for execution options?

Regarding the {.python} and {python}Fundamentally, these are different syntax

• Source code: https://quarto.org/docs/authoring/markdown-basics.html#source-code
• Computation code blocks: https://quarto.org/docs/computations/python.html#code-blocks

They are not processed the same. For computation, you typically set much more options than in the source code.
The in-cell YAML syntax for passing options is more readable than the attributes one. This allows Quarto to offer nice features like auto-completion for options and YAML validation, too.

Some attributes like filename could be useful to set on source code in output after execution (when echo: true). This is why some attributes like this one are also available as options for computation

```{python}
#| filename: my.py
```

Hope it helps clarify; Happy to give more details if needed.

[floholl]

Thanks for this excellent answer, which really helped to solidify my previously vague assumptions about what exactly what was going on here!

In retrospect, I think I must have been under the incorrect assumptions that

• {python}, {.python}, and {=python} were flavors of essentially the same thing,
• that the presence/absence of a preceding dot or equal sign merely controlled the respective inclusion of source code and result in the printout (whereas I now understand that the equal sign treats the code as raw content, and
• that any options could somewhat interchangeably be either defined as "special comments" or directly on the {python} / {.python} / {=python} line.

For me, the key information was that it is the presence absence of a preceding dot that (a) signifies that a completely different syntax applies, which (b) requires the specification of all options as "special comments".

I wonder whether these points could perhaps be made more explicit in the Quarto documentation somehow? If I think about how, then I note that what might have contributed to my confusion is that the documentation on Quarto-style computation code blocks says that

Code blocks that use braces around the language name (e.g. ```{python}) are executable [...]

while the documentation of Pandoc-style source code notes that

Equivalent to the short form used in the examples above is a longer form that uses the language as a class (i.e. .python) inside braces: [...]

Thus, two ideas:

1. Perhaps the documentation of Quarto-style computation code blocks could focus less on the presence of braces and more on the presence absence of a preceding dot as the defining criterion of such code blocks?
2. Perhaps the documentation of execution options could be more explicit about the respective differences in how to specify options for Pandoc-style source code vs. Quarto-style computation code blocks?

Again, many thanks for taking the time to write up such a comprehensive response!

[cderv]

Perhaps the documentation of Quarto-style computation code blocks could focus less on the presence of braces and more on the presence of a preceding dot as the defining criterion of such code blocks?

The computation code block does not have a preceding dot. Is that what you suggest highlighting instead of braces?

Perhaps the documentation of execution options could be more explicit about the respective differences in how to specify options for Pandoc-style source code vs. Quarto-style computation code blocks?

I'll think of something. If you gave idea of wording, feel free to submit a PR.

Again, many thanks for taking the time to write up such a comprehensive response!

You're welcome !

[floholl]

Ah, yes, sorry, I got confused... to highlight the absence of a preceding dot as the defining criterion of such code blocks is what I mean. I have corrected this now in the original comment.

Yes, I'll see whether I can think of suitable wording to submit in a PR.