[Feature Request] Python codegen: docstrings and attribute access so item docs show on hover #1215

Description

Make the module generated by @generatePythonEnv show each item's description, @docs() links and source in the editor on hover, the way the generated TypeScript types do through JSDoc.

Today the Python generator writes the description and docs as # comments next to each TypedDict field:

class Env(TypedDict):
    # Secret key of the Langfuse project that receives traces
    # Docs: https://langfuse.com/docs/observability/sdk/python/setup | Langfuse Python SDK setup
    LANGFUSE_SECRET_KEY: str

Python tooling ignores comments, so none of this reaches the developer while they write env["LANGFUSE_SECRET_KEY"].

Motivation

We moved a Python monorepo (uv workspace) to varlock with @generatePythonEnv and wrote descriptions and @docs() links for every item. In the TypeScript integration that work shows up on hover. In Python it is only visible if you open the generated file.

I checked what the pyright language server (1.1.414, the engine behind Pylance) returns for a few variants of the generated module:

Pyright offers no hover or go-to-definition on TypedDict key strings at all. Key completion inside env["…"] shows only the type. So docstrings fix the declaration site, but only attribute access gets documentation where values are actually read.

Proposed Solution

1. Emit attribute docstrings instead of # comments on the TypedDict fields, with the description, the @docs() links as Markdown links, and the schema file that declares the item, which matters once a monorepo imports schemas from several packages. This is a small change to the generator and immediately helps anyone reading or hovering the declaration.

   class Env(TypedDict):
       LANGFUSE_SECRET_KEY: str
       """Secret key of the Langfuse project that receives traces
   
       Docs: [Langfuse Python SDK setup](https://langfuse.com/docs/observability/sdk/python/setup)
       Source: packages/common/.env.schema
       """

2. Optionally generate an attribute-access type, such as a Protocol with one documented read-only property per item, so that env.LANGFUSE_SECRET_KEY carries the documentation where it is used. Add native Python integration #952 already gives the native ENV object attribute access at runtime, so the generated module could type that path too, for example @generatePythonEnv(path=env.py, access=attributes), or emitting both shapes. This is the variant that showed full hover and go-to-definition in my test:

   class Env(Protocol):
       @property
       def LANGFUSE_SECRET_KEY(self) -> str:
           """Secret key of the Langfuse project that receives traces
   
           Docs: [Langfuse Python SDK setup](https://langfuse.com/docs/observability/sdk/python/setup)
           Source: packages/common/.env.schema
           """
           ...

@deprecated could map to typing_extensions.deprecated / warnings.deprecated (3.13+) on the property, which editors render as strikethrough. That's the Python counterpart of the JSDoc @deprecated tag from #644.

Alternatives

• Keep the TypedDict and only switch to docstrings (step 1). That's cheap and an improvement, but in pyright/Pylance it doesn't show the documentation where values are read.
• Wrap the generated Env by hand in our own typed accessor class. That duplicates every item and drifts from the schema, which is what codegen is meant to avoid.

Additional Information

• varlock 1.22.0 (standalone binary), Python 3.13, uv workspace.
• I tested with the open-source pyright language server only. Pylance adds closed-source features on top, so its behaviour for TypedDict keys might differ.
• Related: Code-generation registry + per-language typegen decorators #849 (per-language codegen), Add native Python integration #952 (native Python integration with attribute access on ENV), fix: escape */ in JSDoc descriptions to prevent premature comment closure in generated types #627 and feat: add @deprecated item decorator #644 (JSDoc descriptions and @deprecated for TypeScript).