[ty] Document the @Todo type - #26324
Merged
Merged
Conversation
charliermarsh
changed the title
@Todo type
Typing conformance resultsNo changes detected ✅Current numbersThe percentage of diagnostics emitted that were expected errors held steady at 94.37%. The percentage of expected errors that received a diagnostic held steady at 89.00%. The number of fully passing files held steady at 94/134. |
Memory usage reportMemory usage unchanged ✅ |
|
AlexWaygood
approved these changes
Jun 24, 2026
Comment on lines
+117
to
+128
| ### Todo type | ||
|
|
||
| `Todo` exists only as a documentation and navigation target for ty's internal `@Todo` type. It | ||
| cannot be used in annotations. | ||
|
|
||
| ```py | ||
| from ty_extensions import Todo | ||
|
|
||
| # error: [invalid-type-form] | ||
| value: Todo | ||
| ``` | ||
|
|
Member
There was a problem hiding this comment.
an admirable attempt at TDD from codex here, but I don't think this test is really necessary or adds anything 😆
|
|
||
| Like `Any` and `Unknown`, `@Todo` is a dynamic type, so ty allows any operation on it. Unlike `Any`, | ||
| it is not explicitly provided in an annotation; unlike `Unknown`, it specifically indicates a | ||
| limitation in ty. Any message shown in parentheses identifies the missing feature. |
Member
There was a problem hiding this comment.
I think we could omit the mention of a message shown in parentheses. We still only retain those messages in debug mode, which most users won't ever use
charliermarsh
force-pushed
the
charlie/document-todo-type
branch
from
June 24, 2026 13:50
9f67773 to
f3076ad
Compare
charliermarsh
enabled auto-merge (squash)
June 24, 2026 13:50
charliermarsh
added a commit
to astral-sh/ty
that referenced
this pull request
Jun 24, 2026
## Summary Add a new FAQ entry explaining what `@Todo` means in ty's type system, how it differs from `Any` and `Unknown`, where it can appear, and why it cannot be used in annotations. This complements astral-sh/ruff#26324, which adds an editor navigation target for inferred `@Todo` types. Part of: #3209.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@Todois a dynamic type that represents a known missing feature or incomplete implementation in ty, but it previously had no user-facing definition. As a result, go-to-type-definition on an inferred@Todotype returned no target, and users had no editor-visible explanation of what the type meant.This adds a documented
Todosymbol toty_extensionsand routes all internal@Todovariants to that definition, following the existingDivergentpattern. Users can now command-click an inferred@Todotype to reach its documentation.ty_extensions.Todoremains an internal navigation target and is rejected in annotations.This complements astral-sh/ty#3847, which adds an FAQ entry.
Closes astral-sh/ty#3209.