microsoft / microsoft/typespec

[Bug]: [http-client-python] Discriminator subclass :vartype points at non-existent symbol

Open
#10,575 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

For every discriminator subclass, the generated `:vartype type:` docstring references the upper-cased discriminator **value** as if it were a module-level symbol. It isn't — the actual symbol is an enum member on the discriminator enum class — so the Sphinx cross-reference is unresolvable.

Example from generated `azure-search-documents`:

```python
class KnowledgeBaseModelWebSummarizationActivityRecord(
KnowledgeBaseActivityRecord, discriminator="modelWebSummarization"
):
"""...
:vartype type: str or ~azure.search.documents.knowledgebases.models.MODEL_WEB_SUMMARIZATION
"""
type: Literal[KnowledgeBaseActivityRecordType.MODEL_WEB_SUMMARIZATION] = rest_discriminator(...)
```

`...models.MODEL_WEB_SUMMARIZATION` does not exist. It should reference the enum **type** (which is exported from the module):

```rst
:vartype type: str or ~azure.search.documents.knowledgebases.models.KnowledgeBaseActivityRecordType
```

### Reproduction

Regenerate any TypeSpec service with discriminated polymorphic models using `@azure-tools/typespec-python` (observed in `0.61.3`). Any generated discriminator subclass shows `:vartype type: ... ~.` pointing at a non-existent attribute.

Concrete instance: https://github.com/Azure/azure-sdk-for-python/pull/46635 — `sdk/search/azure-search-documents/azure/search/documents/knowledgebases/models/_models.py`, class `KnowledgeBaseModelWebSummarizationActivityRecord`.

### 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.