Skip to content

docs: rewrite type checking guide for strict mypy, pyright and ty - #567

Merged
leandrodamascena merged 3 commits into
ferrumio:mainfrom
vicolby:fm/pydynox-325-typing-guide
Nov 1, 2026
Merged

leandrodamascena merged 3 commits into
ferrumio:mainfrom
vicolby:fm/pydynox-325-typing-guide

Conversation

@vicolby

@vicolby vicolby commented Oct 30, 2026

Copy link
Copy Markdown
Contributor

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

  • Updated docs/guides/type-checking.md to 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 the isinstance/cast advice for query()/scan() results. The guide now says these results already have the model type, and as_dict=True returns dict[str, Any].
  • Rewrote the attribute types table as T | None and added missing attributes (DecimalAttribute, MapAttribute(MyClass), EnumAttribute, VectorAttribute). Added a "Handling None" section. It explains why required=True and default=... still leave the type as T | None, and shows the is None check that narrows the type.
  • Added strict config examples for mypy (pyproject.toml), pyright (pyrightconfig.json with pythonVersion: "3.11") and ty ([tool.ty.rules] all = "error"). Also added a reveal_type section with each checker's output. The Pydantic section now says that pyright and ty see @dynamodb_model classes as Any.

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 with required=True. The reveal_type output matches the guide for all three checkers: str | None on the instance, StringAttribute (fully qualified in mypy) on the class, and ConditionComparison for the comparison. The guide's Pydantic claim, that mypy sees str while pyright and ty see Any, 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.

  • Live validation: ✅ go - 3 of 3 scenarios driven live against the product
Scenario Result Live Evidence
A user copies the guide's strict mypy, pyright and ty configs, and the guide's examples (attributes, None handling, CRUD types, S3 isinstance, async query, Pydantic) pass all three checkers ✅ pass live checker-transcript-snippets.txt: mypy no issues in 6 files, pyright 0 errors, ty all checks passed
Adversarial: a user skips the None check and calls user.name.upper() on a required=True, default attribute, and every checker rejects it ✅ pass live checker-transcript.txt negative section: mypy union-attr, pyright reportOptionalMemberAccess, ty unresolved-attribute
A user runs reveal_type on user.name and User.name and gets the output the guide shows for each checker ✅ pass live checker-transcript.txt reveal_type section: mypy 'str | None', pyright 'str | None', ty 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!

== mypy 2.4.0 --strict (guide snippets)
Success: no issues found in 6 source files
exit=0
== pyright 1.1.414 strict (guide snippets)
0 errors, 0 warnings, 0 informations
== ty 0.0.64 all=error (guide snippets)
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 / StringAttribute negative: mypy union-attr, pyright reportOptionalMemberAccess, ty unresolved-attribute on user.name.upper()

== mypy 2.4.0 --strict (guide snippets)
basic_types.py crud_types.py handle_none.py s3_snippet.py query_snippet.py pydantic_snippet.py: error: Cannot read file: No such file or directory
Found 1 error in 1 file (errors prevented further checking)
exit=2
== pyright 1.1.414 strict (guide snippets)
File or directory "file://~/.no-mistakes/evidence/01M65YR8DN2B8956WR6S62NQ01/userproj/basic_types.py%20crud_types.py%20handle_none.py%20s3_snippet.py%20query_snippet.py%20pydantic_snippet.py" does not exist
exit=0
== ty 0.0.64 all=error (guide snippets)
WARN No python files found under the given path(s)
error[io]: `~/.no-mistakes/evidence/01M65YR8DN2B8956WR6S62NQ01/userproj/basic_types.py crud_types.py handle_none.py s3_snippet.py query_snippet.py pydantic_snippet.py`: No such file or directory (os error 2)

Found 1 diagnostic
== reveal_type
reveal_snippet.py:15: note: Revealed type is "str | None"
reveal_snippet.py:16: note: Revealed type is "pydynox.attributes.primitives.StringAttribute"
reveal_snippet.py:17: note: Revealed type is "pydynox._internal._conditions.ConditionComparison"
Success: no issues found in 1 source file
  ~/.no-mistakes/evidence/01M65YR8DN2B8956WR6S62NQ01/userproj/reveal_snippet.py:15:13 - information: Type of "user.name" is "str | None"
  ~/.no-mistakes/evidence/01M65YR8DN2B8956WR6S62NQ01/userproj/reveal_snippet.py:16:13 - information: Type of "User.name" is "StringAttribute"
  ~/.no-mistakes/evidence/01M65YR8DN2B8956WR6S62NQ01/userproj/reveal_snippet.py:17:13 - information: Type of "User.name == "John"" is "ConditionComparison"
reveal_snippet.py:15:13: info[revealed-type] Revealed type: `str | None`
reveal_snippet.py:16:13: info[revealed-type] Revealed type: `StringAttribute`
reveal_snippet.py:17:13: info[revealed-type] Revealed type: `ConditionComparison`
== negative (unguarded user.name.upper())
negative_snippet.py:14: error: Item "None" of "str | None" has no attribute "upper"  [union-attr]
Found 1 error in 1 file (checked 1 source file)
  ~/.no-mistakes/evidence/01M65YR8DN2B8956WR6S62NQ01/userproj/negative_snippet.py:14:22 - error: "upper" is not a known attribute of "None" (reportOptionalMemberAccess)
1 error, 0 warnings, 0 informations
negative_snippet.py:14:12: error[unresolved-attribute] Attribute `upper` is not defined on `None` in union `str | None`
Found 1 diagnostic
  • Evidence: Disposable user project with documented configs and snippets (local file: ~/.no-mistakes/evidence/01M65YR8DN2B8956WR6S62NQ01/userproj)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 warning
  • ⚠️ docs/guides/type-checking.md:172 - The documented mypy reveal_type output mypy: Revealed type is "str | None" is very likely wrong. mypy's reveal_type note prints fully qualified names (messages.py uses typ.str_with_options(...)), so the real output is Revealed type is "builtins.str | None". The guide even says on line 177 that "mypy adds the full module path" for User.name, which contradicts the unqualified str on line 172. Users who compare their output against the guide will see a mismatch. Fix: change line 172 to Revealed 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.

  • Live validation: ✅ go - 3 of 3 scenarios driven live against the product
Scenario Result Live Evidence
A user copies the guide's strict mypy, pyright and ty configs, and the guide's examples (attributes, None handling, CRUD types, S3 isinstance, async query, Pydantic) pass all three checkers ✅ pass live checker-transcript-snippets.txt: mypy no issues in 6 files, pyright 0 errors, ty all checks passed
Adversarial: a user skips the None check and calls user.name.upper() on a required=True, default attribute, and every checker rejects it ✅ pass live checker-transcript.txt negative section: mypy union-attr, pyright reportOptionalMemberAccess, ty unresolved-attribute
A user runs reveal_type on user.name and User.name and gets the output the guide shows for each checker ✅ pass live checker-transcript.txt reveal_type section: mypy 'str | None', pyright 'str | None', ty str | None; class access StringAttribute (mypy fully qualified)
  • uv sync + uv run --with maturin maturin develop --release to build pydynox from this commit
  • uvx 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.py with the documented [tool.mypy] strict = true
  • uvx 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 checkers
  • Negative snippet: unguarded user.name.upper() on StringAttribute(required=True, default="x") under all three checkers
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

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.
@leandrodamascena

Copy link
Copy Markdown
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 builtins.str is a false positive—I got str | None with mypy 2.4.0. Looks good to me 🙂

@sonarqubecloud

sonarqubecloud Bot commented Nov 1, 2026

Copy link
Copy Markdown

@leandrodamascena
leandrodamascena merged commit b17b99e into ferrumio:main Nov 1, 2026
2 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants