Add info about classes and types to 'getting started' docs #6557

Michael0x2a · 2019-03-17T00:28:34Z

While helping somebody use mypy, it came to my attention that our docs never actually quite explain how classes and types interact.

This PR adds a new section named "Types and classes" to the "Getting started" docs that tries to fix this.

This section focuses on introducing two ideas:

That you can use any Python class as a type
That if a variable has type T, it can also accept any instances of subclasses of type T.

The examples also give us an opportunity to sneak in a brief mini-lesson on how to add type hints to classes, and what sorts of things do and do not get inferred.

I also rewrote the next section about stubs/typeshed partly so it would dovetail better with this new section but also partly because I always felt that section was a little too dense and rushed.

Three other minor changes made:

I added an example about sqlalchemy and sqlalchemy-stubs to one of the other pages.
I removed a line directing people to the mypy issue tracker if they have questions.
I dropped the term "library stubs" in favor of just "stub files".

While helping somebody use mypy, it came to my attention that our docs never actually quite explain how classes and types interact. This PR adds a new section named "Types and classes" to the "Getting started" docs that tries to fix this. This section focuses on introducing two ideas: 1. That you can use any Python class as a type 2. That if a variable has type T, it can also accept any instances of *subclasses* of type T. The examples also give us an opportunity to sneak in a brief mini-lesson on how to add type hints to classes, and what sorts of things do and do not get inferred. I also rewrote the next section about stubs/typeshed partly so it would dovetail better with this new section but also partly because I always felt that section was a little too dense and rushed. Three other minor changes made: - I added an example about sqlalchemy and sqlalchemy-stubs to one of the other pages. - I removed a line directing people to the mypy issue tracker if they have questions. - I dropped the term "library stubs" in favor of just "stub files".

ilevkivskyi

Not a full review, just couple random thoughts.

ilevkivskyi · 2019-03-18T11:10:34Z

docs/source/getting_started.rst

+This behavior is actually a fundamental aspect of the PEP 484 type system: when 
+we annotate some variable with a type ``T``, we are actually telling mypy that
+variable can be assigned an instance of ``T``, or an instance of a *subclass* of ``T``.
+The same rule applies to type hints on parameters or fields.


Should we mention that mypy enforces LSP to make sure this is actually safe (maybe in a footnote)?

I don't think we need to mention that in this article, since this is a beginner's tutorial.

ilevkivskyi · 2019-03-18T11:13:26Z

docs/source/getting_started.rst

+1. Look for a separate package containing stubs for that library. For example,
+   if you want type hints for the `sqlalchemy <https://www.sqlalchemy.org/>`_ 
+   library, you can install
+   `sqlalchemy-stubs <https://pypi.org/project/sqlalchemy-stubs/>`_.


Should we also mention other notable stubs projects? This link appears twice (here and in the section on running mypy), maybe replace one of them with e.g. django-stubs?

ilevkivskyi · 2019-05-08T16:36:30Z

@JukkaL are you going to review this PR? If no, I can do a more thorough review.

msullivan · 2020-10-18T04:58:26Z

Hey, @Michael0x2a, if you rebase this, I'll review it.

97littleleaf11 · 2021-10-07T19:34:09Z

Any progress on this PR?

JukkaL · 2021-11-25T14:45:31Z

These still look useful improvements, and I can review this if the merge conflicts get resolved.

…docs

97littleleaf11 · 2021-11-25T18:26:09Z

docs/source/getting_started.rst

+the types are: it'll assume the entire library is
+:ref:`dynamically typed <dynamic-typing>` and report an error
+whenever you import the library.
+


@JukkaL I tried to merge the conflicts. But I am not sure about this parts.

I think this section (from lines 452-487) should be moved to running_mypy.rst, or maybe just cut altogether. With the changes made in this PR, it's a very different topic to the rest of the article, and I don't think we need it here since it's covered in depth elsewhere.

I removed the changes by Michael. But I keep the current example since it's quite useful for beginners IMHO.

I'd vote for cutting this section entirely. At this point, typeshed is good enough that users don't need to know at all about typeshed and beginner users don't really need to know about stubs to get started

AlexWaygood

This is a really nice PR! Some thoughts below :)

docs/source/getting_started.rst

AlexWaygood · 2022-04-25T16:40:18Z

docs/source/getting_started.rst

+            # In this case, mypy can't infer the exact type of this field
+            # based on the information available in this constructor, so we
+            # need to add a type annotation.
+            self.audit_log: List[str] = []


I'm not massively keen on an example that requires a three-line comment, especially since this is a beginner's tutorial. Can we think of a different example here, that doesn't involve having to instantiate an empty list? (I'm also trying to think of one.)

In any event, we should use PEP 585 syntax here :)

Suggested change

# In this case, mypy can't infer the exact type of this field

# based on the information available in this constructor, so we

# need to add a type annotation.

self.audit_log: List[str] = []

# In this case, mypy can't infer the exact type of this field

# based on the information available in this constructor, so we

# need to add a type annotation.

self.audit_log: list[str] = []

Maybe a transaction count as an int?

I like that idea!

IMHO it's not really a big deal since typing an empty list is a frequent case (personal feeling).

mypy would be able to infer an int

I'm going to keep the list[str] but remove the comments since the rule has been introduced in previous section

AlexWaygood · 2022-04-25T16:49:26Z

docs/source/getting_started.rst

+the types are: it'll assume the entire library is
+:ref:`dynamically typed <dynamic-typing>` and report an error
+whenever you import the library.
+


I think this section (from lines 452-487) should be moved to running_mypy.rst, or maybe just cut altogether. With the changes made in this PR, it's a very different topic to the rest of the article, and I don't think we need it here since it's covered in depth elsewhere.

AlexWaygood · 2022-04-28T15:44:24Z

(BTW @97littleleaf11, I'm only a triager so I can review, but I can't edit the PR :)

Co-authored-by: AlexWaygood <[email protected]>

…docs

97littleleaf11 · 2022-05-01T04:11:27Z

@AlexWaygood Thanks for your reviews! It's quite an old PR and let's make it merged soon.

I fixed the conflicts and added back some changes made after this PR. Could you take another round of check and merge it if possible?

AlexWaygood · 2022-05-01T04:16:41Z

Could you take another round of check and merge it if possible?

I don't have merge privileges, but I'd be happy to do another review at some point in the next few days! :)

hauntsaninja · 2022-05-01T21:38:40Z

docs/source/getting_started.rst

+            # In this case, mypy can't infer the exact type of this field
+            # based on the information available in this constructor, so we
+            # need to add a type annotation.
+            self.audit_log: List[str] = []


mypy would be able to infer an int

hauntsaninja · 2022-05-01T21:41:45Z

docs/source/getting_started.rst

+the types are: it'll assume the entire library is
+:ref:`dynamically typed <dynamic-typing>` and report an error
+whenever you import the library.
+


I'd vote for cutting this section entirely. At this point, typeshed is good enough that users don't need to know at all about typeshed and beginner users don't really need to know about stubs to get started

docs/source/getting_started.rst

hauntsaninja · 2022-05-07T22:32:43Z

Thanks everyone for getting this over the line!

ilevkivskyi reviewed Mar 18, 2019

View reviewed changes

ilevkivskyi requested a review from JukkaL March 18, 2019 11:15

97littleleaf11 added the documentation label Nov 19, 2021

Merge branch 'master' into add-info-about-classes-to-getting-started-…

ac78d3c

…docs

97littleleaf11 reviewed Nov 25, 2021

View reviewed changes

97littleleaf11 requested a review from AlexWaygood April 25, 2022 04:59

AlexWaygood reviewed Apr 25, 2022

View reviewed changes

AlexWaygood mentioned this pull request Apr 28, 2022

Document typeshed better: a mypy upgrade suddenly triggers new errors due to typeshed changes python/typeshed#7735

Open

97littleleaf11 and others added 5 commits May 1, 2022 11:21

Update docs

c3511a4

Co-authored-by: AlexWaygood <[email protected]>

Merge branch 'master' into add-info-about-classes-to-getting-started-…

f3dc44a

…docs

Fix

3630186

Add back the example introduced in PR9973

0f03e2b

Fix

310cf34

hauntsaninja reviewed May 1, 2022

View reviewed changes

97littleleaf11 added 2 commits May 6, 2022 09:46

Update

ea58976

Update

b75b855

hauntsaninja approved these changes May 7, 2022

View reviewed changes

hauntsaninja merged commit 91e890f into python:master May 7, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add info about classes and types to 'getting started' docs #6557

Add info about classes and types to 'getting started' docs #6557

Michael0x2a commented Mar 17, 2019

ilevkivskyi left a comment

ilevkivskyi Mar 18, 2019

AlexWaygood Apr 25, 2022

ilevkivskyi Mar 18, 2019

ilevkivskyi commented May 8, 2019

msullivan commented Oct 18, 2020

97littleleaf11 commented Oct 7, 2021

JukkaL commented Nov 25, 2021

97littleleaf11 Nov 25, 2021

AlexWaygood Apr 25, 2022

97littleleaf11 May 1, 2022

hauntsaninja May 1, 2022

AlexWaygood left a comment

AlexWaygood Apr 25, 2022

JelleZijlstra May 1, 2022

AlexWaygood May 1, 2022

97littleleaf11 May 1, 2022

hauntsaninja May 1, 2022

97littleleaf11 May 6, 2022

AlexWaygood Apr 25, 2022

AlexWaygood commented Apr 28, 2022

97littleleaf11 commented May 1, 2022

AlexWaygood commented May 1, 2022 •

edited

Loading

hauntsaninja May 1, 2022

hauntsaninja May 1, 2022

hauntsaninja commented May 7, 2022

Add info about classes and types to 'getting started' docs #6557

Add info about classes and types to 'getting started' docs #6557

Conversation

Michael0x2a commented Mar 17, 2019

ilevkivskyi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ilevkivskyi commented May 8, 2019

msullivan commented Oct 18, 2020

97littleleaf11 commented Oct 7, 2021

JukkaL commented Nov 25, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AlexWaygood left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AlexWaygood commented Apr 28, 2022

97littleleaf11 commented May 1, 2022

AlexWaygood commented May 1, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hauntsaninja commented May 7, 2022

AlexWaygood commented May 1, 2022 •

edited

Loading