Repository navigation
docs: rewrite type checking guide for strict mypy, pyright and ty - #567
Merged
leandrodamascena merged 3 commits intoNov 1, 2026
Merged
Conversation
Mark ty as supported, document strict configs for all three checkers, add reveal_type and None narrowing sections, and drop the obsolete isinstance/cast and ty descriptor advice. Note that the Pydantic integration is only typed under mypy.
Member
|
Thanks @vicolby! I ran the examples with all three checkers using the documented configs and confirmed the Pydantic limitation too. Everything matches the guide. The bot warning about |
|
leandrodamascena
approved these changes
Nov 1, 2026
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
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.



Intent
Part of #325 (support strict type checking for mypy, pyright and ty). Rewrite docs/guides/type-checking.md. Measured on upstream main cdd8c85: the ty row still says Partial (line 11); the isinstance/cast section (lines 67-86) is obsolete; the ty descriptor section (lines 88-96) is wrong; there are no sections on a strict config, reveal_type, or a pyrightconfig. Include the T | None guard pattern: the decision is to keep attributes typed T | None, so users narrow with a None check.
What Changed
docs/guides/type-checking.mdto mark mypy, pyright and ty as supported in strict mode, and to state which checker versions the examples were checked with. Removed the old "ty doesn't understand descriptors" section and theisinstance/castadvice forquery()/scan()results. The guide now says these results already have the model type, andas_dict=Truereturnsdict[str, Any].T | Noneand added missing attributes (DecimalAttribute,MapAttribute(MyClass),EnumAttribute,VectorAttribute). Added a "Handling None" section. It explains whyrequired=Trueanddefault=...still leave the type asT | None, and shows theis Nonecheck that narrows the type.pyproject.toml), pyright (pyrightconfig.jsonwithpythonVersion: "3.11") and ty ([tool.ty.rules] all = "error"). Also added areveal_typesection with each checker's output. The Pydantic section now says that pyright and ty see@dynamodb_modelclasses asAny.Risk Assessment
✅ Low: This is a docs-only rewrite. It meets every point in the intent: the ty row now says Supported, the isinstance/cast section and the wrong ty descriptor section are removed, and it adds sections on strict config, reveal_type, pyrightconfig and the T | None guard pattern. The attribute types table matches the source. The only issue is one probably-inaccurate sample of mypy output.
Testing
I built pydynox from this commit and set up a disposable user project with exactly the guide's strict mypy, pyright and ty configs, the guide's code examples, a reveal_type snippet and a negative unguarded-access case. All guide examples pass all three checkers with zero diagnostics. The unguarded
.upper()is rejected by each checker even withrequired=True. Thereveal_typeoutput matches the guide for all three checkers:str | Noneon the instance,StringAttribute(fully qualified in mypy) on the class, andConditionComparisonfor the comparison. The guide's Pydantic claim, that mypy seesstrwhile pyright and ty seeAny, was not checked: that snippet was only checked for passing, with no reveal_type on its fields. Checker transcripts are saved in the evidence directory. There is no UI, so no screenshots were taken. The temporary venv link was removed and the worktree is clean.str | None; class access StringAttribute (mypy fully qualified)Evidence: Checker transcript: guide snippets under strict mypy, pyright, ty
mypy 2.4.0 --strict: Success: no issues found in 6 source files pyright 1.1.414 strict: 0 errors, 0 warnings, 0 informations ty 0.0.64 all=error: All checks passed!Evidence: Checker transcript: reveal_type and negative unguarded-access case
mypy: Revealed type is "str | None" / "pydynox.attributes.primitives.StringAttribute" pyright: Type of "user.name" is "str | None" / "StringAttribute" ty: Revealed type:str | None/StringAttributenegative: mypy union-attr, pyright reportOptionalMemberAccess, ty unresolved-attribute on user.name.upper()~/.no-mistakes/evidence/01M65YR8DN2B8956WR6S62NQ01/userproj)Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
docs/guides/type-checking.md:172- The documented mypy reveal_type outputmypy: Revealed type is "str | None"is very likely wrong. mypy's reveal_type note prints fully qualified names (messages.py usestyp.str_with_options(...)), so the real output isRevealed type is "builtins.str | None". The guide even says on line 177 that "mypy adds the full module path" forUser.name, which contradicts the unqualifiedstron line 172. Users who compare their output against the guide will see a mismatch. Fix: change line 172 toRevealed type is "builtins.str | None"after confirming with mypy 2.4.0, and reword line 177 so it covers both cases.✅ **Test** - passed
✅ No issues found.
str | None; class access StringAttribute (mypy fully qualified)uv sync+uv run --with maturin maturin develop --releaseto build pydynox from this commituvx mypy==2.4.0 --python-executable <worktree .venv python> basic_types.py crud_types.py handle_none.py s3_snippet.py query_snippet.py pydantic_snippet.pywith the documented[tool.mypy] strict = trueuvx pyright==1.1.414 <same files>with the documented pyrightconfig.json (strict, venvPath/venv, pythonVersion 3.11)uvx ty==0.0.64 check <same files>with the documented[tool.ty.rules] all = "error"reveal_type snippet (user.name, User.name, User.name == "John") under all three checkersNegative snippet: unguardeduser.name.upper()onStringAttribute(required=True, default="x")under all three checkers✅ **Document** - passed
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.