Substitution Raw Latex Error

[mtgstuber]

I have a large document where I need to mark some blocks of text to be rendered as portrait pages when the PDF is generated. I've added the necessary packages to my latex preamble, and I'm able to successfully insert .. raw:: latex directives to switch from portrait to landscape and back.

Instead of littering the .rst files with .. raw:: directives, I'd like to use the substitution feature. Unfortunately, when I do this by adding my substitution directive in conf.py, I get an error. Specially, I've tried to add:

rst_prolog = f"""
.. |landscape| raw:: latex

  \\begin\{landscape\}

.. |landscape-end| raw:: latex

   \\end{landscape} 
"""

Unfortunately, when I do this, the python interpreter chokes on "landscape" wanting to look it up as a name:

Traceback
=========

      File "/home/michael/Development/specification-mtgs/venv/lib/python3.12/site-packages/sphinx/config.py", line 611, in eval_config_file
        raise ConfigError(msg % traceback.format_exc()) from exc
    sphinx.errors.ConfigError: There is a programmable error in your configuration file:

    Traceback (most recent call last):
      File "/home/michael/Development/specification-mtgs/venv/lib/python3.12/site-packages/sphinx/config.py", line 596, in eval_config_file
        exec(code, namespace)  # NoQA: S102
        ^^^^^^^^^^^^^^^^^^^^^
      File "/home/michael/Development/specification-mtgs/source/conf.py", line 152, in <module>
        \\begin{landscape}
                ^^^^^^^^^
    NameError: name 'landscape' is not defined

If I make the substitution directly in the .rst file, it works fine. I tried escaping the braces with backslashes so that the parser wouldn't try looking up "landscape", but that just gives me an error about an unexpected character after the backslash:

Traceback
=========

      File "/home/michael/Development/specification-mtgs/venv/lib/python3.12/site-packages/sphinx/config.py", line 599, in eval_config_file
        raise ConfigError(msg % err) from err
    sphinx.errors.ConfigError: There is a syntax error in your configuration file: unexpected character after line continuation character (conf.py, line 152)

While I could potentially handle the substitution by defining it in another .rst file and using an .. include::, I have 54 .rst files in this document tree, and I'd prefer not to have to include the .rst with the substitutions across lots of files.

Is there some magical way to include this substitution in the conf.py file? Is there a different place to include this substitution that doesn't require lots of .. include:: directives?

[mtgstuber]

After taking the time to write all this up I did some more digging and determined I can escape the braces by using two of them: \\begin{{landscape}}. I have no idea why python works this way, but it works.

[parulin]

In Python, "{landscape}" should be converted into a string containing the variable landscape (and you found how to escape them). I don't know if it is expected from the raw directive...