What is the intended use of {.python}?

[alan-isaac]

Description

---
title: "Reproducible Quarto Document"
format:
  html:
    code-annotations: true
engine: jupyter
---

I am new to Quarto. It is great, but I'm not understanding the intended functionality of the python class annotation.
I expected to be able to toggle code to not execute by changing `python` to `.python`,
but this is only partially true. 

```{python}
#| lst-label: lst-import
#| lst-cap: A Test

print("This is a test.")  # <1>
```

1. just a test

```{.python}
#| lst-label: lst-import
#| lst-cap: A Test

print("This is a test.")  # <1>
```

1. just a test that surprise

More generally, with the `.python` class specification, there does not seem to be a way to get both annotations and a caption,
not even using an extra div. Is all this behavior expected (i.e., deducible from the docs)? Thanks!

[mcanouil]

I suggest to read the documentation Markdown Basics.

[cderv]

I expected to be able to toggle code to not execute by changing python to .python,

@alan-isaac I think you understand the differences between {python} for cell execution. This engine syntax so code content is executed. and {.python} as code block syntax where .python is the class to get the right syntax highlighting language.

One of the main differences though, not really obvious for newcomers I guess, is that executed cell process the content, so the #| special comment is used to pass configuration for cell execution. BUT highlighted code blocks do not process content, so the #| means nothing - it won't be process and just shown as cell content.
Those code block cells use attributes syntax like Divs ({#id .class key=value})

there does not seem to be a way to get both annotations and a caption, not even using an extra div

If you want lst caption on a cell block non executed, you need to use the right syntax
See https://quarto.org/docs/authoring/cross-references.html#code-listings

And more generally, the div syntax for crossref can be useful to have similar syntax for both case: https://quarto.org/docs/authoring/cross-references-divs.html

Hope it helps understand