Documenting functional-form TypedDicts?

[sneakers-the-rat]

I found the prior discussion here: #132

and i have a followup - we have some TypedDicts with keys that aren't valid python names, (i.e. use hyphens), so we have to use the functional form of TypedDict sometimes, but perhaps predictably the documentation treats it like a module attribute and it ends up all smashed and ugly

additionally, i'm not quite sure how to do docstrings for the individual keys (this is less important, since we can put that in the class-level docstring if need be.)

Seems like a pretty special case, but also not an uncommon one - not sure if anyone else has already cooked up an extension for this, or if maintainers would be interested in a special parser for functional form type dicts?

[pawamoy]

Can you show what a functional-form TypedDict looks like 🙂? Ah, I suppose it's TypedDict('ResolutionTable', {'allow-prereleases': bool}, total=False)?

What would you suggest? Surely we can't display it the usual way when the keys are invalid Python names.

[sneakers-the-rat]

it's a special case, but one that's well defined by the python typing PEPs - type checkers handle the functional TypedDict just fine, even though it's a structurally dynamic syntax. i am not sure what maintainers would think of having this as a builtin extension, but i wrote a version of this that handles what we needed over here: pdm-project/pdm#3784

https://github.com/sneakers-the-rat/pdm/blob/7d3d57ce6645d4b0c60c63022e48bb790559bb11/docs/_ext/typeddict.py#L1-L111

where e.g. from this:

ToolPDMTable = TypedDict(
    "ToolPDMTable",
    {
        "distribution": bool,
        "ignore_package_warnings": list[str],
        "plugins": list[str],
        "build": BuildTable,
        # Control how pdm-backend builds the package
        "options": OptionsTable,
        # Add parameters to every pdm cli call
        "resolution": ResolutionTable,
        # Rules governing lockfile resolution
        "scripts": dict[str, Union[str, UserScript]],
        # See [pdm-scripts][pdm-scripts]
        "source": list[SourceTable],
        # Repositories where packages may be found
        "version": VersionTable,
        # Dynamic Versioning
        "dev-dependencies": dict[str, list[str]],
        # Development-only dependencies
    },
    total=False,
)
"""
Root table for setting pdm options within pyproject.toml
"""

and this

expand/collapse autodoc invocation

::: pdm.project.project_file.ToolPDMTable
    options:
      heading: "[tool.pdm]"
      toc_label: "[tool.pdm]"
      heading_level: 2
      show_bases: false
      show_root_heading: true
      show_root_toc_entry: true
      show_source: false
      show_if_no_docstring: true
      summary:
        attributes: true

one gets this

[pawamoy]

Nice!

To me it sounds like retro-fitting API docs functinality to document configuration options, so I don't think I'd want to maintain this as a built-in Griffe extension. Happy to list it in Griffe docs if you want to package and distribute it on PyPI 🙂