Format Multi Line String Variables

[ddkasa]

Hi all,

So I have multi-line strings that are attached as class variables, but the default formatting ignores and renders newline characters inline.

So for example this snippet:

class Foo:
    BAR: ClassVar[str] = """
        layout: vertical;
        align: center middle;
        height: auto;
        width: auto;
    """
    """Random Docstring"""

Renders out to this:

My wish is to be able to format these strings, so they are displayed and newlines are properly formatted, similar to how black or ruff formats function/class signatures.

Is there a built-in way to change this? Otherwise I think this would be a great feature to add.

[pawamoy]

Yes that's a limitation of our static analysis agent: ast gives us regular strings, and we loose the information of whether they were triple-quoted strings or not. Then, when "unparsing" expressions, we cannot know whether we should render as regular or triple-quoted strings.

I see two solutions to this:

• somehow fetch again the string from source (thanks to line/column number/offsets)
• parse code as a CST (Concrete Syntax Tree) instead of AST (Abstract Syntax Tree) to maintain source format (drastic change, not happening soon)

It might also be possible to work around this with a Griffe extension, but I'm not sure if that's possible yet, I'll have to run some tests. The extension would accept a list of object paths, and simply go and update these object values to transform strings as triple-quoted strings.

[ddkasa]

Thank you for clarifying. Feared it was a limitation of the implementation.

I might give a shot in writing a Griffe extension if I get time to do it, as I would like to see if it's possible to format these strings with different varying code syntax as well.

[pawamoy]

Quick extension example:

import griffe

class ToHex(griffe.Extension):
    def __init__(self, objects: list[str]) -> None:
         self._objects = set(objects)

    def on_attribute(self, *, attr: griffe.Attribute, **kwargs) -> None:
        if attr.path in self._objects:
            attr.value = attr.value.replace("\\\\n", "\n")
            # or maybe .replace("\\\\n", "\\n")?
            # or with raw strings to make it more readable: .replace(r"\\n", r"\n")

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          extensions:
          - scripts/griffe_extensions.py:  # or wherever you wrote your extension
              objects:
              - path.to.Foo.BAR

[ddkasa]

Thank you @pawamoy. End up going with this:

from typing import Any

from griffe import Extension, Class

class DefaultCSSFormatter(Extension):
    def on_class_members(self, *, cls: Class, **kwargs: Any) -> None:
        if (attr := cls.attributes.get("DEFAULT_CSS")) is not None:
            attr.value = '"""' + attr.value.replace('\\n', '\n')[1:-1] + '"""'

Since its a particular attribute I am looking for I didn't need to pass in any objects.

Curious if you have any pointers in how I could change syntax highlighting to CSS for just this attribute? I tried through adding <code> tags and using markdown as well, but it seems the code field is applied somewhere else.

[pawamoy]

Awesome, thanks for sharing your solution 🚀

Curious if you have any pointers in how I could change syntax highlighting to CSS for just this attribute?

You'd have to override the attribute.html.jinja template, in order to add a condition on the object path, in the signature block: if the object is your DEFAULT_CSS attribute, you'd only render its value (without wrapping triple-quotes) in a CSS code block instead of a Python one.

# mkdocs.yml
plugins:
- mkdocstrings:
    custom_templates: templates

project/
  mkdocs.yml
  docs/
  templates/
    python/
      material/
        attribute.html.jinja

{% extends "_base/attribute.html.jinja" %}
{% block signature scoped %}
  {% if config.separate_signature %}
    {% if attribute.path == "....DEFAULT_CSS" %}
      {{ attribute.value | highlight(language="css") }}
    {% else %}
      {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs) %}
        {{ attribute.name }}
      {% endfilter %}
    {% endif %}
  {% endif %}
{% endblock signature %}

Something like this 😄

[ddkasa]

Thanks again! Worked like a charm.

The only thing I had to change is line 4 in the jinja template:

{% if attribute.path.endswith("DEFAULT_CSS") %}