Docs in python functions

[peterdudfield]

This came about when i wanted to know which way the deltas were calculated. I looked in here and found the sql code here and then saw it was rv.p50_sip - og.value_sip AS delta_sip, which is forecast - observation

I know the python functions are auto generated, but perhaps they could have a doc string taken from go code?

[devsjc]

They should be generated from the proto files - any comments in there come out in the generated client code. If they aren't coming through, I might be using the wrong style for the comments in the protobuf or something?

[peterdudfield]

I couldnt see any in the functions, this create_user is faily obvious but other functions perhaps do need a little describing or clarifying

[FranciscoZanonDP]

The observation you made—that the delta_sip calculation is defined as rv.p50_sip - og.value_sip (forecast minus observation)—is correct based on the SQL code you found. Since the Python functions are auto-generated, they often lack detailed internal documentation like docstrings. Adopting a practice of extracting the equivalent Go code definition or key calculation logic (like the forecast - observation structure for deltas) and automatically including it as a docstring in the generated Python functions would be an excellent way to improve clarity and transparency for users seeking to understand how core metrics, such as deltas, are calculated.

[231233123]

Your observation about the delta calculation () aligns with the core logic: represents the difference between the forecasted value (p50_sip) and the observed value (value_sip) (forecast - observation).rv.p50_sip - og.value_sip AS delta_sipdelta_sip
Regarding auto-generated Python functions with docstrings extracted from Go code:This is absolutely feasible, and it’s a common practice to maintain consistent documentation across multi-language codebases (Go → Python). Below is a structured approach to implement this:

1. Extract Documentation from Go Code
   First, identify and extract the relevant comments/docstrings from the Go code that defines the delta calculation logic.
2. Inject Extracted Docs into Auto-Generated Python Functions
   When generating the Python functions (e.g., via a code generator like or a custom script), pass the extracted Go docstrings into the template to auto-populate Python docstrings.
3. Tools to Automate the Workflow
   Go Doc Extraction: Use + to parse Go code and extract comments programmatically.golang.org/x/tools/go/packagesgo/doc
   Python Code Generation: Use (for template-based generation) or (if using data models).jinja2pydantic-codegen
   CI/CD Integration: Embed this extraction + generation step into your CI/CD pipeline to ensure Python docstrings are always in sync with Go code changes.

[caelum-artifex]

Correct — delta_sip is calculated as forecast - observation.

For the docstrings:
Python client code only inherits documentation from the protobuf comments, not from Go code. If we want Python functions to include descriptions (e.g., explaining delta definitions), the comments need to be added directly into the relevant .proto fields/methods.

Once the comments exist in the proto, the Python generator will produce the correct docstrings automatically and keep them in sync across Go/Python.