tortoise / tortoise/tortoise-orm
[Enhancement] Improve Developer Experience (DX) by using `TypedDict` and `Unpack` (PEP 692) for `Field.__init__`
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 5.6k
- Forks
- 516
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 9
Description
🚀 Summary
As a developer using TortoiseORM with VS Code (Pylance/Pyright), I've noticed that defining models can be a bit "blind" because Field classes use **kwargs: Any in their __init__.
I would like to propose using PEP 692 (Unpack with TypedDict) to provide explicit type hints for field arguments. This would significantly improve the autocompletion and static analysis experience for all users.
😟 Current Problem
Currently, most Field classes (e.g., IntField, CharField) have an __init__ signature like this:
def __init__(self, **kwargs: Any) -> None: ...
Because of Any, IDEs cannot suggest valid arguments like pk, null, default, or index. Developers have to refer to the documentation constantly, and simple typos in argument names are not caught by type checkers (Mypy/Pyright) in "Standard" or "Strict" modes.
💡 Proposed Solution
By leveraging PEP 692, we can define a TypedDict for common field arguments. This allows the IDE to provide real-time suggestions while maintaining the flexibility of **kwargs.
Example Implementation:
from typing import TypedDict, Optional, Any
from typing_extensions import Unpack # For compatibility with older Python versions
class FieldArgs(TypedDict, total=False):
pk: bool
null: bool
default: Any
index: bool
unique: bool
db_index: bool
description: Optional[str]
source_field: Optional[str]
generated: bool
# etc.
class Field:
def __init__(self, **kwargs: Unpack[FieldArgs]) -> None:
...
🎯 Benefits
- Full Autocompletion: IDEs like VS Code (Pylance) will show the list of valid arguments as soon as the user types
(. - Early Bug Detection: Type checkers will flag invalid arguments or incorrect types (e.g., passing a string to
null). - Self-Documenting Code: The code itself becomes the documentation for what a
Fieldcan accept.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
The issue names Field.init and examples such as IntField and CharField, but no repository files or tests. Start by locating those constructors and checking existing Python-version and type-checker compatibility. Done means field arguments have explicit TypedDict-based hints, invalid argument types are detectable, and existing field behavior remains unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- database
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100