microsoft / microsoft/typespec

[Bug]: Docstring generated without expected escape character (or with an unnecessary one?)

Open
#6,084 0 comments 0 reactions 0 assignees View on GitHub
bug emitter:client:python
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### Describe the bug

Generating our python SDK, we're running into a case where a docstring is generated with either a missing escape character, or an unnecessary one.

Our typespec contains the following sentence in a docstring for one of the properties of a model:
"Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length."

When generated, this shows up in two different places. The first is the docstring for the class the model is being generated into
`Also note that the message content may be partially cut off if ``finish_reason="length"``\\ , which indicates the generation exceeded ``max_tokens`` or the conversation exceeded the max context length.` In this case, it has the double escape characters in the middle of the sentence, and then a space, before the comma. It's unclear to me why those are there, as the typespec docstring has no space, or new line or anything at that point in the docstring which would seemingly need to be escaped. But this doesn't actually cause any issues.

The second place it shows up is as a comment under the actual property, within the generated class, and looks like
`Also note that the message content may be partially cut off if ``finish_reason=\"length\"``\ , which indicates the generation exceeded ``max_tokens`` or the conversation exceeded the max context length.` In this case, it only generated a single escape character (and additional ones for the quotes around "length"), which is causing pylint to error out.

### Reproduction

I've created a branch where the generated code can be seen. [This](https://github.com/Azure/azure-sdk-for-python/blob/trangevi/typespec-bug-repro/sdk/ai/azure-ai-inference/azure/ai/inference/models/_models.py#L323) is the first location (which is fine, albeit odd), and [this](https://github.com/Azure/azure-sdk-for-python/blob/trangevi/typespec-bug-repro/sdk/ai/azure-ai-inference/azure/ai/inference/models/_models.py#L400) is the second (which breaks pylint). [Here](https://github.com/Azure/azure-rest-api-specs/blob/dargilco/ai-model-inference/specification/ai/ModelClient/models/chat_completions.tsp#L92) is a pointer to the typespec docstring.

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
- [x] Check that this is a concrete bug. For Q&A open a [GitHub Discussion](https://github.com/Microsoft/typespec/discussions).
- [x] The provided reproduction is a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) of the bug.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.