Type hints and type checking - Issue #36 #66
Conversation
|
Thank you for this @SimonMolinsky !! this pr is next in my review queue for this week!! |
There was a problem hiding this comment.
@SimonMolinsky I am going to make some edits here and will divide this into two pages of content as we discussed on slack!!
if there is anything that i'm doing that you don't like please let me know. my main goal is to make the content match the other content. some of this is a nice tutorial on typing
| @@ -207,3 +207,302 @@ def add_me(aNum, aNum2): | |||
|
|
|||
|
|
|||
| ``` | |||
|
|
|||
|
|
|||
| ## Beyond docstrings: type hints | |||
There was a problem hiding this comment.
This is great. In this guide i've been using "you" rather than we and us. To be consistent i'm going to add some comments below.
documentation/write-user-documentation/document-your-code-api-docstrings.md
Outdated
Show resolved
Hide resolved
| We use docstrings to describe data types that we pass into functions as parameters or | ||
| into classes as attributes. *We do it with our users in mind.* | ||
|
|
||
| **What with us – developers?** We can think of ourselves and the new contributors, |
There was a problem hiding this comment.
Is the point here that type hinting can help both new contributors and developers get to know a code base more quickly or something to that effect perhaps?
documentation/write-user-documentation/document-your-code-api-docstrings.md
Outdated
Show resolved
Hide resolved
documentation/write-user-documentation/document-your-code-api-docstrings.md
Outdated
Show resolved
Hide resolved
documentation/write-user-documentation/document-your-code-api-docstrings.md
Outdated
Show resolved
Hide resolved
documentation/write-user-documentation/document-your-code-api-docstrings.md
Outdated
Show resolved
Hide resolved
|
|
||
| ## Type hints in practice | ||
|
|
||
| Type hinting was introduced with Python 3.5 and is described in [PEP 484](https://peps.python.org/pep-0484/). |
There was a problem hiding this comment.
this is great text but i suggest that we leave this paragraph out of the guide for now. We were told to NOT link to PEPs as they are not intended to use read by the public - rather they are for tool developers. And i also think it's a bit too much information for this section.
| The power of type hints lies somewhere between docstrings and unit tests, and with it, we can avoid many bugs | ||
| throughout development. | ||
|
|
||
| We've seen type hints in the simple example earlier. Let's come back to it and change it slightly: |
There was a problem hiding this comment.
This is really good - it is reading a bit more like a tutorial. i'm wondering if we want to pull this into the tutorials section rather than here?
| The nice feature of type hinting is that we can define variable's type within a function: | ||
|
|
||
| ```python | ||
| from typing import Dict |
There was a problem hiding this comment.
this would be better if it was a a much simpler example. the function takes data as an input but never uses it. and also it's using numpy arrays. couldn't we just use a function that says adds two numbers or something like that?
|
oops @SimonMolinsky are you working on this - i just tried to update the pr but it seems like it's closed. or did i unintentionally close it? |
|
ok i see i closed the issue but i didn't actually close the issue so i'm trying to figure out what the heck happened here. |
This PR is related to Issue #36 from the core repository.
I've added a section with type hinting to this document: Document the code in your package's API using docstrings. I'm waiting for your comments :)
Just thinking... This part is related to the main document, but it is also something more. Maybe it will be better to move it into another file? It's just a proposition.