How to render my attribute values as hex

[mrossington]

In my source code my enum is specified as

class MessageType(Enum):
    BEST_MESSAGE = 0x0123
    WORST_MESSAGE = 0xB33F

The generated docs converts these to decimal values as so:

I'd like to maintain the source code representation. Is this possible?

Additionally I'd love the table to also say what the value is too.

[pawamoy]

Oh, interesting, ast might transform the values when parsing 🤔

[pawamoy]

Yep:

% cat hex.py 
class MessageType:
    BEST_MESSAGE = 0x0123
    WORST_MESSAGE = 0xB33F

% python -m ast hex.py
Module(
   body=[
      ClassDef(
         name='MessageType',
         body=[
            Assign(
               targets=[
                  Name(id='BEST_MESSAGE', ctx=Store())],
               value=Constant(value=291)),
            Assign(
               targets=[
                  Name(id='WORST_MESSAGE', ctx=Store())],
               value=Constant(value=45887))])])

I don't see how to prevent that 😕

[mrossington]

Thanks for your response!

Damn, just tried it with griffe dump too and they don't preserve the original value either.

Fun discovery: I see that astexplorer.net does preserve the original value:

They use https://github.com/codecombat/filbert which is a js parser. So not relevant but interesting nonetheless.

---

I wonder if there is a way to postprocess these values. I will look into extra_javascript.

[mrossington]

Worst case I'll add a docstring with the value manually put in. Unfortunately for the use case in mind: our team speak and reason about all these message IDs in hex. So the document (and search) isn't very useful without it.

[pawamoy]

OK so, it won't be possible to fix this while we keep using ast, but I can imagine a few solutions:

• we move to a CST parser (Concrete rather than Abstract Syntax Tree), but this is a drastic change so won't happen soon
• you write a small, custom Griffe extension that converts back values of specific objects to hex

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:
            if isinstance(attr.value, griffe.ExprConstant):  # just to be sure
                attr.value.value = hex(int(attr.value.value))

Maybe make it accept paths to enums instead of enum values:

import griffe

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

    def on_class_members(self, *, cls: griffe.Class, **kwargs) -> None:
        if cls.path in self._objects:
            for attr in cls.attributes.values():
                if isinstance(attr.value, griffe.ExprConstant):  # just to be sure
                    attr.value.value = hex(int(attr.value.value))

In mkdocs.yml:

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

[mrossington]

This worked amazingly, thank you! Also it has taught me a lot about the extensions structure.

One note, I had to change the extension to

import griffe


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

    def on_class_members(self, *, cls: griffe.Class, **kwargs) -> None:
        if cls.path in self._objects:
            for attr in cls.attributes.values():
                if isinstance(attr, griffe.Attribute):  # just to be sure
                    attr.value = hex(int(attr.value))

RE the just to be sure line: When I inherit a baseclass of enum the type comes out as Attrribute, not ExprConstant.
RE value.value: I think maybe it was a copy paste error?

Thanks again :)

[pawamoy]

Great! I definitely meant to check the type of attr.value, which is the right operand in BEST_MESSAGE = 0x0123. attr itself will always be an Attribute instance, since we get it from its parent attributes property. Then attr.value.value was on purpose too, since if attr.value is an ExprConstant, it will have a value attribute storing the actual constant value (the integer) 🙂 See https://mkdocstrings.github.io/griffe/reference/api/expressions/#griffe.ExprConstant.value.

But your solution works too, because attribute values can be expressions (like ExprConstant) or strings directly, so you can definitely keep this shortcut, it's supported 🙂 (you just don't need the isinstance check). I'm not sure how int(attr.value) works here though 🤔

[pawamoy]

Huh, turns out attr.value is the integer (represented as a string) directly. Hmmm. I thought it would be an ExprConstant, my bad!

[pawamoy]

Right, the expression builder doesn't ever instantiate ExprConstant 😂 _build_constant returns the value directly. Well, I'll add a note to the code. Or I guess I can just remove the ExprConstant class.