-
Notifications
You must be signed in to change notification settings - Fork 249
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Best Practices document #851
Comments
What knowledge should the document assume and what are prerequisite documents to read? The typing tutorial + type stub tutorial? If yes then I think this is blocked by those two documents being created first just to build on them. One practice common in my team is if python 3.7+ is fine (most of our code) then use Another one is prefer TypedDict over dicts. Sometimes we do need a mapping[str, str] and don't know much about input argument, but a lot of times we do know the structure of dict. I often see people new to types used dict when a specific typeddict is actual expectation. Similarly NamedTuple > namedtuple. Most of the time where mapping is correct its utility functions while main business/api logic has more knowledge of the dict. If you are indexing elements by specific values like d['foo'] then mapping can probably be typeddict instead. Unsure if this goes in tutorial or best practices, method compatibility check (liskov substituation) is an important one I occasionally see broken. One common reason I see it broken is from superclass really being generic on a type but not stating it. Include partial/py.typed for any libraries you make. Avoid relying on implicit imports. Specifically the section on what symbols are publicly exported from a module here. Some libraries I use heavily ignore this rule which leads to some type checker confusion. The May fit better in a different doc, but one practice that's helped a lot in improving type coverage of our codebase is adding a CI check that runs type checkers twice on changed files and requires the error count to go down by 5 on every PR compared to master. It's pretty difficult for 1/2 people to add types to large codebase so making a CI rule that pushes in that direction has helped a lot. Any type checker is fine for this and I currently run 2 in CI. Simpler check of requiring 0 type errors would have been unfeasible when a lot files had 100+ type errors (mostly missing types). There's also question of how to handle recent pep type features that are not supported by all type checkers yet. My current practice is to allow them if some checker handles it and type ignore as needed for other checker (recursive types being one). That's very debatable practice though and it may be better for a best practices doc to avoid type features missing support in a popular checker. |
We should include a section about I/O types:
Came up in python/typeshed#6067. |
Another best practice: Use |
Move all "style guide" items over that apply to both stubs as well as implementation. The items are reordered and the "Types" section was split, but the text itself is unchanged. Part of python#851
Move all "style guide" items over that apply to both stubs as well as implementation. The items are reordered and the "Types" section was split, but the text itself is unchanged. Part of #851
Part of #851 Co-authored-by: Jelle Zijlstra <[email protected]>
Any
orT | Any
Any
vsobject
object
instead ofNone
orAny
if the returned value is ignoredPlease add anything you think the document should contain.
The text was updated successfully, but these errors were encountered: